How svenwoltmann/hexagonal-architecture-java works
Project Type and Purpose
• This is a Java REST application implemented according to the Hexagonal (Ports & Adapters) architecture.
• Its goal is to demonstrate how to structure a small online shop: defining a domain model, application services, inbound REST controllers, and outbound persistence adapters (in-memory and JPA).
• It’s a tutorial/sample project, not a full-stack app with a UI; it focuses on backend layers and clear separation of concerns.
File Structure Analysis
• Top-level modules (Maven):
• model: pure domain model (entities, value objects, exceptions)
• application: domain services (“use cases”) and inbound/outbound port interfaces
• adapter: implements ports – inbound REST controllers and outbound persistence adapters (in-memory & JPA)
• bootstrap: application entry point, wiring adapters and ports, RESTEasy + Undertow configuration
• Supporting directories:
• img: static images
• Key configuration files: persistence.xml (JPA), build CI workflow, pom.xml at root and per module.
README Insights
• Confirms four modules correspond to the hexagon’s layers.
• Describes technical stack: RESTEasy (Jakarta REST), Hibernate/JPA (Jakarta Persistence), Undertow web server.
• Shows how to switch adapters at runtime (in-memory vs. MySQL JPA).
a. Main Components
• Domain Model (model module)
• Application Core / Ports (application module)
• Inbound Adapters – REST controllers (adapter module)
• Outbound Adapters – Persistence implementations (in-memory and JPA) (adapter module)
• Bootstrap & Configuration (bootstrap module)
• External services: MySQL database or in-memory store
b. Relationships & Interactions
• REST controllers call Application use-case interfaces (ports in)
• Application services implement business logic, call Persistence ports (ports out)
• Persistence adapters implement port interfaces, read/write to DB or in-memory
• Bootstrap wires interfaces to concrete adapters and launches the web server
c. Architectural Patterns and Principles
• Hexagonal Architecture: central hexagon houses domain + application, surrounded by adapters
• Dependency Inversion: application layer depends only on port interfaces, not on adapter implementations
• Layered separation: clear boundaries between model, application logic, infrastructure code
d. Technologies & Frameworks
• RESTEasy + Jakarta WS for REST layer
• Hibernate/JPA for ORM and SQL persistence
• Undertow as embeddable web server
• Maven multi-module project structure
• Possibility to swap adapters at startup via VM properties
Sketch a central hexagon labeled “Application Core” containing
– Ports In (AddToCartUseCase, GetCartUseCase, EmptyCartUseCase, FindProductsUseCase)
– Application Services (AddToCartService, GetCartService, EmptyCartService, FindProductsService)
– Ports Out (CartRepository, ProductRepository)
– Cart, CartLineItem, Product, Money, CustomerId
At the bottom/right, show bootstrap
– Launcher class, wiring logic
6. Modules (Maven modules names), and include VM switch for persistence selection.