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

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

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

## Overview

This is a Spring Boot, multi-module Java proof of concept for a hexagonal person-management API. A client submits person CRUD or paginated-search requests; the controller maps HTTP data to domain objects and calls the service, which delegates persistence through a database port to a MySQL adapter. The README also documents Kafka producer/consumer modules and an observability stack. Those optional integrations are represented, but their runtime wiring is not established by the sampled excerpts; configuration and edge limits are noted rather than inferred.

Main entry points: [`application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java) (Person REST API), [`infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java`](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java) (MySQL adapter), [`domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java`](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java) (Person service), [`ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java`](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java) (Bean wiring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["API and startup"]
  node_launcher["Application launcher<br/>[Application.java]"]
  node_wiring["Bean wiring"]
  node_controller["Person REST API"]
  node_httpmapper["HTTP mapper"]
  node_requests["API requests<br/>[PersonRequest.java]"]
  node_queryrequest["Search request"]
  node_response["API response"]
  node_exceptionhandler["Exception handler"]
end

subgraph group_core["Domain core"]
  node_service["Person service"]
  node_apiport["Service port"]
  node_domainmodel["Person domain<br/>[PersonDomain.java]"]
  node_dbport["Database port"]
  node_domainerrors["Domain exceptions"]
end

subgraph group_storage["MySQL persistence"]
  node_adapter["MySQL adapter"]
  node_dbmapper["Persistence mapper<br/>[PersonMapper.java]"]
  node_repository["Person repository"]
  node_entity["Person entity<br/>[PersonEntity.java]"]
  node_mysql[("MySQL database")]
end

subgraph group_integrations["Messaging and observability"]
  node_producer["Kafka producer"]
  node_consumer["Kafka consumer"]
  node_kafka["Kafka broker"]
  node_observability["Observability stack"]
  node_jaegerconfig["Jaeger configuration<br/>[JaegerConfig.java]"]
end

node_client(("API client"))

node_client -->|"sends requests"| node_controller
node_launcher -.->|"boots with"| node_wiring
node_wiring -->|"registers"| node_service
node_wiring -->|"registers"| node_adapter
node_controller -->|"calls"| node_apiport
node_controller -->|"maps data"| node_httpmapper
node_httpmapper -->|"maps to"| node_domainmodel
node_controller -->|"accepts"| node_requests
node_controller -->|"accepts"| node_queryrequest
node_controller -->|"returns"| node_response
node_apiport -->|"implemented by"| node_service
node_service -->|"delegates"| node_dbport
node_service -->|"raises"| node_domainerrors
node_adapter -->|"implements"| node_dbport
node_adapter -->|"queries"| node_repository
node_adapter -->|"maps data"| node_dbmapper
node_dbmapper -->|"maps to"| node_entity
node_repository -->|"persists"| node_entity
node_adapter -.->|"reads and writes"| node_mysql
node_exceptionhandler -->|"handles"| node_domainerrors
node_producer -.->|"publishes"| node_kafka
node_kafka -.->|"delivers messages"| node_consumer
node_jaegerconfig -.->|"configures tracing"| node_observability

click node_launcher "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/Application.java"
click node_wiring "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java"
click node_controller "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java"
click node_httpmapper "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/mapper/PersonHttpMapper.java"
click node_requests "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonRequest.java"
click node_queryrequest "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonQueryRequest.java"
click node_response "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/response/PersonResponse.java"
click node_exceptionhandler "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/exception/GlobalDefaultExceptionHandler.java"
click node_service "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java"
click node_apiport "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/ports/api/PersonServicePort.java"
click node_domainmodel "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/domain/PersonDomain.java"
click node_dbport "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/ports/spi/PersonDatabasePort.java"
click node_domainerrors "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/exception/ResourceNotFoundException.java"
click node_adapter "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java"
click node_dbmapper "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/mapper/PersonMapper.java"
click node_repository "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/repository/PersonRepository.java"
click node_entity "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/entity/PersonEntity.java"
click node_producer "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/kafka-producer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonProducer.java"
click node_consumer "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/kafka-consumer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonConsumer.java"
click node_observability "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/tree/main/config"
click node_jaegerconfig "https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/JaegerConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_wiring,node_controller,node_httpmapper,node_requests,node_queryrequest,node_response,node_exceptionhandler,node_client toneBlue
class node_service,node_apiport,node_domainmodel,node_dbport,node_domainerrors toneAmber
class node_adapter,node_dbmapper,node_repository,node_entity,node_mysql toneMint
class node_producer,node_consumer,node_kafka,node_observability,node_jaegerconfig toneRose
```

## Components

### API and startup

- [Application launcher](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/Application.java): `ms-launcher/src/main/java/io/github/wesleyosantos91/Application.java`
- [Bean wiring](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java): `ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java`
- [Person REST API](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java): `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`
- [HTTP mapper](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/mapper/PersonHttpMapper.java): `application/src/main/java/io/github/wesleyosantos91/api/v1/mapper/PersonHttpMapper.java`
- [API requests](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonRequest.java): `application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonRequest.java`
- [Search request](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonQueryRequest.java): `application/src/main/java/io/github/wesleyosantos91/api/v1/request/PersonQueryRequest.java`
- [API response](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/v1/response/PersonResponse.java): `application/src/main/java/io/github/wesleyosantos91/api/v1/response/PersonResponse.java`
- [Exception handler](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/application/src/main/java/io/github/wesleyosantos91/api/exception/GlobalDefaultExceptionHandler.java): `application/src/main/java/io/github/wesleyosantos91/api/exception/GlobalDefaultExceptionHandler.java`

### Domain core

- [Person service](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java): `domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java`
- [Service port](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/ports/api/PersonServicePort.java): `domain/src/main/java/io/github/wesleyosantos91/ports/api/PersonServicePort.java`
- [Person domain](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/domain/PersonDomain.java): `domain/src/main/java/io/github/wesleyosantos91/core/domain/PersonDomain.java`
- [Database port](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/ports/spi/PersonDatabasePort.java): `domain/src/main/java/io/github/wesleyosantos91/ports/spi/PersonDatabasePort.java`
- [Domain exceptions](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/domain/src/main/java/io/github/wesleyosantos91/core/exception/ResourceNotFoundException.java): `domain/src/main/java/io/github/wesleyosantos91/core/exception/ResourceNotFoundException.java`

### MySQL persistence

- [MySQL adapter](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java): `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java`
- [Persistence mapper](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/mapper/PersonMapper.java): `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/mapper/PersonMapper.java`
- [Person repository](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/repository/PersonRepository.java): `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/repository/PersonRepository.java`
- [Person entity](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/entity/PersonEntity.java): `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/entity/PersonEntity.java`
- **MySQL database**

### Messaging and observability

- [Kafka producer](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/kafka-producer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonProducer.java): `infrastructure/kafka-producer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonProducer.java`
- [Kafka consumer](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/infrastructure/kafka-consumer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonConsumer.java): `infrastructure/kafka-consumer/src/main/java/io/github/wesleyosantos91/kafka/KafkaPersonConsumer.java`
- **Kafka broker**
- [Observability stack](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/tree/main/config): `config`
- [Jaeger configuration](https://github.com/sartrebrasil/poc-multi-module-arch-hexagonal-springboot/blob/main/ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/JaegerConfig.java): `ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/JaegerConfig.java`

### Other components

- **API client**

## Connections

- API client → Person REST API: sends requests (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- Application launcher → Bean wiring: boots with
- Bean wiring → Person service: registers (evidence: `ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java`)
- Bean wiring → MySQL adapter: registers (evidence: `ms-launcher/src/main/java/io/github/wesleyosantos91/configuration/AppBeansConfig.java`)
- Person REST API → Service port: calls (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- Person REST API → HTTP mapper: maps data (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- HTTP mapper → Person domain: maps to (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/mapper/PersonHttpMapper.java`)
- Person REST API → API requests: accepts (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- Person REST API → Search request: accepts (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- Person REST API → API response: returns (evidence: `application/src/main/java/io/github/wesleyosantos91/api/v1/controller/PersonController.java`)
- Service port → Person service: implemented by (evidence: `domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java`)
- Person service → Database port: delegates (evidence: `domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java`)
- Person service → Domain exceptions: raises (evidence: `domain/src/main/java/io/github/wesleyosantos91/core/service/PersonServicePortImpl.java`)
- MySQL adapter → Database port: implements (evidence: `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java`)
- MySQL adapter → Person repository: queries (evidence: `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java`)
- MySQL adapter → Persistence mapper: maps data (evidence: `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/adapter/PersonMySQLAdapter.java`)
- Persistence mapper → Person entity: maps to (evidence: `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/mapper/PersonMapper.java`)
- Person repository → Person entity: persists (evidence: `infrastructure/datastore-mysql/src/main/java/io/github/wesleyosantos91/repository/PersonRepository.java`)
- MySQL adapter → MySQL database: reads and writes
- Exception handler → Domain exceptions: handles (evidence: `application/src/main/java/io/github/wesleyosantos91/api/exception/GlobalDefaultExceptionHandler.java`)
- Kafka producer → Kafka broker: publishes
- Kafka broker → Kafka consumer: delivers messages
- Jaeger configuration → Observability stack: configures tracing