Multi-Tenant B2B SaaS Platform

Tenant isolation models (pool, bridge, silo), a control plane for onboarding and metering, tenant-aware identity and data access, noisy-neighbour protection, cells and per-tenant cost.

[!ASSUMPTION] Scope "FlowDesk", a hypothetical B2B SaaS for service operations (tickets, workflows, knowledge base) serving 20,000 tenants from 5-person startups to 100,000-employee enterprises. Numbers are assumptions.

1. Business problem and objectives

FlowDesk started as a single-tenant-per-customer deployment model. Each new customer costs weeks of setup and a dedicated stack; upgrades require hundreds of deployments. Objectives:

  • Self-service onboarding in under 5 minutes for small tenants.
  • Enterprise tier with stronger isolation, data residency and customer-managed keys.
  • One codebase, one release train for all tenants.
  • Gross margin above 75% (infrastructure cost per tenant visible and controlled).
  • Prevent any cross-tenant data access.

2. Business model and revenue generation

Tier Price model Isolation
Free/Starter Per user/month, limits on records and automations Pooled
Business Per user + usage add-ons (automation runs, AI credits) Pooled with stronger quotas
Enterprise Annual contract, SSO/SCIM, audit, residency, CMK Dedicated database or dedicated cell (silo)

Usage-based components require accurate metering and transparent usage dashboards.

3. Functional requirements

  1. Tenant sign-up, provisioning, plan selection, trial to paid conversion.
  2. Users, roles, groups; SSO (SAML/OIDC) and SCIM provisioning for enterprise.
  3. Tickets, workflows/automations, knowledge base, reporting.
  4. Per-tenant configuration and custom fields.
  5. Usage metering, quotas, billing integration, invoices.
  6. Tenant admin console: audit log, data export, API keys.
  7. Platform admin: tenant lifecycle (suspend, migrate tier, delete), support access with consent.

4. Non-functional requirements

Attribute Target
Isolation Zero cross-tenant data exposure; tested continuously
Availability 99.9% standard, 99.95% enterprise SLA
Latency p95 API < 300 ms for all tenants regardless of neighbour load
Scalability 20K → 100K tenants; largest tenant 100K users
Residency EU, US, India data locations
Compliance SOC 2 Type II, ISO 27001, GDPR; HIPAA option for some tenants
Cost Infrastructure ≤ 12% of revenue

5. Expected user base and traffic assumptions

  • 20K tenants, 2 M total users, 400K daily active.
  • Distribution: 90% of tenants are small (< 50 users) but produce 25% of load; the top 1% produce 40%.
  • 8K RPS average, 25K peak (business hours overlap).
  • 3 B ticket records, 50 TB attachments.

The skewed distribution drives a tiered isolation design.

6. High-level architecture

  • Control plane (global): tenant registry, onboarding, plans, provisioning, metering, billing integration, tenant routing, feature flags.
  • Application plane (regional cells): stateless services (tickets, workflows, KB, search, reporting), tenant-aware data access, async workers.
  • Identity: central identity service issuing tokens with tenant context; per-tenant IdP federation.
  • Data: pooled multi-tenant databases with row-level security, dedicated databases for enterprise tenants; search indices per cell with tenant filtering; object storage with tenant-prefixed keys.

7. Detailed component architecture

Component Responsibility Design choice
Tenant registry Tenant ID, tier, region, cell, database location, status Global, strongly consistent store (PostgreSQL in control-plane region + replicas)
Provisioning service Create tenant resources, run migrations, seed config Workflow engine; idempotent steps; minutes for pooled, longer for silo
Tenant router Map tenant → cell/region Edge lookup cached at gateway; vanity domain → tenant
Identity service Login, SSO federation, token issuance with tenant_id claim OIDC provider (Auth0/Okta/Cognito/Keycloak) + tenant connections
Data access layer Enforce tenant scoping Library + DB row-level security (RLS) as defence in depth
Metering service Count billable events Events → stream aggregation → usage store; idempotent with event IDs
Quota/rate limiter Per-tenant limits per plan Token buckets keyed by tenant; tier-specific
Billing integration Invoices, payments Stripe Billing/Chargebee/Zuora via usage export
Tenant migration tool Move tenant between cells/tiers CDC-based copy, verify, cutover

