sarancoding/multi-tenant-customer-operating-system-billing-engine

Purpose and Runtime Entry Points

This is a Python 3.11+ multi-tenant SaaS control plane providing tenant isolation, reliable outbound webhook delivery, Stripe usage billing, and self-serve onboarding. The FastAPI application starts at src/api/main.py; HTTP surface is partitioned under src/api/routes/. Docker deployment and local service topology are defined in docker/docker-compose.yml and docker/Dockerfile.

API and Request Boundary

FastAPI routes expose tenant, onboarding, billing, admin, and webhook operations: src/api/routes/tenants.py, src/api/routes/onboarding.py, src/api/routes/webhooks.py, and src/api/routes/billing.py. Shared dependency wiring resides in src/api/dependencies.py. Requests must establish tenant scope before data access, rather than trusting application-level filtering alone.

Tenant Isolation Layer

The shared-schema tenancy model uses tenant_id rows with PostgreSQL Row-Level Security as the authoritative isolation boundary. Tenant resolution/context, request middleware, and RLS integration are concentrated in src/core/tenant_context.py, src/tenants/middleware.py, and src/tenants/rls.py. Tenant metadata and lifecycle access are represented by src/tenants/models.py and src/tenants/registry.py; database setup is centralized in src/db.py. The intended transaction boundary sets the PostgreSQL tenant setting locally so FORCE RLS protects even raw SQL.

Event Backbone and Webhook Delivery

Business writes publish through an event subsystem rather than fire-and-forget delivery: src/events/bus.py, src/events/producers.py, and src/events/consumers.py. Webhook processing validates signatures, deduplicates, resolves tenant context, persists event/outbox state, and dispatches deliveries through src/webhooks/engine.py and src/webhooks/dispatcher.py. Delivery is at-least-once: retry policy and endpoint protection live in src/webhooks/retry.py; exhausted events enter the replayable dead-letter flow in src/webhooks/dlq.py; duplicate suppression uses src/webhooks/idempotency.py. Redis Streams and Kafka are material event infrastructure, with Redis also supporting idempotency state.

Billing and Usage Reconciliation

Usage is metered into hourly counters, constrained by product tiers, then sent to Stripe metered-billing APIs. The core pipeline is src/billing/meter.py, src/billing/aggregator.py, and src/billing/stripe_client.py; commercial limits and invoice behavior are in src/billing/tiers.py and src/billing/invoices.py. Stripe is an external system of record for subscriptions, metered usage, and invoicing; scheduled monthly billing and nightly drift reconciliation are expected runtime jobs.

Self-Serve Onboarding

Onboarding drives signup through verification, workspace creation, tier-specific guidance, required checklist gates, and time-to-first-value (TTFV) capture. The orchestration boundary is src/onboarding/flow.py, with self-service initiation in src/onboarding/self_serve.py, checklist state in src/onboarding/checklist.py, and TTFV tracking in src/onboarding/ttfv.py. This flow is event-driven and uses LangGraph state-machine infrastructure alongside the webhook delivery graph.

Persistence, Operations, and Delivery

PostgreSQL 16 is the durable store, managed through Alembic (migrations/env.py, migrations/versions/0001_initial.py); Redis, Kafka, and Stripe dependencies are wired through docker/docker-compose.yml. Cross-cutting configuration, exception behavior, and observability setup are in src/core/config.py, src/core/exceptions.py, and src/core/logging.py. CI validates lint, unit, integration, load, and security stages in .github/workflows/ci.yml; operational reliability expectations and deployment details are documented in docs/RELIABILITY.md and docs/ARCHITECTURE.md.