# oscarroman1230/php-ddd-user architecture

> Architecture diagram of the GitHub repository oscarroman1230/php-ddd-user, 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/oscarroman1230/php-ddd-user
- Repository: https://github.com/oscarroman1230/php-ddd-user

## Overview

##### Project Type & Purpose
- This is a backend PHP application to manage user registration. It uses DDD and Clean Architecture to separate concerns between the Application, Domain, and Infrastructure layers.
- It uses Doctrine ORM for persistence with MySQL, exposes an API endpoint for user registration, and is containerized using Docker (with Docker Compose), running on Apache.

##### Break Down the File Structure
- Top-level configuration files (Dockerfile, docker-compose.yml, .env) indicate a containerized deployment and environment variable management.
- The “public” directory contains the web-accessible entry point (index.php) and .htaccess for Apache, setting up the API endpoint to receive HTTP requests.
- The “src” directory is organized to reflect Clean Architecture:
- The Application layer (src/Application) holds use cases like RegisterUser, handling input and application logic, including the RegisterUserUseCase and its Request model.
- The Domain layer (src/Domain) encapsulates business entities (User, Email, Name, Password, UserId), domain events (UserRegisteredEvent), and repository interfaces, ensuring core business rules are independent of external frameworks.
- The Infrastructure layer (src/Infrastructure) integrates with external systems: Controllers (e.g., RegisterUserController), event dispatching (EventDispatcher and SendWelcomeEmailListener), middleware for exception handling, and the actual implementations for persistence (DoctrineUserRepository).
- The “tests” directory includes both unit and integration tests to verify correct behavior for use cases and repository implementations.

##### Main Components & Their Interactions
- API Layer: The public/index.php entry point routes HTTP requests to the relevant Infrastructure Controllers, such as RegisterUserController.
- Application Layer: The controller invokes the RegisterUserUseCase, which handles the business logic for user registration.
- Domain Layer: The use case communicates with Domain entities (User, Email, etc.) and domain events (like UserRegisteredEvent) to enforce business rules.
- Persistence Layer: The Domain’s persistence abstraction (UserRepositoryInterface) is implemented by the DoctrineUserRepository in the Infrastructure. When a user is registered, this repository uses Doctrine ORM to interact with the MySQL database.
- Event Handling: Once an event is triggered (like a user registration event), the event dispatcher and linked listeners (such as SendWelcomeEmailListener) handle domain events, which can trigger further processes (like sending welcome emails).

##### Architectural Patterns
- DDD & Clean Architecture: Clear separation of concerns – with the Domain and Application layers isolated from external frameworks through interfaces and dependency injection.
- The use of Doctrine ORM illustrates the Repository pattern for persistence, and the implementation of clear boundaries (e.g., the infrastructure layer only implements what the domain requires).
- API endpoints are organized in a layered approach, with the “Controller” in Infrastructure managing incoming requests and delegating to Application services.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Client/API Layer
    subgraph "Client/API Layer"
        clientIndex["index.php (API Endpoint)"]:::client
        clientHtaccess[".htaccess (Apache Config)"]:::client
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        IRController["RegisterUserController"]:::infra
        IMiddleware["ExceptionHandlerMiddleware"]:::infra
        IEventDispatcher["EventDispatcher"]:::infra
        IWelcomeListener["SendWelcomeEmailListener"]:::infra
        IDoctrine["DoctrineUserRepository"]:::infra
    end

    %% Application Layer
    subgraph "Application Layer"
        AppUseCase["RegisterUserUseCase"]:::app
        AppRequest["RegisterUserRequest"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        subgraph "User Aggregate"
            userMain["User"]:::domain
            userEmail["Email"]:::domain
            userName["Name"]:::domain
            userPassword["Password"]:::domain
            userId["UserId"]:::domain
        end
        DomainEvent["UserRegisteredEvent"]:::domain
        DomainRepoInterface["UserRepositoryInterface"]:::domain
    end

    %% Deployment & External Systems
    subgraph "Deployment & External Systems"
        DockerPHP["PHP/Apache (Docker)"]:::deploy
        MySQL["MySQL Database"]:::deploy
        Adminer["Adminer"]:::deploy
        DoctrineORM["Doctrine ORM"]:::deploy
        PHPUnit["PHPUnit"]:::deploy
    end

    %% Connections
    clientIndex -->|"HTTP_POST/register"| IRController
    clientHtaccess --> IRController

    IRController -->|"invoke UseCase"| AppUseCase
    IRController --> IMiddleware

    AppUseCase -->|"with Request"| AppRequest
    AppUseCase -->|"creates"| userMain
    AppUseCase -->|"calls_repository"| DomainRepoInterface
    AppUseCase -->|"emits_event"| DomainEvent

    DomainRepoInterface -->|"implemented_by"| IDoctrine
    DomainEvent -->|"dispatches"| IEventDispatcher
    IEventDispatcher -->|"notifies"| IWelcomeListener

    IDoctrine -->|"persists_to"| MySQL
    IDoctrine -->|"uses"| DoctrineORM
    Adminer ---|"manages"| MySQL
    DockerPHP ---|"hosts"| IRController

    %% Click Events
    click clientIndex "https://github.com/oscarroman1230/php-ddd-user/blob/main/public/index.php"
    click clientHtaccess "https://github.com/oscarroman1230/php-ddd-user/blob/main/public/.htaccess"
    click AppUseCase "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Application/RegisterUser/RegisterUserUseCase.php"
    click AppRequest "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Application/RegisterUser/RegisterUserRequest.php"
    click userMain "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/User.php"
    click userEmail "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/Email.php"
    click userName "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/Name.php"
    click userPassword "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/Password.php"
    click userId "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/UserId.php"
    click DomainEvent "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/UserRegisteredEvent.php"
    click DomainRepoInterface "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Domain/User/UserRepositoryInterface.php"
    click IRController "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Infrastructure/Controller/RegisterUserController.php"
    click IDoctrine "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Infrastructure/Persistence/DoctrineUserRepository.php"
    click IEventDispatcher "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Infrastructure/Event/EventDispatcher.php"
    click IWelcomeListener "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Infrastructure/Event/SendWelcomeEmailListener.php"
    click IMiddleware "https://github.com/oscarroman1230/php-ddd-user/blob/main/src/Infrastructure/Middleware/ExceptionHandlerMiddleware.php"

    %% Styles
    classDef client fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef app fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef domain fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef infra fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef deploy fill:#D3D3D3,stroke:#333,stroke-width:2px;
```
