{"id":50728422,"url":"https://github.com/rahul-ghadge/order-management-microservices","last_synced_at":"2026-06-10T06:03:25.096Z","repository":{"id":354887014,"uuid":"1225304774","full_name":"rahul-ghadge/order-management-microservices","owner":"rahul-ghadge","description":"Production-ready Order Management System built with Spring Boot 3, Apache Kafka, Redis \u0026 PostgreSQL. Features event-driven microservices, stateless JWT auth, RBAC, per-service databases, Prometheus/Grafana observability, and full Docker Compose setup. One command to run everything.","archived":false,"fork":false,"pushed_at":"2026-05-29T18:38:27.000Z","size":151,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T20:15:04.610Z","etag":null,"topics":["ddd","docker","event-driven","java21","jwt","kafka","microservices","open-api","postgresql","prafana","prometheus","redis","spring-boot","spring-cloud-gateway"],"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/rahul-ghadge.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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-30T06:37:07.000Z","updated_at":"2026-05-29T18:38:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rahul-ghadge/order-management-microservices","commit_stats":null,"previous_names":["rahul-ghadge/order-management-microservices"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rahul-ghadge/order-management-microservices","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahul-ghadge%2Forder-management-microservices","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahul-ghadge%2Forder-management-microservices/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahul-ghadge%2Forder-management-microservices/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahul-ghadge%2Forder-management-microservices/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rahul-ghadge","download_url":"https://codeload.github.com/rahul-ghadge/order-management-microservices/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rahul-ghadge%2Forder-management-microservices/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34139191,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ddd","docker","event-driven","java21","jwt","kafka","microservices","open-api","postgresql","prafana","prometheus","redis","spring-boot","spring-cloud-gateway"],"created_at":"2026-06-10T06:03:24.589Z","updated_at":"2026-06-10T06:03:25.090Z","avatar_url":"https://github.com/rahul-ghadge.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏗️ Spring Boot Order Management System — Microservices Architecture\n\n\u003e Demonstrating production-ready microservices\n\u003e with event-driven communication, distributed security, observability, and containerization.\n\n\u003e ### This is high level Architectural documentation.  \n\u003e ### To deep dive into more technical stuff for these micro-services, [Detailed technical guide](https://github.com/rahul-ghadge/order-management-microservices/blob/main/DETAILED_TECHNICAL_GUIDE.md) is also present\n\n\n---\n\n## 📐 Architecture Overview\n\n```\n                        ┌──────────────────────────────────────────┐\n                        │             CLIENT (Browser / Mobile)    │\n                        └───────────────────┬──────────────────────┘\n                                            │ HTTPS\n                        ┌───────────────────▼──────────────────────┐\n                        │           API GATEWAY  :8080             │\n                        │  JWT validation · Rate limiting · CORS   │\n                        │  Spring Cloud Gateway + Redis            │\n                        └──────┬──────────┬──────────┬──────────┬──┘\n                               │          │          │          │\n                   ┌───────────▼──┐ ┌─────▼─────┐ ┌──▼──────┐ ┌─▼─────────────┐\n                   │ user-service │ │order-svc  │ │pay-svc  │ │notif-svc      │\n                   │    :8081     │ │  :8082    │ │ :8083   │ │    :8084      │\n                   │ JWT issuance │ │ Order     │ │Payment  │ │Email dispatch │\n                   │ Redis cache  │ │ Kafka pub │ │Kafka pub│ │Kafka consumer │\n                   └──────┬───────┘ └────┬──────┘ └──┬──────┘ └───────────────┘\n                          │              │           │\n                   ┌──────▼──────┐ ┌─────▼─────┐ ┌───▼───────┐\n                   │ PostgreSQL  │ │PostgreSQL │ │PostgreSQL │\n                   │  user_db    │ │ order_db  │ │payment_db │\n                   └─────────────┘ └─────┬─────┘ └───────────┘\n                                         │\n                        ┌────────────────▼───────────────┐\n                        │         Apache Kafka           │\n                        │  order.placed                  │\n                        │  payment.processed             │\n                        │  order.status.changed          │\n                        └────────────────────────────────┘\n\n                        ┌──────────────┐   ┌─────────────┐\n                        │  Prometheus  │   │   Grafana   │\n                        │    :9090     │──▶│    :3000    │\n                        └──────────────┘   └─────────────┘\n```\n\n---\n\n## ✨ Key Features\n\n| Category | Feature |\n|---|---|\n| **Architecture** | Event-driven microservices, Domain-Driven Design, clean package structure |\n| **Security** | Stateless JWT (access + refresh tokens), token blacklisting via Redis, RBAC (`ROLE_USER`, `ROLE_ADMIN`), Spring Security 6 |\n| **Messaging** | Apache Kafka with idempotent producer, consumer retry (3× with back-off), DLT-ready |\n| **Caching** | Redis for JWT blacklisting, user profiles (`@Cacheable`), order lookups, API Gateway rate limiting |\n| **Persistence** | PostgreSQL per service (database-per-service pattern), JPA/Hibernate, UUID primary keys |\n| **API** | RESTful APIs, Swagger/OpenAPI 3 on every service, standardised `ApiResponse\u003cT\u003e` envelope |\n| **Observability** | Micrometer + Prometheus + Grafana dashboards, Spring Boot Actuator on all services |\n| **Containerisation** | Docker multi-stage builds (non-root user), Docker Compose for full local stack |\n| **Testing** | Unit tests (`@MockitoExtension`), controller tests (`@WebMvcTest`), idempotency guards |\n| **Code Quality** | Lombok, MapStruct, `@Builder`, interface+impl pattern, constants classes, `@Transactional` |\n\n---\n\n## 📦 Module Structure\n\n```\norder-management-microservices/\n│\n├── common-lib/                    # Shared library (NOT a Spring Boot app)\n│   └── src/main/java/com/orderms/common/\n│       ├── dto/ApiResponse.java               # Generic response envelope\n│       ├── event/BaseEvent.java               # Kafka event base class\n│       ├── event/OrderPlacedEvent.java        # order-service → payment-service\n│       ├── event/PaymentProcessedEvent.java   # payment-service → order + notification\n│       ├── event/OrderStatusChangedEvent.java # order-service → notification-service\n│       ├── exception/BaseException.java\n│       └── util/KafkaTopics.java              # Topic + group ID constants\n│\n├── api-gateway/    :8080          # Spring Cloud Gateway – JWT validation at edge\n├── user-service/   :8081          # Auth, JWT, user CRUD, Redis blacklist\n├── order-service/  :8082          # Order lifecycle, Kafka producer + consumer\n├── payment-service/:8083          # Payment processing, Kafka consumer + producer\n├── notification-service/:8084     # Email dispatch, Kafka consumer\n│\n├── infra/\n│   ├── prometheus/prometheus.yml  # Scrape config for all 5 services\n│   └── grafana/provisioning/      # Auto-provisioned Prometheus datasource\n│\n├── scripts/\n│   ├── init-databases.sql         # Creates all 4 PostgreSQL databases\n│   └── start-dev.sh               # One-command dev stack launcher\n│\n├── docker-compose.yml             # Full stack: 5 services + 4 DBs + Kafka + Redis + monitoring\n├── Dockerfile                     # Multi-stage build template\n├── pom.xml                        # Maven multi-module parent POM\n└── README.md\n```\n\n---\n\n## ⚡ Kafka Event Flow\n\n```\nUser places order\n    │\n    ▼\norder-service  ──[order.placed]──────────────────▶  payment-service\n                                                         │\n                                                         │  Simulates payment (85% success)\n                                                         │\n                                          ┌──────────────▼──────────────────┐\n                                          │      [payment.processed]        │\n                                          └──────────┬──────────────────────┘\n                                                     │\n                              ┌──────────────────────┼────────────────────────┐\n                              │                      │                        │\n                              ▼                      ▼                        ▼\n                        order-service         order-service           notification-service\n                     (Updates status:      [order.status.changed]     (Sends payment\n                      PAID or FAILED)             │                    success/failure\n                              │                   │                        email)\n                              │                   ▼\n                              │          notification-service\n                              └────────▶  (Sends order status\n                                           update email)\n```\n\n---\n\n## 🔐 Security Architecture\n\n### JWT Token Flow\n\n```\n1. POST /api/v1/auth/register  OR  POST /api/v1/auth/login\n        │\n        └──▶ user-service validates credentials\n                │\n                └──▶ Issues: access_token (15 min) + refresh_token (7 days)\n\n2. Every protected request:\n   Client sends: Authorization: Bearer \u003caccess_token\u003e\n        │\n        └──▶ API Gateway validates JWT at edge\n                │\n                └──▶ Forwards X-User-Id + X-User-Role headers to downstream\n\n3. POST /api/v1/auth/logout\n        │\n        └──▶ JTI (JWT ID) stored in Redis with TTL = remaining token lifetime\n                └──▶ Subsequent requests with this token are rejected (blacklisted)\n\n4. POST /api/v1/auth/refresh\n        │\n        └──▶ Valid refresh token → new access token (refresh token reused)\n```\n\n### RBAC\n\n| Role | Permissions |\n|---|---|\n| `ROLE_USER` | Place orders, view own orders/payments, manage own profile |\n| `ROLE_ADMIN` | All of the above + list all users, all orders, all payments |\n| `ROLE_MANAGER` | Intermediate access (extensible) |\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n| Tool | Minimum Version |\n|---|---|\n| Java | 21 |\n| Maven | 3.9 |\n| Docker + Docker Compose | 24 |\n\n## 🚀 One-command startup 🚀- just run one command and all sevices will be up and running (can be verified on Docker Desktop)\n\n```bash\ngit clone https://github.com/rahul-ghadge/order-management-microservices.git\ncd order-management-microservices\nchmod +x scripts/start-dev.sh\n./scripts/start-dev.sh\n```\n\n### Manual startup\n\n```bash\n# 1. Build\nmvn clean install -DskipTests\n\n# 2. Start infrastructure\ndocker-compose up -d postgres-user postgres-order postgres-payment postgres-notification \\\n                     redis zookeeper kafka kafka-ui\n\n# 3. Wait for infra, then start services\nsleep 20\ndocker-compose up -d user-service order-service payment-service notification-service api-gateway\n\n# 4. Start monitoring\ndocker-compose up -d prometheus grafana\n```\n\n---\n\n## 🌐 Service URLs\n\n| Service | URL | Description |\n|---|---|---|\n| API Gateway | http://localhost:8080 | Single entry point |\n| User Service | http://localhost:8081/swagger-ui.html | Auth + user management |\n| Order Service | http://localhost:8082/swagger-ui.html | Order lifecycle |\n| Payment Service | http://localhost:8083/swagger-ui.html | Payment records |\n| Notification Service | http://localhost:8084/swagger-ui.html | Notification logs |\n| Kafka UI | http://localhost:8090 | Topic / message browser |\n| Prometheus | http://localhost:9090 | Metrics scraping |\n| Grafana | http://localhost:3000 | Dashboards (admin/admin) |\n\n---\n\n## 📋 API Reference\n\n### Authentication\n\n```bash\n# Register\ncurl -X POST http://localhost:8080/api/v1/auth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"username\":  \"rahulghadage\",\n    \"email\":     \"rahul@example.com\",\n    \"password\":  \"stringP@ssw0rd\",\n    \"firstName\": \"Rahul\",\n    \"lastName\":  \"ghadage\"\n  }'\n\n# Login\ncurl -X POST http://localhost:8080/api/v1/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{ \"usernameOrEmail\": \"john@example.com\", \"password\": \"Password1\" }'\n\n# Save the token\nTOKEN=\"\u003caccess_token_from_response\u003e\"\n\n# Logout (blacklists token in Redis)\ncurl -X POST http://localhost:8080/api/v1/auth/logout \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Place an Order\n\n```bash\ncurl -X POST http://localhost:8080/api/v1/orders \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"userEmail\":       \"rahul@example.com\",\n    \"shippingAddress\": \"123 Main Street, New York, NY 10001\",\n    \"currency\":        \"USD\",\n    \"items\": [\n      { \"productId\": \"PROD-001\", \"productName\": \"Laptop Pro\",  \"quantity\": 1, \"unitPrice\": 1299.99 },\n      { \"productId\": \"PROD-002\", \"productName\": \"USB-C Hub\",   \"quantity\": 2, \"unitPrice\":  49.99  }\n    ]\n  }'\n```\n\nAfter placing the order, watch the Kafka event chain:\n1. `order.placed` → payment-service processes payment (85% success rate)\n2. `payment.processed` → order-service updates status; notification-service sends email\n3. `order.status.changed` → notification-service sends status email\n\n```bash\n# Check order status (cached in Redis)\ncurl http://localhost:8080/api/v1/orders/\u003corder-id\u003e \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Check payment result\ncurl http://localhost:8080/api/v1/payments/order/\u003corder-id\u003e \\\n  -H \"Authorization: Bearer $TOKEN\"\n\n# Check notification logs\ncurl http://localhost:8080/api/v1/notifications/order/\u003corder-id\u003e \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n### Cancel an Order (only PENDING or CONFIRMED)\n\n```bash\ncurl -X PATCH http://localhost:8080/api/v1/orders/\u003corder-id\u003e/cancel \\\n  -H \"Authorization: Bearer $TOKEN\"\n```\n\n---\n\n## 🗃️ Database Schema\n\nEach service owns its own PostgreSQL database (Database-per-Service pattern):\n\n| Service | Database | Key Tables |\n|---|---|---|\n| user-service | `user_db` | `users` |\n| order-service | `order_db` | `orders`, `order_items` |\n| payment-service | `payment_db` | `payments` |\n| notification-service | `notification_db` | `notification_logs` |\n\n---\n\n## 📊 Observability\n\n### Health Checks\n\n```bash\ncurl http://localhost:8081/actuator/health\ncurl http://localhost:8082/actuator/health\ncurl http://localhost:8083/actuator/health\ncurl http://localhost:8084/actuator/health\n```\n\n### Prometheus Metrics\n\nAll services expose metrics at `/actuator/prometheus` — automatically scraped by Prometheus.\n\n**Key metrics to monitor:**\n- `http_server_requests_seconds` — request latency per endpoint\n- `kafka_consumer_fetch_manager_records_consumed_total` — event throughput\n- `jvm_memory_used_bytes` — heap usage per service\n- `hikaricp_connections_active` — DB connection pool saturation\n- `spring_cache_gets_total` — Redis cache hit/miss ratio\n\n### Grafana\n\nNavigate to http://localhost:3000, login with `admin/admin`.\nThe Prometheus datasource is auto-provisioned. Import dashboard ID **4701** (JVM Micrometer)\nor **11378** (Spring Boot Statistics) from grafana.com/dashboards.\n\n---\n\n## 🧪 Running Tests\n\n```bash\n# All tests\nmvn test\n\n# Specific module\nmvn test -pl user-service\nmvn test -pl order-service\nmvn test -pl payment-service\nmvn test -pl notification-service\n\n# Test coverage report\nmvn test jacoco:report\n```\n\n### Test Inventory\n\n| Module | Tests | Coverage |\n|---|---|---|\n| user-service | `UserServiceImplTest` (8 tests), `AuthControllerTest` (7 tests) | Auth, CRUD, validation |\n| order-service | `OrderServiceImplTest` (5 tests), `OrderControllerTest` (7 tests) | Lifecycle, RBAC, cancel guards |\n| payment-service | `PaymentEventProcessorTest` (4 tests) | Idempotency, success/failure, Kafka publish |\n| notification-service | `NotificationEventConsumerTest` (5 tests) | Email dispatch, failure handling, NPE guards |\n\n---\n\n## ⚙️ Configuration Reference\n\n### Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `JWT_SECRET` | (long default) | HS256 signing secret – **change in production** |\n| `DB_HOST` | `localhost` | PostgreSQL host |\n| `DB_USERNAME` | `postgres` | PostgreSQL username |\n| `DB_PASSWORD` | `postgres` | PostgreSQL password |\n| `REDIS_HOST` | `localhost` | Redis host |\n| `KAFKA_BOOTSTRAP_SERVERS` | `localhost:9092` | Kafka broker address |\n| `NOTIFICATION_EMAIL_ENABLED` | `false` | Set `true` to send real emails |\n| `MAIL_HOST` | `smtp.gmail.com` | SMTP server host |\n| `MAIL_USERNAME` | — | SMTP username |\n| `MAIL_PASSWORD` | — | SMTP password |\n\n---\n\n## 🏛️ Architecture Decisions (ADR Summary)\n\n| Decision | Choice | Rationale |\n|---|---|---|\n| Inter-service communication | Kafka (async) | Decouples services; payment/notification don't block order creation |\n| Synchronous API | REST/JSON | Gateway routing + Swagger; simpler than gRPC for CRUD |\n| Auth token storage | Stateless JWT + Redis blacklist | Horizontal scaling without shared session; instant logout |\n| Database strategy | Database-per-service (separate PostgreSQL) | Independent schema evolution; blast radius containment |\n| Caching | Redis | Shared infrastructure; supports rate limiting + token blacklist + entity cache |\n| Idempotency | JTI-based blacklist + orderId guard in payment | Prevents double-processing on consumer retry |\n| Secret management | Environment variables | 12-Factor App compliance; Kubernetes-compatible |\n\n\n---\n\n## 📝 License\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n\n## 🧪 Manuaal startup\n\u003cimg width=\"1016\" height=\"384\" alt=\"image\" src=\"https://github.com/user-attachments/assets/fe935658-a8cb-405a-bb89-919e3ceffd7a\" /\u003e\n\u003cimg width=\"1620\" height=\"568\" alt=\"image\" src=\"https://github.com/user-attachments/assets/cd9c2ab4-b3a7-4b9c-aa36-984a731cd20b\" /\u003e\n\u003cimg width=\"1564\" height=\"967\" alt=\"image\" src=\"https://github.com/user-attachments/assets/5d8a9093-bf4a-46fa-9fbf-dd2c9c9104b7\" /\u003e\n\u003cimg width=\"1576\" height=\"592\" alt=\"image\" src=\"https://github.com/user-attachments/assets/135694ad-ed57-4746-a2e5-9863b38cb2d4\" /\u003e\n\n---\n\n\n## 🚀 One-command startup\nRun the script below (which is mentioned [here](#-one-command-startup---just-run-one-command-and-all-sevices-will-be-up-and-running-can-be-verified-on-docker-desktop)) from the command line\n\n```bash\n./scripts/start-dev.sh\n```\n\nAttached sample logs from local [here](https://github.com/rahul-ghadge/order-management-microservices/blob/main/order-management-microservices.log) \n\n\u003cimg width=\"1614\" height=\"913\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ff92a309-0726-4d0a-b2f8-a01df72cb5ad\" /\u003e\n\n\u003cimg width=\"1505\" height=\"912\" alt=\"image\" src=\"https://github.com/user-attachments/assets/faf0772f-942c-42ae-b6a0-add09f9c5947\" /\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahul-ghadge%2Forder-management-microservices","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frahul-ghadge%2Forder-management-microservices","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frahul-ghadge%2Forder-management-microservices/lists"}