# mguinea/laravel-ddd-example architecture

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

- Interactive diagram: https://gitdiagram.com/mguinea/laravel-ddd-example
- Repository: https://github.com/mguinea/laravel-ddd-example

## Overview

##### Main Components
- API/Application Layer – Represented by the “apps/kanban-api” directory. This is the Laravel-based adapter layer that exposes HTTP endpoints (e.g., controllers for boards and health check). Include key middleware, route handling (routes/api.php), and essential configuration from “config” directory.
- Domain & Application Logic – Located in “src/Kanban/Board” and “src/Shared”. This folder structure is used to implement the core business logic. Break it into:
- Domain Layer: Contains business entities (e.g., Board, BoardId, BoardName) and domain exceptions.
- Application Layer: Includes command, query, and event classes and their corresponding handlers. This layer orchestrates use cases (e.g., create, update, delete, get boards).
- Infrastructure Layer – Found both in “apps/kanban-api” (Laravel specific repositories and service providers) and “src/Kanban/Board/Infrastructure”. This represents persistence (e.g., Eloquent implementations), external bus integrations (with Symfony Messenger), and any external integrations.
- Shared Components – In “src/Shared” which includes shared domain concepts (aggregates, buses, etc.) that work across other bounded contexts.
- External Services – Include external dependencies like RabbitMQ (see “etc/rabbitmq” and reference in the README), MySQL (configured via Docker and connections in “config/database.php”), and monitoring/log aggregation (Grafana and Prometheus in “etc/grafana”, “etc/prometheus”).

##### Relationships and Interactions
- The API layer (Laravel controllers) acts as an adapter, receiving HTTP requests and then dispatching commands and queries via the infrastructure’s bus (CQRS/Symfony Messenger) toward the Application layer.
- The Application layer handles incoming commands/queries, interacts with the Domain layer for business rules, and coordinates persistence using Repository interfaces defined in the Domain.
- The Infrastructure layer implements the Repository pattern and translates calls to the underlying database (MySQL).
- Event flows include domain events (e.g., BoardWasCreated) that may trigger subscribers (for example, SomethingWithCreatedBoardSubscriber) possibly plugged into RabbitMQ.

##### Architectural Patterns and Design Principles
- Hexagonal Architecture (Ports & Adapters): Clearly distinguish between “inside” components (domain, application) and “adapters” (Laravel API, persistence, external messaging).
- DDD Elements: Show the business logic in the Domain layer, including entities, value objects, and domain events.
- CQRS: Separate command (write) and query (read) responsibilities; mark the bus channels (CommandBus, QueryBus, EventBus) and their handlers.
- Repository Pattern: Emphasize how repositories abstract the persistence mechanism.

##### Relevant Technologies and Frameworks
- Laravel 8/PHP 8 for the API layer.
- Docker with provided Dockerfiles and docker-compose for environment management.
- MySQL as the persistent store.
- Symfony Messenger for implementing CQRS.
- RabbitMQ as a message broker (with associated configuration under etc/rabbitmq).
- Terraform and CI/CD (CircleCI, GitHub Actions) support continuous integration and deployment.

##### Additional Details
- Testing layers (tests/) to show that each component is validated via unit and integration tests.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Systems
    subgraph "External Systems"
        G1("External HTTP Request"):::external
    end

    %% API/Adapter Layer
    subgraph "API/Adapter Layer"
        A1("Laravel API Controller"):::api
        A2("API Routes (routes/api.php)"):::api
        A3("API Config"):::api
        A4("API Providers"):::api
    end

    %% Messaging Bus
    subgraph "Messaging Bus"
        B1("Messenger Bus Implementation"):::infra
    end

    %% Core Domain
    subgraph "Core Domain"
        C1("Board Domain Logic"):::domain
        C2("Shared Domain Components"):::domain
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        D1("Eloquent Repository"):::infra
    end

    %% External Services
    subgraph "External Services"
        E1("MySQL Database"):::external
        E2("RabbitMQ"):::external
        E3("Grafana"):::external
        E4("Prometheus"):::external
    end

    %% Containerization & CI/CD
    subgraph "Containerization & CI/CD"
        F1("Docker Compose"):::cicd
        F2("CI/CD Pipelines"):::cicd
        F3("GitHub Workflows"):::cicd
    end

    %% Connections between layers
    G1 -->|"sends"| A1
    A1 -->|"dispatches"| B1
    A3 -->|"configures"| E1
    A4 -->|"binds_to"| D1
    B1 -->|"handles_command"| C1
    C1 -->|"persists"| D1
    D1 -->|"communicates"| E1
    C1 -->|"emits_event"| B1
    B1 -->|"delivers_event"| E2
    C2 -->|"supports"| B1

    %% Containerization influence
    F1 -->|"orchestrates"| A1
    F1 -->|"orchestrates"| E1
    F1 -->|"orchestrates"| E2
    F2 -->|"deploys"| A1
    F2 -->|"deploys"| D1

    %% Styles
    classDef api fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef domain fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef infra fill:#FFA07A,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef cicd fill:#FFFFE0,stroke:#000,stroke-width:1px;

    %% Click events for component mapping
    click A1 "https://github.com/mguinea/laravel-ddd-example/tree/master/apps/kanban-api"
    click A2 "https://github.com/mguinea/laravel-ddd-example/blob/master/apps/kanban-api/routes/api.php"
    click A3 "https://github.com/mguinea/laravel-ddd-example/tree/master/apps/kanban-api/config"
    click A4 "https://github.com/mguinea/laravel-ddd-example/tree/master/apps/kanban-api/app/Providers"
    click C1 "https://github.com/mguinea/laravel-ddd-example/tree/master/src/Kanban/Board"
    click C2 "https://github.com/mguinea/laravel-ddd-example/tree/master/src/Shared"
    click D1 "https://github.com/mguinea/laravel-ddd-example/tree/master/src/Kanban/Board/Infrastructure"
    click B1 "https://github.com/mguinea/laravel-ddd-example/tree/master/src/Shared/Infrastructure/Bus/Messenger"
    click E1 "https://github.com/mguinea/laravel-ddd-example/blob/master/apps/kanban-api/config/database.php"
    click E2 "https://github.com/mguinea/laravel-ddd-example/tree/master/etc/rabbitmq"
    click E3 "https://github.com/mguinea/laravel-ddd-example/tree/master/etc/grafana"
    click E4 "https://github.com/mguinea/laravel-ddd-example/blob/master/etc/prometheus/prometheus.yml"
    click F1 "https://github.com/mguinea/laravel-ddd-example/tree/master/etc/docker"
    click F2 "https://github.com/mguinea/laravel-ddd-example/blob/master/.circleci"
    click F3 "https://github.com/mguinea/laravel-ddd-example/tree/master/.github/workflows"
```
