https://github.com/arivan-amin/clean-microservices-template
Template for Microservices applications
https://github.com/arivan-amin/clean-microservices-template
api api-gateway eureka flyway grafana java junit kafka loki lombok microservices mockito mongodb mysql prometheus spring-cloud swagger-ui tempo
Last synced: 4 months ago
JSON representation
Template for Microservices applications
- Host: GitHub
- URL: https://github.com/arivan-amin/clean-microservices-template
- Owner: arivan-amin
- License: mit
- Created: 2024-10-15T07:14:25.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-01-13T12:53:26.000Z (6 months ago)
- Last Synced: 2025-02-05T11:38:39.187Z (5 months ago)
- Topics: api, api-gateway, eureka, flyway, grafana, java, junit, kafka, loki, lombok, microservices, mockito, mongodb, mysql, prometheus, spring-cloud, swagger-ui, tempo
- Language: Java
- Homepage:
- Size: 217 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: Audit-Service/pom.xml
- Security: SECURITY.md
Awesome Lists containing this project
README
# App-Name
## Overview
This project is a template for an enterprise-level backend application with **Microservices
Architecture** using **Java**.
It serves as a practice project to demonstrate the implementation of microservices using
modern **Java** and **Spring Boot** and follow some of the best practices in development.
---
## Notable Features
- **Automatic Audit Logs Recording**: Uses Spring **AOP** to create Audit Events automatically
whenever any API in any of the services are called and uses **Kafka** to send them to the Audit
Service to be recorded, allowing the controllers to be clutter-free and simple.
- **Clean and concise Restful API in all services**: the API follows the modern best practices in
Restful services recommendations like using **ResponseEntity** and returning **ProblemDetails**.
- **CQRS**: Command and Query Separation Principle to implement Business logic.
- **ArchUnit**: to validate architectural boundaries and verify adherence to best coding standards
- **@RestControllerAdvice**: to handle specific exceptions and return a unified and standard error
response instead of an exception stack trace using Spring **ProblemDetail**.
- **OpenAPI and Swagger Docs**: to provide detailed documentation for all endpoints.
- **Entity and DTO separation**: decouples core business logic from presentation using request and
response pojo.
- **Core Entity and Jpa separation**: core entities have no association with JPA and are never
annotated with @Entity.
## Quick Info
## 🛠️ Architecture concepts demonstrated and implemented
- **Microservices**
- **Clean Architecture**
- **Clean Code**
- **Command-Query Responsibility Separation**
- **Solid Principles**
- **Loose Coupling of Components**
- **Spring Dependency Injection**
- **Aspect-Oriented Programming (AOP)**
---
## 🛠️ Technical Features Implemented
- **Microservices Architecture**.
- **Automatic Audit Logs recording**: Uses Spring AOP to automatically store audit logs.
- **Robust Monitoring**: Real-time monitoring with Grafana, Loki, and Tempo.
- **Event-Driven Communication**: Using Kafka.
- **Centralized Logging & Tracing**: Using Logback and Tempo.
- **Database Migrations**: Using Liquibase.
- **Dockerized Deployment**: Using Docker and Docker Compose.
---
### Currently, the following services are implemented, other services will be added:
- Discovery Server
- API Gateway
- Employee Service
- Audit Service
---
## Technologies used and their responsibility
- **Java 21**
- **Spring Boot**
- **Spring Cloud**
- **Eureka**: Dynamic service registry.
- **MySQL**: Services data storage.
- **MongoDB**: Storage for Audit logs.
- **Kafka**: Event streaming for microservices.
- **Docker**
- **Grafana, Loki, Tempo**: Observability stack for metrics, logging, and tracing.
- **JUnit & Mockito**: Unit testing and Mocking.
- **Swagger/OpenAPI**: API documentation.
- **Liquibase**: Database Migrations.
- **Lombok**: Cleaner code with reduced boilerplate.
---
## Grafana Monitoring Sample
## 🚀 Installation Guide
### Prerequisites
- **Java 21**
- **Maven**
- **Docker** & **Docker Compose**
---
### Steps to Get Started
1. **Clone the Repository:**
```bash
git clone https://github.com/arivan-amin/Clean-Microservices-Template.git
cd Clean-Microservices-Template
```
2. **Build Core Module:**
```bash
cd Core
mvn clean install
cd ..
```
3. **Build and Package the Project:**
```bash
mvn clean package
```
4. **Set Environment Variables (Linux/MacOS):**
```bash
export EUREKA_USER=admin
export EUREKA_PASSWORD=admin
```
```
*(For Windows, use `set` command)*
```
5. **Run Services with Docker Compose:**
```bash
docker compose up -d
```
6. **Access the Services:**
- **API Gateway:** [http://localhost:8080](http://localhost:8080)
- **Eureka Dashboard:** [http://localhost:8080/eureka/web](http://localhost:8080/eureka/web)
- **Swagger UI:** [http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)
- **Grafana Dashboard:** [http://localhost:3000/dashboards](http://localhost:3000/dashboards)
7. **Grafana Dashboard Setup:**
- Import pre-built dashboard JSON configuration from `docker/grafana/` folder.
---
## 🧪 Testing
- **Run Unit and Integration Tests:**
```bash
mvn test
```
---
## ⚙️ Microservices Overview
- **Discovery Server**: Dynamic service discovery and registry.
- **API Gateway**: Centralized entry point for routing and security.
- **Core Module**: Shared utilities and functionality.
- **Employee Service**: Manages employee data.
- **Audit Service**: Logs events and ensures compliance.
---
## 🤝 Contributing
We welcome contributions! Fork the repository, create a new branch, and submit a pull request.
---
## 📜 License
This project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for more
details.
---
## 📧 Contact
For questions or inquiries:
- **Name:** Arivan Amin
- **Email:** [[email protected]](mailto:[email protected])