# saas-laravel/laravel-cqrs architecture

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

- Interactive diagram: https://gitdiagram.com/saas-laravel/laravel-cqrs
- Repository: https://github.com/saas-laravel/laravel-cqrs

## Overview

##### Main Components
- HTTP / Presentation Layer – Represented by the “app/Http” folder, including controllers (for example, UserController) and middleware.
- Command & Query Bus Layer – Found in “app/Bus”. You have CommandBus, QueryBus, and their implementations (IlluminateCommandBus, IlluminateQueryBus). This is the core orchestration component that routes requests to the right handlers.
- Domain and Modules – Under “src/Modules”, there are several domain modules such as User, Ai, and FeatureFlag. Each module is further divided into sub-components:
– Commands (for creating or updating domain entities, e.g., CreateUserCommand and its handler)
– Queries (for read operations such as FindUserQuery and its handler)
– Service layers (e.g., AiService, FeatureFlagService) that enforce business logic
– Repository patterns for data persistence (both read and write repositories in the User module)
- Core Components – The “src/Core” directory contains shared elements like exceptions which support error management across modules.
- Infrastructure & External Services – The “src/Modules/Ai/Client” (with implementations like AiClient and OpenAiClient) and “src/Modules/FeatureFlag/Clients” indicate external service integrations.

##### Data Flows and Interactions
- Controllers translate these requests into Commands or Queries which are dispatched via the Command Bus/Query Bus layer.
- The Command/Query Bus then forwards the request to the appropriate handler (located within the domain modules in “src/Modules/User/Commands” or “src/Modules/User/Queries”).
- Handlers may interact with the service layer, which further uses repositories (read/write) to interact with the database.
- For actions related to AI or feature flagging, the corresponding modules delegate processing to external API clients (such as OpenAiClient or GrowthbookFeatureFlagClient).

##### Architectural Patterns and Design Principles
- Separation of Concerns – Clear distinctions are made between controllers, command/query handling, and domain logic.
- CQRS – The creation of separate commands and queries ensures that write and read operations are handled independently.
- Dependency Injection – While not explicitly detailed in the file tree, Laravel’s service container (supported by “app/Providers”) facilitates loosely-coupled dependencies.
- Repository Pattern – Under the User module, separate contracts and repository implementations (both read and write) are present, indicating abstractions over data access.
- Modular Design – With modules for AI, feature flags, and user management, the design promotes a high degree of encapsulation and reusability.

- Presentation layer (controllers, middleware)
- Orchestration layer (command and query buses)
- Domain/Business logic (modules with commands, queries, services)
- Infrastructure dependencies (repositories, external API clients)
- Annotations indicating key architectural patterns such as CQRS, repository pattern, and dependency injection.

## Diagram (Mermaid)

```mermaid
graph TD
    %% HTTP Layer
    subgraph "HTTP Layer"
        HTTPCONTROLLER("UserController"):::presentation
    end

    %% Bus Layer
    subgraph "Command & Query Bus Layer"
        CMD_BUS("CommandBus"):::orchestration
        CMD_IMPL("IlluminateCommandBus"):::orchestration
        QUERY_BUS("QueryBus"):::orchestration
        QUERY_IMPL("IlluminateQueryBus"):::orchestration
    end

    %% User Module
    subgraph "User Module"
        USER_CREATE("CreateUserCommand & Handler"):::domain
        USER_FIND("FindUserQuery & Handler"):::domain
        USER_REPO("User Repositories"):::infrastructure
        USER_VO("User Value Objects"):::domain
    end

    %% AI Module
    subgraph "AI Module"
        AI_SERVICE("AiService"):::domain
        AI_DTOS("Ai DTOs"):::domain
        AI_CLIENT("Ai External Client"):::infrastructure
    end

    %% FeatureFlag Module
    subgraph "FeatureFlag Module"
        FF_SERVICE("FeatureFlagService"):::domain
        FF_CONTRACTS("FeatureFlag Contracts & Enums"):::domain
        FF_CLIENT("FeatureFlag Client"):::infrastructure
    end

    %% Core Components
    subgraph "Core Components"
        CORE_EXC("Core Exceptions"):::core
    end

    %% Infrastructure: Database
    DB("Database"):::infrastructure

    %% Connections: HTTP Layer to Bus Layer
    HTTPCONTROLLER -->|"dispatches"| CMD_BUS
    HTTPCONTROLLER -->|"dispatches"| QUERY_BUS

    %% Bus Layer internal connections
    CMD_BUS -->|"implementation"| CMD_IMPL
    QUERY_BUS -->|"implementation"| QUERY_IMPL

    %% Bus Layer to User Module
    CMD_BUS -->|"executes"| USER_CREATE
    QUERY_BUS -->|"executes"| USER_FIND

    %% User Module internal flows
    USER_CREATE -->|"uses"| USER_REPO
    USER_FIND -->|"uses"| USER_REPO
    USER_CREATE -->|"validates"| USER_VO
    USER_FIND -->|"validates"| USER_VO
    USER_REPO -->|"persists"| DB

    %% Modules error handling via Core
    USER_CREATE -->|"handlesError"| CORE_EXC
    USER_FIND -->|"handlesError"| CORE_EXC

    %% AI Module flows
    AI_SERVICE -->|"calls"| AI_CLIENT
    AI_SERVICE -->|"handlesError"| CORE_EXC

    %% FeatureFlag Module flows
    FF_SERVICE -->|"calls"| FF_CLIENT
    FF_SERVICE -->|"handlesError"| CORE_EXC

    %% Click Events
    click HTTPCONTROLLER "https://github.com/saas-laravel/laravel-cqrs/blob/main/app/Http/Controllers/UserController.php"
    click CMD_BUS "https://github.com/saas-laravel/laravel-cqrs/blob/main/app/Bus/CommandBus.php"
    click CMD_IMPL "https://github.com/saas-laravel/laravel-cqrs/blob/main/app/Bus/IlluminateCommandBus.php"
    click QUERY_BUS "https://github.com/saas-laravel/laravel-cqrs/blob/main/app/Bus/QueryBus.php"
    click QUERY_IMPL "https://github.com/saas-laravel/laravel-cqrs/blob/main/app/Bus/IlluminateQueryBus.php"
    click USER_CREATE "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/User/Commands"
    click USER_FIND "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/User/Queries"
    click USER_REPO "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/User/Repositories"
    click USER_VO "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/User/ValueObjects"
    click AI_SERVICE "https://github.com/saas-laravel/laravel-cqrs/blob/main/src/Modules/Ai/Service/AiService.php"
    click AI_DTOS "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/Ai/DataTransferObjects"
    click AI_CLIENT "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/Ai/Client"
    click FF_SERVICE "https://github.com/saas-laravel/laravel-cqrs/blob/main/src/Modules/FeatureFlag/Services/FeatureFlagService.php"
    click FF_CONTRACTS "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/FeatureFlag/Contracts"
    click FF_CLIENT "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Modules/FeatureFlag/Clients"
    click CORE_EXC "https://github.com/saas-laravel/laravel-cqrs/tree/main/src/Core/Exceptions"

    %% Styles
    classDef presentation fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef orchestration fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef domain fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef infrastructure fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef core fill:#F5B7B1,stroke:#943126,stroke-width:2px;
```
