# archtechx/tenancy architecture

> Architecture diagram of the GitHub repository archtechx/tenancy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/archtechx/tenancy
- Repository: https://github.com/archtechx/tenancy

## Overview

stancl/tenancy is a Laravel package that identifies a tenant for an incoming request, initializes tenant context, and scopes framework services and data to that tenant. Tenant lifecycle operations also manage tenant databases, migrations, domains, and storage; optional capabilities include PostgreSQL row-level security, resource syncing, impersonation, and tenant asset serving. The graph follows documented capabilities and the supplied excerpts; several subsystem connections are based on the README and tree rather than sampled implementation.

Main entry points: [`src/Bootstrappers`](https://github.com/archtechx/tenancy/tree/master/src/Bootstrappers) (Context bootstrappers), [`src/Database/DatabaseManager.php`](https://github.com/archtechx/tenancy/blob/master/src/Database/DatabaseManager.php) (Tenant DB manager), [`src/Tenancy.php`](https://github.com/archtechx/tenancy/blob/master/src/Tenancy.php) (Tenancy coordinator), [`src/Middleware/IdentificationMiddleware.php`](https://github.com/archtechx/tenancy/blob/master/src/Middleware/IdentificationMiddleware.php) (Identification middleware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identification["Tenant identification"]
  node_identification_middleware["Identification middleware"]
  node_tenant_resolvers["Tenant resolvers"]
  node_tenant_domain["Tenant and domains<br/>[Tenant.php]"]
end

subgraph group_context["Tenancy context"]
  node_tenancy_core["Tenancy coordinator<br/>[Tenancy.php]"]
  node_service_provider["Laravel integration"]
  node_bootstrapper_set["Context bootstrappers"]
  node_scoped_services["Scoped framework services"]
  node_db_session["Tenant sessions"]
end

subgraph group_data["Tenant data"]
  node_database_bootstrapper["Database tenancy"]
  node_database_manager["Tenant DB manager"]
  node_tenant_db_drivers["Database drivers"]
  node_central_db[("Central database")]
  node_tenant_db[("Tenant databases")]
end

subgraph group_operations["Lifecycle operations"]
  node_lifecycle_commands["Tenant commands"]
  node_lifecycle_jobs["Lifecycle jobs"]
  node_storage_actions["Storage actions"]
  node_tenant_storage["Tenant storage"]
end

subgraph group_capabilities["Tenant capabilities"]
  node_rls["Postgres RLS"]
  node_resource_sync["Resource syncing"]
  node_features["Optional features"]
  node_asset_controller["Tenant asset delivery"]
end

node_request(("Application request"))

node_request -->|"enters"| node_identification_middleware
node_identification_middleware -->|"resolves tenant"| node_tenant_resolvers
node_tenant_resolvers -->|"finds tenant"| node_tenant_domain
node_tenant_domain -->|"reads tenant records"| node_central_db
node_identification_middleware -->|"initializes context"| node_tenancy_core
node_service_provider -->|"registers"| node_tenancy_core
node_tenancy_core -->|"runs bootstrap"| node_bootstrapper_set
node_bootstrapper_set -->|"includes"| node_database_bootstrapper
node_database_bootstrapper -->|"switches connection"| node_database_manager
node_database_manager -->|"reads database config"| node_tenant_domain
node_database_manager -->|"selects driver"| node_tenant_db_drivers
node_tenant_db_drivers -->|"creates and manages"| node_tenant_db
node_database_manager -->|"connects tenant"| node_tenant_db
node_bootstrapper_set -->|"reconfigures services"| node_scoped_services
node_bootstrapper_set -->|"reconfigures sessions"| node_db_session
node_db_session -->|"uses connection"| node_tenant_db
node_lifecycle_commands -->|"dispatches operations"| node_lifecycle_jobs
node_lifecycle_jobs -->|"manages databases"| node_tenant_db_drivers
node_lifecycle_jobs -->|"runs storage actions"| node_storage_actions
node_storage_actions -->|"creates or removes links"| node_tenant_storage
node_tenant_storage -.-> node_tenant_db
node_rls -.->|"generates policies"| node_tenant_db
node_resource_sync -.->|"syncs resources"| node_tenant_db
node_features -.->|"extends behavior"| node_tenancy_core
node_request -.->|"requests tenant asset"| node_asset_controller
node_asset_controller -->|"reads tenant files"| node_tenant_storage

click node_identification_middleware "https://github.com/archtechx/tenancy/blob/master/src/Middleware/IdentificationMiddleware.php"
click node_tenant_resolvers "https://github.com/archtechx/tenancy/tree/master/src/Resolvers"
click node_tenant_domain "https://github.com/archtechx/tenancy/blob/master/src/Database/Models/Tenant.php"
click node_tenancy_core "https://github.com/archtechx/tenancy/blob/master/src/Tenancy.php"
click node_service_provider "https://github.com/archtechx/tenancy/blob/master/src/TenancyServiceProvider.php"
click node_bootstrapper_set "https://github.com/archtechx/tenancy/tree/master/src/Bootstrappers"
click node_database_bootstrapper "https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/DatabaseTenancyBootstrapper.php"
click node_database_manager "https://github.com/archtechx/tenancy/blob/master/src/Database/DatabaseManager.php"
click node_tenant_db_drivers "https://github.com/archtechx/tenancy/tree/master/src/Database/TenantDatabaseManagers"
click node_scoped_services "https://github.com/archtechx/tenancy/tree/master/src/Bootstrappers"
click node_db_session "https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/DatabaseSessionBootstrapper.php"
click node_lifecycle_commands "https://github.com/archtechx/tenancy/tree/master/src/Commands"
click node_lifecycle_jobs "https://github.com/archtechx/tenancy/tree/master/src/Jobs"
click node_storage_actions "https://github.com/archtechx/tenancy/tree/master/src/Actions"
click node_tenant_storage "https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/FilesystemTenancyBootstrapper.php"
click node_rls "https://github.com/archtechx/tenancy/tree/master/src/RLS"
click node_resource_sync "https://github.com/archtechx/tenancy/tree/master/src/ResourceSyncing"
click node_features "https://github.com/archtechx/tenancy/tree/master/src/Features"
click node_asset_controller "https://github.com/archtechx/tenancy/blob/master/src/Controllers/TenantAssetController.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_identification_middleware,node_tenant_resolvers,node_tenant_domain toneBlue
class node_tenancy_core,node_service_provider,node_bootstrapper_set,node_scoped_services,node_db_session toneAmber
class node_database_bootstrapper,node_database_manager,node_tenant_db_drivers,node_central_db,node_tenant_db,node_request toneMint
class node_lifecycle_commands,node_lifecycle_jobs,node_storage_actions,node_tenant_storage toneRose
class node_rls,node_resource_sync,node_features,node_asset_controller toneIndigo
```

## Components

### Tenant identification

- [Identification middleware](https://github.com/archtechx/tenancy/blob/master/src/Middleware/IdentificationMiddleware.php): `src/Middleware/IdentificationMiddleware.php`
- [Tenant resolvers](https://github.com/archtechx/tenancy/tree/master/src/Resolvers): `src/Resolvers`
- [Tenant and domains](https://github.com/archtechx/tenancy/blob/master/src/Database/Models/Tenant.php): `src/Database/Models/Tenant.php`

### Tenancy context

- [Tenancy coordinator](https://github.com/archtechx/tenancy/blob/master/src/Tenancy.php): `src/Tenancy.php`
- [Laravel integration](https://github.com/archtechx/tenancy/blob/master/src/TenancyServiceProvider.php): `src/TenancyServiceProvider.php`
- [Context bootstrappers](https://github.com/archtechx/tenancy/tree/master/src/Bootstrappers): `src/Bootstrappers`
- [Scoped framework services](https://github.com/archtechx/tenancy/tree/master/src/Bootstrappers): `src/Bootstrappers`
- [Tenant sessions](https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/DatabaseSessionBootstrapper.php): `src/Bootstrappers/DatabaseSessionBootstrapper.php`

### Tenant data

- [Database tenancy](https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/DatabaseTenancyBootstrapper.php): `src/Bootstrappers/DatabaseTenancyBootstrapper.php`
- [Tenant DB manager](https://github.com/archtechx/tenancy/blob/master/src/Database/DatabaseManager.php): `src/Database/DatabaseManager.php`
- [Database drivers](https://github.com/archtechx/tenancy/tree/master/src/Database/TenantDatabaseManagers): `src/Database/TenantDatabaseManagers`
- **Central database**
- **Tenant databases**

### Lifecycle operations

- [Tenant commands](https://github.com/archtechx/tenancy/tree/master/src/Commands): `src/Commands`
- [Lifecycle jobs](https://github.com/archtechx/tenancy/tree/master/src/Jobs): `src/Jobs`
- [Storage actions](https://github.com/archtechx/tenancy/tree/master/src/Actions): `src/Actions`
- [Tenant storage](https://github.com/archtechx/tenancy/blob/master/src/Bootstrappers/FilesystemTenancyBootstrapper.php): `src/Bootstrappers/FilesystemTenancyBootstrapper.php`

### Tenant capabilities

- [Postgres RLS](https://github.com/archtechx/tenancy/tree/master/src/RLS): `src/RLS`
- [Resource syncing](https://github.com/archtechx/tenancy/tree/master/src/ResourceSyncing): `src/ResourceSyncing`
- [Optional features](https://github.com/archtechx/tenancy/tree/master/src/Features): `src/Features`
- [Tenant asset delivery](https://github.com/archtechx/tenancy/blob/master/src/Controllers/TenantAssetController.php): `src/Controllers/TenantAssetController.php`

### Other components

- **Application request**

## Connections

- Application request → Identification middleware: enters
- Identification middleware → Tenant resolvers: resolves tenant
- Tenant resolvers → Tenant and domains: finds tenant
- Tenant and domains → Central database: reads tenant records
- Identification middleware → Tenancy coordinator: initializes context
- Laravel integration → Tenancy coordinator: registers
- Tenancy coordinator → Context bootstrappers: runs bootstrap
- Context bootstrappers → Database tenancy: includes
- Database tenancy → Tenant DB manager: switches connection
- Tenant DB manager → Tenant and domains: reads database config
- Tenant DB manager → Database drivers: selects driver
- Database drivers → Tenant databases: creates and manages
- Tenant DB manager → Tenant databases: connects tenant
- Context bootstrappers → Scoped framework services: reconfigures services
- Context bootstrappers → Tenant sessions: reconfigures sessions
- Tenant sessions → Tenant databases: uses connection
- Tenant commands → Lifecycle jobs: dispatches operations
- Lifecycle jobs → Database drivers: manages databases
- Lifecycle jobs → Storage actions: runs storage actions
- Storage actions → Tenant storage: creates or removes links
- Tenant storage → Tenant databases
- Postgres RLS → Tenant databases: generates policies
- Resource syncing → Tenant databases: syncs resources
- Optional features → Tenancy coordinator: extends behavior
- Application request → Tenant asset delivery: requests tenant asset
- Tenant asset delivery → Tenant storage: reads tenant files