Spring Boot Hexagonal Architecture Template

This is a professional-grade Spring Boot template following the Hexagonal Architecture (Ports and Adapters) pattern. It is designed to be production-ready, featuring a robust static analysis toolchain, standardized error handling, and comprehensive documentation.

🚀 Features

• Hexagonal Architecture: Clear separation of concerns between Domain, Application, and Infrastructure layers.
• Java 21 & Spring Boot 3.5: Leveraging the latest features of the Java ecosystem.
• Static Analysis Toolchain:
  • Checkstyle: Enforces naming conventions and structural constraints.
  • PMD: Detects source-level anti-patterns and best practices.
  • SpotBugs: Performs deep bytecode-level analysis to find potential bugs.
  • ErrorProne: Catches common Java mistakes at compile-time.
  • NullAway: High-performance nullability analysis (via ErrorProne).
  • Spotless: Single source of truth for code formatting (Palantir style).
• API Documentation: Integrated SpringDoc OpenAPI (Swagger) for interactive API exploration.
• Standardized Error Handling: Implementation of RFC 7807 (Problem Details for HTTP APIs) for consistent error responses.
• Quality Assurance:
  • JUnit 5: Modern unit and integration testing.
  • ArchUnit: Architectural constraints enforcement (layer isolation, naming conventions).
  • JaCoCo: Test coverage reporting (configured with 80% minimum threshold).
• Mapping: MapStruct for type-safe and efficient object mapping between layers.
• License: MIT License.

📁 Project Structure

src/main/java/org/example/hexagonaltemplate/
├── application/                # Use Cases (Application Services)
├── domain/                     # Pure Business Logic (Technology Agnostic)
│   ├── model/                  # Domain Models (Records)
│   ├── ports/                  # Inbound & Outbound Interfaces
│   └── exception/              # Business Exceptions
└── infrastructure/             # Technical Implementations
    ├── adapters/
    │   ├── in/web/             # REST Controllers and DTOs
    │   └── out/persistence/    # Persistence Implementations (Repositories)
    └── config/                 # Spring Configurations (Bean, Swagger, etc.)

🛠 Tech Stack

• JDK: 21
• Framework: Spring Boot 3.5.10
• Build Tool: Gradle
• Static Analysis: Checkstyle, PMD, SpotBugs, ErrorProne, NullAway, Spotless
• Documentation: SpringDoc OpenAPI v2
• Testing: JUnit 5, Mockito, ArchUnit, JaCoCo
• Utilities: MapStruct, Apache Commons Lang3

⚙️ How to Run

Build and Test

To run all tests and static analysis checks:

./gradlew check

Run the Application

./gradlew bootRun

The API will be available at http://localhost:8080.

API Documentation

Access the Swagger UI at:

http://localhost:8080/swagger-ui.html

📊 Quality Reports

After running ./gradlew check, reports are generated in the following locations:

• JaCoCo Coverage: build/reports/jacoco/test/html/index.html
• PMD: build/reports/pmd/main.html
• Checkstyle: build/reports/checkstyle/main.html
• SpotBugs: build/reports/spotbugs/main.html

⚖️ License

This project is licensed under the MIT License - see the LICENSE file for details.