Complete Solution: Building a Multi-Tenant SaaS Application with Laravel and React

Last year, our team at a growing B2B platform faced a challenge that kept me up at night: we needed to transform our single-tenant application into a proper multi-tenant SaaS product. We had 12 enterprise clients, each demanding their own isolated environment, custom branding, and the ability to manage their own users. The kicker? We had eight weeks to ship it before our biggest client's contract renewal.

I'll be honest—my first attempt was a disaster. I thought I could just add a tenant_id column to every table and call it a day. Three weeks in, we discovered data leaking between tenants during a security audit. Our CTO, Maria, nearly had a heart attack. We had to scrap everything and start over with a proper architecture.

Here's what I learned building a production-ready multi-tenant SaaS application that now serves 50,000+ tenants across three continents. This isn't theory—these are battle-tested patterns from real production code, complete with the mistakes we made and how we fixed them.

The Multi-Tenancy Architecture Decision That Changed Everything

When we restarted the project, I spent two days researching every multi-tenancy pattern out there. The three main approaches are: single database with tenant discrimination (what I tried first), database per tenant, and schema per tenant. Each has massive trade-offs that nobody talks about in the tutorials.

Single database with shared schema seemed simple—just add tenant_id everywhere. But here's what the docs don't tell you: you'll spend months hunting down edge cases where queries forget the tenant scope. We had a developer named Jake who joined mid-project and wrote a report query that accidentally exposed data from all tenants. The bug made it to staging. That's when I realized this approach requires perfect discipline from every developer, forever. Not realistic.

Database per tenant gives you true isolation. Each tenant gets their own PostgreSQL database. Sounds perfect, right? Until you hit 1,000 tenants and realize you're managing 1,000 database connections. We tested this approach on AWS RDS and the connection overhead killed us. At 5,000 concurrent tenants, we were spending $8,000/month just on database instances. Plus, running migrations across 1,000 databases took 45 minutes.

Schema per tenant was our Goldilocks solution. One database, but each tenant gets their own PostgreSQL schema (namespace). Migrations run once per tenant but within the same connection pool. We can scale to 50,000 tenants on a single RDS instance. The catch? You need rock-solid schema switching logic and connection management.

Here's the production architecture we settled on:

// config/tenancy.php
return [
    'tenant_model' => \App\Models\Tenant::class,
    'id_generator' => \App\Support\TenantIdGenerator::class,
    
    'database' => [
        'based_on' => env('TENANCY_DATABASE_BASED_ON', 'postgresql'),
        'template_tenant_connection' => 'tenant_template',
        'prefix' => 'tenant',
        'suffix' => '',
    ],
    
    'redis' => [
        'prefix_base' => 'tenant',
        'prefixed_connections' => ['default'],
    ],
    
    'cache' => [
        'tag_base' => 'tenant',
    ],
    
    'filesystem' => [
        'suffix_base' => 'tenant',
        'disks' => ['local', 's3'],
        'root_override' => [
            's3' => '%storage_path%/app/public/',
        ],
    ],
    
    'routes' => [
        'web' => true,
        'api' => true,
    ],
    
    'migration_parameters' => [
        '--force' => true,
        '--path' => [database_path('migrations/tenant')],
        '--realpath' => true,
    ],
];

This config took us three iterations to get right. The migration_parameters section was crucial—we initially forgot --force and migrations would hang waiting for confirmation in production. Cost us two hours of downtime during a deployment.

Building the Tenant Model and Database Structure

The tenant model is the heart of your multi-tenancy setup. Here's our production model after six months of refinement:

// app/Models/Tenant.php
namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;
use Stancl\Tenancy\Contracts\TenantWithDatabase;
use Stancl\Tenancy\Database\Concerns\HasDatabase;
use Stancl\Tenancy\Database\Concerns\HasDomains;

class Tenant extends BaseTenant implements TenantWithDatabase
{
    use HasDatabase, HasDomains, HasUuids;

    protected $fillable = [
        'id',
        'name',
        'email',
        'plan',
        'trial_ends_at',
        'data',
    ];

    protected $casts = [
        'trial_ends_at' => 'datetime',
        'data' => 'array',
    ];

    public static function getCustomColumns(): array
    {
        return [
            'id',
            'name',
            'email',
            'plan',
            'trial_ends_at',
        ];
    }

    public function users()
    {
        return $this->hasMany(User::class);
    }

    public function isOnTrial(): bool
    {
        return $this->trial_ends_at && 
               $this->trial_ends_at->isFuture();
    }

    public function hasFeature(string $feature): bool
    {
        $features = config("plans.{$this->plan}.features", []);
        return in_array($feature, $features);
    }

    public function remainingTrialDays(): int
    {
        if (!$this->isOnTrial()) {
            return 0;
        }
        
        return now()->diffInDays($this->trial_ends_at);
    }

    // Custom method for tenant-specific configuration
    public function getConfig(string $key, $default = null)
    {
        return data_get($this->data, $key, $default);
    }

    public function setConfig(string $key, $value): void
    {
        $data = $this->data ?? [];
        data_set($data, $key, $value);
        $this->data = $data;
        $this->save();
    }
}

The data JSON column was a game-changer for us. Initially, we created new database columns for every tenant-specific setting. After the 15th column, I realized we needed a flexible approach. Now we store custom branding, feature flags, and integration credentials in that JSON field.