Billing & Subscription — Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                        SELLER DASHBOARD (Next.js)                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────────┐  │
│  │  Plans Tab   │  │  Invoices    │  │  Coins & Add-ons Tab     │  │
│  │  (Pricing    │  │  Tab         │  │  (Balance, Buy Coins,    │  │
│  │   Cards +    │  │  (Razorpay   │  │   Purchase Add-ons,      │  │
│  │   Toggle)    │  │   Invoices)  │  │   Transaction History)   │  │
│  └──────┬───────┘  └──────┬───────┘  └────────────┬─────────────┘  │
│         │                 │                        │                │
│  Razorpay modal opens inline (no redirect) — JS SDK  │              │
│  ┌──────┴─────────────────┴────────────────────────┴─────────────┐  │
│  │               Billing Settings API Client                     │  │
│  └───────────────────────────┬───────────────────────────────────┘  │
└──────────────────────────────┼──────────────────────────────────────┘
                               │ HTTPS
┌──────────────────────────────┼──────────────────────────────────────┐
│                     GATEWAY (Hono / Cloudflare Workers)            │
│  auth.middleware → access.middleware → rate-limit → proxy          │
└──────────────────────────────┼──────────────────────────────────────┘
                               │
             ┌─────────────────┴─────────────────┐
             │                                   │
┌────────────▼───────────┐          ┌────────────▼───────────┐
│   MANAGER SERVICE      │          │  PAYMENT PROVIDER      │
│   (Billing Domain)     │          │  IPaymentProvider      │
│  ┌───────────────────┐ │          │  ┌──────────────────┐  │
│  │ Billing Router    │ │  ←────── │  │ RazorpayProvider │  │
│  │ PaymentProvider   │ │  ──────→ │  │ (current)        │  │
│  │  interface calls  │ │          │  ├──────────────────┤  │
│  └────────┬──────────┘ │          │  │ StripeProvider   │  │
│           │            │          │  │ (Phase 8, future)│  │
│  ┌────────▼──────────┐ │          │  └──────────────────┘  │
│  │ Webhook Handler   │ │          └────────────────────────┘
│  │  Normalizes &     │ │
│  │  processes events │ │
│  └────────┬──────────┘ │
│           │            │
│  ┌────────▼──────────┐ │
│  │ Entitlement Svc   │ │
│  │  Rebuilds limits  │ │
│  │  in tenant_svc    │ │
│  └───────────────────┘ │
└────────────┬───────────┘
             │
┌────────────▼─────────────────────────────────┐
│              POSTGRES (Neon / Supabase)       │
│  ┌────────────┐  ┌────────────────────────┐  │
│  │  Building   │  │  Floor (Tenant)        │  │
│  │  plans      │  │  subscriptions         │  │
│  │  services   │  │  tenant_services       │  │
│  │  svc_limits │  │  tenant_coins          │  │
│  │  plan_svc_  │  │  coin_transactions     │  │
│  │   limits    │  │  tenant_addons         │  │
│  │  coin_packs │  │  processed_rzp_events  │  │
│  │  addon_cat  │  └────────────────────────┘  │
│  └────────────┘                               │
└──────────────────────────────────────────────┘

rebuildEntitlements(tenantId):
  1. Read tenant's current plan from `subscriptions`
  2. Load limits from `plan_service_limits` for that plan
  3. Load active `tenant_addons` (coin-purchased extras)
  4. Merge limits:  plan_limits + addon_boosts = effective_limits
  5. Upsert `tenant_services` rows with merged limits
  6. Optionally: invalidate cached JWT so next token refresh picks up new entitlements

rebuildEntitlements(tenantId):
  1. Read tenant's plan_id from subscriptions
  2. SELECT * FROM plan_service_limits WHERE plan_id = :planId
     → gives all services + all limits for the plan
  3. SELECT * FROM tenant_addons WHERE tenant_id = :tenantId AND status = 'active'
     → gives coin-purchased boosts
  4. For each service_code:
       effective_limits = plan_limits + addon_boosts
       UPSERT tenant_services SET limits = effective_limits, enabled = true
  5. For services NOT in the plan:
       UPSERT tenant_services SET enabled = false

User clicks "Upgrade to Pro"
  → Dashboard POST /billing/checkout { planId: "pro", cycle: "yearly" }
  → Manager creates Stripe Checkout Session
      price: plans.stripe_price_id_yearly
      trial_period_days: 30 (if eligible)
      automatic_tax: true
      allow_promotion_codes: true
  → Returns session.url
  → Dashboard redirects to Stripe
 
