Skip to main content

Order Service 🧾

The Order Service is responsible for managing the order lifecycle in ShopVerse — from order creation to status updates.

It coordinates with Product Service for inventory validation and Payment Service for payment processing, while publishing events for asynchronous workflows.

🎯 Responsibilities​

The Order Service handles:

  • Order creation and persistence
  • Order item management
  • Order status transitions
  • Stock validation via Product Service
  • Publishing order-related events
  • Fetching orders for users and admins

🧠 Why a Separate Order Service?​

Orders represent a critical transactional domain.

Separating Order Service ensures:

  • Clear ownership of order logic
  • Isolation from product and payment concerns
  • Easier handling of transactional consistency
  • Independent scaling for high order volumes

🏗️ High-Level Architecture​

🔐 Security Model​

  • All requests go through API Gateway

  • Gateway injects:

    • X-User-Email
    • X-User-Role

  • Role-based access enforced inside Order Service

  • Customers can access only their own orders

  • Admins can access all orders

🔁 Order Placement Flow​

🗄️ Data Model​

Order Entity​

  • id
  • customerId (email)
  • orderDate
  • totalAmount
  • status (CREATED, CONFIRMED, CANCELLED)
  • createdAt

OrderItem Entity​

  • id
  • orderId
  • productId
  • quantity
  • price

Each order contains multiple order items.

🔄 Order Status Lifecycle​

  • CREATED → Order placed, payment pending
  • CONFIRMED → Payment successful
  • CANCELLED → Order cancelled / failed

📡 Kafka Events Published​

Event TypeTopicDescription
ORDER_PLACEDorder-eventsOrder successfully created
ORDER_STATUS_UPDATEDorder-eventsOrder status change

These events are consumed by:

  • Notification Service
  • Analytics Service
  • Recommendation Service

🌐 APIs​

Customer APIs​

MethodEndpointDescription
POST/api/ordersPlace order
GET/api/orders/{id}Get order by ID
GET/api/orders/myGet user orders

Admin APIs​

MethodEndpointRoleDescription
GET/api/ordersADMINGet all orders
PUT/api/orders/{id}/statusADMINUpdate order status

🛡️ Inventory Consistency Strategy​

  • Stock is validated before order creation
  • Stock reduction happens after order confirmation
  • Prevents overselling
  • Uses synchronous REST call to Product Service
  • Kafka used only for async side effects

⚠️ Failure Scenarios​

❌ Insufficient Stock​

  • Order creation fails
  • Returns 400 Bad Request

❌ Product Service Down​

  • Order placement blocked
  • Prevents inconsistent state

❌ Duplicate Order Requests​

  • Handled using transactional boundaries

⚙️ Key Components​

  • OrderController – Order APIs
  • OrderService – Core order logic
  • ProductClient – WebClient for Product Service
  • OrderRepository – JPA repository
  • KafkaEventPublisher – Order events
  • GlobalExceptionHandler – Standard error handling

📈 Scalability Considerations​

  • Stateless service → horizontal scaling
  • Database indexed on customerId
  • Kafka decouples downstream consumers
  • Read-heavy APIs can be cached

🧪 Testing Strategy​

  • Unit tests for order creation
  • Integration tests for stock validation
  • Negative tests for unauthorized access
  • Failure tests for external service downtime

📌 Summary​

The Order Service ensures:

  • Reliable order lifecycle management
  • Inventory consistency
  • Secure user-level access
  • Event-driven extensibility

It acts as the transactional backbone of the ShopVerse platform.