# Design: GitHub as Single Source of Truth + Phase 2 Execution

## Date: 2026-02-16
## Author: Claude Code (session-016)

---

## Problem

1. GitHub is not being used as the single source of truth — backlog lives in `docs/backlog/` (130 items across 11 epics), but GitHub Issues has 0 visible issues (previous 33 were lost to account flag).
2. Phase 2 critical path (auth + billing + gating) needs to be designed and executed.
3. Account is flagged (60 REST/hr, 0 GraphQL/hr) — constrains what we can set up now.

---

## Design: GitHub Setup

### What We're Setting Up

| Component | Status | Notes |
|-----------|--------|-------|
| **Milestones** | DONE | Phase 1-4 created |
| **Labels** | DONE | 36 labels (epic, phase, priority, size, type, status) |
| **Issues** | IN PROGRESS | 37 priority issues from backlog (rate limited) |
| **GitHub Projects** | BLOCKED | Requires GraphQL (0/hr on flagged account) |
| **Branch protection** | BLOCKED | Requires GitHub Pro |
| **CI/CD** | BLOCKED | Actions may not work on flagged account |
| **Sub-issues** | DEFERRED | Available after flag lifts (GA feature) |

### Issue Taxonomy

Issues follow a naming convention for quick scanning:

- `[P1-DONE]` — Phase 1, completed
- `[P2]` — Phase 2, active work
- `[P2-DONE]` — Phase 2, completed
- `[P3]` — Phase 3, planned
- `[BLOCKED]` — Deferred, waiting on external dependency

### Sync Strategy: Docs ↔ GitHub

- `docs/backlog/` remains the detailed epic specification
- GitHub Issues is the **execution tracking** layer
- Each GitHub issue maps to one or more backlog items
- Status flows: GitHub Issue closed → backlog item marked DONE
- Session tracker references issue numbers

### Rate Limit Mitigation

With 60 REST API calls/hour on the flagged account:
- Issue creation via `gh api repos/.../issues` (REST) — works
- `gh issue create` (GraphQL) — fails
- Seeding script at `tools/seed-github-issues.py` handles rate limits with retry + sleep
- Can create ~30 issues per rate limit window (with overhead for reads)

---

## Design: Phase 2 Architecture

### Auth Bridge: Next.js ↔ Python CLI

```
┌─────────────────┐         ┌──────────────────┐
│  Next.js Dashboard │       │  Python CLI Proxy  │
│                     │       │                    │
│  Auth.js v5 (JWT)   │──────▶│  AuthMiddleware    │
│  Prisma User model  │  API  │  ProxyKeyStore     │
│  Stripe billing     │  Key  │  RateLimitMiddleware│
│                     │       │                    │
│  /auth/login        │       │  /v1/chat/completions│
│  /auth/register     │       │  /v1/messages      │
│  /api/keys/generate │       │  /v1/models        │
└─────────────────┘         └──────────────────┘
```

**How it works:**
1. User registers/logs in on Next.js dashboard
2. Dashboard generates a proxy API key (calls ProxyKeyStore)
3. User configures `llmhosts` CLI with the API key
4. CLI sends requests with `Authorization: Bearer <key>`
5. Python proxy validates key, checks plan limits, routes request

**Key decision**: The proxy API key is the bridge token. The Next.js dashboard creates keys via a shared key store (JSON file or SQLite). No JWT validation needed in Python — the API key is the auth mechanism.

### Stripe Flow

```
User → Pricing Page → Stripe Checkout → Webhook → DB Update → Plan Active
                                            ↓
                                    Proxy enforces plan limits
```

Already built:
- Webhook handler (4 event types handled)
- Plan mapping (price ID → free/pro/team/enterprise)
- User model with Stripe fields

Still needed:
- `/api/stripe/checkout` route (creates Stripe Checkout Session)
- `/api/stripe/portal` route (redirects to Stripe Billing Portal)
- Pricing page component
- Plan enforcement in proxy rate limiter

### Feature Gating

| Feature | Free | Pro | Team | Enterprise |
|---------|------|-----|------|-----------|
| Devices | 1 | 5 | 25 | Unlimited |
| RPM | 60 | 300 | 600 | Unlimited |
| Dashboard | TUI + local web | + Cloud | + Team view | + Admin |
| Tunnel | localhost | + public | + shared | + dedicated |
| Router data | Local only | + Global | + Team | + Custom |
| Hive Mode | No | No | Yes | Yes |
| RBAC | No | No | Yes | Yes |
| SSO | No | No | No | Yes |
| Audit export | No | No | No | Yes |

Enforcement points:
1. **Proxy middleware** — RPM limits based on plan
2. **Device registration** — count check on `llmhosts serve`
3. **Dashboard** — feature visibility based on session plan
4. **Tunnel** — `--public` requires Pro+

---

## Implementation Priority

| Order | Issue | Size | Critical Path? |
|-------|-------|------|---------------|
| 1 | GitHub issues seeded | M | Setup |
| 2 | Auth bridge (Next.js → CLI) | XL | YES |
| 3 | Stripe checkout flow | L | YES |
| 4 | Feature gating | L | YES |
| 5 | TestPyPI publish | M | No (parallel) |
| 6 | tunnel --public | L | No |
| 7 | Dashboard completion | XL | No |
| 8 | Multi-device activation | L | No |

Items 2-4 are the **revenue critical path**. Items 5-8 can be parallelized.

---

## Success Criteria

- [ ] 37 GitHub issues created and properly labeled/milestoned
- [ ] Phase 2 critical path items (#2-4) implemented
- [ ] User can: register → subscribe → get API key → use CLI
- [ ] 282+ tests passing (maintain green)
- [ ] Session tracker updated
