Multi-Tenancy Design: [SaaS product or platform name]

Design document for the multi-tenant architecture of a SaaS product: tenancy model (silo, pool, bridge) and trade-offs, tenant identification and context propagation, data isolation, noisy neighbour controls, tenant onboarding and offboarding, per-tenant configuration and feature flags, security and compliance including data residency, per-tenant observability, cost allocation, scaling and migration between tiers. Based on common SaaS architecture practice. Replace every [bracketed] value and every row marked Example; the examples follow a B2B project management product with about 400 business tenants.

Document control

Approvals

Revision history

Contents

1. Introduction
2. Tenancy requirements
3. Tenancy model
4. Tenant identification and context propagation
5. Data isolation
6. Noisy neighbour controls
7. Tenant lifecycle
8. Per-tenant configuration and feature flags
9. Security and compliance
10. Observability per tenant
11. Cost allocation
12. Scaling
13. Migration between tiers
14. Risks and open questions
15. Appendices

1. Introduction

1.1 Purpose

This document defines how [Product] serves many customer organisations (tenants) from shared infrastructure while keeping their data, performance and configuration isolated. It is the reference for engineering, security and operations decisions that depend on tenancy.

1.2 Definitions

1.3 Tenant profile

2. Tenancy requirements

3. Tenancy model

3.1 Options

3.2 Decision

Rationale: [summary and ADR link]. Example: pooled compute keeps Starter unit cost under USD 20 per month; siloed data for Enterprise meets contractual isolation and residency requirements without running a separate application stack per customer (ADR-031).

4. Tenant identification and context propagation

4.1 Identification

4.2 Context propagation

Tenant context is resolved once at the edge and carried in signed tokens and message headers. The sequence shows a request through to the database.

Rules: [list]. Example: services reject requests without tenant context; the context library sets the database session variable on every connection checkout and clears it on return; events without a tenant_id header are dead-lettered; logs and traces include tenant_id automatically.

5. Data isolation

Row-level security example for the pooled database (PostgreSQL syntax):

ALTER TABLE project ENABLE ROW LEVEL SECURITY;
ALTER TABLE project FORCE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON project
  USING (tenant_id = current_setting('app.tenant_id')::uuid)
  WITH CHECK (tenant_id = current_setting('app.tenant_id')::uuid);

6. Noisy neighbour controls

Fair scheduling: [describe]. Example: background workers pull from per-tenant queues in weighted round-robin, so a tenant importing a million rows cannot delay notifications for others. Database statement timeout is 5 s for pooled tenants. Heavy tenants are detected when they use more than 5% of pooled capacity for 15 minutes and are flagged for review or tier change.

7. Tenant lifecycle

The state diagram shows the lifecycle of a tenant.

7.1 Onboarding

7.2 Offboarding

8. Per-tenant configuration and feature flags

Rules: flags are evaluated with tenant ID and tier as attributes; every override has an owner and an expiry; entitlement checks run on the server, never only in the client.

9. Security and compliance

10. Observability per tenant

11. Cost allocation

The monthly cost attributed to tenant $t$ is

where $D_t$ is the cost of resources dedicated to the tenant, $C_{\text{pool}}$ is the cost of pooled resources, $u_t$ is the tenant's usage units (for example weighted request and storage units), $N$ is the number of tenants and $C_{\text{fixed}}$ is shared platform cost that does not vary with usage.

Example for a Business tenant: $D_t = 500$, $C_{\text{pool}} = 40{,}000$, $u_t = 1{,}200$ of $\sum u_k = 20{,}000$ units, $C_{\text{fixed}} = 12{,}000$ and $N = 400$: $C_t = 500 + 40{,}000 \times 0.06 + 30 = 500 + 2{,}400 + 30 = 2{,}930$ USD. At a price of USD 4,500 the gross margin is $(4{,}500 - 2{,}930) / 4{,}500 \approx 34.9\%$.

12. Scaling

Cell placement: new tenants go to the least-loaded cell in their region. A cell is a blast-radius boundary: an incident in one cell affects at most its tenants.

13. Migration between tiers

Downgrades (silo to pool) follow the same steps in reverse and are allowed only at contract renewal.

14. Risks and open questions

15. Appendices

15.1 References

15.2 Tenant registry fields

Standard and licence note

Based on common SaaS architecture practice for multi-tenant systems, including the widely used silo, pool and bridge tenancy models. Original text written for this collection; examples, limits and figures are illustrative. Template licence: MIT.