# naspredam/rest-spring-boot-hexagonal-architecture architecture

> Architecture diagram of the GitHub repository naspredam/rest-spring-boot-hexagonal-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/naspredam/rest-spring-boot-hexagonal-architecture
- Repository: https://github.com/naspredam/rest-spring-boot-hexagonal-architecture

## Overview

##### Project Type and Purpose
- This is a backend microservice built with Spring Boot implementing a classic Hexagonal (Ports & Adapters) or Clean Architecture.
- Its sole responsibility is user management exposed over a REST API backed by a relational database (with Liquibase changelogs).

##### High-Level File Structure Analysis
- src/main/java/com/example/service/user
- adapter – Implements inbound (REST controllers) and outbound (JPA) ports
- application – Defines ports (interfaces) and application services / use cases
- domain – Core business model (entities, value objects, domain functions)
- infrastructure – Cross-cutting concerns (validators, custom annotations)
- src/main/resources
- application.yaml – app configuration
- db/changelog – Liquibase DB migrations
- build.gradle, gradle wrapper – build and dependency management

##### README Insights
- Confirms Hexagonal Architecture:
- Orange = Domain
- Blue = Application (use cases & ports)
- Green = Adapters (controllers & repositories)
- Mentions architecture tests via ArchUnit in com.example.service.user.architecture.

##### Main Components
a. Client / API Consumer
- External clients (Postman, web app, mobile) invoke REST endpoints.
b. Inbound Adapter
- UserController, ChangeUserEndpointAdapter, FindUserEndpointAdapter
- Maps HTTP requests → application ports / DTOs
c. Application Layer
- Ports: FindUserEndpointPort, ChangeUserEndpointPort
- Use Cases / Services: SubmitNewUserUseCase, FindUserByIdUseCase, ChangeExistingUserUseCase, DeleteUsersByIdUseCase
- Encapsulates business workflows
d. Domain Layer
- Entities: User (aggregate root)
- Value Objects: FullName, Phone, UserId
- Domain Functions: UserFunctions utility
e. Outbound Adapter
- ReadUserAdapter, WriteUserAdapter
- Uses UserRepository (Spring Data JPA) and UserJpaMapper → CRUD in DB
f. Infrastructure
- ObjectValidator for @Adapter, @Mapper validation
- Shared cross-cutting code
g. Database
- Relational DB (Liquibase migrations under src/main/resources/db)

##### Relationships and Data Flow
- Client → HTTP → Inbound Adapter (Controller)
- Controller → DTO Mapper → Application Port Interface
- Application Port → Application Service / Use Case
- Service → Domain (validate & manipulate User entity)
- Service → Persistence Port (ReadUserPort / WriteUserPort interfaces)
- Persistence Adapter → JPA Repository → Database
- Infrastructure components (validators, mappers) intervene via AOP or dependency injection

##### Architectural Patterns & Principles
- Hexagonal / Ports and Adapters: clear separation between core (domain & application) and infrastructure
- Dependency Inversion: application & domain define interfaces (ports) which adapters implement
- Single Responsibility: each class has one reason to change (controllers, services, adapters, mappers, validators)
- Layered testing: unit tests per layer + integration on controller + ArchUnit rules

