Billing

Billing manages organization subscriptions, plan tiers, monthly credits, and current-month usage through Stripe checkout, billing portal, and signature-verified webhook flows. BillingController creates Checkout and Portal sessions and returns plan, credit-balance, and usage summaries, while BillingService maps checkout keys to configured Stripe prices. PlanGuard and RequiresPlan gate routes or controllers by required plan level, and credit-cost constants meter AI and technical-documentation operations.

24 entities in atloria-monorepo/apps/api/src/billing. 9 other subsystems depend on it, which makes it the 5th most depended-upon part of this codebase.

What it is made of

Its 24 entities sit in 8 files under atloria-monorepo/apps/api/src/billing: 11 constants, 4 HTTP endpoints, 3 services, 2 type aliases and 4 more. billing.constants.ts holds 10 of them — more than any other file here. BillingService declares 4 methods, the widest surface here.

Where work enters

1 controller publishes 4 HTTP endpoints — 2 POST and 2 GET. They answer under /billing. Every one of them sits behind JwtAuthGuard.

• BillingController — atloria-monorepo/apps/api/src/billing/billing.controller.ts:23
• checkout — atloria-monorepo/apps/api/src/billing/billing.controller.ts:29
• portal — atloria-monorepo/apps/api/src/billing/billing.controller.ts:41
• summary — atloria-monorepo/apps/api/src/billing/billing.controller.ts:49
• webhook — atloria-monorepo/apps/api/src/billing/billing.controller.ts:57
• BillingModule — atloria-monorepo/apps/api/src/billing/billing.module.ts:14

How work moves through it

mermaid
flowchart LR
  BillingController0["BillingController"]
  BillingService10["BillingService"]
  BillingController0 --> BillingService10
  PrismaService20["PrismaService"]
  BillingService10 --> PrismaService20
  AIUsageService21["AIUsageService"]
  BillingService10 --> AIUsageService21
  stop["refused"]
  BillingService10 -. "NotFoundException" .-> stop

Work enters at BillingController and passes through 3 other components. Each step below is a dependency edge between two entities in this repository, followed outward in order.

1. BillingController takes the work first — atloria-monorepo/apps/api/src/billing/billing.controller.ts:23.
2. Next, BillingController hands off to BillingService — atloria-monorepo/apps/api/src/billing/billing.service.ts:23.
3. Finally, BillingService calls PrismaService and AIUsageService.

Where the work stops

• BillingService stops the work with NotFoundException when !org — “Organization not found”, in 3 places.
• BillingService stops the work with BadRequestException when !envVar.
• AIUsageService stops the work with BadRequestException when !Number.isFinite(amount) || amount <= 0 — “Credit deduction amount must be a positive number”.
• AIUsageService stops the work with PaymentRequiredException when result.count === 0.

When a step fails

• BillingService handles failure in 1 place: it lets it reach the caller in all 1.
• PrismaService handles failure in 1 place: it lets it reach the caller in all 1.
• AIUsageService handles failure in 1 place: it logs it and continues in all 1.

How it refuses and fails

3 of its components record a refusal or a failure handler. All 3 of them refuse work outright, under a condition written into the component itself. Their catch blocks handle a failure that already happened in 1 place.

Boundaries

9 other subsystems depend on this one — Api, Auth, Branding, Documentation, Platform, Project, Reader Access, Reader Account, Scim. Changing what it exposes changes them.

Those 9 hold 15 edges between them, unevenly: Branding reaches in across 2 edges, while 3 of them hold one each. 15 edges arrive against 6 leaving — more of this repository reaches into it than it reaches out to. What they reach is narrower than the folder: 2 of its 24 members carry every inbound edge — BillingModule (9) and PlanService (6). Of the 6 it sends out, 3 go to Database — more than to any other.

It depends on Database, Auth, Ai, and on nothing else in this repository.