Multi-Tenant SaaS Platform

Tenants, plans, metering and isolation

Design the platform under a B2B SaaS product: onboarding, isolation per plan, entitlements, usage billing, enterprise sign-in, and moving a large tenant to its own database.

Overview

A business-to-business (B2B) SaaS product sells one running service to many companies. Each company is a tenant: it has its own users, data, plan and bill. The product's features (projects, tasks, documents) are the part customers see. Underneath sits the platform, and that is what this problem asks you to design: how a tenant signs up and gets its resources, how its data and its share of capacity stay its own, what its plan lets it do, how its usage becomes an invoice, how its employees sign in through their company's identity system, and what happens when it outgrows the shared setup.

The concept topic Multi-Tenancy Architecture covers the vocabulary: silo, pool and bridge, row-level security, noisy neighbors and sharding by tenant. This page assumes it and builds the whole system. The hard part is not any one component. It is that tenant identity has to reach everything: an API call, a background job hours later, a cache key, a log line, a backup file and a usage event all have to say whose they are, or data leaks and bills go wrong.

Questions to ask first

What is the product? — A B2B work-management app: projects, tasks, files
How many tenants? — 20,000, from 3-person teams to companies with 50,000 users; 2 million users in all
Plans? — Free, Team and Enterprise; Enterprise adds SSO, SCIM, audit logs and its own database on request
How is it billed? — A price per seat, plus usage (API calls, storage) above what the plan includes
Compliance? — Some customers need their data kept in the EU, and their own encryption keys
Self-service? — Free and Team sign up alone in seconds; Enterprise is set up with a sales contract

What you will be able to do

Split the platform into a control plane and an application plane, and onboard a tenant through an automated, repeatable workflow.
Choose pool, bridge or silo per plan, and carry a trusted tenant ID into every query, job and cache key.
Protect tenants from each other with per-tenant limits, and see each tenant's health and cost.
Turn plans into entitlements and usage events into correct invoices.
Connect enterprise SSO and SCIM, keep a tenant's data in its region, restore or delete one tenant, and move a large tenant to its own database.

Key concepts

Control plane
Application plane
Tenant directory
Tenant context
Pool, bridge and silo tiers
Row-level security
Per-tenant rate limits
Entitlements
Usage metering
SAML, OIDC and SCIM

Functional requirements

Create a tenant by self-service sign-up or by an operator, and provision it for its plan
Sign users in with a password, Google, or the company's SAML or OIDC identity provider
Create, update and deactivate users through SCIM from the company's directory
Enforce each plan's features and limits, with per-tenant overrides from contracts
Meter usage per tenant and send it to billing; show tenants their usage
Keep a tenant's data in its chosen region
Export, restore and permanently delete one tenant's data
Move a tenant between pooled and dedicated databases

Non-functional requirements

No request, job, cache entry or export ever returns another tenant's data
One tenant's load cannot push other tenants' p99 latency past target (a target we chose: 300 ms for API reads)
99.9% monthly availability for the application plane (a target we chose); the control plane may be less available without stopping existing tenants
A self-service tenant is usable within 30 seconds of sign-up (a target we chose)
Usage is counted once: replays and retries never bill twice
Deleting a tenant reaches every store, and backups age out within the stated retention

Interview questions

Walk me through what happens when a new company signs up.
Which isolation model would you use for 20,000 tenants, a few of them very large or regulated?
How do you make sure tenant A never sees tenant B's data?
One customer's integration is hammering the API. What protects everyone else?
How would you build usage-based billing so invoices are right?
An enterprise customer wants SSO and automatic deprovisioning. What do you build?
A customer asks you to restore their data to yesterday, without affecting anyone else. Can you?
How do you move your largest tenant to its own database with no downtime?
An EU customer requires its data to stay in the EU. What changes?
How do you roll out a schema change when some tenants have their own databases?