# xsreality/spring-modulith-with-ddd architecture

> Architecture diagram of the GitHub repository xsreality/spring-modulith-with-ddd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xsreality/spring-modulith-with-ddd
- Repository: https://github.com/xsreality/spring-modulith-with-ddd

## Overview

##### Project type and purpose
- This is a backend-only “modular monolith” built with Spring Boot, Spring Modulith and Domain-Driven Design.
- Purpose: manage library operations (catalog management, holds & checkouts) with OAuth2 security via Keycloak.

##### File structure
- Top-level modules (bounded contexts) under `src/main/java/example`:
- catalog – book catalog management
- borrow  – hold & checkout workflows
- useraccount – shared security integration (JWT conversion, argument resolvers)
- Each module follows a Hexagonal/Docker-style layering:
- application – service APIs (use-case layer)
- domain – core entities & repositories (domain layer)
- infrastructure / ui / web – REST controllers (interface adapters)
- Root configs: `LibraryApplication.java`, `LibraryWebSecurityConfiguration`, Spring Modulith annotations for module partitioning.
- `application.yaml`, Maven (`pom.xml`), Docker Compose + Keycloak realm JSON.

##### README for additional insights
- Explicit mention of Spring Modulith modularization & eventual consistency.
- OAuth2 flows via Keycloak (external Authorization server).
- Single Docker Compose stack: application + Keycloak.
- Database interactions via Spring Data JPA (SQL scripts under `src/test/resources`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Modules
    subgraph "Catalog Module" 
        direction TB
        CC["CatalogController"]:::catalog
        CM["CatalogManagement"]:::catalog
        BD["BookDto"]:::catalog
        BE["BookAddedToCatalog"]:::catalog
        CEntity["CatalogBook"]:::catalog
        CRepo["CatalogRepository"]:::catalog
    end

    subgraph "Borrow Module"
        direction TB
        CDC["CirculationDeskController"]:::borrow
        CD["CirculationDesk"]:::borrow
        HI["HoldInformation"]:::borrow
        BEntity["Book"]:::borrow
        HEntity["Hold"]:::borrow
        PEntity["Patron"]:::borrow
        BRepo["BookRepository"]:::borrow
        HRepo["HoldRepository"]:::borrow
    end

    subgraph "UserAccount Module"
        direction TB
        UA["UserAccount"]:::security
        KAuth["KeycloakJwtAuthenticationConverter"]:::security
        AResolver["AuthenticatedUserArgumentResolver"]:::security
    end

    subgraph "Core Infrastructure"
        direction TB
        SEC["LibraryWebSecurityConfiguration"]:::infra
        ENTRY["LibraryApplication"]:::infra
        DB["Library DB (JPA)"]:::infra
        BUS["Spring Modulith Event Bus"]:::infra
    end

    %% External
    Keycloak["Keycloak (OAuth2 / OpenID)"]:::external
    Client["Client"]:::external
    Maven["Maven (pom.xml)"]:::external
    DockerComp["Docker Compose"]:::external

    %% Relationships
    Client -->|"HTTP Request"| CC
    Client -->|"HTTP Request"| CDC

    AResolver -->|used by| CC
    AResolver -->|used by| CDC

    CC -->|"calls"| CM
    CM -->|"uses"| BD
    CM -->|"manipulates"| CEntity
    CEntity -->|"persist via JPA"| CRepo
    CRepo -->|"CRUD"| DB

    CM -->|-->|BE
    BE -.->|async event| BUS

    BUS -.->|consumes| CD

    CDC -->|"calls"| CD
    CD -->|"uses"| HI
    CD -->|"manipulates"| BEntity
    BEntity -->|"persist via JPA"| BRepo
    BRepo -->|"CRUD"| DB
    CD -->|"manipulates"| HEntity
    HEntity -->|"persist via JPA"| HRepo
    HRepo -->|"CRUD"| DB
    PEntity -->|"persist via JPA"| DB

    %% Security
    Client -->|Bearer Token| SEC
    SEC -->|"token introspection"| Keycloak
    KeycloakJwtAuthenticationConverter -->|converts JWT| SEC

    ENTRY -->|starts| CC
    ENTRY -->|starts| CDC
    ENTRY -->|configures| SEC

    %% Build & Deploy
    Maven -->|builds| ENTRY
    ENTRY -->|Docker Image| DockerComp
    DockerComp -->|orchestrates| Keycloak
    DockerComp -->|orchestrates| ENTRY

    %% Click Events
    click CC "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/ui/CatalogController.java"
    click CM "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/application/CatalogManagement.java"
    click BD "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/application/BookDto.java"
    click BE "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/BookAddedToCatalog.java"
    click CEntity "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/domain/CatalogBook.java"
    click CRepo "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/catalog/domain/CatalogRepository.java"

    click CDC "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/infrastructure/CirculationDeskController.java"
    click CD "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/application/CirculationDesk.java"
    click HI "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/application/HoldInformation.java"
    click BEntity "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/domain/Book.java"
    click HEntity "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/domain/Hold.java"
    click PEntity "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/domain/Patron.java"
    click BRepo "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/domain/BookRepository.java"
    click HRepo "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/borrow/domain/HoldRepository.java"

    click UA "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/useraccount/UserAccount.java"
    click KAuth "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/useraccount/KeycloakJwtAuthenticationConverter.java"
    click AResolver "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/useraccount/web/AuthenticatedUserArgumentResolver.java"

    click ENTRY "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/LibraryApplication.java"
    click SEC "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/src/main/java/example/LibraryWebSecurityConfiguration.java"

    click Maven "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/pom.xml"
    click DockerComp "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/docker-compose.yml"
    click Keycloak "https://github.com/xsreality/spring-modulith-with-ddd/blob/main/keycloak-realm/library-realm.json"

    %% Styles
    classDef catalog fill:#D6EAF8,stroke:#1A5276,color:#1A5276
    classDef borrow fill:#D5F5E3,stroke:#196F3D,color:#196F3D
    classDef security fill:#FDEBD0,stroke:#B9770E,color:#B9770E
    classDef infra fill:#FADBD8,stroke:#922B21,color:#922B21
    classDef external fill:#F5CBA7,stroke:#7D6608,color:#7D6608
```
