# tarikulcodes/laravel-multi-tenant architecture

> Architecture diagram of the GitHub repository tarikulcodes/laravel-multi-tenant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tarikulcodes/laravel-multi-tenant
- Repository: https://github.com/tarikulcodes/laravel-multi-tenant

## Overview

##### Project type and purpose
- This is a demo multi-tenant SaaS application built with Laravel 10. It demonstrates how a single codebase can serve multiple tenant domains, isolating each tenant’s data while sharing the core infrastructure.

##### File structure
- Top-level folders follow the standard Laravel MVC layout:
- app/Http/Controllers (separated into App-scoped and global auth controllers)
- app/Models (User, Tenant)
- config/tenancy.php and a TenancyServiceProvider in app/Providers
- database/migrations (central and tenant directories)
- resources/views (Blade templates separated by scope: app, auth, tenants)
- routes (web.php, tenant.php, tenant-auth.php, api.php)
- Notice “database/migrations/tenant” vs “database/migrations” – indicates two logical databases.
- Vite, Tailwind, and Blade live in resources/js, resources/css, and resources/views.
- Jobs (SeedTenantJob) and queue config hint at background workers.

##### README
- Confirms Laravel 10, Blade, Vite JS, Tailwind CSS, Tenancy for Laravel, and Spatie Permission.
- Explains multi-tenant concept: one instance, multiple customers, isolated data.

##### Main components
a. Web Browser / Client
- Static assets (CSS/JS via Vite)
- HTTP(S) requests to tenant domains (e.g. tenant1.localhost) or main domain
b. Load Balancer or Reverse Proxy (optional for production)
c. Laravel Application Container
- Public/index.php → bootstrap/app.php → HTTP Kernel
- Middleware stack including tenancy identification (identify tenant from subdomain or path)
- Service Providers: TenancyServiceProvider, AuthServiceProvider, RouteServiceProvider
- Routing: web.php (central) vs tenant.php (tenant routes)
- Controllers: App-scoped vs global, Profile, TenantController
- Blade View Renderer & Vite asset pipeline
- Queue Worker (processes jobs like SeedTenantJob)
d. Databases
- Central Database: tenants table, domains table, user_global tables, permissions tables
- Tenant-specific Database(s): user, password_resets, personal_access_tokens, permission tables (scoped per tenant)
- Eloquent ORM manages connections based on tenancy context
e. Storage & Cache
- Filesystem (local/public) for uploads
- Cache & sessions (configured in config/cache.php and config/session.php)
- Queue backend (database or Redis)
f. External Services
- Mail (configured in config/mail.php)
- Broadcasting (Pusher, Redis, etc.)
- Third-party APIs or payment gateways (via config/services.php)

##### Relationships and data flow
- Client → (Load Balancer) → Web Server (Nginx/Apache) → index.php
- index.php loads the Laravel kernel → Middleware identifies tenant → Service Providers boot
- Router dispatches to either central or tenant route group → Controller logic
- Controllers interact with models → Eloquent sends queries to central or tenant DB
- Views rendered with Blade and assets injected via Vite → Response to client
- Jobs (e.g., Tenant Seeding) dispatched to queue → Queue Worker picks up job → writes to tenant DB
- File uploads go to storage/app/public, served via symbolic link to public/storage

##### Architectural patterns and design principles
- MVC (Model-View-Controller) for request handling
- Service Provider pattern for modular bootstrapping (especially tenancy)
- Middleware chain for cross-cutting concerns (auth, tenancy, CSRF)
- Repository/ORM (Eloquent) for data access
- Tenancy pattern: central vs tenant context, subdomain routing
- Command Bus/Queue for asynchronous processing

