Architecture for Serving Multiple Clients from One Codebase

The Core Constraint

The fundamental challenge of multi-tenancy isn't technical complexity. It's preventing data leakage while maintaining development velocity. Every query, every cache key, every background job, every file upload must be scoped to the correct tenant. Miss one, and you've created a security incident.

The naive approach is to add WHERE tenant_id = ? to every query manually. This works until someone forgets. In a codebase with hundreds of queries across dozens of models, the probability of missing a scope approaches certainty. And the failure mode is silent: the wrong data gets returned, the wrong records get updated, and you don't know until a customer notices they're seeing someone else's orders.

Multi-Tenancy Approaches

Three patterns dominate. Each trades off isolation, operational complexity, and development velocity differently.

The rest of this page focuses on the shared-database approach. The principles apply to other approaches, but the implementation details differ.

Tenant Identification Strategies

Before you can scope queries, you need to know which tenant the request is for. Four strategies dominate, each with different tradeoffs for user experience, infrastructure complexity, and flexibility.

Most applications start with subdomain identification and add custom domain support later if customers demand it. Start simple; add complexity when it's paid for.

Setting Tenant Context

Once you've identified the tenant from the request, you need to make that context available throughout the request lifecycle. The pattern is straightforward: resolve early in the middleware stack, store in a singleton, access everywhere.

The Tenant Context Singleton

A simple class holds the current tenant and provides static access throughout the application:

class TenantContext
{
    private static ?Tenant $current = null;

    public static function set(Tenant $tenant): void
    {
        static::$current = $tenant;
    }

    public static function get(): ?Tenant
    {
        return static::$current;
    }

    public static function id(): ?int
    {
        return static::$current?->id;
    }

    public static function reset(): void
    {
        static::$current = null;
    }
}

For applications using Laravel's container more heavily, you can bind the tenant as a scoped singleton instead of using static state. The static approach is simpler for most use cases and explicit about its global nature.

Tenant Resolution Middleware

Middleware runs early in the stack to resolve and set the tenant context:

class ResolveTenant
{
    public function handle(Request $request, Closure $next)
    {
        $subdomain = explode('.', $request->getHost())[0];

        $tenant = Tenant::where('subdomain', $subdomain)->first();

        if (! $tenant) {
            abort(404, 'Tenant not found');
        }

        if (! $tenant->is_active) {
            abort(403, 'Account suspended');
        }

        TenantContext::set($tenant);

        return $next($request);
    }

    public function terminate(Request $request, $response)
    {
        TenantContext::reset();
    }
}

Key points: fail fast if the tenant doesn't exist or is inactive. Check account status here rather than scattering status checks throughout the application. Reset context in terminate() to prevent state leakage in long-running processes (Octane, queue workers with --once).

Caching Tenant Lookups

Tenant resolution happens on every request. For high-traffic applications, cache the lookup:

$tenant = Cache::remember(
    "tenant:subdomain:{$subdomain}",
    now()->addMinutes(5),
    fn () => Tenant::where('subdomain', $subdomain)->first()
);

// Bust cache when tenant is updated
Tenant::updated(function (Tenant $tenant) {
    Cache::forget("tenant:subdomain:{$tenant->subdomain}");
});

Keep the TTL short (5-10 minutes). Tenant records change infrequently, but when they do (suspension, plan change, subdomain rename), you want changes to propagate quickly.

Database Isolation with Global Scopes

This is where multi-tenancy succeeds or fails. Every tenant-scoped model needs to automatically filter queries by the current tenant and automatically set tenant_id on creation. Eloquent global scopes make this automatic.

The Tenant Scope

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model): void
    {
        if (TenantContext::id()) {
            $builder->where($model->getTable() . '.tenant_id', TenantContext::id());
        }
    }
}

Note the table prefix on the column name. Without it, queries with joins will fail with ambiguous column errors. This is an easy thing to miss in early development and catch in production when someone adds a join.

The BelongsToTenant Trait

A trait applies the scope and handles automatic tenant assignment:

trait BelongsToTenant
{
    public static function bootBelongsToTenant(): void
    {
        static::addGlobalScope(new TenantScope());

        static::creating(function (Model $model) {
            if (! $model->tenant_id && TenantContext::id()) {
                $model->tenant_id = TenantContext::id();
            }
        });
    }

