Spring Boot Microservices Project

A comprehensive microservices architecture built with Spring Boot, featuring:

🐳 Dockerized Microservices Architecture

• JWT Authentication & Authorization - Centralized security through API Gateway with stateless token validation
• API Gateway - Single entry point for all client requests with intelligent routing and load balancing
• Service Registry (Eureka) - Automatic service discovery and registration for dynamic scaling
• Account Service - User management and authentication with MySQL database
• Product Service - Product catalog management with MongoDB for flexible document storage
• Order Service - Order processing with Cassandra for high-performance distributed data storage
• Payment Service - Payment processing with MySQL for ACID transaction compliance

🔄 Inter-Service Communication

• Synchronous HTTP calls via OpenFeign for real-time data exchange
• Asynchronous event-driven messaging through Kafka for scalable, decoupled operations

Microservices Architecture

How to Run This Project

Prerequisites

• Docker & Docker Compose
• Git

Step 1: Clone the Repository

git clone https://github.com/ariannalangwang/Spring-Boot-Microservices.git
cd Spring-Boot-Microservices

Step 2: Create Environment Variables

Create a .env file in the root directory.
Use included .env.example as the .env template.

Step 3: Deploy Everything with One Command

docker compose up -d

Step 4: Verify Services

• Eureka Dashboard: http://localhost:8761
• API Gateway: http://localhost:8088
• Kafka UI: http://localhost:8090

Step 5: Shut Down Everything with One Command

docker compose down

# Or if you want to remove all saved data so to have a clean-slate start next time:
docker compose down --volumes

---

API Endpoints

Base URL

All requests go through the API Gateway: http://localhost:8088

Account Service Endpoints

1. Health Check

GET /api/accounts/health

2. User Registration

POST /api/accounts/register
Content-Type: application/json

{
  "email": "user@example.com",
  "firstName": "John",
  "lastName": "Doe", 
  "password": "password123",
  "shippingAddress": "123 Main St",
  "billingAddress": "123 Main St",
  "paymentMethod": "Credit Card"
}

3. User Login

POST /api/accounts/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

4. Get User by ID (Requires JWT)

GET /api/accounts/user/{userId}
Authorization: Bearer <jwt-token>

5. Update User (Requires JWT)

PUT /api/accounts/user/{userId}
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "email": "updated@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "password": "newpassword123",
  "shippingAddress": "456 Oak St",
  "billingAddress": "456 Oak St", 
  "paymentMethod": "Debit Card"
}

6. Delete User (Requires JWT)

DELETE /api/accounts/user/{userId}
Authorization: Bearer <jwt-token>

Product Service Endpoints

1. Health Check

GET /api/products/health

2. Get All Products (Paginated)

GET /api/products?page=0&size=10&sortBy=name&sortDir=asc

3. Get Product by ID

GET /api/products/{productId}

4. Create Product (Admin Only - Requires JWT + ROLE_ADMIN)

POST /api/products
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "iPhone 14",
  "description": "Latest Apple smartphone",
  "skuCode": "IPH14-128GB",
  "price": 999.99,
  "quantity": 50,
  "pictureUrl": "https://example.com/iphone14.jpg"
}

5. Update Product (Admin Only - Requires JWT + ROLE_ADMIN)

PUT /api/products/{productId}
Authorization: Bearer <admin-jwt-token>
Content-Type: application/json

{
  "name": "iPhone 14 Pro",
  "description": "Premium Apple smartphone",
  "skuCode": "IPH14P-128GB", 
  "price": 1099.99,
  "quantity": 30,
  "pictureUrl": "https://example.com/iphone14pro.jpg"
}

6. Delete Product (Admin Only - Requires JWT + ROLE_ADMIN)

DELETE /api/products/{productId}
Authorization: Bearer <admin-jwt-token>

Order Service Endpoints

1. Health Check

GET /api/orders/health

2. Place Order (Requires JWT)

POST /api/orders
Authorization: Bearer <jwt-token>
Content-Type: application/json

{
  "skuCode": "IPH14-128GB",
  "quantity": 2
}

Note: User ID is automatically extracted from JWT token

3. Get My Orders (Paginated, Requires JWT)

GET /api/orders?page=0&pageSize=20
Authorization: Bearer <jwt-token>

Returns paginated orders for the authenticated user

4. Get Order by ID (Requires JWT)

GET /api/orders/{orderId}
Authorization: Bearer <jwt-token>

Note: User context is automatically extracted from JWT token

5. Delete Order (Requires JWT)

DELETE /api/orders/{orderId}
Authorization: Bearer <jwt-token>

Note: User context is automatically extracted from JWT token

Payment Service Endpoints

1. Health Check

GET /api/payments/health

2. Get Payments by User ID (Paginated, Requires JWT)

GET /api/payments/users/{userId}?page=0&size=10
Authorization: Bearer <jwt-token>

3. Get Payment by Order ID (Requires JWT)

GET /api/payments/users/{userId}/orders/{orderId}
Authorization: Bearer <jwt-token>

Authentication Flow

1. Register a new user using the registration endpoint
2. Login to get a JWT token from the response
3. Copy the token from the login response
4. Add Authorization header to subsequent requests:
   • Header: Authorization
   • Value: Bearer <your-jwt-token>

---

✨ Project Highlights ✨

Authentication & Authorization

Comprehensive security implementation with JWT and role-based access:

• JWT-based authentication implemented in API Gateway
• Role-based authorization using custom @RequireRole annotation with AOP
• Stateless security - no session management required
• Token validation at gateway level with user context propagation to downstream services

Containerization & Docker

Full containerization strategy for modern deployment:

• Isolated environments - Each service and database runs in its own Docker container for complete isolation
• Easy scalability - Individual services can be scaled independently based on demand without affecting others
• Cloud-ready deployment - Containers can be easily deployed to any cloud platform (AWS ECS, GKE, Azure Container Instances)

Global Exception Handling

The project uses @RestControllerAdvice for centralized exception handling:

• Validation errors - @Valid constraint violations
• Business logic exceptions - Custom exceptions like InsufficientStockException
• Database errors - Cassandra, MongoDB, MySQL connection issues
• Feign client errors - Service communication failures
• Generic exceptions - Catch-all error handling

Aspect-Oriented Programming (AOP)

Custom aspects for cross-cutting concerns:

• @RequireRole authorization aspect - Intercepts method calls to check user roles
• JWT token processing - Extracts user information from gateway headers
• Security enforcement - Prevents unauthorized access to admin endpoints
• Clean separation - Business logic separated from security concerns

Input Validation

Comprehensive validation using Jakarta Validation:

• Bean Validation - @NotNull, @NotBlank, @Email, @Size, @Min, @Max
• Custom constraints - SKU code pattern validation, price validation
• Method-level validation - @Validated controllers with parameter validation
• Request body validation - @Valid on DTOs

Pagination

Multiple pagination strategies implemented:

• Product Service: Standard Spring Data pagination with Page<T> and Pageable
• Order Service: Cassandra-specific pagination using Slice<T> for token-based paging
• Payment Service: MySQL pagination with custom page response DTOs
• Configurable parameters: page size, sorting, and direction