# spring-projects/spring-modulith architecture

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

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

## Overview

##### Main Components
- Modules/Artifacts: Represent each top-level module (spring-modulith-core, spring-modulith-api, spring-modulith-apt, spring-modulith-actuator, spring-modulith-events, spring-modulith-docs, spring-modulith-runtime, spring-modulith-starters, spring-modulith-test, etc.). Each of these modules is built to support a certain domain:
– Core / API: Provides the model for application modules and common utilities.
– APT (Annotation Processing): Processes annotations to verify module structure.
– Actuator: Exposes module details and integrates with Spring Boot Actuator.
– Events: Manages domain events (with separate implementations for AMQP, JDBC, Kafka, JMS, etc.).
– Observability/Runtime: Monitors module behavior and metrics.
– Starters & Test components: Provide simplified integration for end-users and testing support.
– Examples/Integration tests: Show sample modular applications and verify integrity.

##### Relationships & Interactions
– The core and API modules form the foundation; other modules (like the actuator and events modules) depend on them.
– The APT module works during compile time to analyze the same package structures that the core uses at runtime.
– Documentation tools (spring-modulith-docs) and testing (spring-modulith-test) integrate with the core model (ApplicationModules) and use outputs from the verification process.
– Starters are thin wrappers that pull in the relevant modules for a Spring Boot application.
- How integration tests (under test directories) leverage specific modules (e.g., “module integration tests” in the examples).

##### Architectural Patterns & Design Principles
- Modular design: The concept of “application modules” is central. These are typically defined by Java packages that are direct subpackages of the application’s base package.
- Annotated Unit and Integration Tests: The project provides support to test individual modules separately.
- Separation of concerns: Core models are isolated from extension modules (e.g., actuator, events, runtime, documentation) which implement specific cross-cutting concerns.
- Build and dependency management through Maven (the use of a BOM and Maven wrapper across modules reinforces version consistency and modular independence).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core/ API Layer
    subgraph "Core/ API Layer"
        C1["spring-modulith-core"]:::core
        C2["spring-modulith-api"]:::core
    end

    %% Compile-Time Tools
    subgraph "Compile-Time Tools"
        APT["spring-modulith-apt"]:::build
    end

    %% Extension Modules
    subgraph "Extension Modules"
        ACT["spring-modulith-actuator"]:::extension
        EV["spring-modulith-events (AMQP,JDBC,etc.)"]:::extension
        DOC["spring-modulith-docs"]:::extension
        RT["spring-modulith-runtime"]:::extension
    end

    %% Integration & Startup Modules
    subgraph "Integration & Startup Modules"
        ST["spring-modulith-starters"]:::integration
        TEST["spring-modulith-test"]:::integration
    end

    %% Examples & Integration Testing
    subgraph "Sample Applications"
        EX["Examples/Integration Tests"]:::sample
        INT["Integration Tests"]:::sample
    end

    %% External Dependencies
    EXTD["Spring Boot/Maven/Docker"]:::external

    %% Relationships
    C1 -->|"provides foundation"| C2
    APT -->|"analyzes"| C1
    APT -->|"analyzes"| C2
    
    C1 -->|"used by"| ACT
    C2 -->|"used by"| ACT

    C1 -->|"used by"| EV
    C2 -->|"used by"| EV

    C1 -->|"drives"| DOC
    C2 -->|"drives"| DOC

    C1 -->|"monitored by"| RT
    C2 -->|"monitored by"| RT

    ST -->|"wraps"| C1
    ST -->|"wraps"| C2

    TEST -->|"verifies"| C1
    TEST -->|"verifies"| EV
    TEST -->|"verifies"| DOC

    EX -->|"demonstrates"| C1
    EX -->|"demonstrates"| C2
    
    INT -->|"verifies integration"| C1

    EXTD -->|"integrates with"| C2

    %% Styles
    classDef core fill:#A9D18E,stroke:#333,stroke-width:2px;
    classDef build fill:#BDD7EE,stroke:#333,stroke-width:2px;
    classDef extension fill:#F4B084,stroke:#333,stroke-width:2px;
    classDef integration fill:#D9D9D9,stroke:#333,stroke-width:2px;
    classDef sample fill:#FFD966,stroke:#333,stroke-width:2px;
    classDef external fill:#C4D79B,stroke:#333,stroke-width:2px;

    %% Click Events
    click C1 "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-core/"
    click C2 "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-api/"
    click APT "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-apt/"
    click ACT "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-actuator/"
    click EV "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-events/"
    click DOC "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-docs/"
    click RT "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-runtime/"
    click ST "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-starters/"
    click TEST "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-test/"
    click EX "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-examples/"
    click INT "https://github.com/spring-projects/spring-modulith/tree/main/spring-modulith-integration-test/"
```
