Here you will describe this project, what it does, and its goals, making it clear to everyone. Example:

The Java Architecture Template is a project designed to serve as a template for creating applications, aiming for development with exceptional technical quality to ensure long-term maintainability. In this template, we provide a user registration endpoint that publishes a CloudEvent to Kafka when a user is registered. A listener consumes CloudEvents of type br.com.helpdev.sample.user.created and enriches the user with address data.

📖 Read this in:

• 🇧🇷 Português

Related skill: hexagon-scaffold for adding feature slices that follow the template's hexagonal structure.

This project follows the Hexagonal Architecture, as proposed by Alistair Cockburn, focuses on decoupling the application’s core business logic from its input and output mechanisms. This design principle promotes adaptability, testability, and sustainability by encapsulating the application layer (business core) and exposing defined ports for interactions with external systems.

The architecture isolates the core domain logic by structuring the application into distinct layers:

• Adapters Layer: Handles communication with external systems (e.g., databases, APIs, or user interfaces). Divided into:

  • Input Adapters: Handle requests coming into the application, such as HTTP requests or events.
  • Output Adapters: Implement communication with external systems like repositories or external services.

• Core Layer: Represents the heart of the application:

  • Domain: Contains the core business entities, value objects, and aggregates.
  • Use Cases: Encapsulates application workflows and orchestrates interactions between domain objects and ports.
  • Ports: Defines interfaces for input and output interactions, ensuring the core remains framework-agnostic.

Read more about: O Core Domain: Modelando Domínios Ricos and O Use Case: Modelando as Interações do Seu Domínio

The structure adheres to the principles of Hexagonal Architecture, as demonstrated below:

application
    br.com.helpdev.sample
    ├── adapters
    │   ├── input         # Controllers, event listeners, or other entry points
    │   ├── output        # Database repositories, external API clients, etc.
    ├── config            # Configuration files and application settings
    ├── core              # Core business logic
    │   ├── ports
    │   │   ├── input     # Interfaces defining input interactions (e.g., commands, queries)
    │   │   ├── output    # Interfaces defining output interactions (e.g., persistence, external APIs)
    │   ├── domain        # Entities, value objects, and aggregates
    │   ├── usecases      # Application-specific business workflows
    
acceptance-test
    # Integration tests with real Docker application.

Related skill: archunit-guard for preserving and evolving the repository's architecture rules safely.

This architecture is warranted by ArchUnit tests to ensure the project's compliance with the defined structure. These tests validate the project's adherence to the Hexagonal Architecture principles, guaranteeing the separation of concerns and the independence of the core business logic from external systems.

Read more about: Garantindo a arquitetura de uma aplicação sem complexidade

Related skill: acceptance-scenario-scaffold for Docker-based black-box scenarios in the acceptance-test/ module.

To ensure robust testing, the acceptance-test module encapsulates the application within a Docker image and executes integration tests in an environment that closely mimics the real-world behavior of the application. This approach guarantees homogeneity in the application modules by restricting unit tests to the main application module, while handling integration tests separately within the acceptance-test module.

This separation ensures:

1. Realistic Test Environments: Integration tests are performed in conditions resembling the actual runtime environment, improving test reliability.

2. Clear Test Scope: Unit tests focus solely on isolated components within the core application, while integration tests validate end-to-end workflows and external interactions.

3. Ease of Deployment: Encapsulation in Docker allows seamless deployment and execution of tests across different environments.

By adhering to this strategy, the acceptance-test module becomes an essential part of maintaining the integrity and reliability of the application during its lifecycle. View module README.

Read more about: Separando os testes integrados de sua aplicação em um novo conceito

This project provides a complete local stack with all the dependencies necessary to run the application. Additionally, an observability environment using OpenTelemetry and Grafana is included.

Ensure you have the following tools installed on your machine:

• Docker: Install Docker
• Docker Compose: Install Docker Compose
• Java 21: Download Java 21

Note: Maven was embedded in the project to avoid the need to install it on your machine.

For a seamless development experience, the project includes a Makefile with predefined commands to simplify common tasks. These commands encapsulate

1. Run Tests:

   • make run-unit-tests: Runs unit tests for the application.
   • make run-acceptance-tests: Executes acceptance tests using Docker.
   • make run-all-tests: Executes all tests, including unit and integration tests.

2. Run Application:

   • make mvn-run: Runs the application with Spring Boot using the local profile.

3. Run Infrastructure:

   • make run-infrastructure: Starts infrastructure services using Docker Compose.
   • make run-observability: Starts observability services (OpenTelemetry, Grafana).
   • make run-stack: Starts both infrastructure and observability services.

4. Run Entire Application:

   • make run-app: Starts the application services.
   • make run-all: Starts the entire stack (infrastructure, observability, and application).