    public function tenant(): BelongsTo
    {
        return $this->belongsTo(Tenant::class);
    }
}

Apply this trait to every tenant-scoped model. The creating callback ensures new records are assigned to the current tenant automatically. The guard (if (! $model->tenant_id)) allows explicit assignment when needed (seeding, admin operations).

Which Models Get Scoped

Not every model belongs to a tenant. A typical split:

The rule: if the data belongs to a customer, it gets scoped. If it's reference data or system configuration, it doesn't.

Bypassing Tenant Scope

Sometimes you need to query across tenants: admin dashboards, cross-tenant reporting, scheduled tasks that process all tenants. Use withoutGlobalScope() explicitly:

// Admin: count orders across all tenants
$totalOrders = Order::withoutGlobalScope(TenantScope::class)->count();

// Process each tenant in a scheduled command
Tenant::each(function (Tenant $tenant) {
    TenantContext::set($tenant);

    // All queries now scoped to this tenant
    $this->processOrders($tenant);

    TenantContext::reset();
});

Queued Jobs and Background Processing

Background jobs run outside the HTTP request lifecycle. There's no middleware to resolve the tenant, no request context to read. Jobs must carry their tenant context explicitly. This extends the patterns we cover in background jobs, with tenant awareness as an additional requirement.

The Naive Approach Fails

The temptation is to assume TenantContext::get() will work in jobs. It won't. By the time the job executes (possibly minutes or hours later, possibly on a different server), the original request context is gone. Every query in the job runs without tenant scope, potentially accessing or modifying data across all tenants.

The Robust Pattern: Tenant-Aware Jobs

Serialize the tenant ID with the job and restore context before execution:

trait TenantAwareJob
{
    public int $tenantId;

    public function initializeTenantAwareJob(): void
    {
        if (TenantContext::id()) {
            $this->tenantId = TenantContext::id();
        }
    }

    public function setUpTenantContext(): void
    {
        $tenant = Tenant::findOrFail($this->tenantId);
        TenantContext::set($tenant);
    }

    public function tearDownTenantContext(): void
    {
        TenantContext::reset();
    }
}

In your job class:

class ProcessOrderJob implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
    use TenantAwareJob;

    public function __construct(public Order $order)
    {
        $this->initializeTenantAwareJob();
    }

    public function handle(): void
    {
        $this->setUpTenantContext();

        try {
            // All queries now scoped to the correct tenant
            $this->order->process();
        } finally {
            $this->tearDownTenantContext();
        }
    }
}

The finally block ensures context is reset even if the job fails, preventing state leakage when queue workers process multiple jobs.

Tenant-Specific Queues

For noisy neighbour isolation, route large tenants to dedicated queues:

class ProcessOrderJob implements ShouldQueue
{
    public function queue(): string
    {
        $tenant = Tenant::find($this->tenantId);

        return $tenant->dedicated_queue ?? 'default';
    }
}

Run separate workers for high-volume tenants. Their job backlogs won't affect other tenants' processing times.

Scheduled Tasks Across Tenants

Scheduled commands (daily reports, cleanup jobs, notification batches) often need to run for all tenants. The pattern: iterate tenants, set context, execute, reset.

class SendDailyReports extends Command
{
    protected $signature = 'reports:daily';

    public function handle(): void
    {
        Tenant::where('is_active', true)
            ->cursor()
            ->each(function (Tenant $tenant) {
                TenantContext::set($tenant);

                try {
                    $this->sendReportForTenant($tenant);
                } catch (Throwable $e) {
                    // Log but don't stop - other tenants still need processing
                    Log::error("Daily report failed for tenant {$tenant->id}", [
                        'exception' => $e->getMessage(),
                    ]);
                } finally {
                    TenantContext::reset();
                }
            });
    }

    private function sendReportForTenant(Tenant $tenant): void
    {
        // All queries automatically scoped to current tenant
        $orders = Order::whereDate('created_at', today())->get();
        // ...
    }
}

Key points: use cursor() for memory efficiency with many tenants. Catch exceptions per-tenant so one failure doesn't stop the batch. Log failures with tenant context for debugging.

Parallelising Tenant Processing

For computationally intensive tasks, dispatch a job per tenant instead of processing sequentially:

