# wesleyosantos91/poc-multi-module-arch-hexagonal-springboot architecture

> Architecture diagram of the GitHub repository wesleyosantos91/poc-multi-module-arch-hexagonal-springboot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot
- Repository: https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot

## Overview

##### Project Type and Purpose
- This is a full-stack backend service built to illustrate the hexagonal architecture pattern. It separates concerns by isolating the core domain logic from the external systems (e.g., database, Kafka, observability tools) via well-defined ports and adapters.
- The README makes clear that the intent is to showcase a multi-module, modular application with decoupled components enabling easier testing and independent evolution.

##### Main Components
- Domain Module:
- Contains core business entities, domain objects (like PersonDomain), domain services, and exception handling. Files in the "domain" directory (e.g., core/domain, core/service, ports/api, ports/spi) show this clearly.
- Application Module:
- Hosts the API layer (controllers, request/response mapping) and exception handlers. Look under "application/src/main/java/io/github/wesleyosantos91/api" where REST controllers and mappers live. This layer is the primary adapter for client interactions.
- Infrastructure Adapters:
- Datastore Module: Found in "infrastructure/datastore-mysql" which includes adapters, repository classes, and entity mappings – this serves as the persistence adapter for the domain.
- Kafka Adapters: Separated into "infrastructure/kafka-consumer" and "infrastructure/kafka-producer" modules, these are responsible for sending and receiving messages using Kafka (with Avro schemas provided).
- Additionally, ms-launcher acts as an orchestration or bootstrap module, setting up configurations (including beans for Jaeger, etc.) and serving as the application’s main entry point.
- External/Observability Services:
- The README lists external tools (e.g., Sonar, Prometheus, Grafana, Alertmanager, Jaeger, and the ELK stack components). Represent these as peripheral components that interact with the system for logging, metrics, tracing, and quality assurance.

##### Relationships & Interactions
- Input/Output Adapters:
- The API layer (in the Application module) receives HTTP requests (REST API endpoints) and then interacts with the Domain via the defined ports.
- The Domain layer uses ports to interact with external adapters (for persistence in MySQL and for asynchronous communication through Kafka).
- From clients → Application (API controllers) → Domain.
- From Domain → Infrastructure (database adapter, Kafka producers/consumers).
- Flow of observability data moving from the application to tools like Prometheus, Grafana, and Jaeger.
- Loose coupling enabled by the hexagonal architecture (the core business logic does not depend directly on technology-specific details).

##### Architectural Patterns and Design Principles
- Use of dependency inversion where your Domain defines contracts (ports) implemented by external infrastructure components.
- Stress the decoupling achieved by isolating the API and integration logic from the core business rules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["Client Request"]:::client

    %% Bootstrap / Configuration
    Bootstrap["ms-launcher (Bootstrap & Config)"]:::bootstrap

    %% Application Layer
    subgraph "Application Layer"
        API["REST API (Application Layer)"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Ports["Domain Ports (Interfaces)"]:::domain
        Domain["Domain Module (Core Business Logic)"]:::domain
    end

    %% Infrastructure Adapters
    subgraph "Infrastructure Adapters"
        MySQL["MySQL Adapter (Datastore)"]:::infrastructure
        KafkaProd["Kafka Producer Adapter"]:::infrastructure
        KafkaCons["Kafka Consumer Adapter"]:::infrastructure
    end

    %% External / Observability
    External["Observability Tools (Prometheus, Grafana, Jaeger, Alertmanager, ELK)"]:::external

    %% Connections
    Client -->|"calls"| API
    Bootstrap -->|"configures"| API
    API -->|"invokes"| Ports
    Ports -->|"delegates_to"| Domain
    Domain -->|"persists"| MySQL
    Domain -->|"publishes"| KafkaProd
    Domain -->|"consumes"| KafkaCons
    API -->|"reports"| External
    Bootstrap -->|"sets_up"| External

    %% Click Events
    click Domain "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/domain/src/main/java/io/github/wesleyosantos91/core"
    click Ports "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/domain/src/main/java/io/github/wesleyosantos91/ports"
    click API "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/application/src/main/java/io/github/wesleyosantos91/api"
    click MySQL "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter"
    click KafkaCons "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/infrastructure/kafka-consumer/src/main/java/io/github/wesleyosantos91/kafka"
    click KafkaProd "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/infrastructure/kafka-producer/src/main/java/io/github/wesleyosantos91/kafka"
    click Bootstrap "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration"
    click External "https://github.com/wesleyosantos91/poc-multi-module-arch-hexagonal-springboot/tree/main/config"

    %% Class Styles
    classDef client fill:#E8DAEF,stroke:#000,stroke-width:2px;
    classDef application fill:#AED6F1,stroke:#000,stroke-width:2px;
    classDef domain fill:#F9E79F,stroke:#000,stroke-width:2px;
    classDef infrastructure fill:#A9DFBF,stroke:#000,stroke-width:2px;
    classDef bootstrap fill:#D7BDE2,stroke:#000,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#000,stroke-width:2px;
```
