Java-Template-Kit 🚀

A robust and scalable project template for Java applications with Spring Boot, designed based on Hexagonal Architecture and SOLID principles. Ideal for kickstarting new microservices quickly and in an organized manner.

Table of Contents

• About The Project
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Project Architecture
  • Hexagonal Architecture (Ports & Adapters)
  • SOLID Principles
• API Endpoints
• Tests
• API Documentation (Swagger)
• Docker
• Actuator

---

About The Project 🎯

This repository serves as a starting point (template) for developing back-end applications with Java and Spring Boot. The project structure is designed to promote low coupling and high cohesion, making the code easier to maintain, test, and evolve.

Key Features:

• Java 17 & Spring Boot 3: Uses modern and stable versions of the Java ecosystem.
• Hexagonal Architecture: Separates business logic (domain) from external technologies (infrastructure).
• SOLID: The code is structured following the five principles of object-oriented design.
• Automated Tests: Ready-to-go setup for unit and integration tests with JUnit 5.
• Swagger Documentation: Automatic generation of API documentation.
• GitHub Actions: CI/CD workflow for automated builds and tests.

---

Getting Started 🏁

Follow these instructions to get a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Java Development Kit (JDK) 17 or higher.
• Apache Maven 3.9+.
• An IDE of your choice (IntelliJ IDEA, VS Code, Eclipse, etc.).

Installation

1. Clone the repository:

   git clone [https://github.com/Pedroo-Nietoo/Java-Template-Kit.git](https://github.com/Pedroo-Nietoo/Java-Template-Kit.git)

2. Navigate to the project directory:

   cd Java-Template-Kit

3. Install dependencies with Maven:

   mvn clean install

---

Usage ▶️

To run the application locally, use the Spring Boot Maven plugin:

mvn spring-boot:run

By default, the application will start on port 8080. You can change the port and other settings in the src/main/resources/application.properties file.

Project Architecture 🏛️

The project's structure is designed to be clean, decoupled, and easy to maintain.

Hexagonal Architecture (Ports & Adapters)

The hexagonal architecture isolates the application's core (domain) from implementation details, such as databases, external APIs, or user interfaces.

• Domain (domain): Contains the pure business logic, entities, and rules. It does not depend on any external layer.
• Application (application): Orchestrates the data flow between the domain and the infrastructure through ports.
• Infrastructure (infrastructure): Implements the adapters. It contains controllers (REST), repositories (JPA), HTTP clients, and other external integrations.

This separation ensures that the business logic can be tested in isolation and that the technology stack can be swapped out with minimal impact on the rest of the system.

SOLID Principles

The project adheres to the SOLID principles to create more understandable, flexible, and maintainable software.

API Endpoints

Below are examples of the endpoints available in this template.

HTTP Method	Route	Description
GET	/api/v1/users/{id}	Lists user info
GET	/api/v1/terms-of-service	Redirects to the terms of service page

Tests 🧪

The project is configured with JUnit 5 for unit and integration tests. To run all tests, use the following Maven command:

mvn test

Test reports can be found in the /target/surefire-reports directory.

API Documentation (Swagger) 📖

The API endpoint documentation is automatically generated with Springdoc (Swagger). After starting the application, you can access it at the following URLs:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Spec (JSON): http://localhost:8080/v3/api-docs

Docker 🐳

To facilitate deployment and ensure a consistent environment, you can run the application in a Docker container.

(Note: This section is a placeholder. Detailed instructions and the Dockerfile will be added soon.)

1. Build the Docker image:

docker build -t java-template-kit .

2. Run the container:

docker-compose up

Spring Actuator ⚙️

Spring Boot Actuator provides ready-to-use monitoring and metrics for your application. It allows you to inspect the internal state, expose metrics, health information, and build details through HTTP endpoints.

Key Endpoints

By default, with this template, the following endpoints are available under /management:

Endpoint	Method	Description
/management/health	GET`	Shows the application health status (UP/DOWN)
/management/info	GET	Custom endpoint providing detailed system information, including CPU, memory, JVM, uptime, process ID, platform, architecture, and current timestamp.
/management/system	GET	Exposes metrics in Prometheus format
/management/prometheus	GET	Exposes metrics in Prometheus format

Grafana and Prometheus

When running the application via Docker, Grafana can be accessed at http://localhost:3000 for login. Prometheus runs alongside the application and serves as the data source for Grafana dashboards.