# cafedemo/modulith architecture

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

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

## Overview

##### Project Type and Purpose
- This is a Spring Boot-based modular monolith demo showcasing the Spring Modulith concept.
- Its purpose is to demonstrate how a modular design can be achieved within a monolithic Spring application by dividing functionality into separate modules—namely, the Common, Shop, and Barista modules.
- The README also highlights external observability components (Prometheus, Grafana, and Tempo) and a sample API file for testing.

##### Analysis of the File Structure
- The top-level directories include configuration files (e.g., build.gradle.kts, settings.gradle.kts), infrastructure-related folders (db for database configurations and migrations in src/main/resources/db), operations tools (ops for Grafana, Prometheus, etc.), and source code (src/main/java).
- Under src/main/java/tut/dushyant/modulith/cafe, the code is organized into sub-packages corresponding to the modules:
- common: shared DTOs, events, and exception handling.
- shop: contains data repositories, service layers, and web resource controllers specifically for shop-related functionality.
- barista: similarly organized for barista-related functionality.
- The modular structure is evident with each module following similar separation subdirectories (events, internal for repositories, service, web).
- There are also evident database migration scripts and configuration files, as well as monitoring and observability configurations under ops and docs.

a. Main Components:
- Application Entry Point: Highlight the main class (CafeApplication.java).
- Three Domain Modules:
- Common Module (shared utilities, DTOs, exception handling)
- Shop Module (shop domain-specific services, repositories, web resources, events)
- Barista Module (barista domain-specific services, repositories, events, web resources)
- Infrastructure Components:
- Database Layer: Represented by SQL migration scripts and the “db” directory which manage the PostgreSQL configurations.
- External Services: Add Prometheus for metrics, Grafana Tempo for traces, along with the corresponding configuration files under the ops folder.
- Build & Deployment: Indicate the Gradle build system (build.gradle.kts, settings.gradle.kts) and containerization aspects (compose.yaml for Docker/Podman).

b. Relationships and Interactions:
- The Application Entry Point initiates the Spring Boot lifecycle and wires together the modules.
- Each module (common, shop, barista) interacts with its own internal components:
- Web Controllers expose API endpoints that interact with service layers.
- Service layers use repository classes (data access layer) to interact with the database.
- Event classes in each module indicate internal messaging and decoupled communication within a module, and possibly across modules.
- The Common module provides shared DTOs, exception handling, and base event classes used by both Shop and Barista modules.
- External communications include API requests (as demonstrated in apitest.http) and observability integration (Prometheus/Grafana/Tempo).

c. Architectural Patterns and Design Principles:
- It uses repository and service patterns within each module.
- Event-driven designs appear to be in place for tracking domain events (e.g., BaristaCreateEvent, ShopCreatedEvent).
- Clear separation of concerns is maintained between the web layer, service layer, and data access layer.

d. Relevant Technologies and Frameworks:
- Spring Boot for application configuration and runtime.
- Gradle for building the application.
- PostgreSQL as the database (supported by SQL migration scripts).
- Prometheus and Grafana Tempo for observability.
- Docker/Podman for containerized deployment (as hinted by the compose.yaml file).

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Application Entry (CafeApplication)"]:::application

    subgraph "Modules"
        CM["Common Module"]:::modular

        subgraph "Shop Module"
            ShopW["Shop Web Controllers"]:::internal
            ShopS["Shop Service Layer"]:::internal
            ShopR["Shop Repository"]:::internal
            ShopE["Shop Events"]:::internal
        end

        subgraph "Barista Module"
            BaristaW["Barista Web Controllers"]:::internal
            BaristaS["Barista Service Layer"]:::internal
            BaristaR["Barista Repository"]:::internal
            BaristaE["Barista Events"]:::internal
        end
    end

    DB["Database (Migration & Config)"]:::database

    subgraph "External Observability"
        Prom["Prometheus"]:::external
        Graf["Grafana"]:::external
        Tempo["Tempo"]:::external
    end

    subgraph "Build & Deployment"
        Gradle["Gradle Build\n(build.gradle.kts & settings.gradle.kts)"]:::build
        Compose["Containerization\n(compose.yaml)"]:::build
    end

    APITest["API Testing (apitest.http)"]:::external

    %% Connections
    A -->|"initializes"| CM
    A -->|"starts"| ShopW
    A -->|"starts"| BaristaW

    ShopW -->|"calls"| ShopS
    ShopS -->|"uses"| ShopR
    ShopS -->|"emits"| ShopE

    BaristaW -->|"calls"| BaristaS
    BaristaS -->|"uses"| BaristaR
    BaristaS -->|"emits"| BaristaE

    ShopR -->|"accesses"| DB
    BaristaR -->|"accesses"| DB

    ShopE -->|"sharesEventsWith"| CM
    BaristaE -->|"sharesEventsWith"| CM

    A -->|"sendsMetricsTo"| Prom
    A -->|"sendsMetricsTo"| Graf
    A -->|"sendsTracesTo"| Tempo

    Gradle -->|"builds"| A
    Compose -->|"deploys"| A

    APITest -->|"tests"| A

    %% Styles
    classDef application fill:#D1E8FF,stroke:#007BFF,stroke-width:2px,color:#000;
    classDef modular fill:#FFECB3,stroke:#FF9800,stroke-width:2px,color:#000;
    classDef internal fill:#D1F2EB,stroke:#26A69A,stroke-width:2px,color:#000;
    classDef database fill:#FFE0B2,stroke:#FB8C00,stroke-width:2px,color:#000;
    classDef external fill:#E1BEE7,stroke:#9C27B0,stroke-width:2px,color:#000;
    classDef build fill:#FFCDD2,stroke:#E53935,stroke-width:2px,color:#000;

    %% Click Events
    click A "https://github.com/cafedemo/modulith/blob/main/src/main/java/tut/dushyant/modulith/cafe/CafeApplication.java"
    click CM "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/common"
    click ShopW "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/shop/web"
    click ShopS "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/shop/service"
    click ShopR "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/shop/internal/data/repo"
    click ShopE "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/shop/events"
    click BaristaW "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/barista/web"
    click BaristaS "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/barista/service"
    click BaristaR "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/barista/internal/data/repo"
    click BaristaE "https://github.com/cafedemo/modulith/tree/main/src/main/java/tut/dushyant/modulith/cafe/barista/events"
    click DB "https://github.com/cafedemo/modulith/tree/main/src/main/resources/db"
    click Prom "https://github.com/cafedemo/modulith/blob/main/ops/prometheus.yaml"
    click Graf "https://github.com/cafedemo/modulith/tree/main/ops/grafana"
    click Tempo "https://github.com/cafedemo/modulith/blob/main/ops/tempo.yaml"
    click Gradle "https://github.com/cafedemo/modulith/blob/main/build.gradle.kts"
    click Compose "https://github.com/cafedemo/modulith/blob/main/compose.yaml"
    click APITest "https://github.com/cafedemo/modulith/blob/main/apitest.http"
```
