Architecting SaaS: Multi-Tenancy in Laravel 🏢

The SaaS Scaling Dilemma

When you transition from building internal company tools to building a Software-as-a-Service (SaaS) platform, the fundamental architecture of your database must evolve. In a standard application, every user accesses the same overarching dataset. However, in a B2B Enterprise SaaS application, you are onboarding entire organizations. Organization A (Tenant A) must never, under any circumstances, see the data belonging to Organization B (Tenant B). A data leak across tenant boundaries is the fastest way to destroy a SaaS company's reputation.

This architectural challenge is known as Multi-Tenancy. There are generally two ways to solve this: a Multi-Database approach (where every tenant gets a physically separate database) or a Single-Database approach (where all tenants share tables, but rows are strictly filtered by a `tenant_id`). While the Multi-Database approach offers ultimate isolation, it creates an infrastructure nightmare when you need to run migrations across 5,000 separate databases.

At Smart Tech Devs, for the vast majority of our enterprise SaaS builds, we utilize a Single-Database Multi-Tenancy Architecture. By leveraging Laravel's powerful Global Scopes and Middleware, we can create a system where data isolation is enforced automatically at the ORM layer, preventing developers from ever accidentally writing a query that leaks data.

Understanding the Architecture

The goal of our architecture is invisibility. The developer writing a controller should not have to remember to append ->where('tenant_id', currentTenantId()) to every single database query. If we rely on human memory, someone will eventually forget, and a catastrophic data breach will occur.

Instead, we intercept the request at the perimeter, identify the tenant from the URL or headers, and then instruct Laravel's Eloquent ORM to automatically append this filter to all queries globally.

Step 1: Identifying the Tenant (Middleware)

First, we need to know who is making the request. In a modern SaaS, this is often done via subdomains (e.g., companyA.smarttechdevs.in) or via an API header. For this example, we will intercept the request using a custom Middleware, identify the Tenant, and bind it to Laravel's Service Container so it can be accessed anywhere.

namespace App\Http\Middleware;

use Closure;
use App\Models\Tenant;
use Illuminate\Http\Request;
use Symfony\Component\HttpFoundation\Response;

class IdentifyTenant
{
    public function handle(Request $request, Closure $next): Response
    {
        // Example: Identifying tenant by a custom HTTP Header
        $tenantId = $request->header('X-Tenant-ID');

        if (! $tenantId) {
            return response()->json(['error' => 'Tenant identification missing.'], 400);
        }

        $tenant = Tenant::findOrFail($tenantId);

        // Bind the active tenant into the Service Container
        app()->instance('currentTenant', $tenant);

        return $next($request);
    }
}

Step 2: Enforcing Isolation (Global Scopes)

Now that the application knows who the tenant is, we must force Eloquent to respect this boundary. We achieve this using a Global Scope. A Global Scope allows us to add constraints to all queries for a given model automatically.

namespace App\Models\Scopes;

use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Scope;

class TenantScope implements Scope
{
    public function apply(Builder $builder, Model $model)
    {
        // If we are in the console (e.g., running migrations) or if no tenant is set, 
        // we might want to skip this, but in production web requests, enforce it strictly.
        if (app()->has('currentTenant')) {
            $tenant = app('currentTenant');
            $builder->where($model->getTable() . '.tenant_id', $tenant->id);
        }
    }
}

Step 3: Creating a Reusable Trait

To easily apply this scope and ensure that newly created records automatically receive the correct tenant_id, we create a Trait that we can attach to any model that belongs to a tenant (like Invoice, Employee, or Project).

namespace App\Traits;

use App\Models\Scopes\TenantScope;

trait BelongsToTenant
{
    protected static function bootBelongsToTenant()
    {
        // 1. Automatically apply the Global Scope to all read queries
        static::addGlobalScope(new TenantScope);

        // 2. Automatically inject the tenant_id on creation (Write queries)
        static::creating(function ($model) {
            if (app()->has('currentTenant')) {
                $model->tenant_id = app('currentTenant')->id;
            }
        });
    }
}

Now, our models remain incredibly clean. We simply add the trait:

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Traits\BelongsToTenant;

class Invoice extends Model
{
    use BelongsToTenant;
    
    protected $fillable = ['amount', 'due_date', 'status']; // No need to make tenant_id fillable!
}

Step 4: The Developer Experience

With this architecture in place, the developer experience becomes flawless and secure. Inside a controller, if a developer writes:

$invoices = Invoice::all();

Laravel will automatically execute the following SQL query behind the scenes:

SELECT * FROM invoices WHERE tenant_id = 5;

Similarly, when creating a record:

Invoice::create(['amount' => 500, 'status' => 'unpaid']);

The system will automatically insert 5 into the tenant_id column without the developer ever needing to specify it.

Advanced Considerations: The Queue Worker Trap

The most common pitfall in Single-Database Multi-Tenancy occurs with Background Jobs. When you dispatch an event to a Redis Queue, the HTTP Request dies. When the Queue Worker picks up the job, there is no HTTP Header, no URL subdomain, and therefore, no Tenant in the Service Container! If your job tries to query an Invoice, it will fail or query the wrong data.

To solve this, your Job classes must explicitly serialize the tenant_id when they are dispatched. When the job is processed by the worker, the first line of the handle() method must manually re-bind the Tenant back into the Service Container before executing any Eloquent queries. This ensures that the global scopes continue to function securely even in asynchronous, background-processed environments.

The Engineering ROI

By implementing Multi-Tenancy at the architectural level rather than the application logic level, you completely eliminate an entire class of security vulnerabilities. Your codebase remains DRY (Don't Repeat Yourself), your controllers remain thin, and your engineering team can build features rapidly without the constant anxiety of accidentally exposing sensitive enterprise data across organizational boundaries.