Skip to main content

Deployment Topology

:::info Source Sourced from services/billing-service/DEPLOYMENT_TOPOLOGY.md in the documentation repo. :::

1. Containers​

  • billing-api — REST API.
  • billing-webhook — webhook receiver (high-availability, dedicated).
  • billing-worker — renewal batches, dunning schedules, payout processor.
  • billing-reconciler — daily reconciliation job.
  • billing-outbox-relay — NATS publisher.

2. Scaling​

ContainerMinMaxHPA
api320CPU>60%
webhook315req rate > 500/s
worker210queue depth > 100
outbox-relay25backlog > 5000

3. Resources​

api: 500m/2000m, 512Mi/1.5Gi. webhook: 300m/1500m, 256Mi/1Gi (lean). worker: 500m/2000m, 512Mi/2Gi.

4. Storage​

  • Postgres schema billing. 7-year hot + cold archive.
  • S3 for invoice PDFs (per-tenant prefix).

5. Caching​

  • Redis: webhook nonce cache (10 min), reconciliation cache, tax rate cache.

6. Regional​

  • Deployed in regions supporting specific processors (Stripe global).
  • PCI scope: webhook endpoint isolated in dedicated cluster.

7. Service Mesh​

mTLS. Egress: Stripe API, tax providers, bank APIs (for payouts), notification, analytics.

8. Network Security​

  • Webhook endpoint: allowlisted source IPs (Stripe publishes list).
  • Firewall: only outbound to Stripe + tax + bank endpoints.
  • VPN for ops access to PCI-scoped components.

9. Release​

Blue/green for API. Webhook: drain + replace (dropped events retry from Stripe). Worker: rolling.

10. DR​

  • RPO 5 min (WAL archive).
  • RTO 60 min.
  • Stripe is source of truth; can rebuild from Stripe API.

11. Diagram​

Buyer ──▶ Stripe Elements (browser)
           │
           ▼
      billing-api (create intent)
           │
           ▼
   Stripe confirms payment
           │
           ▼
 Stripe webhook ──▶ billing-webhook (allowlisted IP)
                         │
                         ├─ Verify signature
                         ├─ Dedup on event.id
                         ├─ Update payment/invoice state
                         └─ Emit billing.payment.succeeded.v1

 billing-worker: nightly renewals, dunning, payouts.
 billing-reconciler: daily Stripe balance reconcile.