# clockworkorange/clean-architecture-with-commands-and-events architecture

> Architecture diagram of the GitHub repository clockworkorange/clean-architecture-with-commands-and-events, 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/clockworkorange/clean-architecture-with-commands-and-events
- Repository: https://github.com/clockworkorange/clean-architecture-with-commands-and-events

## Overview

Based on our analysis of the provided file tree and the README, we can see that this is a Java project following a “clean architecture” (or hexagonal architecture) approach. The project is split into multiple Maven modules that clearly separate the core business logic (domain), application orchestration/service layer (application), and external integrations such as APIs, persistence, and messaging (infrastructure). In addition, there’s a root module that houses Docker deployment assets and end-to-end or integration tests.

##### Main Components
- Domain Module:
- Contains core business entities (e.g., Account), commands (e.g., CreateAccountCommand), events (e.g., AccountCreated, AccountCanceled), and custom exceptions.
- This layer is independent of any external frameworks.
- Application Module:
- Implements business services (AccountService), domain event publishing (DomainEventPublisher), metrics (MetricSender), and possibly some interceptor mechanisms (LoggingInterceptor).
- Acts as a coordinator between user actions and the core domain logic.
- Infrastructure Module:
- Deals with APIs, controllers (AccountController, GreetingController), mapping (AccountMapper), repository implementations (AccountMemoryRepository, AccountOracleRepository) and data persistence, as well as metrics and publisher implementations.
- This module is responsible for connecting the inner layers to external systems.
- Root Module / Docker & Testing:
- Contains Dockerfiles for JVM, native images and distroless configurations, indicating containerized deployment.
- Holds integration tests and cucumber features that test the overall system integration and external interactions.

##### Relationships and Interactions
- The Infrastructure layer exposes endpoints (APIs) that receive external requests.
- The API controllers forward requests to the Application layer, where service classes (like AccountService) process business logic.
- Application interacts with the Domain layer, invoking domain entities, commands, and handling events.
- The Domain layer encapsulates core business rules and is designed to be free of any external dependency.
- Data persistence and external communications (metrics and publishing domain events) are handled by the Infrastructure, using mapped repository interfaces (AccountMemoryRepository, AccountOracleRepository) and event publishers.
- There’s clear data flow: External -> Infrastructure (API Requests) -> Application (Services, Business Logic) -> Domain (Core Rules/Entities) and back out via Infrastructure for persistence or messaging.

##### Architectural Patterns and Design Principles
- Clean Architecture: The main focus is on separating concerns, where business logic (Domain) does not depend on outer layers (Application or Infrastructure).
- Dependency Inversion: The structure implies that higher-level modules do not depend on lower level implementations; rather, interfaces and abstractions are defined at the appropriate layers (e.g., repository interfaces in the Application/Domain and implemented in Infrastructure).
- Modularization: Use of Maven multi-module setup to independently manage core domain logic, application orchestration and infrastructure concerns.
- Interceptors and Metrics: Within the Application layer, interceptors (LoggingInterceptor) and metrics (MetricSender) denote cross-cutting concerns that should be represented as cross-layer integrations.

##### Relevant Technologies, Frameworks, and Libraries
- Java + Maven for dependency management.
- Likely use of RESTful APIs (based on the existence of controllers).
- Repository patterns with multiple implementations (in-memory and Oracle repositories).
- Metrics support via Micrometer (as seen from MetricMicrometerSender and related metric senders).
- Docker for containerized deployment (multiple Dockerfile variants).
- Testing frameworks for integration testing (Cucumber) and unit tests.

##### Detail and Clarity
- That each component appears as a clearly labeled element.
- Annotating each interaction with notes on the protocols (e.g., REST API calls, repository method calls, asynchronous event publishing).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Actor
    EXT["External HTTP Request"]:::externalColor

    %% Domain Layer
    subgraph "Domain"
        D1["Account Entity"]:::domainColor
        D2["Domain Commands(e.g.,CreateAccountCommand)"]:::domainColor
        D3["Domain Events(AccountCreated,AccountCanceled)"]:::domainColor
        D4["Custom Exceptions"]:::domainColor
    end

    %% Application Layer
    subgraph "Application"
        A1["AccountService"]:::applicationColor
        A2["DomainEventPublisher"]:::applicationColor
        A3["MetricSender"]:::applicationColor
        A4["LoggingInterceptor"]:::applicationColor
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        I1["AccountController"]:::infrastructureColor
        I2["GreetingController"]:::infrastructureColor
        I3["AccountMapper"]:::infrastructureColor
        I4["AccountMemoryRepository"]:::infrastructureColor
        I5["AccountOracleRepository"]:::infrastructureColor
        I6["CounterMetricSender"]:::infrastructureColor
        I7["GreetingsMetricSender"]:::infrastructureColor
        %% Deployment and Testing Block inside Infrastructure for clarity
        IT1["Docker Deployment Assets"]:::infrastructureColor
        IT2["Integration & Cucumber Tests"]:::infrastructureColor
    end

    %% Data Flow and Interactions
    %% External to Infrastructure
    EXT -->|"REST"| I1
    EXT -->|"REST"| I2

    %% Infrastructure Controllers call Application Service
    I1 -->|"calls"| A1
    I2 -->|"calls"| A1

    %% Application Service invokes Domain
    A1 -->|"invokes"| D1
    A1 -->|"sendsCommand"| D2
    A1 -->|"triggersEvent"| D3
    A1 -->|"handles"| D4

    %% Domain events published back to Application
    D3 -->|"publishedBy"| A2

    %% Application interacting with cross-cutting concerns
    A3 -.->|"metrics"| I6
    A3 -.->|"metrics"| I7
    A4 -.->|"intercepts"| A1

    %% Application persists data via Infrastructure repositories
    A1 -->|"persistsData"| I4
    A1 -->|"persistsData"| I5

    %% Infrastructure linking deployment and tests
    I1 --- IT1
    I2 --- IT1
    IT1 --- IT2

    %% Click Events for Component Mapping
    click D1 "https://github.com/clockworkorange/clean-architecture-with-commands-and-events/tree/main/domain/src/main/java/es/jripoll/domain"
    click A1 "https://github.com/clockworkorange/clean-architecture-with-commands-and-events/tree/main/application/src/main/java/es/jripoll/application"
    click I1 "https://github.com/clockworkorange/clean-architecture-with-commands-and-events/tree/main/infrastructure/src/main/java/es/jripoll/infrastructure"
    click IT1 "https://github.com/clockworkorange/clean-architecture-with-commands-and-events/tree/main/root/src/main/docker"
    click IT2 "https://github.com/clockworkorange/clean-architecture-with-commands-and-events/tree/main/root/src/test"

    %% Style Definitions
    classDef domainColor fill:#F4A582,stroke:#D95F02,stroke-width:2px;
    classDef applicationColor fill:#92C5DE,stroke:#0571B0,stroke-width:2px;
    classDef infrastructureColor fill:#B2ABD2,stroke:#5E3C99,stroke-width:2px;
    classDef externalColor fill:#CAB2D6,stroke:#6A3D9A,stroke-width:2px,stroke-dasharray: 5 5;
```