##### Final Recommendations
- Be exhaustive: represent all 4 main layers plus infrastructure and external DB.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    Client["External Client"]:::external

    %% Inbound Adapter Layer
    subgraph "Adapters Layer (Inbound)" 
        direction TB
        UC["UserController\n(Inbound Adapter)"]:::adapter
        CA["ChangeUserEndpointAdapter"]:::adapter
        FA["FindUserEndpointAdapter"]:::adapter
        DM["UserDtoMapper"]:::adapter
        SU["SaveUserBodyDto"]:::adapter
        UD["UserDto"]:::adapter
    end

    %% Application Layer
    subgraph "Application Layer" 
        direction TB
        subgraph "Ports (Entrypoint)" 
            direction TB
            CEP["FindUserEndpointPort"]:::port
            CPP["ChangeUserEndpointPort"]:::port
        end
        subgraph "Use Cases" 
            direction TB
            SUC["SubmitNewUserUseCase"]:::usecase
            FUB["FindUserByIdUseCase"]:::usecase
            CEU["ChangeExistingUserUseCase"]:::usecase
            DUB["DeleteUsersByIdUseCase"]:::usecase
            FAU["FindAllUsersUseCase"]:::usecase
        end
        subgraph "Ports (Persistence)" 
            direction TB
            RUP["ReadUserPort"]:::port
            WUP["WriteUserPort"]:::port
        end
    end

    %% Domain Layer
    subgraph "Domain Layer" 
        direction TB
        U["User"]:::domain
        FN["FullName"]:::domain
        P["Phone"]:::domain
        UI["UserId"]:::domain
        UF["UserFunctions"]:::domain
    end

    %% Outbound Adapter Layer
    subgraph "Adapters Layer (Outbound)" 
        direction TB
        RUA["ReadUserAdapter"]:::adapter
        WUA["WriteUserAdapter"]:::adapter
        JM["UserJpaMapper"]:::adapter
        UR["UserRepository"]:::adapter
        UD2["UserData"]:::adapter
    end

    %% Database
    DB[("Relational Database\n(Liquibase)")]:::database

    %% Infrastructure
    subgraph "Infrastructure" 
        direction TB
        OV["ObjectValidator"]:::infra
        AN1["@Adapter Annotation"]:::infra
        AN2["@Mapper Annotation"]:::infra
    end

    %% Connections
    Client -->|"HTTP/JSON"| UC
    UC -->|calls| CEP
    CA -->|calls| CPP
    FA -->|calls| CEP
    DM -->|maps HTTP↔DTO| SU
    SUC -->|uses| RUP
    SUC -->|uses| WUP
    FUB -->|uses| RUP
    CEU -->|uses| WUP
    DUB -->|uses| WUP
    FAU -->|uses| RUP
    CEP -->|invoke| SUC
    CPP -->|invoke| CEU
    RUP -->|port→adapter| RUA
    WUP -->|port→adapter| WUA
    RUA -->|calls JpaRepo| UR
    WUA -->|calls JpaRepo| UR
    JM -->|maps| UD2
    UR -->|CRUD| DB

    %% Infrastructure injection
    OV -.->|validates| UC
    OV -.->|validates| RUA
    AN1 -.-> UC
    AN2 -.-> JM

    %% Click Events
    click UC "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/UserController.java"
    click CA "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/ChangeUserEndpointAdapter.java"
    click FA "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/FindUserEndpointAdapter.java"
    click DM "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/UserDtoMapper.java"
    click SU "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/model/SaveUserBodyDto.java"
    click UD "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/entrypoint/api/model/UserDto.java"
    click CEP "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/port/entrypoint/api/FindUserEndpointPort.java"
    click CPP "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/port/entrypoint/api/ChangeUserEndpointPort.java"
    click RUP "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/port/persistence/ReadUserPort.java"
    click WUP "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/port/persistence/WriteUserPort.java"
    click SUC "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/usecase/SubmitNewUserUseCase.java"
    click FUB "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/usecase/FindUserByIdUseCase.java"
    click CEU "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/usecase/ChangeExistingUserUseCase.java"
    click DUB "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/usecase/DeleteUsersByIdUseCase.java"
    click FAU "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/application/usecase/FindAllUsersUseCase.java"
    click U "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/domain/User.java"
    click FN "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/domain/FullName.java"
    click P "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/domain/Phone.java"
    click UI "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/domain/UserId.java"
    click UF "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/domain/UserFunctions.java"
    click RUA "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/persistence/ReadUserAdapter.java"
    click WUA "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/persistence/WriteUserAdapter.java"
    click JM "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/persistence/UserJpaMapper.java"
    click UR "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/persistence/UserRepository.java"
    click UD2 "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/adapter/persistence/model/UserData.java"
    click OV "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/infrastructure/validator/ObjectValidator.java"
    click AN1 "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/infrastructure/annotations/Adapter.java"
    click AN2 "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/java/com/example/service/user/infrastructure/annotations/Mapper.java"
    click DB "https://github.com/naspredam/rest-spring-boot-hexagonal-architecture/blob/main/src/main/resources/db/changelog/db.changelog-master.yaml"

    %% Styles
    classDef adapter fill:#b2f2bb,stroke:#2d6a4f,color:#1b4332
    classDef application fill:#ade8f4,stroke:#0077b6,color:#03045e
    classDef port fill:#caf0f8,stroke:#0096c7,color:#03045e
    classDef usecase fill:#90e0ef,stroke:#0077b6,color:#03045e
    classDef domain fill:#ffc8a2,stroke:#e85d04,color:#6a040f
    classDef infra fill:#e5e5e5,stroke:#6c757d,color:#343a40
    classDef database fill:#ffd6a5,stroke:#d00000,color:#6a040f
    classDef external fill:#ffffff,stroke:#000000,color:#000000,stroke-dasharray: 5 5
    class DM,SU,UD2,UR application
    class SUC,FUB,CEU,DUB,FAU usecase
```
