ShopFlow Order Service

A Spring Boot microservice that manages the full order lifecycle in the ShopFlow system. It handles order placement, payment orchestration, tracking, and cancellation with event-driven architecture using Kafka.

Features

• Order Lifecycle Management: PENDING → RESERVED → CONFIRMED/CANCELLED/FAILED state transitions
• REST API: Complete CRUD operations for orders with proper authentication
• Event-Driven: Kafka integration for ORDER_PLACED, ORDER_CONFIRMED, ORDER_CANCELLED events
• External Service Integration: HTTP clients for inventory-service and wallet-service
• Idempotency: Duplicate request prevention using X-Idempotency-Key header
• Security: Header-based authentication via X-User-Id from API gateway
• Health Monitoring: Actuator health endpoints

Technology Stack

• Java 21 with Spring Boot 4.0.5
• PostgreSQL database with JPA/Hibernate
• Apache Kafka for event streaming
• Spring Security with custom authentication filter
• Maven for dependency management
• Docker for containerization

API Endpoints

Method	Path	Description	Auth
POST	/orders	Place a new order	JWT (X-User-Id)
GET	/orders	List orders for authenticated user	JWT
GET	/orders/{id}	Get order details	JWT
GET	/orders/{id}/status	Get current order status	JWT
DELETE	/orders/{id}	Cancel order (buyer, within 1hr)	JWT
GET	/orders/seller	List orders for seller's products	JWT
PATCH	/orders/{id}/status	Update order status (internal/admin)	JWT
GET	/actuator/health	Health check	Public

Configuration

Environment Variables

• DB_URL: PostgreSQL database URL (default: jdbc:postgresql://localhost:5432/orders)
• DB_USERNAME: Database username (default: postgres)
• DB_PASSWORD: Database password (default: password)
• KAFKA_BOOTSTRAP_SERVERS: Kafka bootstrap servers (default: localhost:9092)
• ORDER_CANCEL_WINDOW_MINUTES: Cancellation window in minutes (default: 60)

Required Headers

• X-User-Id: UUID of authenticated user (required for all endpoints except health)
• X-Idempotency-Key: Unique key for preventing duplicate orders (required for POST /orders)

Order Status Flow

PENDING → RESERVED → CONFIRMED
    ↓         ↓         ↓
CANCELLED CANCELLED CANCELLED (admin only)
    ↓         ↓
  FAILED    FAILED

Running the Application

Prerequisites

• Java 21+
• Maven 3.6+
• PostgreSQL 14+
• Apache Kafka
• Docker (optional)

PostgreSQL Setup

To avoid DB mismatch and issues, you can use Docker to run a PostgreSQL instance:

docker --version
docker pull postgres:15
docker run --name postgres-orders -p 5432:5432 -e POSTGRES_PASSWORD=password -e POSTGRES_DB=orders -d postgres:15
docker ps
docker exec -it postgres-orders psql -U postgres -d orders # To access DB in terminal

Local Development

1. Start PostgreSQL and Kafka

docker compose up -d

2. Run the application

mvn spring-boot:run

The service will be available at http://localhost:8083

Docker Build

docker build -t shopflow-order-service .
docker run -p 8083:8083 shopflow-order-service

Testing

Run the test suite:

mvn test

Run integration tests:

mvn test -Dspring.profiles.active=test

Event Topics

Produced Events

• ORDER_PLACED: When an order is successfully placed and inventory is reserved
• ORDER_CONFIRMED: When payment is completed and order is confirmed
• ORDER_CANCELLED: When an order is cancelled

Consumed Events

• PAYMENT_COMPLETED: Triggers order confirmation and inventory confirmation
• PAYMENT_FAILED: Triggers order failure and inventory release

Business Rules

• Orders can be cancelled by buyers within 60 minutes of placement
• Confirmed orders can only be cancelled by administrators
• Unit prices are snapshotted at order time (price changes don't affect existing orders)
• Insufficient inventory immediately fails order placement
• All requests require proper authentication headers

Monitoring

• Health check: GET /actuator/health
• Application info: GET /actuator/info

Contributing

1. Follow the existing code structure and naming conventions
2. Write unit tests for new functionality
3. Update documentation for API changes
4. Ensure all tests pass before submitting PRs