Building Multi-Tenant SaaS: Architecture Decisions That Matter

Multi-tenant SaaS architecture decisions lock you in for years. Get tenant isolation wrong and you'll face security incidents or impossible migrations. Get the data model wrong and scaling becomes prohibitively expensive.

We've designed and reviewed SaaS platforms across B2B and B2C. These are the decisions that matter most.

Tenant isolation: shared DB vs. schema-per-tenant vs. DB-per-tenant

Shared database with a tenant_id column is simple and cost-effective. It's also the riskiest: one query bug can leak data across tenants. Mitigate with row-level security, strict tenant context in every query, and thorough testing of isolation.

Schema-per-tenant (e.g. one PostgreSQL schema per tenant) gives stronger isolation and makes per-tenant backup or migration easier. Database-per-tenant goes further — full isolation, but operational complexity and cost scale with tenant count. Use shared DB until you have a clear reason to split (compliance, very large tenants, or need to move tenants independently).

Pricing tiers and feature gating

Your architecture should make feature gating by plan straightforward. Hardcoding plan checks in every feature is brittle. Prefer a central capability model: at login or request time, resolve the tenant's plan and inject a set of capabilities (e.g. can_export, max_users, has_analytics). Features check capabilities, not plan names.

This lets you add new plans or change what's included without touching feature code. It also makes A/B testing and custom enterprise overrides tractable.

Tenant context in every layer

Tenant context must be explicit and non-optional. Use a tenant_id (or tenant context object) in every service call, every query, every event. Never infer tenant from URL or session in the backend — resolve it once at the edge and propagate it.

• Middleware or API gateway resolves tenant from subdomain, JWT, or API key and attaches to request context.
• Data access layer always filters by tenant. Consider making tenant_id a required parameter so it's impossible to forget.
• Background jobs and event handlers must receive and use tenant context. No "global" jobs that touch all tenants without explicit iteration.

Scaling and noisy neighbors

In a shared environment, one tenant's load can affect others. Use per-tenant rate limiting, query timeouts, and resource quotas. For heavy workloads (reporting, batch jobs), consider queue-based processing with per-tenant fairness.

Monitor per-tenant resource usage. Identify and isolate or throttle tenants that consistently push limits. Your architecture should make it possible to move a high-impact tenant to dedicated infrastructure if needed.