Multi-Tenant SaaS Architecture: What I Learned Building One

Building a multi-tenant SaaS forces you to make decisions early that are painful to undo later. After doing it twice — once wrong, once right — here's what actually matters.

The biggest mistake I made the first time was mixing tenant data at the application layer instead of isolating it at the database level. Row-level security in PostgreSQL is underrated. It makes isolation a database guarantee, not something you have to remember in every query.

Schema-per-tenant sounds clean until you have 500 tenants and need to run a migration. Shared schema with tenant_id is messy until you add proper indexing and row-level security. Pick based on your isolation requirements, not aesthetics.

For auth, I use a JWT structure where the tenant context is baked into the token. Every API call carries the tenant ID, every query is automatically scoped. No accidental data leaks.

The hardest part isn't the architecture — it's the edge cases. Tenant onboarding (provision database, seed defaults, set up subdomain), tenant offboarding (export data, delete records in order due to foreign keys), and tenant suspension (flag, not delete).

If I were starting over: start with shared schema + row-level security, PostgreSQL, and a clear tenant context middleware. Scale to schema-per-tenant only when a single tenant's data volume demands it.