How naspredam/rest-spring-boot-hexagonal-architecture works
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.