System Type: Multi-Tenant SaaS

Patterns, failure modes, and anti-patterns for multi-tenant software-as-a-service platforms.

1. Isolation Models

Every multi-tenant system lives on a spectrum between full sharing and full isolation. The choice is not one-time — most mature SaaS platforms mix models across their stack.

The Spectrum

When to Mix Models

The right answer is almost always a hybrid. Small tenants on shared infrastructure, enterprise tenants on dedicated. The boundary is driven by:

• Revenue: A tenant paying $50/month cannot justify a dedicated database. A tenant paying $500K/year can justify a dedicated cluster.
• Compliance: HIPAA, SOC2 Type II, FedRAMP, and data residency laws (GDPR Article 44+, China's PIPL) may require physical isolation regardless of cost.
• Risk tolerance: If a single tenant's data breach would be existential (healthcare, finance), isolate by default.
• Noisy neighbor exposure: If one tenant can generate 100x the load of a median tenant, shared compute is a liability.

The Compliance Driver

Compliance is the most common reason teams are forced up the isolation spectrum against their economic interest. Understand these constraints early:

• Data residency: Some tenants require data to stay in a specific geographic region. This forces at minimum a separate data store, often a separate deployment.
• SOC2 / ISO 27001: Auditors want to see logical or physical isolation. Row-level tenant_id filtering is defensible but requires strong evidence (query audit logs, automated testing, access controls).
• HIPAA: Business Associate Agreements (BAAs) often require encryption at rest per tenant and audit trails. Shared-everything makes this operationally painful.
• FedRAMP: Usually requires a fully separate environment. Not a spectrum decision — it's a separate product deployment.

Practical Guidance

Design for shared-everything first, but make the isolation boundary a first-class abstraction. Every data access path should go through a tenant context that can be swapped from "row filter" to "connection router" without rewriting application code. Teams that don't do this spend 6-18 months retrofitting isolation when their first enterprise customer demands it.

2. Data Partitioning

Data partitioning is where multi-tenancy gets real. The schema design you pick on day one will constrain your options for years.

Row-Level Isolation (tenant_id Columns)

The most common starting point. Every table has a tenant_id column. Every query includes a WHERE tenant_id = ? predicate.

What goes wrong:

• Missed predicates: One query without a tenant_id filter leaks data across every tenant. This is the single most common multi-tenant security vulnerability. Mitigate with: PostgreSQL Row-Level Security (RLS), ORM-level query interceptors that inject tenant filters, automated test suites that assert every query plan includes the tenant predicate.
• Index bloat: Without composite indexes that lead with tenant_id, queries scan far more data than needed. Every index should be (tenant_id, ...) not (..., tenant_id).

…