What is it?

A multi-tenant backbone is the part of a SaaS product that is not the product: telling tenants apart, keeping their data separate, onboarding a new one without manual work, and metering what each one uses. The application logic sits on top of it and stays unaware of how separation is done.

The Problem it Solves

Most SaaS products start with one shared database and a tenant column on every table. It works until three things happen at once. A large customer demands its data in a dedicated database. One tenant's traffic starts degrading everybody else's response times. And onboarding a customer requires an engineer to run scripts by hand.

At that point tenant handling is spread across every query in the codebase, and changing it means changing everything. Putting the tenant boundary in one place, early, is what keeps that from happening.

How the Architecture Works

1. Resolving the tenant, once

   • The Tenant Router is the only component that answers "which tenant is this, and where does its data live". It authenticates against the Identity Provider, reads settings from the Tenant Config Cache, and checks the Quota Counters.
   • The Application Service behind it receives an already resolved tenant. Product code contains no routing logic.

2. Two isolation models, one architecture

   • The Pooled Tenant Database holds tenants on the standard plan.
   • The Dedicated Tenant Database holds a tenant that requires its own. Both sit on the same relational platform, which is the point: moving a customer from pooled to dedicated is a configuration change and a migration, not a new architecture.

3. Onboarding without an engineer

   • The Admin API puts a request on the Provisioning Queue. The Provisioning Worker creates the tenant record, its data, and its configuration.
   • Provisioning is asynchronous and retryable. Half created tenants are the most common failure in SaaS onboarding, and a queue with a dead letter queue is what prevents them.

4. Metering and exit

   • The Usage Collector turns metered events into billable records in the Control Database.
   • The Export Worker produces the export a tenant is entitled to take away. Build this on day one. It is a contractual and regulatory requirement, and it is painful to retrofit.

Why quotas are in the request path

Noisy neighbours are the failure mode of pooled tenancy. Counters read on every request are what let you throttle one tenant before it degrades the others. Detecting it afterwards in a dashboard is too late.

Control plane and tenant data are separate

Plans, quotas, and billing live in the Control Database, never inside a tenant's database. Two reasons: deleting a tenant must not delete its billing history, and a bug in tenant routing must not expose commercial data.

What is in the Fractal

24 components. Runs on is the platform the component is hosted by, talks to is what it connects to. The two are different things: a workload runs on the container platform and talks to a database.

| Component | Catalog type | Runs on | Talks to | |---|---|---|---| | API Gateway | APIManagement.PaaS.APIGateway | - | Tenant Router, Admin API | | Container Platform | NetworkAndCompute.PaaS.ContainerPlatform | - | - | | Service Mesh security | Security.CaaS.ServiceMeshSecurity | Container Platform | - | | Identity Provider | Security.PaaS.IdentityProvider | - | - | | Tenant Router | CustomWorkloads.CaaS.Workload | Container Platform | Identity Provider, Tenant Config Cache, Quota Counters, Tenant Database (Pooled), Tenant Database (Dedicated), Application Service | | Application Service | CustomWorkloads.CaaS.Workload | Container Platform | Tenant Database (Pooled), Tenant Database (Dedicated), Tenant Config Cache | | Admin API | CustomWorkloads.CaaS.Workload | Container Platform | Identity Provider, Control Database, Provisioning Queue, Export Store | | Provisioning Worker | CustomWorkloads.CaaS.Workload | Container Platform | Provisioning Queue, Provisioning Dead Letter Queue, Control Database, Tenant Database (Pooled), Tenant Database (Dedicated), Tenant Config Cache | | Usage Collector | CustomWorkloads.CaaS.Workload | Container Platform | Usage Topic, Control Database, Quota Counters | | Export Worker | CustomWorkloads.CaaS.Workload | Container Platform | Provisioning Queue, Control Database, Tenant Database (Pooled), Tenant Database (Dedicated), Export Store | | Relational DBMS | Storage.PaaS.RelationalDbms | - | - | | Control Database | Storage.PaaS.RelationalDatabase | Relational DBMS | - | | Tenant Database (Pooled) | Storage.PaaS.RelationalDatabase | Relational DBMS | - | | Tenant Database (Dedicated) | Storage.PaaS.RelationalDatabase | Relational DBMS | - | | Key-Value DBMS | Storage.PaaS.KeyValueDbms | - | - | | Tenant Config Cache | Storage.PaaS.KeyValueEntity | Key-Value DBMS | - | | Quota Counters | Storage.PaaS.KeyValueEntity | Key-Value DBMS | - | | Messaging Platform | Messaging.PaaS.Broker | - | - | | Provisioning Queue | Messaging.PaaS.Entity | Messaging Platform | - | | Provisioning Dead Letter Queue | Messaging.PaaS.Entity | Messaging Platform | - | | Usage Topic | Messaging.PaaS.Entity | Messaging Platform | - | | Export Store | Storage.PaaS.FilesAndBlobs | - | - | | Observability Logging | Observability.CaaS.Logging | Container Platform | - | | Observability Monitoring | Observability.CaaS.Monitoring | Container Platform | - |

When to Use It

• A product sold to multiple organizations from one deployment.
• Any case where a customer will eventually ask for isolation, its own region, or its data back.

When Not to Use It

• Internal tools with one organization.
• Products where every customer already gets a fully separate deployment. The pooling machinery has no job there.