8. Architecture diagram

flowchart TB
  subgraph Control plane [Global control plane]
    ONB[Onboarding & provisioning]
    REG[(Tenant registry)]
    MET[Metering & usage]
    BILL[Billing integration]
    FF[Feature flags / plans]
  end
  U[Tenant users] --> EDGE[Edge: CDN, WAF,<br/>tenant router]
  EDGE --> ID[Identity service<br/>SSO, tenant claims]
  EDGE --> C1
  EDGE --> C2
  subgraph C1 [Cell EU-1: pooled tenants]
    API1[Services: tickets, workflow, KB] --> DB1[(Pooled Postgres<br/>RLS by tenant_id)]
    API1 --> S1[(Search index)]
  end
  subgraph C2 [Cell EU-ENT: enterprise tenants]
    API2[Same services] --> DBA[(Tenant A DB)]
    API2 --> DBB[(Tenant B DB)]
  end
  ONB --> REG
  EDGE -.lookup.-> REG
  API1 & API2 -- usage events --> MET --> BILL
  ONB --> C1 & C2

9. Frontend architecture

  • Single React SPA (or Next.js) with tenant theming (logo, colors) loaded from tenant config.
  • Tenant-aware URLs (acme.flowdesk.app) or path-based routing; custom domains for enterprise with managed TLS certificates.
  • Feature availability by plan driven by the control plane (entitlements API) so the UI hides features not in the plan.
  • Admin console separated from the end-user app; strict CSP; no cross-tenant state in browser storage.

10. Backend architecture

  • Modular services per domain; every request carries a tenant context extracted from the verified token, never from user input.
  • Data access layer automatically applies tenant filters; PostgreSQL RLS as a second guard:
ALTER TABLE ticket ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON ticket
  USING (tenant_id = current_setting('app.tenant_id')::uuid);
-- Set per transaction by the data access layer:
-- SET LOCAL app.tenant_id = '<tenant from token>';
  • Async jobs carry tenant ID in message headers; workers set tenant context before processing.
  • Per-tenant configuration (custom fields) stored as JSONB with validated schemas.

11. API design with sample endpoints

POST /v1/tenants                      (control plane, public sign-up)
GET  /v1/tickets?status=open&assignee=me&cursor=...
POST /v1/tickets                      { "subject": "...", "priority": "P2", "customFields": {...} }
POST /v1/automations/{id}/runs
GET  /v1/usage?period=2026-11         -> { "automationRuns": 18230, "aiCredits": 4200, "limits": {...} }
POST /scim/v2/Users                   (enterprise SCIM provisioning)
GET  /v1/audit-events?from=...

Tenant ID is not a path or body parameter on application APIs; it comes from the token. API keys are scoped to a tenant and a set of permissions.

12. Database schema and data model

CREATE TABLE tenant (               -- control plane
  tenant_id uuid PRIMARY KEY, name text, tier text, region text, cell_id text,
  isolation text CHECK (isolation IN ('POOL','BRIDGE','SILO')),
  db_ref text, status text, created_at timestamptz
);

CREATE TABLE ticket (               -- application plane (pooled)
  tenant_id uuid NOT NULL,
  ticket_id bigint NOT NULL,
  subject text, status text, priority text, assignee_id uuid,
  custom jsonb NOT NULL DEFAULT '{}',
  created_at timestamptz NOT NULL,
  PRIMARY KEY (tenant_id, ticket_id)
);
CREATE INDEX ON ticket (tenant_id, status, created_at DESC);

CREATE TABLE usage_event (
  event_id uuid PRIMARY KEY, tenant_id uuid, meter text, quantity int, occurred_at timestamptz
);

tenant_id leads every primary key and index: it keeps tenant data clustered, makes RLS efficient, and prepares for sharding by tenant.

