{"id":27934166,"url":"https://github.com/arivan-amin/spring-microservices","last_synced_at":"2025-05-07T05:27:21.307Z","repository":{"id":252359389,"uuid":"839505049","full_name":"arivan-amin/Spring-Microservices","owner":"arivan-amin","description":"Modern Microservices Back-End application using Java and Spring Boot,  serves as a template to demonstrate the implementation of microservices using modern and best practices in development.","archived":false,"fork":false,"pushed_at":"2025-05-02T07:07:15.000Z","size":4725,"stargazers_count":9,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-02T08:23:20.505Z","etag":null,"topics":["api","api-gateway","eureka","grafana","java","junit","kafka","keycloak","liquibase","loki","lombok","microservices","mockito","mysql","pitest","pmd","prometheus","spring-cloud","swagger-ui","tempo"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arivan-amin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":"Audit-Service/pom.xml","citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-08-07T18:41:18.000Z","updated_at":"2025-05-02T07:07:19.000Z","dependencies_parsed_at":"2024-09-12T15:36:27.777Z","dependency_job_id":"a2b97e4e-d03d-4f4f-b9f2-35a09ca4bdff","html_url":"https://github.com/arivan-amin/Spring-Microservices","commit_stats":{"total_commits":165,"total_committers":2,"mean_commits":82.5,"dds":0.0060606060606061,"last_synced_commit":"e4f4dcfa6bb658c6ddd73dcf6ffcc260c68af6b1"},"previous_names":["arivan-amin/healthcare-management-microservices","arivan-amin/healthcare-clean-microservices","arivan-amin/clean-architecture-microservices","arivan-amin/spring-clean-microservices","arivan-amin/spring-microservices"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arivan-amin%2FSpring-Microservices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arivan-amin%2FSpring-Microservices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arivan-amin%2FSpring-Microservices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arivan-amin%2FSpring-Microservices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arivan-amin","download_url":"https://codeload.github.com/arivan-amin/Spring-Microservices/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252820659,"owners_count":21809264,"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":["api","api-gateway","eureka","grafana","java","junit","kafka","keycloak","liquibase","loki","lombok","microservices","mockito","mysql","pitest","pmd","prometheus","spring-cloud","swagger-ui","tempo"],"created_at":"2025-05-07T05:27:20.754Z","updated_at":"2025-05-07T05:27:21.292Z","avatar_url":"https://github.com/arivan-amin.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring Microservices\n\n## Overview\n\nThis is a **Spring Microservices Back-End** using **Java** and **Spring Boot** following\n**Clean Architecture** and **SOLID Principles**.\n\nIt serves as a template to demonstrate the implementation of microservices following some of the\nbest development practices.\n\n---\n\n## Quick Info\n\n![Java](https://img.shields.io/badge/java-21-brightgreen)\n![SpringBoot](https://img.shields.io/badge/spring--boot-3.4.5-brightgreen)\n![Maven](https://img.shields.io/badge/Maven-3.9.9-blue)\n![Build Status](https://img.shields.io/badge/build-passing-brightgreen)\n![License](https://img.shields.io/badge/license-MIT-brightgreen)\n\n![Last Commit](https://img.shields.io/github/last-commit/arivan-amin/Spring-Clean-Microservices)\n![Repo Size](https://img.shields.io/github/repo-size/arivan-amin/Spring-Clean-Microservices)\n![Contributors](https://img.shields.io/github/contributors/arivan-amin/Spring-Clean-Microservices)\n![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20MacOS-informational)\n\n## Architecture Overview\n\n```\n                               +----------------+\n                               |    Keycloak    |\n                               | (Auth Server)  |\n                               +-------+--------+\n                                       | Keycloak not yet implemented\n                                       v\n                               +-------+--------+             +-------------------+\n      Client Request           |   API Gateway  | ----------\u003e | Discovery Server  |\u003c---\n----------------------------\u003e  |    (Spring)    | \u003c---------- |      (EUREKA)     |\u003c- |\n                               +-------+--------+             +-------------------+ | |\n                                       |                                            | |\n                         Authenticated | Request                                    | |\n                                       |                                            | |\n                                       v                                            | |\n                 Actuator    +---------+---------+     AOP     +-----------------+  | |\n          -------------------|  Patient Service  | ----------\u003e |   Audit Events  |  | |\n          |     Prometheus   |   (RESTful API)   | \u003c---------- |       Table     |  | |\n          v                  +---------+---------+    Aspect   +--------+--------+  | |\n+---------+--------+                    |     |                         ^           | |\n|      Grafana     |                    |     ------------              |           | |\n|  Metrics \u0026 Logs  |                    |                |              | Query     | |\n|  Visualization   |              Write |                |              |           | |\n+---------+--------+              Logs  |   Write Logs   |     +--------+--------+  | |\n          |                             |  --------------|-----|  Audit Service  |--- |\n          | Read Logs                   v  v             |     +--------+--------+    |\n          |                     +-------+-------+        |                            |\n          --------------------\u003e | Docker Volume |        |                            |\n                                +-------+-------+        ------------------------------ \n                                                               Register with Eureka\n```\n\n## Notable Features\n\n### Automatic Audit Logs Recording\n\nUses Spring **AOP** to create Audit Events automatically whenever any API in any of the services are\ncalled and save it to persistence, allowing the controllers to be clutter-free and simple.\n\n### Clean Restful API in all services\n\nThe API follows the modern best practices in RESTful services recommendations,\nlike using **ResponseEntity** and returning **ProblemDetail**.\n\n### CQRS\n\nCommand and Query Separation Principle to implement Business logic.\n\n### Rate Limiting\n\nImplemented in **API Gateway** using **Redis Rate Limiter**.\n\n### Outbox Pattern\n\nImplements Transactional Outbox Pattern for sending events to guarantee 100% message delivery.\n\n### ArchUnit\n\nValidate architectural boundaries and verify adherence to best coding standards.\n\n### PMD and Pitest\n\nUse PMD to verify the coding style and Pitest for mutation testing.\n\n### RestControllerAdvice\n\nHandle specific exceptions and return a unified and standard error response instead of an exception\nstack trace using Spring **ProblemDetail**.\nExample of API response for every error.\n\n```\n{\n    \"type\": \"https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/RuntimeException.html\",\n    \"title\": \"Requested Patient Not Found\",\n    \"status\": 404,\n    \"detail\": \"Patient by the requested id not found\",\n    \"instance\": \"/patients/protected/v1/accounts/33bff7c7-77ee-4c51-9ee0-c870b437f82e\",\n    \"category\": \"Resource Not Found\",\n    \"timestamp\": \"2025-04-22T18:45:43.927431130Z\"\n}\n```\n\n### OpenAPI and Swagger Docs\n\nProvides detailed documentation for all endpoints.\n\n### Entity and DTO separation\n\nDecouples core business logic from presentation using request and response POJO.\n\n### Core Entity and JPA separation\n\nCore entities have no association with JPA and are never annotated with @Entity.\n\n## Sample audit log from Audit-Service captured from API calls in Patient-Service\n\n```\n        // Create Patient Endpoint\n        {\n            \"id\": \"6797e0215829937787277607\",\n            \"serviceName\": \"patient-service\",\n            \"location\": \"/patients/protected/v1/accounts\",\n            \"action\": \"Create\",\n            \"data\": \"CreatePatientRequest(firstName=Hayden, lastName=Ondricka, email=Helen21@gmail.com, dateOfBirth=977659882000, gender=MALE, address=Bernhard Cape)\",\n            \"creationDate\": \"2025-01-27T14:36:01.528\",\n            \"duration\": \"50ms\",\n            \"response\": \"CreatePatientResponse(id=9622e5ef-5ab7-4faf-89db-7dd970ea8ef0)\"\n        }\n\n        // Delete Patient Endpoint\n        {\n            \"id\": \"6797e0115829937787277605\",\n            \"serviceName\": \"patient-service\",\n            \"location\": \"/patients/protected/v1/accounts/{id}\",\n            \"action\": \"Delete\",\n            \"data\": \"e8cd23d1-4bad-44bb-9b58-a3ca89dbf793\",\n            \"creationDate\": \"2025-01-27T14:35:45.631\",\n            \"duration\": \"25ms\",\n            \"response\": \"Void\"\n        },\n        \n        // Read Patient by ID Endpoint\n        {\n            \"id\": \"6797e0145829937787277606\",\n            \"serviceName\": \"patient-service\",\n            \"location\": \"/patients/protected/v1/accounts/{id}\",\n            \"action\": \"Read\",\n            \"data\": \"e8cd23d1-4bad-44bb-9b58-a3ca89dbf793\",\n            \"creationDate\": \"2025-01-27T14:35:48.66\",\n            \"duration\": \"14ms\",\n            \"response\": \"Error: Patient by the requested id not found\"\n        }\n```\n\n## Architecture concepts and technical features demonstrated and implemented\n\n- **Microservices Architecture**.\n- **Clean Architecture \u0026 Clean Code**\n- **Command-Query Responsibility Separation (CQRS)**\n- **SOLID Principles**\n- **Outbox Pattern**\n- **Mutation Testing**\n- **Spring Dependency Injection**\n- **Aspect-Oriented Programming (AOP)**\n- **Rate Limiting API**\n- **Automatic Audit Logs recording**: Uses Spring AOP to store audit logs automatically.\n- **Event-Driven Communication**: Using Kafka.\n- **Robust Monitoring**: Real-time monitoring with Grafana, Loki, and Tempo.\n- **Centralized Logging \u0026 Distributed Tracing**: Using Loki and Tempo.\n- **Database Migrations**: Using Liquibase.\n- **Dockerized Deployment**: Using Docker and Docker Compose.\n\n---\n\n### Currently, the following services are implemented; other services will be added:\n\n- Discovery Server\n- API Gateway\n- Patient Service\n- Audit Service\n\n---\n\n## Technologies used and their responsibility\n\n- **Java 21**\n- **Spring Boot**\n- **Spring Cloud**\n- **Eureka**: Dynamic service registry.\n- **MySQL**: Services data storage.\n- **Kafka**: Event streaming for microservices.\n- **Keycloak**: Authentication and SSO provider.\n- **Docker**\n- **Grafana, Loki, Tempo**: Observability stack for metrics, logging, and tracing.\n- **JUnit \u0026 Mockito**: Unit testing and Mocking.\n- **ArchUnit**: Architecture boundaries testing and coding standards validation.\n- **PMD**: Validate coding standards and best practices.\n- **Pitest**: Mutation testing.\n- **Swagger/OpenAPI**: API documentation.\n- **Liquibase**: Database Migrations.\n- **Lombok**: Cleaner code with reduced boilerplate.\n\n---\n\n## Grafana Monitoring Sample\n\n![image](https://raw.githubusercontent.com/arivan-amin/Spring-Clean-Microservices/master/Docs/Grafana/Grafana-Dashboard-1.png)\n\n## 🚀 Installation Guide\n\n### Prerequisites\n\n- **Java 21**\n- **Maven**\n- **Docker** \u0026 **Docker Compose**\n\n---\n\n### Steps to Get Started\n\n1. **Clone the Repository:**\n   ```\n   git clone https://github.com/arivan-amin/Spring-Clean-Microservices.git\n   cd Spring-Clean-Microservices\n   ```\n\n2. **Build and deploy the services to Docker using JIB:**\n   ```\n   mvn clean install\n   ```\n\n3. **Set Environment Variables (Linux/MacOS):**\n   ```\n   export EUREKA_USER=admin\n   export EUREKA_PASSWORD=admin\n   ```\n   ```\n   *(For Windows, use `set` command)*\n   ```\n\n4. **Start the required backbone apps with Docker Compose:**\n   ```\n   docker compose up -d\n   ```\n5. **Start the services(Patient, Audit,...) manually or uncomment the section in docker compose file\n   to run everything with Docker Compose:**\n   ```\n   docker compose up -d\n   ```\n\n# Access the Services\n\n## API Gateway\n\n[http://localhost:8080](http://localhost:8080)\n\n## Eureka Dashboard\n\n#### Username: admin\n\n#### Password: admin\n\n[http://localhost:8080/eureka/web](http://localhost:8080/eureka/web)\n\n## API Documentation\n\n[http://localhost:8080/swagger-ui.html](http://localhost:8080/swagger-ui.html)\n\n## Grafana Dashboard\n\n#### Import pre-built dashboard JSON configuration from the `docker/grafana/` folder\n\n[http://localhost:3000/dashboards](http://localhost:3000/dashboards)\n\n---\n\n## 🧪 Testing\n\n- **Run Unit and Integration Tests:**\n   ```bash\n   mvn test\n   ```\n\n---\n\n## ⚙️ Microservices Overview\n\n- **Discovery Server**: Dynamic service discovery and registry.\n- **API Gateway**: Centralized entry point for routing and security.\n- **Core Module**: Shared utilities and functionality.\n- **Storage Common Module**: Contains classes related to storage and database handling shared with\n  all modules.\n- **Patient Service**: Manages patient data.\n- **Audit Service**: Stores Audit Events, ensures compliance, and data integrity.\n- **SSO Service**: Handles authentication and authorization using Keycloak.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Fork the repository, create a new branch, and submit a pull request.\n\n---\n\n## 📜 License\n\nThis project is licensed under the **MIT License**. See the [LICENSE](LICENSE) file for more\ndetails.\n\n---\n\n## 📧 Contact\n\nFor questions or inquiries:\n\n- **Name:** Arivan Amin\n- **Email:** [arivanamin@gmail.com](mailto:arivanamin@gmail.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farivan-amin%2Fspring-microservices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farivan-amin%2Fspring-microservices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farivan-amin%2Fspring-microservices/lists"}