Stripe collects payment / starts trial
  → Stripe POST /webhooks/stripe  (checkout.session.completed)
  → Manager Webhook Handler:
      1. Upsert `subscriptions` row (status: 'trialing' or 'active')
      2. Update `tenants.plan_id`
      3. Call rebuildEntitlements(tenantId)
  → User returns to Dashboard → sees "Pro Plan" badge

User clicks "Buy Medium Pack (2,200 coins, $20)"
  → Dashboard POST /billing/coins/buy { pack: "medium" }
  → Manager creates Stripe Checkout Session (one-time, $20)
  → Redirect to Stripe → payment
 
Stripe POST /webhooks/stripe  (checkout.session.completed, mode: 'payment')
  → Manager:
      1. INSERT coin_transaction (+2200, reason: 'purchase')
      2. UPDATE tenant_coins.balance += 2200
 
User clicks "Buy +5GB Storage (500 coins)"
  → Dashboard POST /billing/addons/buy { type: "storage", qty: 5 }
  → Manager:
      1. Check tenant_coins.balance >= 500
      2. INSERT coin_transaction (-500, reason: 'addon_storage')
      3. UPDATE tenant_coins.balance -= 500
      4. INSERT tenant_addons (type: 'storage', qty: 5, status: 'active')
      5. Call rebuildEntitlements(tenantId)  → storage limit += 5GB

Stripe auto-charge fails
  → Stripe POST /webhooks/stripe  (invoice.payment_failed)
  → Manager:
      1. SET subscriptions.status = 'past_due'
      2. SET flag for sitewide warning banner
  → Dashboard shows ⚠️ banner with "Update Payment" link
 
Stripe retries over 7-day grace period...
 
If all retries fail:
  → Stripe POST /webhooks/stripe  (customer.subscription.deleted)
  → Manager:
      1. SET subscriptions.status = 'canceled'
      2. SET tenants.plan_id = 'free'
      3. Call rebuildEntitlements(tenantId)  → Free limits applied
      4. Coin-based addons set to 'paused'
  → Dashboard shows 🔴 downgrade banner
  → Soft enforcement: existing data preserved, new creation blocked

CRON job or scheduled worker runs daily
  → For each tenant_addon WHERE status = 'active' AND next_renewal <= NOW():
      1. Check tenant_coins.balance >= addon.coin_cost
      2. If sufficient:
           Deduct coins → INSERT coin_transaction → advance next_renewal by 30 days
      3. If insufficient:
           SET addon.status = 'paused'
           Notify tenant: "Your +5GB storage add-on has been paused. Top up coins to reactivate."
           Call rebuildEntitlements(tenantId)  → remove addon boost

async function checkLimit(tenantId: string, resource: string): Promise<void> {
  const entitlement = await db.query.tenantServices.findFirst({
    where: { tenantId, serviceCode: resourceToService(resource) }
  });
 
  const limit = entitlement?.limits?.[resource];
  if (limit === undefined || limit === -1) return; // unlimited
 
  const current = await countResource(tenantId, resource);
 
  if (current >= limit) {
    throw new PlanLimitError({
      error: 'PLAN_LIMIT_REACHED',
      resource,
      limit,
      current,
      upgrade_url: `/dashboard/settings/billing`
    });
  }
}

apps/manager/src/
  routes/
    billing.router.ts          ← API endpoints (provider-agnostic)
  services/
    billing.service.ts         ← Calls IPaymentProvider interface
    entitlement.service.ts     ← rebuildEntitlements()
    coins.service.ts           ← Coin balance + transactions
  providers/
    payment-provider.interface.ts  ← IPaymentProvider interface
    razorpay.provider.ts           ← RazorpayProvider (current)
    stripe.provider.ts             ← StripeProvider (Phase 8, stub now)
  webhooks/
    razorpay.webhook.ts        ← Razorpay webhook handler
    stripe.webhook.ts          ← Stripe webhook handler (Phase 8)
    webhook.normalizer.ts      ← Normalizes provider events → BillingEvent
  utils/
    razorpay-client.ts         ← Razorpay SDK init + helpers
    stripe-client.ts           ← Stripe SDK init (Phase 8)