##### Technologies and frameworks to annotate
- Laravel 10 core
- Tenancy for Laravel (tenant resolution, multi-DB management)
- Spatie Laravel-Permission (role and permission management in both contexts)
- Blade templating (views/components)
- Vite JS + Tailwind CSS (asset bundling and styling)
- PHP-FPM, Nginx/Apache (deployment), MySQL/PostgreSQL

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Infrastructure
    LB["Load Balancer / Reverse Proxy"]:::infra
    WS["Web Server<br/>(Nginx/Apache)"]:::infra
    LB --> WS

    %% Client
    Client["Web Browser / Client<br/>- Static Assets"]:::infra
    Client --> WS

    %% Public Entry & Bootstrap
    WS --> Index
    subgraph "Public Entry & Bootstrap"
        direction TB
        Index["public/index.php"]:::core
        Bootstrap["bootstrap/app.php"]:::core
    end
    click Index "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/public/index.php"
    click Bootstrap "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/bootstrap/app.php"
    Index --> Bootstrap

    %% Laravel Application Container
    subgraph "Laravel Application Container" 
        direction TB
        Kernel["HTTP Kernel"]:::core

        subgraph "Middleware Stack" 
            direction TB
            AuthM["Authenticate"]:::core
            CsrfM["VerifyCsrfToken"]:::core
            ProxyM["TrustProxies"]:::core
            OtherM["Other Middleware"]:::core
        end
        click AuthM "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Middleware/Authenticate.php"
        click CsrfM "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Middleware/VerifyCsrfToken.php"
        click ProxyM "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Middleware/TrustProxies.php"
        click OtherM "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/app/Http/Middleware"
        
        subgraph "Service Providers"
            direction TB
            TenancySP["TenancyServiceProvider"]:::tenancy
            AuthSP["AuthServiceProvider"]:::core
            RouteSP["RouteServiceProvider"]:::core
            AppSP["AppServiceProvider"]:::core
            EventSP["EventServiceProvider"]:::core
            BroadcastSP["BroadcastServiceProvider"]:::core
        end
        click TenancySP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/TenancyServiceProvider.php"
        click AuthSP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/AuthServiceProvider.php"
        click RouteSP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/RouteServiceProvider.php"
        click AppSP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/AppServiceProvider.php"
        click EventSP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/EventServiceProvider.php"
        click BroadcastSP "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Providers/BroadcastServiceProvider.php"

        subgraph "Routing"
            direction TB
            CentralRoutes["routes/web.php"]:::core
            TenantRoutes["routes/tenant.php"]:::tenancy
            TenantAuthRoutes["routes/tenant-auth.php"]:::tenancy
            ApiRoutes["routes/api.php"]:::core
            AuthRoutes["routes/auth.php"]:::core
        end
        click CentralRoutes "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/routes/web.php"
        click TenantRoutes "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/routes/tenant.php"
        click TenantAuthRoutes "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/routes/tenant-auth.php"
        click ApiRoutes "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/routes/api.php"
        click AuthRoutes "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/routes/auth.php"

        subgraph "Controllers"
            direction TB
            ProfileCtrl["ProfileController"]:::core
            UserCtrl["UserController"]:::core
            AppAuthCtrls["App-scoped Auth Controllers"]:::core
            GlobalAuthCtrls["Global Auth Controllers"]:::core
            TenantCtrl["TenantController"]:::tenancy
        end
        click ProfileCtrl "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Controllers/App/ProfileController.php"
        click UserCtrl "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Controllers/App/UserController.php"
        click AppAuthCtrls "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/app/Http/Controllers/App/Auth"
        click GlobalAuthCtrls "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/app/Http/Controllers/Auth"
        click TenantCtrl "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Http/Controllers/TenantController.php"

        subgraph "Views & Assets"
            direction TB
            AppViews["resources/views/app"]:::core
            AuthViews["resources/views/auth"]:::core
            TenantViews["resources/views/tenants"]:::tenancy
            Layouts["resources/views/layouts"]:::core
            Components["resources/views/components"]:::core
            JSAsset["resources/js/app.js"]:::core
            CSSAsset["resources/css/app.css"]:::core
            ViteCfg["vite.config.js"]:::core
        end
        click AppViews "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/resources/views/app"
        click AuthViews "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/resources/views/auth"
        click TenantViews "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/resources/views/tenants"
        click Layouts "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/resources/views/layouts"
        click Components "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/resources/views/components"
        click JSAsset "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/resources/js/app.js"
        click CSSAsset "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/resources/css/app.css"
        click ViteCfg "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/vite.config.js"

        subgraph "Models & DB Context"
            direction TB
            TenantModel["Tenant Model"]:::tenancy
            UserModel["User Model"]:::core
            DBConfig["config/database.php"]:::core
        end
        click TenantModel "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Models/Tenant.php"
        click UserModel "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Models/User.php"
        click DBConfig "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/database.php"

        Kernel --> AuthM --> CsrfM --> ProxyM --> OtherM --> TenancySP --> Kernel
        Kernel --> RouteSP --> CentralRoutes
        Kernel --> RouteSP --> TenantRoutes
        CentralRoutes --> ProfileCtrl
        TenantRoutes --> TenantCtrl
        AuthRoutes --> GlobalAuthCtrls
        ProfileCtrl --> UserModel
        TenantCtrl --> TenantModel
        UserModel --> DBConfig
    end

    %% Databases
    subgraph "Databases"
        direction TB
        CentralDB["Central Database"]:::db
        TenantDB["Tenant Databases"]:::db
    end
    click CentralDB "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/database/migrations"
    click TenantDB "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/database/migrations/tenant"
    DBConfig --> CentralDB
    DBConfig --> TenantDB

    %% Queue & Jobs
    subgraph "Queue & Background Jobs"
        direction TB
        QueueCfg["config/queue.php"]:::core
        SeedJob["SeedTenantJob"]:::tenancy
        Worker["Queue Worker"]:::core
    end
    click QueueCfg "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/queue.php"
    click SeedJob "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/app/Jobs/SeedTenantJob.php"
    QueueCfg --> Worker
    ProfileCtrl -->|"dispatch job"| SeedJob
    SeedJob --> TenantDB
    Worker --> SeedJob

    %% Storage & Cache
    subgraph "Storage & Cache"
        direction TB
        FSConfig["config/filesystems.php"]:::core
        CacheCfg["config/cache.php"]:::core
        SessionCfg["config/session.php"]:::core
        Uploads["storage/app/public"]:::core
        CacheStore["storage/framework/cache"]:::core
    end
    click FSConfig "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/filesystems.php"
    click CacheCfg "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/cache.php"
    click SessionCfg "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/session.php"
    click Uploads "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/storage/app/public"
    click CacheStore "https://github.com/tarikulcodes/laravel-multi-tenant/tree/main/storage/framework/cache"
    ProfileCtrl -->|"store files"| Uploads
    ProfileCtrl -->|"cache"| CacheStore

    %% External Services
    subgraph "External Services"
        direction TB
        Mail["Mail Service"]:::external
        Broadcast["Broadcasting Service"]:::external
        ThirdParty["Third-party APIs"]:::external
    end
    click Mail "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/mail.php"
    click Broadcast "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/broadcasting.php"
    click ThirdParty "https://github.com/tarikulcodes/laravel-multi-tenant/blob/main/config/services.php"
    ProfileCtrl --> Mail
    ProfileCtrl --> Broadcast
    ProfileCtrl --> ThirdParty

    %% Styles
    classDef infra fill:#dddddd,stroke:#888888,color:#333333
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef tenancy fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef db fill:#f0f0f0,stroke:#666666,color:#333333,nodeShape:roundCylinder
```