class DispatchDailyReports extends Command
{
    public function handle(): void
    {
        Tenant::where('is_active', true)
            ->pluck('id')
            ->each(fn ($id) => GenerateTenantReportJob::dispatch($id));
    }
}

Now each tenant's report generates in parallel across your queue workers. Add rate limiting if the downstream service (email provider, PDF generator) can't handle the burst.

Cross-Tenant Queries and Reporting

Admin dashboards and platform-level analytics need to query across tenants. This is where shared-database multi-tenancy shines: cross-tenant queries are just SQL, not a distributed data aggregation problem.

Platform Metrics

// Admin dashboard: aggregate metrics
$metrics = DB::table('orders')
    ->selectRaw('tenant_id, COUNT(*) as order_count, SUM(total) as revenue')
    ->whereDate('created_at', '>=', now()->subDays(30))
    ->groupBy('tenant_id')
    ->get();

// Join to get tenant names
$report = DB::table('orders')
    ->join('tenants', 'orders.tenant_id', '=', 'tenants.id')
    ->selectRaw('tenants.name, COUNT(orders.id) as orders, SUM(orders.total) as revenue')
    ->groupBy('tenants.id', 'tenants.name')
    ->orderByDesc('revenue')
    ->get();

These queries bypass Eloquent (and thus global scopes) intentionally. For platform-level reporting, raw queries are often clearer and more performant than Eloquent with withoutGlobalScope() scattered throughout.

Tenant Comparison Reports

SaaS platforms often want to show tenants how they compare to benchmarks:

// "Your conversion rate vs. platform average"
$platformAverage = Order::withoutGlobalScope(TenantScope::class)
    ->where('status', 'completed')
    ->count() / Order::withoutGlobalScope(TenantScope::class)->count();

$tenantRate = Order::where('status', 'completed')->count()
    / Order::count();

Anonymise carefully. Tenants shouldn't be able to identify competitors' specific metrics. Show percentiles, not raw numbers from other accounts.

Data Export for Business Intelligence

For platforms that feed data into external BI tools, consider a read replica with tenant scoping applied at the database level (row-level security in PostgreSQL) rather than relying on application-level scopes. This prevents BI tools with direct database access from accidentally querying across tenants.

Tenant Provisioning and Lifecycle

New tenants need more than a database record. Provisioning typically includes creating the tenant record, seeding default data, provisioning external resources, and notifying the tenant.

Provisioning Workflow

class ProvisionTenantJob implements ShouldQueue
{
    public function __construct(public Tenant $tenant) {}

    public function handle(): void
    {
        TenantContext::set($this->tenant);

        try {
            // Seed default data
            $this->createDefaultRoles();
            $this->createDefaultSettings();
            $this->createSampleData(); // Optional: demo data for trials

            // Provision external resources
            $this->createStripeCustomer();
            $this->provisionStorageBucket();
            $this->createSubdomain(); // If using external DNS

            // Mark as ready
            $this->tenant->update(['status' => 'active', 'provisioned_at' => now()]);

            // Notify
            $this->tenant->owner->notify(new TenantReady($this->tenant));

        } catch (Throwable $e) {
            $this->tenant->update(['status' => 'provisioning_failed']);
            throw $e;
        } finally {
            TenantContext::reset();
        }
    }
}

Tenant Lifecycle States

Each state affects what the tenant can do. Suspended tenants might have read-only access. Cancelled tenants might have a data export option but no operational access. State transitions should be audited.

Tenant Deletion and Data Retention

Deleting a tenant is rarely a simple $tenant->delete(). Consider data retention requirements (legal, contractual), related resource cleanup (Stripe subscriptions, storage buckets, DNS records), and soft deletion for recovery during a grace period.

class DeleteTenantJob implements ShouldQueue
{
    public function __construct(public Tenant $tenant) {}

    public function handle(): void
    {
        // Cancel external subscriptions
        $this->cancelStripeSubscription();

        // Schedule storage cleanup (after retention period)
        CleanupTenantStorageJob::dispatch($this->tenant)
            ->delay(now()->addDays(30));

        // Soft delete tenant and cascade
        $this->tenant->update(['deleted_at' => now(), 'status' => 'deleted']);

        // Hard delete after retention period
        PurgeTenantDataJob::dispatch($this->tenant->id)
            ->delay(now()->addDays(90));
    }
}