packages/core-billing/src/
  index.ts                 ← public exports
  limit-guard.ts           ← checkLimit(tenantId, serviceCode, limitKey)
  billing.errors.ts        ← PlanLimitReachedError, InsufficientCoinsError
  billing.constants.ts     ← LIMIT_KEYS, BILLING_EVENTS enum, PLAN_IDS

// packages/core-types/src/billing.ts
export type PaymentProvider = 'razorpay' | 'stripe'
export type BillingCycle = 'monthly' | 'yearly'
export type SubscriptionStatus = 'active' | 'trialing' | 'past_due' | 'canceled'
 
export interface Plan { id: string; name: string; priceMonthlyInr: number; ... }
export interface CoinTransaction { id: string; tenantId: string; amount: number; ... }
export interface NormalizedBillingEvent {
  type: 'SUBSCRIPTION_ACTIVATED' | 'SUBSCRIPTION_CHARGED' | ...
  provider: PaymentProvider
  tenantId: string
  payload: Record<string, any>
}

// Add to role_admin permissions:
"billing:invoices.read", "billing:coins.read", "billing:addons.read",
"billing:info.read", "billing:plans.read"

interface IPaymentProvider {
  // Subscriptions
  createSubscription(params: {
    tenantId: string;
    planId: string;
    cycle: 'monthly' | 'yearly';
    trialDays?: number;
  }): Promise<{ providerId: string; customerId: string; status: string }>;
 
  cancelSubscription(providerId: string): Promise<void>;
 
  changePlan(params: {
    subscriptionId: string;
    newPlanId: string;
    cycle: 'monthly' | 'yearly';
  }): Promise<{ action: 'upgraded' | 'downgraded'; effective: 'immediate' | 'end_of_period' }>;
 
  // One-time payments (coin packs)
  createOrder(params: {
    tenantId: string;
    amount: number;     // in smallest currency unit (paise for INR, cents for USD)
    currency: string;   // 'INR' or 'USD'
    metadata: Record<string, string>;
  }): Promise<{ orderId: string; amount: number; currency: string; keyId: string }>;
 
  // Invoices
  getInvoices(customerId: string, cursor?: string): Promise<ProviderInvoice[]>;
 
  // Customer management
  createCustomer(params: { name: string; email: string }): Promise<{ customerId: string }>;
  updateCustomer(customerId: string, params: { name?: string; taxId?: string }): Promise<void>;
 
  // Webhook
  verifyWebhookSignature(payload: string, signature: string): boolean;
  parseWebhookEvent(payload: string): NormalizedBillingEvent;
}

Phase 1 — Prepare (while still in Manager)
  ✅ All billing code already isolated in billing/ directories
  ✅ Billing service/router has zero imports from auth/team modules
  ✅ Shared types live in @repo/core-types (not Manager internals)
  ✅ Database queries use a dedicated billing query layer (not raw db calls scattered everywhere)
 
Phase 2 — Extract
  1. Create apps/billing-service/ (Hono + Cloudflare Worker)
  2. Move billing.router, billing.service, entitlement.service, coins.service, stripe.webhook
  3. Update Gateway routing: /billing/* → billing-service (instead of Manager)
  4. Stripe webhook endpoint URL updated in Stripe Dashboard
 
Phase 3 — Inter-Service Communication
  1. Billing service reads tenant/membership data via internal API calls to Manager
     OR shared DB access with billing-specific read models
  2. Entitlement updates publish events to the Event Bus
     → Manager listens and invalidates JWT cache
  3. Coin renewal CRON runs as a Cloudflare Durable Object or separate scheduled worker
 
Phase 4 — Verify
  1. All billing endpoints respond identically (API contract tests)
  2. Webhook processing works end-to-end
  3. Manager has zero billing code remaining

// ✅ CORRECT — check before processing
const existing = await db.query.processedEvents.findFirst({
  where: { stripeEventId: event.id }
});
if (existing) return; // Already processed, skip
 
// Process the event...
await db.insert(processedEvents).values({ stripeEventId: event.id });

// ✅ CORRECT — use SELECT FOR UPDATE to prevent race conditions
await db.transaction(async (tx) => {
  const wallet = await tx.query.tenantCoins.findFirst({
    where: { tenantId },
    forUpdate: true  // Lock the row
  });
 
  if (wallet.balance < cost) throw new InsufficientCoinsError();
 
  await tx.update(tenantCoins).set({ balance: wallet.balance - cost });
  await tx.insert(coinTransactions).values({ amount: -cost, reason, tenantId });
});