# vinh0809it/laravel-ddd-salary architecture

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

- Interactive diagram: https://gitdiagram.com/vinh0809it/laravel-ddd-salary
- Repository: https://github.com/vinh0809it/laravel-ddd-salary

## Overview

##### Main Components
- API Gateway / Entry Point: Represent the public-facing component using Laravel’s HTTP kernel (in bootstrap, public/index.php, and routes) that handles incoming API requests.
- Domains – User and SalaryHistory: In the src folder, each domain is partitioned into four main sub-layers:
○ Presentation: Controllers and Request objects handling client HTTP requests.
○ Application: Contains use cases, command and query buses, DTOs, and handlers responsible for orchestrating business operations.
○ Domain: Contains entities, value objects, domain events, rules, exceptions, and factories encapsulating the core business logic.
○ Infrastructure: Provides concrete implementations for repositories, persistence (migrations and Eloquent models), policies, services, and provider bindings.
- Shared Components: There is a Shared folder to hold common infrastructure, application services, and exception handling logic to keep cross-cutting concerns centralized.
- External Services & Integration: Although not fully implemented, the design shows entry points for external domain services (e.g., IUserDomainService) that allow integration with external systems.
- Tests: Both Unit and Feature tests are organized to validate domain logic and API behavior, which are crucial for maintaining architectural integrity.

##### Relationships and Interactions Between Components
- The HTTP Layer in the Presentation folder receives API calls through Laravel’s routing (routes/web.php, routes/api.php, and domain-specific route files in Presentation).
- Controllers pass requests to the Application layer by dispatching commands/queries through command and query buses.
- The Application layer interacts with the Domain layer, instantiating entities, enforcing business rules, and triggering domain events.
- The Domain layer remains pure by containing business logic and validation, while the Infrastructure layer implements persistence (via Eloquent and migrations), policies, and external service communication.
- Shared components (in the Shared folder) provide base classes and utilities used across multiple domains.
- Data flows from the API entry point to the respective domain’s use case handlers, processes through different layers, and then returns a response to the client.

##### Architectural Patterns and Design Principles
- Domain-Driven Design: Clear separation of concerns across Domain, Application, Presentation, and Infrastructure layers enhances maintainability and testability.
- Command-Query Responsibility Segregation (CQRS): Notice the separate handling for commands (writes) and queries (reads), which are managed by distinct buses and handlers.
- Dependency Injection and Inversion of Control: Laravel’s Service Providers (with distinct providers in each domain’s Infrastructure) are used to bind interfaces to implementations.
- Layered Architecture: Each domain encapsulates its own full-stack (from Controller to Repository), allowing isolated evolution.

##### Technologies and Frameworks
- Laravel 10 and PHP 8.1, which form the backbone for the API.
- Eloquent ORM: Your persistence layer using migrations and Eloquent models.
- Testing Framework: PHPUnit for unit and feature testing.
- Composer for dependency management and package configuration.
- Postman for API testing, as evidenced in the postman folder.

- How the API Gateway (via Laravel routing and controllers) dispatches commands and queries to the respective bus in the Application layer.
- That the domain logic (entities, services, rules, etc.) remains isolated from the infrastructure-specific implementations.
- In the testing framework and configuration files as supporting auxiliary components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Gateway Subgraph
    subgraph "API Gateway"
        HTTPKernel("HTTP Kernel"):::api
        Routes("Routes"):::api
    end

    %% SalaryHistory Domain Subgraph
    subgraph "SalaryHistory Domain"
        SH_Presentation("SalaryHistory Presentation"):::presentation
        SH_Application("SalaryHistory Application"):::application
        SH_Domain("SalaryHistory Domain"):::domain
        SH_Infrastructure("SalaryHistory Infrastructure"):::infrastructure
    end

    %% User Domain Subgraph
    subgraph "User Domain"
        U_Presentation("User Presentation"):::presentation
        U_Application("User Application"):::application
        U_Domain("User Domain"):::domain
        U_Infrastructure("User Infrastructure"):::infrastructure
    end

    %% Shared Components Subgraph
    subgraph "Shared Components"
        Shared("Shared Components"):::shared
    end

    %% External Services & Integration Subgraph
    subgraph "External Services & Integration"
        IUserDomainService("IUserDomainService"):::external
        UserDomainServiceImpl("UserDomainService Implementation"):::external
    end

    %% Testing Subgraph
    subgraph "Testing"
        Tests("Tests"):::testing
    end

    %% Connections within API Gateway
    HTTPKernel -->|"initializes"| Routes

    %% API Gateway dispatches to domain presentation layers
    Routes -->|"dispatches"| SH_Presentation
    Routes -->|"dispatches"| U_Presentation

    %% SalaryHistory Domain Layered Flow
    SH_Presentation -->|"calls"| SH_Application
    SH_Application -->|"orchestrates"| SH_Domain
    SH_Domain -->|"persists"| SH_Infrastructure

    %% User Domain Layered Flow
    U_Presentation -->|"calls"| U_Application
    U_Application -->|"orchestrates"| U_Domain
    U_Domain -->|"persists"| U_Infrastructure

    %% Shared Components provide common services to Application layers
    Shared -->|"provides"| SH_Application
    Shared -->|"provides"| U_Application

    %% External Services Integration linked with SalaryHistory Domain
    SH_Domain -->|"uses"| IUserDomainService
    IUserDomainService -->|"implemented_by"| UserDomainServiceImpl

    %% Testing validates both domains
    Tests -->|"validates"| SH_Domain
    Tests -->|"validates"| U_Domain

    %% Click Events
    click HTTPKernel "https://github.com/vinh0809it/laravel-ddd-salary/blob/master/public/index.php"
    click Routes "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/routes"
    click SH_Presentation "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/SalaryHistory/Presentation"
    click SH_Application "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/SalaryHistory/Application"
    click SH_Domain "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/SalaryHistory/Domain"
    click SH_Infrastructure "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/SalaryHistory/Infrastructure"
    click U_Presentation "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/User/Presentation"
    click U_Application "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/User/Application"
    click U_Domain "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/User/Domain"
    click U_Infrastructure "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/User/Infrastructure"
    click Shared "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/src/Shared"
    click IUserDomainService "https://github.com/vinh0809it/laravel-ddd-salary/blob/master/src/SalaryHistory/Domain/Services/External/IUserDomainService.php"
    click UserDomainServiceImpl "https://github.com/vinh0809it/laravel-ddd-salary/blob/master/src/SalaryHistory/Infrastructure/Services/UserDomainService.php"
    click Tests "https://github.com/vinh0809it/laravel-ddd-salary/tree/master/tests"

    %% Class Definitions for styling
    classDef api fill:#ffdddd,stroke:#cc0000,stroke-width:2px;
    classDef presentation fill:#ddffdd,stroke:#008800,stroke-width:2px;
    classDef application fill:#ddffff,stroke:#008888,stroke-width:2px;
    classDef domain fill:#ffffdd,stroke:#888800,stroke-width:2px;
    classDef infrastructure fill:#ffddee,stroke:#cc0088,stroke-width:2px;
    classDef shared fill:#eeeeee,stroke:#666666,stroke-width:2px;
    classDef testing fill:#e6e6fa,stroke:#663399,stroke-width:2px;
    classDef external fill:#fff0b3,stroke:#cc9900,stroke-width:2px;
```
