Multi-tenant SaaS architecture in Laravel is not complete when every business table has a tenant_id. Isolation is an end-to-end property spanning tenant resolution, authorization, queries, queues, cache, files, search, logs, exports, support access, and deletion. Any path that loses context can expose or mutate another customer’s data. The architecture should therefore begin with tenant boundaries and a threat model, then select database and framework mechanisms that reinforce those boundaries.
Define the tenant precisely
A tenant might be a company, legal entity, workspace, or branch. A user may belong to one tenant or several. Write down what is tenant-owned, what is genuinely global, how membership changes, and whether a parent organisation can view subsidiaries. Ambiguous language becomes ambiguous code, especially around reports and administration.
Separate tenant identification from authorization. Resolving workspace A does not prove that the authenticated user may view invoice X inside A. Laravel policies or equivalent application rules still need to authorize the action and resource. Never accept a tenant identifier from a request body as the sole source of context.
Choose a database model from constraints
A shared PostgreSQL schema stores tenants in the same tables and scopes rows by a tenant key. It can simplify migrations and operations for many products, but it makes query discipline and defence in depth critical. A database-per-tenant model strengthens some operational boundaries and can simplify individual restoration, while multiplying connections, migrations, monitoring targets, and backups. Hybrid approaches can isolate selected tenants or workloads.
Evaluate regulatory obligations, expected data size, cross-tenant reporting, restoration requirements, scaling patterns, and the team’s operational capacity. A database-per-tenant design is not safer if the team cannot patch and monitor every database consistently. A shared schema is not economical if weak isolation creates unacceptable risk.
Establish trusted context early
Resolve the tenant from a trusted domain, route, token claim, or verified membership and create an explicit context object before business logic runs. Reject missing context on tenant-required paths. Silent default tenants turn mistakes into data access. Keep global administration separate and highly visible rather than casually disabling a global scope.
Long-lived PHP workers and tests need careful cleanup. Clear tenant context at the end of every request and job so state cannot survive into the next unit of work. Treat context setup and teardown as infrastructure with automated tests, not a convention developers must remember.
Enforce isolation at several layers
An Eloquent global scope reduces accidental omissions, but it cannot cover every raw query, join, aggregate, import, or upsert automatically. Review escape hatches and require an explicit reason for unscoped operations. Use policies for resource authorization and use cases or repositories that receive tenant context where that makes dependencies clearer.
PostgreSQL Row Level Security can provide valuable defence in depth. It must be configured with correct policies, connection roles, session variables, and transaction behaviour. Test the role used by the application; a policy existing in the schema does not prove every runtime role is constrained as intended.
Carry context into queues
A queued job runs after the request context has disappeared. Include a trusted tenant identifier in the job payload, reconstruct context at the beginning of handling, verify relevant membership or resource state when needed, and clear context in a finally path. Avoid serializing a large model graph and assuming later relationships will scope themselves.
Retries must remain idempotent and tenant-safe. Monitor failed jobs by an internal tenant reference without placing sensitive names in queue metadata. A stale worker context should never determine the tenant.
Namespace cache and locks
Every cache key, tag, lock, rate limit, and feature flag that represents tenant data needs a tenant namespace. A missing prefix can expose one tenant’s result to another even when the database query is correct. Centralise key generation instead of relying on string concatenation throughout the codebase.
Invalidation must use the same namespace discipline. Test both cache hits and misses across multiple tenants. Consider what happens when a tenant is renamed or moved; stable internal identifiers are usually safer than mutable slugs.
Isolate files, search, and real-time channels
Object paths, signed downloads, generated exports, search indexes, websocket channels, notification destinations, and analytics events all carry tenant context. A storage path alone is not authorization; verify access before issuing a signed URL. Search filters should be mandatory and tested against direct identifiers.
Create an inventory of external stores and processors: Redis, object storage, search, monitoring, email providers, and data warehouses. Document what tenant information each receives, how access is scoped, and how export or deletion propagates.
Design onboarding as a recoverable process
Tenant creation can include account verification, owner membership, defaults, plan assignment, provider setup, and seed data. Orchestrate these steps with explicit state and idempotency. If one step fails, operations should know what completed and whether to resume or compensate. A single large transaction cannot protect external side effects.
Provisioning should not make the new tenant visible as ready before required controls exist. Consider a state machine such as pending, provisioning, active, suspended, and closing, with authorization rules for each.
Make tenant switching explicit
Users who belong to several tenants need a secure switch flow. Revalidate membership on every switch, rotate or update the trusted context, clear tenant-specific client state, and reload permissions. Do not trust a value left in local storage without server verification. The interface should make the current tenant unmistakable before destructive actions.
Support access deserves a separate, audited mechanism. Use time-limited impersonation or delegated access with a reason, approver where needed, visible indicator, and automatic expiry. Never ask staff to share customer credentials.
Protect neighbours from expensive work
One tenant can create large exports, heavy imports, inefficient reports, or high API traffic. Use fair limits, job queues, concurrency controls, and plan-aware quotas where appropriate. Attribute latency, errors, queue depth, and resource consumption to a non-sensitive internal tenant identifier.
Design heavy operations as cancellable background work with progress and bounded resource use. The aim is not to penalise active customers; it is to prevent one workload from degrading every other tenant and to make capacity planning evidence-based.
Plan schema changes for the tenancy model
In a shared schema, one migration affects everyone. Prefer expand-and-contract changes: add compatible structure, deploy code that handles old and new states, backfill in controlled batches, observe, then enforce constraints and remove obsolete fields. Measure lock behaviour on representative data before production.
With separate databases, maintain a version registry and a resumable migration coordinator. Track partial failure and tenants that lag behind. Running an artisan command in a loop without status, retries, and observability is not an operational migration strategy.
Build tenant-aware observability
Correlate requests, jobs, and failures with an internal tenant identifier while minimising sensitive log content. Do not record full request payloads by default. Dashboards should show latency, error rates, queue age, integration health, and limit consumption, with strict access to tenant detail.
Alerts should identify whether a problem is global, provider-specific, or limited to one tenant. That distinction speeds response and avoids unnecessary broad communication. Preserve audit evidence for privileged support actions.
Test isolation as a system invariant
Every important test suite should create at least two tenants and attempt cross-tenant reads, updates, deletes, associations, searches, downloads, and exports. Test guessed identifiers and direct URLs, not only normal navigation. Include queues, cache, files, realtime channels, bulk actions, and global admin tools.
Property-based cases or data-driven matrices can expand coverage, but human review remains necessary when new storage or integration paths appear. The Clean Architecture and DDD guide for Laravel shows how explicit use cases and boundaries keep tenancy rules out of ad hoc controllers.
Distinguish backup, restore, export, and deletion
Backups restore service. Tenant exports provide usable customer data. They are different deliverables. Test full restoration and document how an individual tenant would be recovered. In a shared schema, that may mean restoring to an isolated environment, extracting consistent tenant records, validating them, and applying a controlled repair—not replacing production wholesale.
Deletion must include relational data, files, search, queued work, and downstream processors according to policy. Be precise about backup retention: immediate removal from every protected backup may conflict with recovery design, so document retention and eventual expiry honestly.
Keep integrations tenant-scoped
Some providers use one platform account; others require credentials per tenant. Model ownership and secret rotation deliberately. A callback must resolve both provider event and tenant through trusted references before changing data. Never choose the tenant from an unsigned callback field.
Rate limits and provider failures may be global or tenant-specific. Preserve that distinction in retry and circuit-breaker behaviour. One tenant’s invalid credentials should not halt every customer’s queue.
Start with boundaries that can evolve
BarmajTek’s SaaS platform development service begins by mapping tenant ownership, identities, operations, and exit before committing to a schema. The Clinic Tek case study illustrates how product and isolation decisions can be described without inventing customer outcomes.
A new platform does not need every future scaling pattern on day one. It does need explicit boundaries, repeatable tests, operational recovery, and portable data. If tenant context is already scattered across controllers and jobs, request a tenant-isolation architecture review before adding another storage or integration path.
