# bdelespierre/laravel-clean-architecture-demo architecture

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

- Interactive diagram: https://gitdiagram.com/bdelespierre/laravel-clean-architecture-demo
- Repository: https://github.com/bdelespierre/laravel-clean-architecture-demo

## Overview

##### Project Type and Purpose
- This is a full-stack Laravel application structured according to Clean/Hexagonal Architecture (also known as Ports & Adapters).
- Its primary feature (demonstrated in the codebase) is a “Create User” use case, exposed over HTTP (JSON/HTML) and CLI.

##### High-Level View of the File Structure
- **app/Domain** holds pure business logic: Entities, Interfaces (ports), and Use Case Interactors.
- **app/Adapters** implements output ports (Presenters) and ViewModels for different delivery mechanisms (CLI, HTTP, JSON).
- **app/Http** and **app/Console** are framework-specific adapters (controllers and Artisan commands).
- **app/Repositories** is the infrastructure adapter implementing the UserRepository interface against a relational database.
- **resources/views**, **resources/js/css** represent the frontend.
- **config/**, **bootstrap/**, **public/**, **routes/** are standard Laravel framework layers and entry points.

##### Main Components and Their Interactions
a. **Clients / Entry Points**
- Web Browser → HTTP(S)
- CLI → Artisan commands
b. **Framework Adapters**
- Public/index.php → HTTP Kernel → Middleware → Controllers (app/Http/Controllers)
- artisan → Console Kernel → Commands (app/Console/Commands)
c. **Use Case Layer (app/Domain/UseCases/CreateUser)**
- CreateUserRequestModel → CreateUserInteractor → CreateUserResponseModel
- Interactor depends on two ports: UserRepository (to persist data) and CreateUserOutputPort (to present results).
d. **Infrastructure Adapters**
- UserDatabaseRepository implements UserRepository, communicates with the database via Eloquent (app/Models/User).
e. **Output Adapters (Presenters & ViewModels)**
- CreateUserHttpPresenter → HttpResponseViewModel → JSON or Blade view
- CreateUserJsonPresenter → JsonResourceViewModel → JSON API
- CreateUserCliPresenter → CliViewModel → Console output
f. **Persistence**
- MySQL (or configured DB) with migrations in database/migrations
g. **Frontend**
- Blade templates (resources/views/user/create.blade.php, show.blade.php)
- JS/CSS assets built via webpack.mix.js

##### Architectural Patterns & Principles
- **Dependency Inversion**: Domain depends on interfaces only; concrete implementations live in Adapters.
- **Single Responsibility**: Controllers orchestrate request mapping; Interactors handle business rules; Presenters format output.
- **Ports & Adapters (Hexagonal)**: Clear separation between core business logic and framework/infrastructure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        Browser["Web Browser"]:::external
        CLIClient["CLI (artisan)"]:::external
    end

    %% Framework Adapters
    subgraph "Framework Adapters"
        direction TB
        HTTPServer["HTTP Server (NGINX/Apache)"]:::infrastructure
        LaravelKernel["Laravel Kernel"]:::framework
        Middleware["Middleware"]:::framework
        CreateUserController["CreateUserController"]:::framework
        RequestValidation["CreateUserRequest"]:::framework
        ConsoleKernel["Console Kernel"]:::framework
        CreateUserCommand["CreateUserCommand"]:::framework
    end

    %% Domain Layer
    subgraph "Domain / Use Cases"
        direction TB
        RequestModel["CreateUserRequestModel"]:::domain
        Interactor["CreateUserInteractor"]:::domain
        ResponseModel["CreateUserResponseModel"]:::domain
        InputPort["CreateUserInputPort"]:::domain
        OutputPort["CreateUserOutputPort"]:::domain
        UserRepositoryIF["UserRepository Interface"]:::domain
        UserEntity["UserEntity"]:::domain
        UserFactory["UserFactory"]:::domain
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        direction TB
        UserRepo["UserDatabaseRepository"]:::infrastructure
        EloquentUser["User (Eloquent Model)"]:::infrastructure
        EmailVO["EmailValueObject"]:::infrastructure
        PasswordVO["PasswordValueObject"]:::infrastructure
        HashedPasswordVO["HashedPasswordValueObject"]:::infrastructure
    end

    %% Output Adapters
    subgraph "Output Adapters"
        direction TB
        HttpPresenter["CreateUserHttpPresenter"]:::adapters
        JsonPresenter["CreateUserJsonPresenter"]:::adapters
        CliPresenter["CreateUserCliPresenter"]:::adapters
        HttpVM["HttpResponseViewModel"]:::adapters
        JsonVM["JsonResourceViewModel"]:::adapters
        CliVM["CliViewModel"]:::adapters
    end

    %% Frontend
    subgraph "Frontend"
        direction TB
        BladeCreate["create.blade.php"]:::frontend
        BladeShow["show.blade.php"]:::frontend
        JSAsset["app.js"]:::frontend
        CSSAsset["app.css"]:::frontend
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        Database[(MySQL Database)]:::external
    end

    %% Flows: HTTP
    Browser -->|HTTP Request| HTTPServer
    HTTPServer -->|to kernel| LaravelKernel
    LaravelKernel -->|to middleware| Middleware
    Middleware -->|validated| CreateUserController
    CreateUserController -->|uses RequestModel| RequestValidation
    CreateUserController -->|calls| Interactor
    RequestValidation -->|transforms to| RequestModel

    %% Flows: CLI
    CLIClient -->|artisan| ConsoleKernel
    ConsoleKernel -->|invokes| CreateUserCommand
    CreateUserCommand -->|builds RequestModel| RequestModel
    CreateUserCommand -->|calls| Interactor

    %% Domain and Ports
    Interactor -->|implements InputPort| InputPort
    Interactor -->|depends on| UserRepositoryIF
    Interactor -->|outputs to| OutputPort
    Interactor -->|uses| UserFactory
    Interactor -->|produces| ResponseModel

    %% Infrastructure
    UserRepo -->|implements| UserRepositoryIF
    UserRepo -->|persists via| EloquentUser
    EloquentUser -->|stores| Database
    EmailVO -->|value object| EloquentUser
    PasswordVO -->|value object| EloquentUser
    HashedPasswordVO -->|value object| EloquentUser

    %% Presenters & ViewModels
    OutputPort -->|Http| HttpPresenter
    OutputPort -->|JSON| JsonPresenter
    OutputPort -->|CLI| CliPresenter
    HttpPresenter -->|formats| HttpVM
    JsonPresenter -->|formats| JsonVM
    CliPresenter -->|formats| CliVM

    %% Frontend rendering
    HttpVM -->|renders| BladeCreate
    HttpVM -->|renders| BladeShow
    JsonVM -->|returns| Browser
    CliVM -->|prints| CLIClient
    JSAsset -->|bundled assets| Browser
    CSSAsset -->|bundled assets| Browser

    %% Database relation
    Database -->|data| EloquentUser

    %% Click Events
    click CreateUserInteractor "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/UseCases/CreateUser/CreateUserInteractor.php"
    click RequestModel "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/UseCases/CreateUser/CreateUserRequestModel.php"
    click ResponseModel "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/UseCases/CreateUser/CreateUserResponseModel.php"
    click InputPort "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/UseCases/CreateUser/CreateUserInputPort.php"
    click OutputPort "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/UseCases/CreateUser/CreateUserOutputPort.php"
    click UserRepositoryIF "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/Interfaces/UserRepository.php"
    click UserEntity "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/Interfaces/UserEntity.php"
    click UserFactory "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Domain/Interfaces/UserFactory.php"
    click UserRepo "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Repositories/UserDatabaseRepository.php"
    click EloquentUser "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Models/User.php"
    click EmailVO "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Models/EmailValueObject.php"
    click PasswordVO "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Models/PasswordValueObject.php"
    click HashedPasswordVO "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Models/HashedPasswordValueObject.php"
    click CreateUserController "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Http/Controllers/CreateUserController.php"
    click RequestValidation "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Http/Requests/CreateUserRequest.php"
    click UserCreatedResource "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Http/Resources/UserCreatedResource.php"
    click UnableToCreateUserResource "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Http/Resources/UnableToCreateUserResource.php"
    click UserAlreadyExistsResource "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Http/Resources/UserAlreadyExistsResource.php"
    click CreateUserCommand "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Console/Commands/CreateUserCommand.php"
    click HttpPresenter "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/Presenters/CreateUserHttpPresenter.php"
    click JsonPresenter "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/Presenters/CreateUserJsonPresenter.php"
    click CliPresenter "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/Presenters/CreateUserCliPresenter.php"
    click HttpVM "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/ViewModels/HttpResponseViewModel.php"
    click JsonVM "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/ViewModels/JsonResourceViewModel.php"
    click CliVM "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/app/Adapters/ViewModels/CliViewModel.php"
    click BladeCreate "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/resources/views/user/create.blade.php"
    click BladeShow "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/resources/views/user/show.blade.php"
    click JSAsset "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/resources/js/app.js"
    click CSSAsset "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/resources/css/app.css"
    click Migration "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/database/migrations/2014_10_12_000000_create_users_table.php"
    click HTTPServer "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/public/index.php"
    click CLIClient "https://github.com/bdelespierre/laravel-clean-architecture-demo/tree/master/artisan"
    click routesWeb "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/routes/web.php"
    click routesApi "https://github.com/bdelespierre/laravel-clean-architecture-demo/blob/master/routes/api.php"

    %% Styles
    classDef framework fill:#D6EAF8,stroke:#3498DB,color:#154360;
    classDef domain fill:#FCF3CF,stroke:#F1C40F,color:#7D6608;
    classDef infrastructure fill:#FADBD8,stroke:#E74C3C,color:#641E16;
    classDef adapters fill:#D5F5E3,stroke:#27AE60,color:#145A32;
    classDef frontend fill:#E8DAEF,stroke:#8E44AD,color:#4A235A;
    classDef external fill:#F2F3F4,stroke:#ABB2B9,color:#2C3E50;
```
