# edreyer/modulith architecture

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

- Interactive diagram: https://gitdiagram.com/edreyer/modulith
- Repository: https://github.com/edreyer/modulith

## Overview

##### Main Components
- Bounded Contexts: At least three core bounded contexts are present—Booking, Payment, and User. Each context follows the hexagonal layout with sub-components for domain, application (ports and workflows), and adapters (inbound for web APIs and outbound for persistence).
- Common Module: Contains shared configurations, utilities (logging, security, extension functions, etc.), and cross-cutting concerns. This module is used by all bounded contexts.
- Server Module: Acts as the compositional layer that bootstraps the application (entry point: ModulithApplication) and provides global configurations (like MongoDB, Jackson, and security configurations).
- External Dependencies: Include external services like the MongoDB database (as configured in the server’s MongoConfig) and potentially other external systems.

##### Relationships and Interactions
– Domain (core business logic using ADTs and DDD concepts)
– Application layer (ports for inbound commands and outbound events, including workflows)
– Adapters:
- Inbound (REST controllers, web configurations that drive the workflows)
- Outbound (persistence adapters, external service calls, event publishing adapters)
- Communications between the components:
– REST API calls hitting the input adapters in each module.
– Workflows orchestrated by the application layer processing Commands/Queries via CQRS.
– Outbound adapters interacting with persistence layers (using repositories and persistence configurations) and external systems.
– The server (or orchestrator) bringing together the various bounded contexts.

##### Important Architectural Patterns and Design Principles
- Hexagonal Architecture (Ports and Adapters): Emphasize the separation between the external world (adapters) and the inner domain logic. Show “port” interfaces that are implemented by inbound and outbound adapters.
- Domain-Driven Design: Identify that each bounded context (User, Booking, Payment) encapsulates its own domain model and that cross-cutting shared utilities live in the Common module.
- CQRS: Demonstrate that incoming commands and queries are handled by specific workflow objects that never throw exceptions but return results (discriminated unions representing success or error states).
- Event-Driven Messaging: Make clear where events are generated (as a result of workflows) and published via Spring’s event system to decouple persistence actions or inter-module communications.

##### Relevant Technologies, Frameworks, and Libraries
- Kotlin & Spring Boot: The core language and framework utilized.
- Maven Structure: Multi-module arrangement (each bounded context is a separate module).
- Coroutine Support: Indicate that non-blocking and asynchronous operations are achieved via Kotlin coroutines.
- MongoDB: As the persistence layer (see server’s MongoConfig and the persistence adapter configuration).
- Testing Frameworks: ArchUnit (for enforcing architectural constraints) as well as integration tests found under the test directories of each module.

