# ramyhakam/multi_tenancy_bundle architecture

> Architecture diagram of the GitHub repository ramyhakam/multi_tenancy_bundle, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ramyhakam/multi_tenancy_bundle
- Repository: https://github.com/ramyhakam/multi_tenancy_bundle

## Overview

##### Project Type & Purpose
- Type: Symfony Bundle (Library) for multi-tenant database support
- Purpose: Allow a Symfony app to manage multiple tenant databases under a single Doctrine setup; switch connections at runtime; provide custom Doctrine console commands for tenant DB management.

##### Major Architectural Components
A. Host Symfony Application
- HTTP Kernel
- Service Container (DI)
- Event Dispatcher
- Main Doctrine EntityManager (default EM)
B. HakamMultiTenancyBundle
1. DependencyInjection Layer
- HakamMultiTenancyExtension (reads `hakam_multi_tenancy.yaml`)
- Configuration classes → registers services in container via services.xml
2. Services
- DbConfigService (reads TenantDbConfig entity via main EM)
- DbService (creation, migration orchestration)
- TenantConnection (extends Doctrine\DBAL\Connection; holds dynamic connection params)
- TenantEntityManager (wraps/extends Doctrine\ORM\EntityManager; uses TenantConnection)
3. Event & Listener
- SwitchDbEvent (payload: tenant identifier)
- DbSwitchEventListener (on SwitchDbEvent: fetch config, update TenantConnection)
4. Console Commands (Doctrine proxies)
- CreateDatabaseCommand
- DiffCommand
- MigrateCommand
- UpdateSchemaCommand
- Shared logic via CommandTrait
C. Databases
- Main Database (holds TenantDbConfig entity and other “main” entities)
- Multiple Tenant Databases (one per tenant; each with its own schema + entities)

##### Component Relationships & Data Flows
1. At App Boot:
- Symfony reads `hakam_multi_tenancy.yaml`
- HakamMultiTenancyExtension registers services: TenantConnection (unconfigured), TenantEntityManager, DbConfigService, DbService, listener, commands
2. HTTP Flow (in a controller):
[Controller]
↓ dispatch
[SwitchDbEvent(id)] → [Event Dispatcher]
↓ invokes
[DbSwitchEventListener]
↓ uses
[DbConfigService] → MainEM → fetch `TenantDbConfig` entity
↓ applies
[TenantConnection::setParams(host,port,dbname,…)]
↓ configured
[TenantEntityManager] now points at correct tenant DB
↓ ORM operations
[TenantEntityManager: persist/flush/find …]
3. CLI Flow (console commands):
`php bin/console tenant:database:create`
↓ uses
[CreateDatabaseCommand → CommandTrait]
↓ uses
[DbService] → MainEM (reads all tenant configs)
↓ for each config
[DbService: create DB via TenantConnection] → run migrations via TenantEntityManager

##### Architectural Patterns & Principles
- Event-Driven: SwitchDbEvent + listener to change connection at runtime
- Dependency-Injection: all services configured via bundle extension & services.xml
- Adapter/Proxy Commands: wrap doctrine:migrations commands for tenant DBs
- Separation of Concerns: main vs. tenant concerns isolated by separate EMs + directories

