recap/docs/architecture-simplification-plan.md

Recaps Architecture Simplification — Plan of Record

Status: Agreed direction, 2026-05-19. Not yet implemented.

Why this exists

The current Recaps architecture has the Keysat license doing too many jobs. For a cloud Pro/Max tenant, the license is acting as: (a) the entitlement check, (b) the relay credit-pool key, (c) the subscription-expiry source, AND (d) the take-it-home portability token. Only (d) actually requires a cryptographically-signed token. The other three are accidental — the license just happens to carry that data because Keysat was already minting license tokens during the MVP.

This doc captures the agreed simplification so we can revisit later before implementation.

---

The three products, cleanly separated

Recap Relay — Backend compute service. AI provider routing (Gemini / Claude / Whisper / Ollama / etc.), credit ledger, BTCPay-backed top-ups. Runs on Grant's StartOS. Sold as a service (subscription gives monthly credit allotment + a la carte top-ups).

Recaps — Frontend cloud SaaS for summarizing podcasts/videos. People sign up, pay a subscription, and use the relay for compute. Hosted at recaps.cc. Also freely available as a .s9pk for self-hosting.

Keysat — Standalone licensing-as-a-service software, separately monetized as a B2B product. Recaps happens to use Keysat for the one specific case of minting a portable license token when a cloud user clicks "Take Recaps home." Otherwise unrelated to Recaps day-to-day.

These are three products that happen to share an author. Tangling them is what made the current architecture confusing.

---

What each layer owns after the simplification

Concern	Lives in	Why
Subscription tier + expires_at	Recaps DB (users.tier, users.subscription_expires_at)	Billing state belongs with the billing surface. Zaprite/BTCPay webhooks fire at Recaps and update one row.
Credit balance (remaining/consumed)	Relay's ledger (credits.json)	Compute happens at the relay. The relay knows when N credits were actually spent on Gemini tokens. Race conditions get ugly if billing and consumption drift.
Purchased credit top-ups (one-shot Lightning)	Relay's ledger	BTCPay webhook → relay → bump purchased_balance on the relevant pool. Unchanged from today.
Monthly tier allotment	Relay computes from tier header passed by Recaps	Recaps sends X-Recap-User-Tier: pro; relay applies its quota config (pro.monthly = 50).
Per-user identity at the relay	Keyed by user:<recaps_user_id> (cloud) or lic:<fp> (self-hosted)	Removes the license-as-credential coupling for cloud requests. License only matters for self-hosted.

The header change

Cloud Recaps → Relay (today):
  Authorization: Bearer <user's LIC1 token>

Cloud Recaps → Relay (after simplification):
  X-Recap-User-Id: <recaps_user_id>
  X-Recap-User-Tier: pro
  Authorization: Bearer <OPERATOR's LIC1>      ← proves THIS Recaps server is authorized

The operator's bearer token is still needed because the relay needs to verify that this is Grant's cloud Recaps server (vs. someone else trying to forge user-id headers). The per-user identity comes from the explicit headers.

---

Cloud Recaps is paid-only

Decided: cloud Recaps drops the "free signed-in" tier entirely. Self- hosted IS the free path.

User states on cloud:

• Anon trial — cookie-tracked, no account. Gets a small allowance of credits to taste-test. After the trial runs out, must subscribe to continue using the cloud service.
• Subscribed — account exists, users.tier ∈ {pro, max}, subscription_expires_at in the future.
• Expired subscription — account preserves the library, can't summarize new things until renewed. Renewal anytime restores access.

What this means for the codebase: tenant_credits table's "free signed-in" codepath stops applying to cloud users. The table stays in the codebase because self-hosted multi-tenant operators (Alice running Recaps for her family) still need per-tenant accounting locally.

---

Payment provider strategy

Pro/Max purchase page has two paths:

