# chaucongtu/laravel-11-command-bus architecture

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

- Interactive diagram: https://gitdiagram.com/chaucongtu/laravel-11-command-bus
- Repository: https://github.com/chaucongtu/laravel-11-command-bus

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Laravel 11. It employs the Command Bus Design Pattern to separate business logic (Commands and Handlers) from Controllers, which simplifies extension and maintenance.
- The project supports typical RESTful endpoints (for User Authentication, File handling, and User management) as well as CLI integrations through Artisan, making it both an HTTP/API and console-driven system.

##### File Structure
- The “app” folder is subdivided into many key subdirectories:
- Commands (e.g., App/Commands/Auth, App/Commands/Users): These represent command requests that encapsulate business intent (e.g., login, register, reset password).
- Handlers (e.g., App/Handlers/Auth, App/Handlers/Users): These process the commands and contain the business logic.
- HTTP Controllers (App/Http/Controllers/Api/v1): These receive incoming HTTP requests and delegate to commands.
- HTTP Requests and Resources: For input validation and formatting API output.
- Other directories such as Builders, Middleware, Exceptions, and Providers show standard Laravel practices.
- There are console commands (in app/Console/Commands) that help to generate boilerplate code/generate features, which reinforces the Command Bus approach.
- Alongside, directories like “config”, “database”, “routes”, and “public” follow standard Laravel patterns.

##### Core Components
a. API (HTTP Layer):
- Controllers (e.g., AuthController, UserController) that handle HTTP requests.
- Middleware for authentication/authorization, ensuring proper request handling.
b. Command Bus Components:
- Commands: Representing actions (e.g., LoginCommand, ResetPasswordCommand).
- Handlers: Dedicated classes that process each Command.
c. Domain/Service Layer:
- Services, Helpers, and Repositories (e.g., EmailService, FileService, UserService) which encapsulate core business logic or interact with the persistence layer.
d. Persistence Layer:
- Models (e.g., User, FileStorage) that represent the database entities.
- Migrations and Seeders under the “database” folder to build and seed the schema.
e. Infrastructure and Configuration:
- Providers, configuration files (config/*), and bootstrap scripts.
- Console command components that generate code or execute system-level commands.
f. Exception Handling:
- Custom Exceptions (e.g., AuthException, NotFoundException) and global error handling.

##### Relationships and Data Flow
- The Controller instantiates a Command (holding the necessary data) and passes it to the appropriate Handler.
- The Handler executes business logic that may invoke Services, perform validation, or interact with Repositories and Models for data persistence.
- Responses are then structured as Resources (for API responses) returned back through the Controller.
- Additional interactions include middleware processing pre-request (e.g., authentication, role checks) and exception handling in case of errors.

##### Architectural Patterns and Design Principles
- Command Bus Pattern: Emphasize the clear separation between Commands (representing user intentions) and Handlers (executing the logic).
- MVC Pattern: Controllers delegate to business logic layers instead of implementing logic directly.
- Service/Repository Patterns: Used to facilitate business logic and abstract data access.
- Use dependency injection as configured in Laravel’s Provider and Service Container.

##### Additional Elements
- Integration points like Artisan commands which generate Controllers, Requests, and Handlers.
- External systems (e.g., Database servers like MySQL/PostgreSQL) and any external service (e.g., Email service) provided via the HTTP Services.
- Error pathways with exception classes and error handling middleware.

## Diagram (Mermaid)

```mermaid
flowchart TD
    ExternalClient["External Client"]:::external
    
    subgraph "API Layer"
        Middleware["HTTP Middleware"]:::middleware
        Controllers["Controllers"]:::controllers
        Middleware --> Controllers
    end

    subgraph "Command Bus"
        Commands["Commands"]:::commands
        Handlers["Handlers"]:::handlers
        Controllers --> Commands
        Commands --> Handlers
    end

    subgraph "Domain/Service Layer"
        Services["Services"]:::services
        Repositories["Repositories"]:::services
        Handlers --> Services
        Services --> Repositories
    end

    subgraph "Persistence Layer"
        Models["Models"]:::models
        Migrations["Migrations"]:::migrations
        Repositories --> Models
        Models --> Migrations
    end

    subgraph "Infrastructure & Others"
        Config["Configuration"]:::config
        Providers["Providers"]:::providers
        Exceptions["Exception Handling"]:::exceptions
        CLI["CLI Commands"]:::cli
        Config --> Providers
        Providers --> Services
    end

    ExternalClient --> Middleware
    Controllers -.->|error_route| Exceptions
    Handlers -.->|error_route| Exceptions
    CLI --> Handlers

    classDef external fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef middleware fill:#87CEFA,stroke:#000,stroke-width:1px
    classDef controllers fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef commands fill:#98FB98,stroke:#000,stroke-width:1px
    classDef handlers fill:#FFA07A,stroke:#000,stroke-width:1px
    classDef services fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef models fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef migrations fill:#C0C0C0,stroke:#000,stroke-width:1px
    classDef config fill:#F5DEB3,stroke:#000,stroke-width:1px
    classDef providers fill:#F5DEB3,stroke:#000,stroke-width:1px
    classDef exceptions fill:#FFC0CB,stroke:#000,stroke-width:1px
    classDef cli fill:#E6E6FA,stroke:#000,stroke-width:1px

    click Controllers "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Http/Controllers/Api/v1"
    click Middleware "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Http/Middleware"
    click Commands "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Commands"
    click Handlers "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Handlers"
    click Services "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Http/Services"
    click Repositories "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Http/Services/Repositories"
    click Models "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Models"
    click Migrations "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/database/migrations"
    click Config "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/config"
    click Providers "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Providers"
    click Exceptions "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Exceptions"
    click CLI "https://github.com/chaucongtu/laravel-11-command-bus/tree/main/app/Console/Commands"
```
