{"id":24251480,"url":"https://github.com/helpdeveloper/java-architecture-template","last_synced_at":"2026-05-07T20:41:49.328Z","repository":{"id":271153389,"uuid":"910480659","full_name":"helpdeveloper/java-architecture-template","owner":"helpdeveloper","description":"[JAVA] Template for a Java project with proper separation of tests, local stack and complete observability","archived":false,"fork":false,"pushed_at":"2025-02-12T16:34:59.000Z","size":592,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-02-12T17:38:49.535Z","etag":null,"topics":["acceptance-tests","adr","clean-architecture","hexagonal-architecture","java","java-template","micrometer","observability","open-telemetry"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helpdeveloper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-12-31T11:46:35.000Z","updated_at":"2025-02-12T16:35:02.000Z","dependencies_parsed_at":"2025-02-12T17:40:04.720Z","dependency_job_id":null,"html_url":"https://github.com/helpdeveloper/java-architecture-template","commit_stats":null,"previous_names":["helpdeveloper/java-architecture-template"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpdeveloper%2Fjava-architecture-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpdeveloper%2Fjava-architecture-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpdeveloper%2Fjava-architecture-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helpdeveloper%2Fjava-architecture-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helpdeveloper","download_url":"https://codeload.github.com/helpdeveloper/java-architecture-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241896539,"owners_count":20038737,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acceptance-tests","adr","clean-architecture","hexagonal-architecture","java","java-template","micrometer","observability","open-telemetry"],"created_at":"2025-01-15T02:50:57.743Z","updated_at":"2026-05-07T20:41:49.322Z","avatar_url":"https://github.com/helpdeveloper.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# **Java Project Architecture Template**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\".images/banner.webp\" width=\"800\"\u003e\n\u003c/p\u003e\n\nHere you will describe this project, what it does, and its goals, making it clear to everyone. Example:\n\nThe **Java Architecture Template** is a project designed to serve as a template for creating applications, aiming for development with exceptional\ntechnical quality to ensure long-term maintainability.\nIn this template, we provide a user registration endpoint that publishes a **CloudEvent** to Kafka when a user is registered. A listener consumes\nCloudEvents of type `br.com.helpdev.sample.user.created` and enriches the user with address data.\n\n📖 Read this in:\n- 🇧🇷 [Português](README.pt.md)\n\n\n## **Architecture**\n\n**Related skill:** [`hexagon-scaffold`](.agents/skills/hexagon-scaffold/SKILL.md) for adding feature slices that follow the template's hexagonal structure.\n\nThis project follows the **Hexagonal Architecture**, as proposed by Alistair Cockburn, focuses on **decoupling the application’s core business logic from its input and output\nmechanisms**. This design principle promotes adaptability, testability, and sustainability by encapsulating the application layer (business core) and\nexposing defined ports for interactions with external systems.\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\".images/hexagonal.png\" width=\"500\"\u003e\n\u003c/p\u003e\n\n### **Core Concept**\n\nThe architecture isolates the core domain logic by structuring the application into distinct layers:\n\n- **Adapters Layer**: Handles communication with external systems (e.g., databases, APIs, or user interfaces). Divided into:\n    - **Input Adapters**: Handle requests coming into the application, such as HTTP requests or events.\n    - **Output Adapters**: Implement communication with external systems like repositories or external services.\n\n- **Core Layer**: Represents the heart of the application:\n    - **Domain**: Contains the core business entities, value objects, and aggregates.\n    - **Use Cases**: Encapsulates application workflows and orchestrates interactions between domain objects and ports.\n    - **Ports**: Defines interfaces for input and output interactions, ensuring the core remains framework-agnostic.\n\n_Read more about: [O Core Domain: Modelando Domínios Ricos](https://medium.com/inside-picpay/o-core-domain-modelando-dom%C3%ADnios-ricos-f1fe664c998f)\nand [O Use Case: Modelando as Interações do Seu Domínio](https://medium.com/inside-picpay/o-use-case-modelando-as-intera%C3%A7%C3%B5es-do-seu-dom%C3%ADnio-c6c568270d0c)_\n\n### **Project Structure**\n\nThe structure adheres to the principles of Hexagonal Architecture, as demonstrated below:\n\n```plaintext\napplication\n    br.com.helpdev.sample\n    ├── adapters\n    │   ├── input         # Controllers, event listeners, or other entry points\n    │   ├── output        # Database repositories, external API clients, etc.\n    ├── config            # Configuration files and application settings\n    ├── core              # Core business logic\n    │   ├── ports\n    │   │   ├── input     # Interfaces defining input interactions (e.g., commands, queries)\n    │   │   ├── output    # Interfaces defining output interactions (e.g., persistence, external APIs)\n    │   ├── domain        # Entities, value objects, and aggregates\n    │   ├── usecases      # Application-specific business workflows\n    \nacceptance-test\n    # Integration tests with real Docker application.\n```\n\n### **Architecture Tests**\n\n**Related skill:** [`archunit-guard`](.agents/skills/archunit-guard/SKILL.md) for preserving and evolving the repository's architecture rules safely.\n\nThis architecture is warranted by [**ArchUnit tests**](application/src/test/java/br/com/helpdev/sample/ArchitectureTest.java) to ensure the project's\ncompliance with the defined structure.\nThese tests validate the project's adherence to the Hexagonal Architecture principles,\nguaranteeing the separation of concerns and the independence of the core business logic from external systems.\n\n_Read more about: [Garantindo a arquitetura de uma aplicação sem complexidade](https://medium.com/luizalabs/garantindo-a-arquitetura-de-uma-aplica%C3%A7%C3%A3o-sem-complexidade-6f675653799c)_\n\n\n\n### **Acceptance Tests**\n\n**Related skill:** [`acceptance-scenario-scaffold`](.agents/skills/acceptance-scenario-scaffold/SKILL.md) for Docker-based black-box scenarios in the `acceptance-test/` module.\n\nTo ensure robust testing, the **acceptance-test** module encapsulates the application within a Docker image and executes integration tests in an\nenvironment that closely mimics the real-world behavior of the application. This approach guarantees homogeneity in the application modules by\nrestricting unit tests to the main application module, while handling integration tests separately within the acceptance-test module.\n\nThis separation ensures:\n\n1. **Realistic Test Environments**: Integration tests are performed in conditions resembling the actual runtime environment, improving test\n   reliability.\n\n2. **Clear Test Scope**: Unit tests focus solely on isolated components within the core application, while integration tests validate end-to-end\n   workflows and external interactions.\n\n3. **Ease of Deployment**: Encapsulation in Docker allows seamless deployment and execution of tests across different environments.\n\nBy adhering to this strategy, the acceptance-test module becomes an essential part of maintaining the integrity and reliability of the application\nduring its lifecycle. View module [README](acceptance-test/README.md).\n\n_Read more about: [Separando os testes integrados de sua aplicação em um novo conceito](https://medium.com/luizalabs/separando-os-testes-integrados-de-sua-aplica%C3%A7%C3%A3o-em-um-novo-conceito-4f511ebb53a4)_\n\n\n\n## **Getting Started**\n\nThis project provides a complete local stack with all the dependencies necessary to run the application. Additionally, an observability environment\nusing **OpenTelemetry** and **Grafana** is included.\n\n### **Prerequisites**\n\nEnsure you have the following tools installed on your machine:\n\n- **Docker**: [Install Docker](https://docs.docker.com/get-docker/)\n- **Docker Compose**: [Install Docker Compose](https://docs.docker.com/compose/install/)\n- **Java 21**: [Download Java 21](https://www.oracle.com/java/technologies/javase/jdk21-archive-downloads.html)\n\n_Note: Maven was embedded in the project to avoid the need to install it on your machine._\n\n### **Running the Project**\n\nFor a seamless development experience, the project includes a Makefile with predefined commands to simplify common tasks. These commands encapsulate\n\n1. **Run Tests**:\n    - `make run-unit-tests`: Runs unit tests for the application.\n    - `make run-acceptance-tests`: Executes acceptance tests using Docker.\n    - `make run-all-tests`: Executes all tests, including unit and **integration tests**.\n\n2. **Run Application**:\n    - `make mvn-run`: Runs the application with Spring Boot using the `local` profile.\n\n3. **Run Infrastructure**:\n    - `make run-infrastructure`: Starts infrastructure services using Docker Compose.\n    - `make run-observability`: Starts observability services (OpenTelemetry, Grafana).\n    - `make run-stack`: Starts both infrastructure and observability services.\n\n4. **Run Entire Application**:\n    - `make run-app`: Starts the application services.\n    - `make run-all`: Starts the entire stack (infrastructure, observability, and application).\n\n5. **Stop Services**:\n    - `make stop-infra`: Stops infrastructure services.\n    - `make stop-observability`: Stops observability services.\n    - `make stop-stack`: Stops both infrastructure and observability services.\n    - `make stop-app`: Stops the application services.\n    - `make stop-all`: Stops all running services (infrastructure, observability, and application).\n\nThis setup ensures an efficient and consistent development experience, enabling seamless integration and monitoring capabilities in a local\nenvironment.\n\n### **The Flyway Database Migration Tool**\n\n**Related skill:** [`flyway-decoupled`](.agents/skills/flyway-decoupled/SKILL.md) for versioned migrations, Flyway runner wiring, and startup ordering.\n\nTo ensure better startup performance and avoid concurrency issues in Kubernetes environments, **Flyway** has been implemented as a decoupled database\nmigration tool. This design enables the migration process to run independently of the application.\n\nKey Features:\n\n- **Pre-deployment Execution**: Migration scripts and the Flyway command are included within a Docker image, allowing them to be executed as a\n  pre-hook during Kubernetes deployments or using other orchestration strategies.\n- **Avoiding Contention**: By decoupling migrations from the application startup, potential race conditions or resource bottlenecks are mitigated.\n- **Consistency Across Environments**: Ensures all database migrations are applied before the application is deployed, maintaining consistency.\n\nThis approach enhances deployment reliability and maintains a clean separation of concerns, aligning with the project's architectural principles.\n\nYou see the sample how to execute in: [application docker-compose file](.docker-compose-local/application.yaml).\n\n### **OpenAPI**\n\n**Related skill:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) for keeping generated API documentation aligned with the source code.\n\nThis project uses **Springdoc OpenAPI** to automatically document REST endpoints.\n\n🔗 [Official OpenAPI site](https://swagger.io/specification/)\n\n#### How to access OpenAPI documentation\nAfter starting the application, access:\n\n- **Swagger UI**: [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)\n- **OpenAPI specification in JSON**: [http://localhost:8080/v3/api-docs](http://localhost:8080/v3/api-docs)\n\n### **AsyncAPI**\n\n**Related skill:** [`api-doc-auditor`](.agents/skills/api-doc-auditor/SKILL.md) for keeping async contracts and generated docs aligned with the source code.\n\nThis project uses **Springwolf** to document asynchronous events (Kafka, RabbitMQ, etc.) with **AsyncAPI**.\nKafka messages on the `user-events` topic follow the **CloudEvents structured JSON** format (`application/cloudevents+json`).\n\n🔗 [Official AsyncAPI site](https://www.asyncapi.com/)\n\n#### How to access AsyncAPI documentation\nAfter starting the application, access:\n\n- **AsyncAPI UI**: [http://localhost:8080/springwolf/asyncapi-ui.html](http://localhost:8080/springwolf/asyncapi-ui.html)\n- **AsyncAPI specification in JSON**: [http://localhost:8080/springwolf/docs](http://localhost:8080/springwolf/docs)\n\n### **Available Infrastructure**\n\nThe local stack also includes infrastructure services to support the application. These services are accessible on `localhost` and provide essential\nfunctionalities:\n\n#### Observability Services\n\n**Related skill:** [`observability`](.agents/skills/observability/SKILL.md) for the local OpenTelemetry, Prometheus, Grafana, and Jaeger stack.\n\nSee the stack: [docker-compose-observability.yaml](.docker-compose-local/observability.yaml)\n\n- **Grafana**: Visualization and monitoring dashboard, available at [http://localhost:3000](http://localhost:3000).\n- **Prometheus**: Metrics collection and monitoring system, available at [http://localhost:9090](http://localhost:9090).\n- **Jaeger**: Distributed tracing system, available at [http://localhost:16686](http://localhost:16686).\n\n#### Infrastructure Services\n\nSee the stack: [docker-compose-infrastructure.yaml](.docker-compose-local/infrastructure.yaml)\n\n- **MySQL**: Relational database system, accessible at `localhost:3306`.\n- **Kafka**: Event streaming platform, available at `localhost:9092`.\n\nThese services are orchestrated using Docker Compose to ensure seamless setup and operation in a local development environment.\n\n\n\n## **Docs**\n\n**Related skills:** [`docs`](.agents/skills/docs/SKILL.md) as the entrypoint, then [`docs-spec`](.agents/skills/docs-spec/SKILL.md), [`docs-adr`](.agents/skills/docs-adr/SKILL.md), [`docs-design-doc`](.agents/skills/docs-design-doc/SKILL.md), [`docs-runbook`](.agents/skills/docs-runbook/SKILL.md), and [`docs-selective-persistence`](.agents/skills/docs-selective-persistence/SKILL.md).\n\nThis template treats documentation as an active part of delivery, guided by repository skills instead of ad-hoc files. The entry point is\n`.agents/skills/docs/SKILL.md`, which decides whether the change needs durable documentation, whether an existing document should be updated, or whether\nexplicitly no new document is needed.\n\nThe flow works like this:\n\n1. Clarify scope first through definition, spec, or plan mode.\n2. Route the work to the right artifact:\n   - **Spec** for scope, scenarios, constraints, and acceptance criteria (`docs/specs/` when created).\n   - **ADR** for long-lived architectural decisions and guardrails in [`docs/adr/`](./docs/adr/README.md).\n   - **Design Doc** for non-trivial structure, integrations, migrations, or risks in [`docs/design/`](./docs/design/README.md).\n   - **Runbook** for operations, rollout, rollback, support, and incident handling (`docs/runbooks/` when created).\n3. When required, ADRs and design docs are written and aligned before implementation starts.\n4. After planning or execution, `docs-selective-persistence` decides what remains durable and what should stay transient.\n\nThis keeps documentation lean, decision-oriented, and connected to execution instead of turning every discussion into a permanent artifact.\n\nRead more about this perspective in [Documentacao na era da IA: quando a documentacao vira contexto de execucao](https://medium.com/@guilherme.zarelli/documenta%C3%A7%C3%A3o-na-era-da-ia-quando-a-documenta%C3%A7%C3%A3o-vira-contexto-de-execu%C3%A7%C3%A3o-cb8d6fdf84ed) _(Portuguese)_.\n\n\n## **Contribute**\n\nPull 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\nappropriate.\n\n\n_**Architecture Template Project proposed by Guilherme Biff Zarelli**_\n\n- **Blog/Site**: [https://helpdev.com.br](https://helpdev.com.br)\n- **LinkedIn**: [https://linkedin.com/in/gbzarelli/](https://linkedin.com/in/gbzarelli/)\n- **GitHub**: [https://github.com/gbzarelli](https://github.com/gbzarelli)\n- **Articles in Medium**: [https://medium.com/@guilherme.zarelli](https://medium.com/@guilherme.zarelli)\n- **Email**: [gbzarelli@helpdev.com.br](mailto:gbzarelli@helpdev.com.br)\n\n_Good software design, as Robert C. Martin emphasizes in his book *Clean Architecture: A Craftsman's Guide to Software Structure and Design*, aims to *\n*minimize the human resources required to build and maintain a system**. This project template draws inspiration from real-world challenges and experiences,\nproviding a comprehensive perspective on building durable, maintainable architectures._\n\n\u003e *\"The only way to go fast, is to go well.\"*  \n\u003e – **Robert C. Martin**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelpdeveloper%2Fjava-architecture-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelpdeveloper%2Fjava-architecture-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelpdeveloper%2Fjava-architecture-template/lists"}