##### Details and Essential Architectural Elements
- Don’t shy away from including every identifiable module based on the file tree: booking-api, booking, payment-api, payment, user-api, user, common, and server. This level of detail is essential to grasp how the modulith architecture isolates, yet interconnects, each bounded context.
- Both runtime interactions (via Spring’s application contexts and event-driven communication) and compile-time/module isolation (Maven artifacts and package design).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global nodes
    Client["Client Requests"]:::client
    ServerModule["Modulith Application (Server Module)"]:::server
    CommonModule["Common Module"]:::common
    MongoDB["MongoDB"]:::db

    %% Connections from Client to Server Module
    Client -->|"calls"| ServerModule

    %% Booking Bounded Context
    subgraph "Booking Bounded Context"
        bookingAPI["Booking API"]:::api
        bookingInbound["Booking Inbound Adapter (Web API)"]:::inbound
        bookingApp["Booking Application & Workflows"]:::app
        bookingDomain["Booking Domain"]:::domain
        bookingOutbound["Booking Outbound Adapter (Persistence)"]:::outbound
    end

    %% Payment Bounded Context
    subgraph "Payment Bounded Context"
        paymentAPI["Payment API"]:::api
        paymentInbound["Payment Inbound Adapter (Web API)"]:::inbound
        paymentApp["Payment Application & Workflows"]:::app
        paymentDomain["Payment Domain"]:::domain
        paymentOutbound["Payment Outbound Adapter (Persistence)"]:::outbound
    end

    %% User Bounded Context
    subgraph "User Bounded Context"
        userAPI["User API"]:::api
        userInbound["User Inbound Adapter (Web API)"]:::inbound
        userApp["User Application & Workflows"]:::app
        userDomain["User Domain"]:::domain
        userOutbound["User Outbound Adapter (Persistence)"]:::outbound
    end

    %% Server Module integrates with each Bounded Context API
    ServerModule -->|"registers"| bookingAPI
    ServerModule -->|"registers"| paymentAPI
    ServerModule -->|"registers"| userAPI

    %% Booking context flow
    bookingAPI -->|"to"| bookingInbound
    bookingInbound -->|"triggers"| bookingApp
    bookingApp -->|"invokes"| bookingDomain
    bookingDomain -->|"persists via"| bookingOutbound
    bookingOutbound -->|"saves to"| MongoDB
    bookingApp -.->|"uses"| CommonModule

    %% Payment context flow
    paymentAPI -->|"to"| paymentInbound
    paymentInbound -->|"triggers"| paymentApp
    paymentApp -->|"invokes"| paymentDomain
    paymentDomain -->|"persists via"| paymentOutbound
    paymentOutbound -->|"saves to"| MongoDB
    paymentApp -.->|"uses"| CommonModule

    %% User context flow
    userAPI -->|"to"| userInbound
    userInbound -->|"triggers"| userApp
    userApp -->|"invokes"| userDomain
    userDomain -->|"persists via"| userOutbound
    userOutbound -->|"saves to"| MongoDB
    userApp -.->|"uses"| CommonModule

    %% Click Events for Booking Bounded Context
    click bookingAPI "https://github.com/edreyer/modulith/blob/main/booking-api/src/main/kotlin/io/liquidsoftware/base/booking/application/port/in/BookingApi.kt"
    click bookingDomain "https://github.com/edreyer/modulith/tree/main/booking/src/main/kotlin/io/liquidsoftware/base/booking/domain"
    click bookingApp "https://github.com/edreyer/modulith/tree/main/booking/src/main/kotlin/io/liquidsoftware/base/booking/application"
    click bookingInbound "https://github.com/edreyer/modulith/tree/main/booking/src/main/kotlin/io/liquidsoftware/base/booking/adapter/in/web"
    click bookingOutbound "https://github.com/edreyer/modulith/tree/main/booking/src/main/kotlin/io/liquidsoftware/base/booking/adapter/out/persistence"

    %% Click Events for Payment Bounded Context
    click paymentAPI "https://github.com/edreyer/modulith/blob/main/payment-api/src/main/kotlin/io/liquidsoftware/base/payment/application/port/in/PaymentApi.kt"
    click paymentDomain "https://github.com/edreyer/modulith/tree/main/payment/src/main/kotlin/io/liquidsoftware/base/payment/domain"
    click paymentApp "https://github.com/edreyer/modulith/tree/main/payment/src/main/kotlin/io/liquidsoftware/base/payment/application"
    click paymentInbound "https://github.com/edreyer/modulith/tree/main/payment/src/main/kotlin/io/liquidsoftware/base/payment/adapter/in/web"
    click paymentOutbound "https://github.com/edreyer/modulith/tree/main/payment/src/main/kotlin/io/liquidsoftware/base/payment/adapter/out/persistence"

    %% Click Events for User Bounded Context
    click userAPI "https://github.com/edreyer/modulith/tree/main/user-api/src/main/kotlin/io/liquidsoftware/base/user/application/port/in"
    click userDomain "https://github.com/edreyer/modulith/tree/main/user/src/main/kotlin/io/liquidsoftware/base/user/domain"
    click userApp "https://github.com/edreyer/modulith/tree/main/user/src/main/kotlin/io/liquidsoftware/base/user/application"
    click userInbound "https://github.com/edreyer/modulith/tree/main/user/src/main/kotlin/io/liquidsoftware/base/user/adapter/in/web"
    click userOutbound "https://github.com/edreyer/modulith/tree/main/user/src/main/kotlin/io/liquidsoftware/base/user/adapter/out/persistence"

    %% Click Events for Common and Server Modules
    click CommonModule "https://github.com/edreyer/modulith/tree/main/common/src/main/kotlin/io/liquidsoftware/common"
    click ServerModule "https://github.com/edreyer/modulith/tree/main/server/src/main/kotlin/io/liquidsoftware/base/server"

    %% Styles
    classDef client fill:#F5DEB3,stroke:#333,stroke-width:2px;
    classDef server fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef api fill:#D8BFD8,stroke:#333,stroke-width:2px;
    classDef inbound fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef app fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef domain fill:#FFEB99,stroke:#333,stroke-width:2px;
    classDef outbound fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef common fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef db fill:#E6E6FA,stroke:#333,stroke-width:2px;
```