13. Database technology selection and reasoning

Tier Model Store Why
Starter/Business Pool: shared schema, tenant_id column + RLS Aurora/AlloyDB/Azure PostgreSQL, sharded by tenant across clusters (Citus optional) Lowest cost per tenant, simple operations
Large Business Bridge: schema per tenant on shared cluster PostgreSQL schemas Easier per-tenant export/restore; moderate isolation
Enterprise Silo: database (or whole cell) per tenant Dedicated PostgreSQL + CMK Strong isolation, residency, per-tenant backup/restore, noisy neighbour immunity
Search Shared index with tenant routing key, or index per large tenant OpenSearch Balance shard count vs isolation
Files Object storage, prefix per tenant, per-tenant KMS key for enterprise S3/GCS/Blob Crypto-shredding on tenant deletion

14. Authentication and authorization

  • OIDC login; enterprise tenants federate their own IdP (SAML/OIDC), with home realm discovery by email domain.
  • Tokens include tenant_id, user ID, roles; services validate tokens and never trust tenant IDs from requests.
  • RBAC per tenant (admin, agent, viewer) plus custom roles for enterprise; ABAC for record-level rules (team, region).
  • SCIM for automated user lifecycle; session policies per tenant (MFA required, IP allow-lists).
  • Support access: just-in-time, tenant-approved, time-boxed, fully audited.

15. Security architecture

  • Defence in depth for isolation: token-derived tenant context → data-layer filter → database RLS → per-tenant encryption keys for silo tenants.
  • Automated cross-tenant tests in CI and in production canaries: create two synthetic tenants and assert that every API rejects cross-tenant access.
  • Per-tenant audit logs exported to customers' SIEMs.
  • Customer-managed keys (BYOK/HYOK) for enterprise; crypto-shredding on deletion.
  • Secure multi-tenant search: filter by tenant at query time on the server, never client-side.

16. Caching strategy

  • Cache keys always prefixed with tenant ID (t:{tenant}:ticket:{id}) to avoid leakage.
  • Tenant config and entitlements cached at the gateway and services with short TTL and invalidation events.
  • Per-tenant cache quotas to prevent one tenant evicting everyone else's data.

17. Messaging and event-driven architecture

  • Domain events (TicketCreated, AutomationTriggered) carry tenant ID in headers.
  • Fair scheduling: per-tenant queues or weighted fair queuing for automation runs so a tenant running 1 M automations does not starve others. Options: SQS queue per tier + per-tenant concurrency limits; Kafka partitions keyed by tenant with dedicated topics for very large tenants.
  • Usage events to metering with idempotent event IDs.

18. Cloud deployment architecture

  • Cells per region (EU, US, IN), each a full application stack for a set of tenants (e.g. 2,000 small tenants or 1 enterprise tenant).
  • Control plane deployed globally (primary + DR), not in the request path except for routing lookups that are cached.
  • New cells stamped from IaC templates; cell size limits keep blast radius and database sizes bounded.

19. CI/CD and DevOps

  • One release train; progressive rollout across cells (internal tenant cell → small-tenant cells → enterprise cells).
  • Database migrations must be backward compatible and run per database (hundreds of silo databases): orchestration with retries and tracking.
  • Tenant-level feature flags for early access and per-tenant rollback of features.

20. Monitoring and observability

  • All telemetry tagged with tenant ID (with care for cardinality: use exemplars and sampled per-tenant metrics for big tenants, aggregated for small).
  • Per-tenant SLO dashboards for enterprise customers.
  • Noisy-neighbour detection: top tenants by CPU/DB time/queue depth per cell.
  • Cost allocation: per-tenant resource usage feeding unit economics.

21. Scalability and performance optimization

  • Per-tenant rate limits and quotas by plan.
  • Shard pooled databases by tenant; rebalance by moving tenants (tenant migration tool).
  • Move tenants that outgrow pool limits to bridge or silo automatically.
  • Heavy reports run on read replicas or a warehouse copy, not on the OLTP database.

