Inside Our Multi-Tenant SaaS Architecture

Multi-tenant SaaS architecture is the backbone of modern enterprise platforms. The fundamental challenge is serving hundreds of organizations from a single codebase and infrastructure while maintaining complete data isolation, per-tenant customization, and enterprise-grade security.

We evaluated three approaches: database-per-tenant (maximum isolation, high operational cost), schema-per-tenant (good isolation, moderate complexity), and row-level isolation (efficient, requires careful implementation). We chose row-level isolation with defense-in-depth — every database table includes a tenant_id foreign key, and three layers of security enforce isolation.

When a new enterprise client signs up through the onboarding wizard, a precisely orchestrated pipeline executes: (1) create the tenant record with subscription plan and feature flags, (2) seed 7 default roles with granular permissions, (3) create the admin user account, (4) provision a sample project with example data, (5) configure the subdomain DNS record. All five steps execute in a single atomic transaction — if any step fails, everything rolls back.

The entire onboarding process completes in under 3 seconds. The new tenant can immediately log in at their subdomain (acme.taptipm.com) and start using the platform. No manual provisioning, no ops tickets, no waiting.

Each tenant gets a unique subdomain resolved through middleware that runs before any authentication. The middleware extracts the hostname, looks up the tenant record (with a 5-minute Redis cache to minimize database load), and injects the tenant context into the request pipeline.

Enterprise clients can bring their own domain (pm.acmecorp.com). The setup flow generates a CNAME target and TXT verification token. Once the client configures their DNS, our verification service validates the records and activates the custom domain. SSL certificates are automatically provisioned via Let's Encrypt.

Layer 1 (Middleware): The tenant resolution middleware sets the tenant context on every request. Requests without a valid tenant context are rejected with a 403 before reaching any business logic.

Layer 2 (Guards): Authentication guards verify that the JWT token's tenant claim matches the request's tenant context. A valid token for Tenant A cannot access Tenant B's resources, even if the user somehow obtains a direct URL.

Layer 3 (Query Scope): Every database query in the application includes a tenantId filter. This is enforced at the ORM level through Prisma middleware — developers cannot accidentally write a query that crosses tenant boundaries. Cross-tenant data access is architecturally impossible.

Each tenant has a featureFlags JSON object controlling module access. The Free plan enables only PM basics; Starter adds HRMS and Finance; Professional unlocks CRM, AI estimation, and advanced analytics; Enterprise enables everything including secrets vault, white-label branding, and reseller program access.

Feature flags are checked at both the API level (guards reject unauthorized requests) and the UI level (sidebar navigation dynamically shows/hides modules). Upgrading a plan instantly unlocks new features — the change propagates through the cached tenant context within 5 minutes.

Tenant data is backed up every 6 hours with point-in-time recovery capability. Enterprise tenants can request on-demand backups and data exports in JSON or CSV format. The backup system is tenant-aware — restoring a single tenant's data does not affect other tenants.

Our disaster recovery plan targets an RPO (Recovery Point Objective) of 6 hours and an RTO (Recovery Time Objective) of 1 hour. Regular DR drills are conducted quarterly, and results are shared with enterprise clients as part of our SOC 2 Type II compliance program.