# svenwoltmann/hexagonal-architecture-java architecture

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

- Interactive diagram: https://gitdiagram.com/svenwoltmann/hexagonal-architecture-java
- Repository: https://github.com/svenwoltmann/hexagonal-architecture-java

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Model Module
    subgraph "Model Module"
        DM["Domain Model"]:::core
    end

    %% Application Core
    subgraph "Application Core"
        subgraph "Ports In"
            AC1["AddToCartUseCase"]:::core
            AC2["GetCartUseCase"]:::core
            AC3["EmptyCartUseCase"]:::core
            AC4["FindProductsUseCase"]:::core
        end
        subgraph "Services"
            S1["AddToCartService"]:::core
            S2["GetCartService"]:::core
            S3["EmptyCartService"]:::core
            S4["FindProductsService"]:::core
        end
        subgraph "Ports Out"
            PO1["CartRepository"]:::core
            PO2["ProductRepository"]:::core
        end
    end

    %% Inbound Adapters
    subgraph "Inbound Adapters"
        C1["AddToCartController"]:::inbound
        C2["GetCartController"]:::inbound
        C3["EmptyCartController"]:::inbound
        C4["FindProductsController"]:::inbound
    end

    %% Outbound Adapters
    subgraph "Outbound Adapters"
        subgraph "In-Memory"
            IM1["InMemoryCartRepository"]:::outbound
            IM2["InMemoryProductRepository"]:::outbound
        end
        subgraph "JPA"
            JPA1["JpaCartRepository"]:::outbound
            JPA2["JpaProductRepository"]:::outbound
            PXML["persistence.xml"]:::outbound
        end
        Demo["DemoProducts"]:::outbound
    end

    %% Infrastructure
    BR["MySQL Database"]:::infra
    MI["In-Memory Store"]:::infra
    BB["Bootstrap & Wiring"]:::infra

    %% Relationships
    C1 -->|calls| AC1
    C2 -->|calls| AC2
    C3 -->|calls| AC3
    C4 -->|calls| AC4

    AC1 -->|implemented by| S1
    AC2 -->|implemented by| S2
    AC3 -->|implemented by| S3
    AC4 -->|implemented by| S4

    DM -->|used by| S1
    DM -->|used by| S2
    DM -->|used by| S3
    DM -->|used by| S4

    S1 -->|uses| PO1
    S2 -->|uses| PO2
    S3 -->|uses| PO1
    S4 -->|uses| PO2

    PO1 -->|implemented by| IM1
    PO1 -->|implemented by| JPA1
    PO2 -->|implemented by| IM2
    PO2 -->|implemented by| JPA2

    JPA1 -->|writes to| BR
    JPA2 -->|writes to| BR
    IM1 -->|stores in| MI
    IM2 -->|stores in| MI

    BB -->|wires| C1
    BB -->|wires| C2
    BB -->|wires| C3
    BB -->|wires| C4
    BB -->|wires| IM1
    BB -->|wires| IM2
    BB -->|wires| JPA1
    BB -->|wires| JPA2

    %% Click Events
    click DM "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/model/src/main/java/eu/happycoders/shop/model"
    click AC1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/in"
    click AC2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/in"
    click AC3 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/in"
    click AC4 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/in"
    click PO1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/out/persistence"
    click PO2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/port/out/persistence"
    click S1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/service"
    click S2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/service"
    click S3 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/service"
    click S4 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/application/src/main/java/eu/happycoders/shop/application/service"
    click C1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/in/rest"
    click C2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/in/rest"
    click C3 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/in/rest"
    click C4 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/in/rest"
    click IM1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/out/persistence/inmemory"
    click IM2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/out/persistence/inmemory"
    click JPA1 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/out/persistence/jpa"
    click JPA2 "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/adapter/src/main/java/eu/happycoders/shop/adapter/out/persistence/jpa"
    click PXML "https://github.com/svenwoltmann/hexagonal-architecture-java/blob/main/adapter/src/main/resources/META-INF/persistence.xml"
    click BB "https://github.com/svenwoltmann/hexagonal-architecture-java/tree/main/bootstrap/src/main/java/eu/happycoders/shop/bootstrap"
    click Demo "https://github.com/svenwoltmann/hexagonal-architecture-java/blob/main/adapter/src/main/java/eu/happycoders/shop/adapter/out/persistence/DemoProducts.java"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef inbound fill:#bbf,stroke:#333,stroke-width:2px;
    classDef outbound fill:#bfb,stroke:#333,stroke-width:2px;
    classDef infra fill:#fbf,stroke:#333,stroke-width:2px;
```