┌─────────────────────────────────────────────┐
│  Upgrade to Pro — $X/month                  │
│                                             │
│   • 50 Recap credits per month              │
│   • Channel + podcast subscriptions         │
│   • Auto-queue + priority processing        │
│                                             │
│      ┌──────────────────────────────────┐   │
│      │  ⚡ Pay with Bitcoin             │   │  ← primary, inline BTCPay
│      └──────────────────────────────────┘   │
│                                             │
│            Pay with card →                  │  ← link → Zaprite hosted
│                                             │
└─────────────────────────────────────────────┘

Bitcoin path: monthly upfront, manual renewal

• User pays one BTCPay invoice for 30 days of Pro
• Inline Lightning QR + BOLT11 + copy button (same UX as credit packs)
• On settle, Recaps sets subscription_expires_at = now + 30 days
• No card on file, no autorenewal — Lightning doesn't have a clean recurring-billing primitive

Renewal-link emails (NEW, needed for Bitcoin path)

Recaps sends automated emails near expiry:

• 7 days before expiry — "Your Pro sub renews in 7 days. Tap to renew →"
• Day of expiry — "Your Pro sub expired. Tap to renew →"
• 7 days after expiry — "We've paused your Pro features. Renew anytime →"
• After 30 days post-expiry — stop emailing (avoid being a nag)

Mechanism:

• Email contains a tokenized URL: https://recaps.cc/renew?token=<base64>
• Token encodes { user_id, action: "renew_pro" }, short-lived (~14 days)
• Click → Recaps mints fresh BTCPay invoice, renders inline Lightning UI
• On settle, subscription_expires_at += 30 days (extends from whichever is later: existing expiry, or current time — so a user who renews 5 days early doesn't lose those days)

Card subscribers don't need this — Zaprite handles recurring billing natively via Stripe.

Card path: Zaprite handles everything

• Click "Pay with card" → redirect to Zaprite hosted checkout
• Zaprite collects card info, charges monthly, handles retries on failure
• Zaprite webhook fires → Recaps updates subscription_expires_at
• Cancel button in Settings → Plan calls Zaprite cancel API
• Card premium pricing handled inside Zaprite admin (not in Recaps code) — Grant configures the card-monthly price to be N% higher than Bitcoin-monthly in Zaprite's product settings

---

Self-hosted scenarios

Self-hosted Recaps is free + open source. Run the .s9pk anywhere, no license check to run the software.

Scenario	Subscriber to Grant's relay?	How relay access works
Bob runs Recaps for himself, brings his own Gemini key	No	Bob pays Google directly. Default .s9pk has no relay configured — Bob enters his AI provider keys in Settings.
Bob runs Recaps for himself + wants Grant's relay	Yes	Bob has a cloud Pro subscription. He clicks "Take Recaps home" in cloud settings → Recaps mints a fresh LIC1 token via Keysat with expires_at = subscription_expires_at. Bob pastes it into his self-hosted install. Self-hosted Recaps uses the token as Authorization: Bearer LIC1-... to the relay.
Alice runs Recaps for family, brings own Gemini key	No	Alice's family is invisible to Grant.
Alice runs Recaps for family + uses Grant's relay	Yes	Alice has a cloud subscription. Family-tenants on Alice's install all share Alice's relay-credit pool via Alice's pasted license. Alice manages per-family-member accounting locally via the existing tenant_credits + operator-grant flow. If Alice needs more credit headroom for her family, she upgrades her cloud sub to Max or buys credit packs.

What the license is for, after the simplification

One job: the credential that authenticates a self-hosted Recaps install against Grant's relay.

Not "are you Pro on cloud" — Recaps DB knows that. Not "credit pool key" — user:<recaps_user_id> keys cloud requests, lic:<fp> keys self-hosted. Not "subscription expiry" — users.subscription_expires_at in Recaps DB is the source of truth.

The license is a deliverable artifact, minted on demand only when a cloud Pro user explicitly clicks "Take Recaps home." Most cloud users never click it; they don't need a license. The license's expires_at mirrors the user's subscription expiry, so when their cloud sub lapses, the self-hosted install's relay access stops working naturally.

Grace period for self-hosted licenses

Decided: Keysat handles this. When a cloud subscription lapses, Keysat can keep the license valid for a short grace period (e.g., 7 days) before revoking. Recaps doesn't manage this — it's a Keysat-internal policy.

---

Migration order

When ready to implement:

1. Decide self-hosted = free + open source ← already decided. Removes the "is this install licensed" check from the cloud path; keeps it only as a guard on relay access.
2. Recaps schema additions: users.tier, users.subscription_expires_at, users.zaprite_customer_id, users.zaprite_subscription_id, users.bitcoin_renewal_token_hash (single-use). Migrate existing users by deriving tier + expires_at from their attached license at boot time.
3. Zaprite webhook handler: Recaps endpoint accepting Zaprite's order
   • subscription lifecycle events; updates user row accordingly.
4. Relay header migration: Cloud Recaps sends X-Recap-User-Id + X-Recap-User-Tier. Relay accepts BOTH old (license-keyed) and new (user-id-keyed) headers for one release as a compat window.
5. Drop license attachment from cloud signup: Pro/Max purchase via Zaprite or BTCPay now updates users.tier + users.subscription_expires_at directly. No LIC1 token attached at signup.
6. Renewal-email pipeline: Scheduled job in Recaps that scans for subscriptions approaching expiry, sends the renewal email with a one-time-use renewal token. Token consumption flow on /renew?token=….
7. Pro/Max purchase UX redesign: Bitcoin primary + Card secondary layout. Bitcoin path uses existing inline BTCPay flow. Card path redirects to Zaprite hosted checkout.
8. "Take Recaps home" rework: Becomes an explicit user-initiated action that mints a fresh LIC1 token via Keysat at click time, not at signup. UI shows the token with copy-to-clipboard + install instructions.
9. Cancel-subscription button: Settings → Plan → cancel. Hits Zaprite cancel API for card subs; for Bitcoin subs there's nothing to cancel (just let it lapse — they paid one month, they get one month).
10. Remove "free signed-in" path from cloud: Anon trial credits stay as taste-test; signup grant goes away. Self-hosted is the free path going forward.

Estimated effort: ~1 week of focused work end-to-end. Steps 2–5 are the core; the rest are polish on top.

---

Decided open questions

Q	Decision
Annual or monthly Bitcoin subscription?	Monthly upfront, manual renewal with automated renewal-link emails
Same price across paths, or premium/discount?	Card premium configured inside Zaprite admin, not in Recaps code
Grace period on self-hosted licenses when cloud sub lapses?	Keysat handles this — Recaps doesn't manage
Free tier on cloud?	No — cloud is paid-only, self-hosted is the free path

---

What stays (don't break)

• Relay's credit ledger + tier-quota math
• BTCPay webhook → relay-pool crediting (for one-shot Lightning credit packs)
• Inline Lightning UX for credit packs (already shipped, working)
• Anon trial mechanic (cookie-tracked taste-test)
• The "Take Recaps home" feature itself (just changes when the token is minted)
• The Keysat license-issuing pipeline (just changes who calls it and when)

What changes

• Recaps stops attaching a license at every Pro/Max signup
• Recaps gains its own subscription state (users.tier + expires_at)
• Relay accepts X-Recap-User-Id for cloud requests (compat with old license-keyed for self-hosted)
• Pro/Max purchase UX gets the two-option layout (Bitcoin primary, Card link)
• New renewal-email pipeline for Bitcoin subscribers
• Cancel-subscription button wired to Zaprite
• Cloud loses the "free signed-in" tier; self-hosted IS the free path
• "Take Recaps home" reshapes as on-demand mint, surfaced as an explicit button in cloud settings

What's deleted

• Nothing — only deprecated. Old license attachment code stays as a fallback for one release window. After migration is fully verified, can be cleaned up in a follow-up.