5. Stop Services:

   • make stop-infra: Stops infrastructure services.
   • make stop-observability: Stops observability services.
   • make stop-stack: Stops both infrastructure and observability services.
   • make stop-app: Stops the application services.
   • make stop-all: Stops all running services (infrastructure, observability, and application).

This setup ensures an efficient and consistent development experience, enabling seamless integration and monitoring capabilities in a local environment.

Related skill: flyway-decoupled for versioned migrations, Flyway runner wiring, and startup ordering.

To ensure better startup performance and avoid concurrency issues in Kubernetes environments, Flyway has been implemented as a decoupled database migration tool. This design enables the migration process to run independently of the application.

Key Features:

• Pre-deployment Execution: Migration scripts and the Flyway command are included within a Docker image, allowing them to be executed as a pre-hook during Kubernetes deployments or using other orchestration strategies.
• Avoiding Contention: By decoupling migrations from the application startup, potential race conditions or resource bottlenecks are mitigated.
• Consistency Across Environments: Ensures all database migrations are applied before the application is deployed, maintaining consistency.

This approach enhances deployment reliability and maintains a clean separation of concerns, aligning with the project's architectural principles.

You see the sample how to execute in: application docker-compose file.

Related skill: api-doc-auditor for keeping generated API documentation aligned with the source code.

This project uses Springdoc OpenAPI to automatically document REST endpoints.

🔗 Official OpenAPI site

After starting the application, access:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI specification in JSON: http://localhost:8080/v3/api-docs

Related skill: api-doc-auditor for keeping async contracts and generated docs aligned with the source code.

This project uses Springwolf to document asynchronous events (Kafka, RabbitMQ, etc.) with AsyncAPI. Kafka messages on the user-events topic follow the CloudEvents structured JSON format (application/cloudevents+json).

🔗 Official AsyncAPI site

After starting the application, access:

• AsyncAPI UI: http://localhost:8080/springwolf/asyncapi-ui.html
• AsyncAPI specification in JSON: http://localhost:8080/springwolf/docs

The local stack also includes infrastructure services to support the application. These services are accessible on localhost and provide essential functionalities:

Related skill: observability for the local OpenTelemetry, Prometheus, Grafana, and Jaeger stack.

See the stack: docker-compose-observability.yaml

• Grafana: Visualization and monitoring dashboard, available at http://localhost:3000.
• Prometheus: Metrics collection and monitoring system, available at http://localhost:9090.
• Jaeger: Distributed tracing system, available at http://localhost:16686.

See the stack: docker-compose-infrastructure.yaml

• MySQL: Relational database system, accessible at localhost:3306.
• Kafka: Event streaming platform, available at localhost:9092.

These services are orchestrated using Docker Compose to ensure seamless setup and operation in a local development environment.

Related skills: docs as the entrypoint, then docs-spec, docs-adr, docs-design-doc, docs-runbook, and docs-selective-persistence.

This template treats documentation as an active part of delivery, guided by repository skills instead of ad-hoc files. The entry point is .agents/skills/docs/SKILL.md, which decides whether the change needs durable documentation, whether an existing document should be updated, or whether explicitly no new document is needed.

The flow works like this:

1. Clarify scope first through definition, spec, or plan mode.
2. Route the work to the right artifact:
   • Spec for scope, scenarios, constraints, and acceptance criteria (docs/specs/ when created).
   • ADR for long-lived architectural decisions and guardrails in docs/adr/.
   • Design Doc for non-trivial structure, integrations, migrations, or risks in docs/design/.
   • Runbook for operations, rollout, rollback, support, and incident handling (docs/runbooks/ when created).
3. When required, ADRs and design docs are written and aligned before implementation starts.
4. After planning or execution, docs-selective-persistence decides what remains durable and what should stay transient.

This keeps documentation lean, decision-oriented, and connected to execution instead of turning every discussion into a permanent artifact.

Read more about this perspective in Documentacao na era da IA: quando a documentacao vira contexto de execucao (Portuguese).

Pull Requests are welcome. For significant changes, please open an issue first to discuss what you would like to change. Make sure to update tests as appropriate.

Architecture Template Project proposed by Guilherme Biff Zarelli

• Blog/Site: https://helpdev.com.br
• LinkedIn: https://linkedin.com/in/gbzarelli/
• GitHub: https://github.com/gbzarelli
• Articles in Medium: https://medium.com/@guilherme.zarelli
• Email: gbzarelli@helpdev.com.br

Good software design, as Robert C. Martin emphasizes in his book Clean Architecture: A Craftsman's Guide to Software Structure and Design, aims to * minimize the human resources required to build and maintain a system*. This project template draws inspiration from real-world challenges and experiences, providing a comprehensive perspective on building durable, maintainable architectures.

"The only way to go fast, is to go well."
– Robert C. Martin