How wesleyosantos91/poc-multi-module-arch-hexagonal-springboot works
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.