##### Key Notes for the Engineer
- For each console command, show it invoking DbService, and DbService invoking TenantConnection and TenantEntityManager.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Symfony App
    subgraph "Host Symfony App"
        direction TB
        HTTPKernel["HTTP Kernel"]:::host
        ServiceContainer["Service Container"]:::host
        EventDispatcher["Event Dispatcher"]:::host
        MainEM["MainEntityManager"]:::doctrine
        Console["bin/console"]:::host
    end

    %% Bundle
    subgraph "HakamMultiTenancyBundle"
        direction TB
        HMTBundle["HakamMultiTenancyBundle"]:::bundle

        subgraph "DependencyInjection"
            direction TB
            Extension["HakamMultiTenancyExtension"]:::bundle
            Configuration["Configuration"]:::bundle
            ServicesXml["services.xml"]:::bundle
        end

        subgraph "Services"
            direction TB
            DbConfigService["DbConfigService"]:::bundle
            DbService["DbService"]:::bundle
            TenantConnection["TenantConnection"]:::doctrine
            TenantEM["TenantEntityManager"]:::doctrine
        end

        subgraph "Event & Listener"
            direction TB
            SwitchDbEvent["SwitchDbEvent"]:::bundle
            DbSwitchListener["DbSwitchEventListener"]:::bundle
        end

        subgraph "Commands"
            direction TB
            CommandTrait["CommandTrait"]:::bundle
            CreateDBCmd["CreateDatabaseCommand"]:::bundle
            DiffCmd["DiffCommand"]:::bundle
            MigrateCmd["MigrateCommand"]:::bundle
            UpdateSchemaCmd["UpdateSchemaCommand"]:::bundle
        end
    end

    %% Databases
    subgraph "Databases"
        direction TB
        MainDB["Main Database"]:::dbMain
        TenantDB["Tenant Databases"]:::dbTenant
    end

    %% Connections
    ServiceContainer -->|provides| Extension
    Extension --> Configuration
    Extension --> ServicesXml
    Extension -->|registers services| ServiceContainer

    HTTPKernel -->|dispatch Request| EventDispatcher
    EventDispatcher -->|dispatch SwitchDbEvent| SwitchDbEvent
    SwitchDbEvent -->|listened by| DbSwitchListener
    DbSwitchListener -->|uses| DbConfigService
    DbConfigService -->|fetch TenantDbConfig via ORM| MainEM
    DbSwitchListener -->|calls setParams| TenantConnection
    TenantConnection -->|used by| TenantEM
    TenantEM -->|ORM operations| TenantDB

    MainEM -->|connects| MainDB

    Console -->|runs command| CreateDBCmd
    Console -->|runs command| DiffCmd
    Console -->|runs command| MigrateCmd
    Console -->|runs command| UpdateSchemaCmd

    CreateDBCmd -->|uses| CommandTrait
    DiffCmd -->|uses| CommandTrait
    MigrateCmd -->|uses| CommandTrait
    UpdateSchemaCmd -->|uses| CommandTrait

    CreateDBCmd -->|uses| DbService
    DiffCmd -->|uses| DbService
    MigrateCmd -->|uses| DbService
    UpdateSchemaCmd -->|uses| DbService

    DbService -->|reads configs| MainEM
    DbService -->|creates connection| TenantConnection
    DbService -->|migrates via| TenantEM

    %% Click Events
    click Extension "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/DependencyInjection/HakamMultiTenancyExtension.php"
    click Configuration "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/DependencyInjection/Configuration.php"
    click ServicesXml "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Resources/config/services.xml"
    click DbConfigService "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Services/DbConfigService.php"
    click DbService "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Services/DbService.php"
    click TenantConnection "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Doctrine/DBAL/TenantConnection.php"
    click TenantEM "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Doctrine/ORM/TenantEntityManager.php"
    click SwitchDbEvent "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Event/SwitchDbEvent.php"
    click DbSwitchListener "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/EventListener/DbSwitchEventListener.php"
    click CommandTrait "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Command/CommandTrait.php"
    click CreateDBCmd "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Command/CreateDatabaseCommand.php"
    click DiffCmd "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Command/DiffCommand.php"
    click MigrateCmd "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Command/MigrateCommand.php"
    click UpdateSchemaCmd "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/Command/UpdateSchemaCommand.php"
    click HMTBundle "https://github.com/ramyhakam/multi_tenancy_bundle/blob/master/src/HakamMultiTenancyBundle.php"

    %% Styles
    classDef host fill:#f2f2f2,stroke:#999,stroke-width:1px;
    classDef bundle fill:#cce5ff,stroke:#339,stroke-width:1px;
    classDef doctrine fill:#ffe5cc,stroke:#e65c00,stroke-width:1px;
    classDef dbMain fill:#ccffcc,stroke:#33a600,stroke-width:1px;
    classDef dbTenant fill:#fff2cc,stroke:#cca300,stroke-width:1px;
```
