Skip to content

Commit e2f4b73

Browse files
piominpiomin
authored
Merge pull request #57 from piomin/coderabbitai/chat/y9kYyNWO
📝 CodeRabbit Chat: Add README.md file
2 parents dab52b9 + 673851d commit e2f4b73

File tree

1 file changed

+265
-0
lines changed

1 file changed

+265
-0
lines changed

‎README.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
## Table of Contents
2+
- [Architecture Overview](#architecture-overview)
3+
- [Technology Stack](#technology-stack)
4+
- [Services Description](#services-description)
5+
- [Message Flow](#message-flow)
6+
- [Prerequisites](#prerequisites)
7+
- [Running the Applications](#running-the-applications)
8+
- [API Endpoints](#api-endpoints)
9+
- [Testing](#testing)
10+
- [Configuration](#configuration)
11+
- [Monitoring and Management](#monitoring-and-management)
12+
13+
## Architecture Overview
14+
15+
This project demonstrates a message-driven microservices architecture using Spring Cloud Stream with RabbitMQ as the message broker. The system consists of three core business services that communicate asynchronously through message queues.
16+
17+
```mermaid
18+
graph TB
19+
subgraph "Client Layer"
20+
C["Client/API Consumer"]
21+
end
22+
subgraph "Microservices"
23+
OS["Order Service<br/>:8090"]
24+
AS["Account Service<br/>:8091"]
25+
PS["Product Service<br/>:8093"]
26+
end
27+
subgraph "Message Broker"
28+
RMQ["RabbitMQ<br/>:5672"]
29+
OIN["orders-in queue"]
30+
OOUT["orders-out queue"]
31+
end
32+
subgraph "Common"
33+
MC["messaging-common<br/>Shared DTOs"]
34+
end
35+
C --> OS
36+
C --> AS
37+
C --> PS
38+
OS --> OIN
39+
OIN --> AS
40+
OIN --> PS
41+
AS --> OOUT
42+
PS --> OOUT
43+
OOUT --> OS
44+
OS -.-> MC
45+
AS -.-> MC
46+
PS -.-> MC
47+
```
48+
49+
## Technology Stack
50+
51+
- **Java**: 21
52+
- **Spring Boot**: 3.5.0
53+
- **Spring Cloud**: 2025.0.0
54+
- **Spring Cloud Stream**: Message-driven microservices framework
55+
- **RabbitMQ**: Message broker for asynchronous communication
56+
- **Maven**: Build and dependency management
57+
- **Docker & Docker Compose**: Containerization and orchestration
58+
- **Testcontainers**: Integration testing with real dependencies
59+
- **CircleCI**: Continuous Integration
60+
- **SonarCloud**: Code quality and security analysis
61+
- **JaCoCo**: Code coverage analysis
62+
63+
## Services Description
64+
65+
### Order Service (port 8090)
66+
The central orchestrator service that manages customer orders. It receives order requests via REST API and publishes order events.
67+
68+
**Key Features:**
69+
- REST API for order management
70+
- Order event publishing with customer-based partitioning
71+
- Order status tracking and updates
72+
73+
### Account Service (port 8091)
74+
Manages customer accounts and financial transactions. It listens for order events and processes withdrawals.
75+
76+
**Key Features:**
77+
- Account management REST API
78+
- Partitioned message consumption
79+
- Account balance withdrawals
80+
81+
### Product Service (port 8093)
82+
Handles product catalog and inventory. It processes order events to update availability.
83+
84+
**Key Features:**
85+
- Product management REST API
86+
- Partitioned message consumption
87+
- Inventory tracking
88+
89+
### Messaging Common
90+
Shared library with common DTOs and enums for consistent message contracts.
91+
92+
**Components:**
93+
- `Order` – Order data model
94+
- `OrderStatus` – Enumeration (NEW, PROCESSING, ACCEPTED, DONE, REJECTED)
95+
96+
## Message Flow
97+
98+
The services communicate through two main message destinations:
99+
100+
1. **orders-in**: Order Service publishes new orders
101+
2. **orders-out**: Account and Product Services publish processing results
102+
103+
**Message Flow Pattern:**
104+
```
105+
1. Client creates order → Order Service
106+
2. Order Service publishes order → orders-in queue
107+
3. Account Service processes withdrawal → orders-out queue
108+
4. Product Service updates inventory → orders-out queue
109+
5. Order Service receives updates → Final order status
110+
```
111+
112+
**Partitioning Strategy:**
113+
- Partitioned by `customerId` for ordered processing
114+
- Supports multiple instances per service with load balancing
115+
116+
## Prerequisites
117+
118+
- **Java 21** or higher
119+
- **Maven 3.6+**
120+
- **Docker & Docker Compose**
121+
- **Git**
122+
123+
## Running the Applications
124+
125+
### 1. Clone the Repository
126+
```bash
127+
git clone https://github.com/piomin/sample-message-driven-microservices.git
128+
cd sample-message-driven-microservices
129+
```
130+
131+
### 2. Start RabbitMQ
132+
```bash
133+
docker-compose up -d
134+
```
135+
- RabbitMQ AMQP on 5672
136+
- Management UI on http://localhost:15672 (guest/guest)
137+
138+
### 3. Build the Project
139+
```bash
140+
mvn clean compile
141+
```
142+
143+
### 4. Start the Services
144+
**Option A: Separate terminals**
145+
```bash
146+
cd order-service && mvn spring-boot:run
147+
cd account-service && mvn spring-boot:run
148+
cd product-service && mvn spring-boot:run
149+
```
150+
**Option B: Background**
151+
```bash
152+
cd order-service && mvn spring-boot:run &
153+
cd account-service && mvn spring-boot:run &
154+
cd product-service && mvn spring-boot:run &
155+
```
156+
157+
### 5. Verify Health
158+
```bash
159+
curl http://localhost:8090/actuator/health
160+
curl http://localhost:8091/actuator/health
161+
curl http://localhost:8093/actuator/health
162+
```
163+
164+
### Multiple Instances (Partitioned)
165+
```bash
166+
SPRING_PROFILES_ACTIVE=instance1 mvn spring-boot:run -pl account-service
167+
SPRING_PROFILES_ACTIVE=instance2 mvn spring-boot:run -pl account-service
168+
169+
SPRING_PROFILES_ACTIVE=instance1 mvn spring-boot:run -pl product-service
170+
SPRING_PROFILES_ACTIVE=instance2 mvn spring-boot:run -pl product-service
171+
```
172+
173+
## API Endpoints
174+
175+
### Order Service (http://localhost:8090)
176+
| Method | Endpoint | Description |
177+
|--------|---------------------------------|----------------------------|
178+
| POST | `/orders` | Create a new order |
179+
| PUT | `/orders` | Update an order |
180+
| GET | `/orders/{id}` | Get order by ID |
181+
| GET | `/orders/customer/{customerId}` | Get orders by customer ID |
182+
183+
### Account Service (http://localhost:8091)
184+
| Method | Endpoint | Description |
185+
|--------|------------------------------------------|-------------------------------|
186+
| POST | `/accounts` | Create a new account |
187+
| PUT | `/accounts` | Update an account |
188+
| PUT | `/accounts/withdraw/{id}/{amount}` | Withdraw amount from account |
189+
| GET | `/accounts/{id}` | Get account by ID |
190+
| GET | `/accounts/customer/{customerId}` | Get accounts by customer ID |
191+
192+
### Product Service (http://localhost:8093)
193+
| Method | Endpoint | Description |
194+
|--------|----------------------|-------------------------|
195+
| POST | `/products` | Create a new product |
196+
| PUT | `/products` | Update a product |
197+
| GET | `/products/{id}` | Get product by ID |
198+
| GET | `/products/ids` | Get products by IDs |
199+
200+
### Example API Usage
201+
```bash
202+
curl -X POST http://localhost:8091/accounts \
203+
-H "Content-Type: application/json" \
204+
-d '{"customerId":1,"balance":1000}'
205+
206+
curl -X POST http://localhost:8093/products \
207+
-H "Content-Type: application/json" \
208+
-d '{"name":"Sample","price":50,"count":100}'
209+
210+
curl -X POST http://localhost:8090/orders \
211+
-H "Content-Type: application/json" \
212+
-d '{"customerId":1,"productIds":[1],"price":50}'
213+
```
214+
215+
## Testing
216+
217+
### Running Tests
218+
```bash
219+
mvn test
220+
mvn test -pl order-service
221+
mvn test -pl account-service
222+
mvn test -pl product-service
223+
```
224+
225+
### Test Structure
226+
- `OrderControllerTest` – Order Service REST endpoints
227+
- `OrderReceiverTest` – Account Service message handling
228+
- `OrderReceiverTest` – Product Service message handling
229+
230+
### Code Coverage
231+
```bash
232+
mvn jacoco:report
233+
```
234+
Coverage reports in `target/site/jacoco/index.html` per module.
235+
236+
## Configuration
237+
238+
### Environment Variables
239+
| Variable | Default | Description |
240+
|--------------------------|--------------------|------------------------------------|
241+
| `PORT` | service-specific | Override default service port |
242+
| `SPRING_PROFILES_ACTIVE` | | Activate specific Spring profiles |
243+
244+
### RabbitMQ Configuration
245+
- Host: localhost
246+
- Port: 5672
247+
- Username: guest
248+
- Password: guest
249+
250+
### Service Discovery
251+
Eureka available at http://localhost:8761/eureka/ (optional)
252+
253+
### Message Destinations
254+
- **orders-in**: Direct exchange for new orders
255+
- **orders-out**: Topic exchange for processing results
256+
- **Partitioning**: 2 partitions by `customerId`
257+
258+
## Monitoring and Management
259+
260+
All services expose Actuator endpoints:
261+
- Health: `/actuator/health`
262+
- Metrics: `/actuator/metrics`
263+
- Stream bindings: `/actuator/bindings`
264+
265+
**RabbitMQ Management UI:** http://localhost:15672 (guest/guest)

0 commit comments

Comments
 (0)