Tenant Customisation

Multi-tenant applications often need per-tenant customisation: configuration, branding, and feature access. The goal is flexibility without creating unmaintainable configuration sprawl.

Configuration Storage Patterns

Branding and White-Labelling

White-label applications need per-tenant visual identity: logo, colours, custom domain, email sender identity, and sometimes terminology changes.

// In a Blade layout


@if($tenant->logo_path)
    
@else
    {{ $tenant->name }}
@endif

For deeper customisation (terminology, content), consider a translation-style approach where tenants can override default strings.

Feature Tiers

Different subscription plans unlock different features. The cleanest pattern: tenants have a plan, plans have features, and a helper method checks access:

// On the Tenant model
public function hasFeature(string $feature): bool
{
    return $this->plan->features->contains('slug', $feature);
}

// In application code
if (TenantContext::get()->hasFeature('advanced-reporting')) {
    // Show advanced reports
}

// In Blade
@can('feature', 'advanced-reporting')
    Advanced Reports
@endcan

Cache the feature check. It's called frequently, and plan/feature relationships change rarely.

Security Considerations

Data isolation is the primary security concern, but multi-tenant applications have additional attack surfaces.

Preventing Data Leakage

URL Manipulation

Users might try changing IDs in URLs to access other records. Tenant scoping should prevent this, but add explicit validation for sensitive operations:

public function show(Order $order)
{
    // Route model binding already applies tenant scope, but be explicit:
    abort_unless($order->tenant_id === TenantContext::id(), 403);

    return view('orders.show', compact('order'));
}

File Storage Isolation

Uploaded files need the same isolation as database records. The pattern: tenant-prefixed paths, validation on access, signed URLs for downloads.

// Upload
$path = $file->store("tenants/{$tenant->id}/documents");

// Access validation in controller
public function download(Document $document)
{
    abort_unless($document->tenant_id === TenantContext::id(), 403);

    return Storage::download($document->path);
}

// Or use signed URLs with expiry
$url = Storage::temporaryUrl($document->path, now()->addMinutes(5));

For S3, consider separate buckets per tenant (maximum isolation) or bucket policies that restrict access by path prefix (simpler, less isolated). For PostgreSQL databases, Row-Level Security provides an additional layer of database-enforced tenant isolation.

Cache Key Isolation

A cache hit from the wrong tenant is a data breach. Prefix all cache keys with the tenant ID:

// Wrong: cache key collision risk
Cache::get('dashboard_stats');

// Right: tenant-scoped key
Cache::get("tenant:{$tenantId}:dashboard_stats");

// Or use a helper
function tenant_cache_key(string $key): string
{
    return "tenant:" . TenantContext::id() . ":{$key}";
}

Same principle applies to session data, rate limiting keys, and any other keyed storage.

Audit Logging

Log all cross-tenant access (admin operations, support access). Include who, when, what, and why. This connects to broader audit trail requirements, with cross-tenant access as particularly sensitive:

AuditLog::create([
    'actor_id' => auth()->id(),
    'actor_type' => 'admin',
    'tenant_id' => $tenant->id,
    'action' => 'viewed_orders',
    'reason' => $request->input('support_ticket_id'),
    'ip_address' => $request->ip(),
]);

Performance Isolation

In a shared-database architecture, one tenant's heavy usage can affect others. This is the "noisy neighbour" problem.

Database Performance

The tenant_id column should be indexed on every tenant-scoped table. For frequently-queried tables, it should be the first column in composite indexes:

// Good: tenant_id first, then commonly filtered columns
Schema::table('orders', function (Blueprint $table) {
    $table->index(['tenant_id', 'status', 'created_at']);
});

// Query optimiser can use the index for:
// - WHERE tenant_id = X
// - WHERE tenant_id = X AND status = Y
// - WHERE tenant_id = X AND status = Y AND created_at > Z

Monitor slow queries by tenant. If one tenant's data size causes performance issues, consider archiving old data, sharding their data to a separate database, or adding tenant-specific indexes.

Queue Isolation

High-volume tenants should have dedicated queues to prevent their job backlogs from blocking other tenants:

