Internal Documentation internal
← Back to TalkIDE
TalkIDE internal documentation

What this context does

The platform’s money layer: it puts a payment method on file, generates invoices, enforces spending limits, processes inbound Stripe webhooks, and — from Phase 2 onward — implements the postpaid hosting billing model on top of the first-class Environment concept (ADR-026). This is where TalkIDE turns AI-token usage and hosting consumption into real charges.

Scope boundary

  • Owns: Stripe Customer lifecycle, SetupIntent / PaymentIntent flows, the stripe_customer_id on users, spending_limit_usd on user_budget, invoice listing, webhook event processing, AI credit top-up, billing markup, the environment entity, and the postpaid hosting accrual / dunning machinery.
  • Does not own: Anthropic spend metering itself (UC-08001 — this context bills on top of the ledger), the deployment pipeline (Stopa B), per-tenant namespaces (ADR-015/024).

Key design decisions

  • One Stripe Customer per user, lazy-created on first billing action.
  • No Stripe Subscriptions — Stripe is used for a payment method on file plus invoice generation, not recurring plans.
  • All Stripe calls are BE-side — the FE never holds a secret key; it only uses the publishable key with Stripe Elements.
  • Webhook endpoint is JWT-exempt — authenticated via the Stripe-Signature header, idempotent per event id.
  • AI stays prepaid; hosting goes postpaid — ADR-026 DP-0. AI credit top-up (UC-10007) is unchanged; postpaid accrual applies only to hosting/infra.

Use cases

UCStatusWhat it does
UC-10001ImplementedRegister Payment Method — SetupIntent + Stripe Elements
UC-10002ImplementedGet Payment Method — card brand / last4 / expiry
UC-10003ImplementedUpdate Billing Email
UC-10004ImplementedList Invoices — paginated, PDF via hosted_invoice_url
UC-10005ImplementedSpending Limit GET + PUT — nullable = unlimited, soft alerts
UC-10006ImplementedStripe Webhook — signature verification, idempotent processing
UC-10007ImplementedCredit Top-up — one-off AI credit purchase ($5–$500)
UC-10008ImplementedApply Markup to Billing — markup flows into credit deduction
UC-10010Ready (F1)Environment Foundation — environment entity, lazy default
UC-10012Ready (F2)Environment Billing — postpaid accrual, monthly invoice, soft dunning
UC-10013Ready (F3)Environment Create/Manage — SHARED environments
UC-10014Ready (F4)Environment Deployment Wiring + live tenant namespace cut-over
UC-10015Ready (F5)Hosting Hard Enforcement — scale-to-zero on SUSPENDED
UC-10016ReadyUsage Breakdown Per-Project — AI top-N + hosting per-namespace

Phasing — Stripe live mode

Dependencies on other contexts

  • UC-01 User Management — stripe_customer_id lives on the users row.
  • UC-08 Mara Platform — postpaid billing reconciles against api_usage_ledger and the hosting cost events; markup (UC-10008) feeds the credit-deduction path.
  • UC-03 / Stopa B deployment — F4 wires the Environment concept into namespace routing; F5 scales published prod Deployments to zero when a billing account is SUSPENDED.

Cross-cutting

  • Spending limits are dual — ADR-026 DP-2 keeps the AI cap (UC-10005) and the hosting cap (hosting_spending_limit_usd) independent.
  • Soft before hard — F1–F3 enforcement is notification-only; hard scale-to-zero only arrives in F4/F5 after a full dunning sequence (3 retries → PAST_DUE → grace → SUSPENDED).
  • Immutable Liquibase — every schema change is a new migration file (0021, 0022, 0031, 0034–0044, …) — production phase, no in-place edits.
Was this page helpful?

Thanks for the feedback.