A practical architecture checklist for multi-tenant SaaS

Make tenancy explicit

Every request should resolve an authenticated user and an active tenant before business data is queried. Tenant identifiers belong in the schema, indexes, cache keys, object-storage paths, audit records, and background jobs. Relying on a UI selection or a developer remembering an extra filter is too fragile.

Database-level controls can add defense in depth, but they do not replace application tests. Write tests that attempt cross-tenant reads and mutations through every sensitive endpoint.

Separate roles from subscription entitlements

Roles answer what a person may do inside an organization. Entitlements answer what the organization has purchased. Mixing these concepts produces confusing permission code and makes plan changes risky.

Keep billing webhooks idempotent. Store the provider event identifier, process each event once, and reconcile subscription state periodically. A delayed webhook should not lock a legitimate customer out without a recovery path.

• Tenant-scoped unique constraints prevent accidental collisions.
• Audit membership and permission changes.
• Rate-limit expensive operations by tenant, not only by IP.
• Test upgrades, downgrades, failed payments, and cancellation.

Design background work for retries

Email, imports, exports, reports, and third-party synchronization should not keep an HTTP request open. Put durable work on a queue and assume it can run more than once. An idempotency key and a recorded status make retries safe and support investigations.

Expose progress for long operations. Users are more tolerant of a slow export when the product acknowledges it and sends a completion notice than when a browser spinner eventually disappears.

Observe the customer experience

Infrastructure metrics are necessary, but they do not explain which tenant cannot complete a task. Structured logs should include a request identifier, tenant identifier, operation, duration, and outcome without exposing secrets or personal data. Pair those logs with product-level measures such as activation and job completion.