Design a multi-tenant SaaS platform

Pooled means all tenants share tables, separated by a tenant_id column. It is the cheapest and simplest to operate (one schema migration, high density), and it fits 50,000 small tenants, but isolation depends on every query being correct and one large tenant affects others. Bridge means a schema per tenant in a shared database: better logical separation and easy per-tenant export, but Postgres struggles with tens of thousands of schemas (catalog bloat, migration time grows with tenant count, connection pooling gets harder). Silo means a dedicated database or full stack per tenant: strongest isolation, per-tenant encryption, residency and maintenance windows, but costly and only manageable with heavy automation. Most real SaaS platforms use a hybrid: pooled for the long tail, silo for the top enterprise customers who pay for it, and the same code and schema everywhere. The tenant catalog makes this possible: the application asks 'where does t42 live?' and gets a cell or dedicated database. Design so a tenant can move between models (pool → silo) with an online migration, because today's startup tenant may be next year's enterprise.

Cross-tenant leaks almost never come from the database model; they come from one forgotten filter, a cache key without a tenant, or a background job that loses context. Treat tenant context as a security principal. Resolve it once at the edge from the verified token (never from a URL parameter or header the client controls), and carry it in the request context. In Postgres, use Row-Level Security as a second line of defence: policies on every tenant table, FORCE ROW LEVEL SECURITY, the application connecting as a non-owner role, and SET LOCAL inside each transaction so a pooled connection cannot leak the previous request's tenant (plain SET with PgBouncer transaction pooling is a classic bug). Every index leads with tenant_id. Cache keys, queue messages, S3 prefixes, search and vector indexes, and log lines all carry the tenant id through shared libraries, not ad-hoc code. For AI features this matters even more: retrieval must be tenant-filtered (RLS on chunk tables, or a separate namespace per tenant in a vector DB), and the semantic cache must be scoped by tenant, or one company's confidential answer is served to another. Finally, test it: an automated suite that logs in as tenant A and asserts zero rows or objects from tenant B for every endpoint, run in CI forever.

In a pooled system one tenant's bulk import, report query or runaway automation can raise everyone's latency. Defend at each shared resource. At the edge, per-tenant rate limits by plan (token bucket in Redis). For async work, avoid one FIFO queue where a tenant's 1M-job import blocks everyone: use per-tenant fair scheduling (weighted round-robin across tenant sub-queues, or a per-tenant concurrency cap on workers). In the database, statement timeouts, per-tenant connection limits in the pooler, and moving heavy analytics to a replica or ClickHouse. For AI, per-tenant token budgets in the LLM gateway, because one tenant's agent loop can exhaust the provider rate limit for everyone. Beyond that, limit the blast radius with cells: independent copies of the full stack (app, DB, cache, queues), each serving a few thousand tenants, with a thin global router and catalog in front. A bad deploy is rolled out cell by cell; a database incident affects 5% of tenants, not 100%. Cells also give data residency (India cells, EU cells) and a unit of scaling: when cells fill, add a new cell rather than growing one database forever. Hot tenants are moved to quieter cells or their own silo with an online migration (logical replication filtered by tenant_id, then a short write freeze and catalog switch).

Shared tables give high density and one migration path; RLS adds a small query overhead and needs discipline with connection pools. Database per tenant gives hard isolation and easy deletion and residency but means thousands of databases to migrate, monitor and pay for. Hybrid by tier is the usual answer.

Cells cap blast radius and allow residency, but add a routing layer, cross-cell operations (global search across tenants, admin reports) become harder, and capacity is fragmented. One global deployment is simpler until a single incident takes down every customer. At 50,000 tenants with enterprise SLAs, cells are worth it.

A shared account with an internal gateway gives volume pricing and central control. Some enterprises want their own provider keys or a model in their own cloud (bring your own key/model); support it as a gateway routing option per tenant, not a different code path.

A tenant growing to 20% of a cell's load makes it hot. Monitor per-tenant share; above a threshold, move it to a dedicated cell with logical replication and a catalog switch, ideally before it becomes an incident.

With dozens of cells and hundreds of silos, migrations take hours and can half-fail. Use expand-and-contract migrations (backward-compatible), a migration orchestrator that tracks version per database, rolling by cell with automatic pause on errors.

Every request needs tenant → cell. Cache the catalog at the edge and in routers with long TTLs and serve stale on error; the catalog changes rarely.

Failover to the synchronous standby in another AZ (~30-60 s). Only that cell's tenants see errors; the status page is per cell. Other cells are untouched.

RLS blocks the query from returning other tenants' rows even if the application forgot the filter; the leak test in CI should catch it first. If a leak happens, the audit log (with tenant and actor on every access) scopes the incident and notification.

The gateway fails over to a backup provider or model; the assistant degrades to plain search results with links if all fail. Core helpdesk functions do not depend on the LLM.