// In the tenant record
$tenant->dedicated_queue = 'tenant_123';

// Job routing
public function viaQueue(): string
{
    return Tenant::find($this->tenantId)->dedicated_queue ?? 'default';
}

// Run dedicated workers
php artisan queue:work --queue=tenant_123

Rate Limiting

Apply rate limits per tenant, not just per user. A tenant with 50 users hitting an endpoint simultaneously should be limited as an entity:

RateLimiter::for('api', function (Request $request) {
    return Limit::perMinute(1000)->by(TenantContext::id());
});

Resource Quotas

For storage, record counts, or compute usage, enforce quotas at the tenant level:

class Order extends Model
{
    protected static function booted()
    {
        static::creating(function (Order $order) {
            $tenant = TenantContext::get();
            $limit = $tenant->plan->order_limit;

            if ($limit && Order::count() >= $limit) {
                throw new QuotaExceededException('Order limit reached');
            }
        });
    }
}

Testing Multi-Tenant Applications

Multi-tenant applications need additional test coverage. The standard unit and feature tests aren't enough; you need tests that specifically verify tenant isolation.

Isolation Tests

public function test_tenant_cannot_access_other_tenant_orders()
{
    $tenantA = Tenant::factory()->create();
    $tenantB = Tenant::factory()->create();

    TenantContext::set($tenantA);
    $orderA = Order::factory()->create();

    TenantContext::set($tenantB);
    $orderB = Order::factory()->create();

    // Tenant B should only see their own orders
    $this->assertCount(1, Order::all());
    $this->assertTrue(Order::all()->contains($orderB));
    $this->assertFalse(Order::all()->contains($orderA));

    // Direct ID lookup should fail
    $this->assertNull(Order::find($orderA->id));
}

Test All Contexts

Tenant isolation must work in all execution contexts. Write tests that verify scoping in HTTP requests, queued jobs, console commands, and scheduled tasks:

public function test_queued_job_maintains_tenant_context()
{
    $tenant = Tenant::factory()->create();
    TenantContext::set($tenant);

    $order = Order::factory()->create();

    ProcessOrderJob::dispatch($order);

    // Process the job
    $this->artisan('queue:work', ['--once' => true]);

    // Verify the job ran in the correct tenant context
    $order->refresh();
    $this->assertEquals($tenant->id, $order->processed_by_tenant_id);
}

Fuzz Testing for Leakage

For critical applications, add fuzz tests that create many tenants with similar data and verify no cross-tenant leakage under various access patterns:

public function test_no_leakage_under_concurrent_access()
{
    $tenants = Tenant::factory()->count(10)->create();

    foreach ($tenants as $tenant) {
        TenantContext::set($tenant);
        Order::factory()->count(100)->create(['reference' => $tenant->id]);
    }

    foreach ($tenants as $tenant) {
        TenantContext::set($tenant);
        $orders = Order::all();

        foreach ($orders as $order) {
            $this->assertEquals(
                $tenant->id,
                $order->reference,
                "Found order from tenant {$order->reference} while querying as tenant {$tenant->id}"
            );
        }
    }
}

Packages and Custom Implementation

Laravel has several multi-tenancy packages. Evaluate them against your specific requirements before adopting.

We use custom implementations for most projects. The patterns are straightforward, the code is transparent, and we avoid dependency on packages that might change direction or become unmaintained. For projects requiring database-per-tenant isolation, we evaluate packages case by case.

What You Get

• ✓
  Complete isolation Tenants can never access each other's data. Verified by architectural patterns and explicit tests.
• ✓
  Simple operations One codebase to deploy and maintain. Schema changes apply once. One monitoring stack.
• ✓
  Per-tenant customisation Branding, features, configuration, and quotas per client. White-label ready.
• ✓
  Efficient scaling Add tenants without infrastructure complexity. Noisy neighbours contained with queue and rate limit isolation.
• ✓
  Cross-tenant insights Platform-level analytics without distributed data aggregation. Benchmark tenants against cohorts.
• ✓
  Tested thoroughly Isolation verified in HTTP requests, queued jobs, console commands, and scheduled tasks. Defence in depth.

SaaS infrastructure that scales with your customer base. The architecture you need for products that serve dozens, hundreds, or thousands of clients from a single deployment.