Architecture patterns
Multi-tenant SaaS architecture
Designing one system for many customers, covering isolation models, tenant scoping, noisy neighbors, tenant-aware sharding and per-tenant cost.
A tenant is a customer organization: a company on Slack, a workspace on Notion, a merchant on Shopify. Multi-tenancy means serving many tenants from one system and sharing infrastructure to get the economics that make SaaS work. It lets a startup sell a $10-per-month plan profitably, because each extra tenant shares servers, databases and operations with thousands of others.
Sharing creates three hard problems. Isolation: tenant A must never see tenant B's data, a bug class that has ended companies. Fairness: one tenant's huge import must not slow everyone else. Flexibility: the largest customers will ask for things the smallest never think about, such as data in a specific country, their own encryption keys, single sign-on and audit logs.
Get these right early. Retrofitting tenant scoping into a system that has run without it for years is one of the most expensive refactors in SaaS.
The pages below cover the isolation models and how to choose between them, scoping every query, controlling noisy neighbors, sharding and moving tenants, and attributing cost per tenant.
Concepts in this section
| Step | Concept | What it answers |
|---|---|---|
| 1 | Isolation models | How much should tenants share, and what do enterprise customers require? |
| 2 | Enforcing tenant scoping | How do you make sure no query crosses tenants? |
| 3 | Noisy neighbors | How do you stop one tenant from slowing the rest? |
| 4 | Moving tenants and sharding | How do you split data across machines, and move a big tenant? |
| 5 | Cost per tenant | Which customers are profitable? |
Common mistakes
- Trusting a tenant ID from the request. Derive it from the verified login. A URL parameter a user can edit is a leak waiting to happen.
- Scoping only in application code. One forgotten
WHEREclause leaks data. Add database-level enforcement and leak tests. - Leaving caches, search and storage unscoped. Put the tenant ID in every cache key, search document, object path and topic.
- Shipping expensive features without limits. Add per-tenant quotas to imports, exports, reports and AI features before launch.
- No way to move a tenant. Build the move tool early, so moving a big tenant is routine.
Key takeaways
- Isolation is a spectrum from shared tables to dedicated stacks. Most companies tier their tenants across several models.
- Derive the tenant from authentication, scope automatically, enforce in the database, and test for leaks.
- Control noisy neighbors with per-tenant limits, concurrency caps, fair queuing and dedicated pools.
- Shard by tenant through many logical shards and a directory, and build an online move tool.
- Meter usage per tenant. It reveals unprofitable customers and informs pricing.
Further learning
Tod Golding's re:Invent talk walks through silo, pool and bridge isolation, with concrete AWS implementations of each.
A later re:Invent session focuses on economics, designing multi-tenant architectures so that cost per tenant stays low and measurable.
Start with isolation models.
Related
Sharding and partitioning
Split data across machines by choosing a shard key, hashing or ranging it, routing requests, handling hot spots, resharding without downtime and generating IDs that stay unique.
Authentication and authorization
Authentication proves who you are, authorization decides what you can do, and service-to-service calls need their own identity. The map for the rest of this topic.
Pricing and packaging
Value metrics, tiers, freemium vs trials, usage-based pricing and how to test prices.