22. High availability and disaster recovery

  • Multi-AZ everywhere; cells independent so a cell failure affects only its tenants.
  • Per-tenant point-in-time restore for silo tenants; for pooled tenants, logical per-tenant restore tooling (restore snapshot to a side database, extract the tenant's rows).
  • Enterprise tenants can buy cross-region DR.

23. Cost optimization

  • Pooling is the main lever: thousands of small tenants per cell.
  • Track cost per tenant and per plan; adjust plan limits where unprofitable.
  • Scale cells down at night for regions with business-hours usage; ARM instances; storage tiering for old attachments.

24. Architecture trade-offs and alternatives

Decision Chosen Alternative When
Isolation Tiered (pool/bridge/silo) Silo for all Few, large, regulated customers
Tenant routing Cells by tenant Single global stack Small scale, single region
Customization Config + JSONB custom fields Per-tenant code forks Never; forks destroy SaaS economics
Identity Buy CIAM Build Only if identity is your product

25. Technology stack recommendations

Java/Kotlin or TypeScript services; PostgreSQL (Aurora/AlloyDB/Azure Database for PostgreSQL) with RLS; Redis; OpenSearch; Kafka or SQS; Temporal for provisioning and automations; Auth0/Okta/Cognito/Keycloak; Stripe Billing or similar; Kubernetes; Terraform; OpenTelemetry.

26. Common architecture mistakes

  1. Taking tenant ID from request parameters or headers set by the client.
  2. Forgetting tenant scoping in background jobs, caches, search and exports.
  3. No per-tenant quotas, letting one tenant degrade everyone.
  4. Building custom features per customer as code branches.
  5. Not measuring cost per tenant, so free/starter plans silently lose money.
  6. Making the control plane a synchronous dependency of every request.

27. Senior architect interview questions and answers

How do you guarantee one tenant can never see another tenant's data?

Derive tenant context only from verified identity; enforce it in a shared data-access layer; add database RLS as a second layer; prefix cache and object keys; filter search server-side; use per-tenant keys for high tiers; and run automated cross-tenant penetration tests continuously.

How do you deal with a noisy neighbour?

Per-tenant rate limits and quotas, fair queuing for async work, resource isolation for heavy features, detection dashboards, and moving the tenant to a dedicated cell or higher tier when it consistently exceeds pooled limits.

How do you run schema migrations across 500 silo databases?

Expand/contract migrations that are backward compatible, an orchestrator that applies them per database with retries and progress tracking, application code that supports both schema versions during rollout, and canary databases first.

28. Enterprise architect interview questions and answers

When would you recommend a silo model?

For regulated industries, contractual isolation, data residency per customer, very large tenants, or customers requiring customer-managed keys and per-tenant maintenance windows. Price it accordingly.

How do you standardize multi-tenancy across 10 product teams?

A shared tenancy SDK (context propagation, data access, cache key helpers), platform-provided control plane APIs, reference architecture, and automated conformance tests in CI.

29. CTO-level business and technology questions

How does architecture affect SaaS gross margin?

Isolation model, cell density and observability of per-tenant cost determine infrastructure cost per customer. Pool small tenants, price isolation as a premium, and watch AI/usage features that can have unbounded cost per tenant.

How do you price AI features in a multi-tenant product?

Credits or usage-based add-ons tied to metered tokens or actions, with per-tenant budgets and hard limits, because AI inference cost scales with usage rather than seats.

30. Real-world implementation roadmap

Phase Duration Outcomes
1. Control plane + pooled cell 0–4 months Tenant registry, self-service onboarding, RLS, metering
2. Enterprise features 3–8 months SSO/SCIM, audit logs, custom roles, silo provisioning
3. Cells and regions 6–12 months EU/IN regions, cell stamping, tenant migration tool
4. Usage pricing and cost 9–15 months Usage-based billing, cost per tenant dashboards
5. Migrate legacy single-tenant customers 12–24 months Customers moved into cells; legacy stacks retired