Design an Order Management System

Lifecycle State Transitions

Every saga progression maps directly to a validated transition in the state machine. State transitions represent append-only facts, and invalid state jumps are rejected at the API gateway rather than patched silently in the database.

Event Bus Design (Kafka)

Order state changes publish to an event streaming bus using the transactional outbox pattern. Downstream consumers for warehouse fulfillment, notification dispatch, and search indexing operate asynchronously, completely decoupled from the synchronous place-order path. Learn more in Message Queues Fundamentals.

Topic: order-events
  Partitions: 128
  Partition key: order_id (preserves per-order state transition ordering)
  Retention: 30 days (allows saga replay and regulatory audit compliance)
  Replication factor: 3, min.insync.replicas: 2

Producer: Order Service following PostgreSQL transaction commit (transactional outbox pattern)
  Event: { order_id, user_id, status, items[], payment_id, timestamp }

Consumer groups:
  1. notification: email, SMS, and push alerts on confirmed, shipped, and delivered states
  2. shipping: generates shipping labels and assigns carriers upon payment confirmation
  3. search-indexer: CDC to Elasticsearch for customer service dashboard queries
  4. analytics: ClickHouse order funnel metrics
  5. recommendation: co-purchase association mining

Topic: payment-events (success or failure) -> Order Service saga compensation
Topic: shipment-events (carrier webhooks) -> Tracking Service
Topic: return-events (initiated, received, refunded) -> Inventory release workflows

Sync path: POST /orders saga (inventory reservation and payment authorization) in under 500 ms.
Async path: notifications, warehouse label generation, and search indexing never block order confirmation.
DLQ: order-events-dlq, triggering alerts when consumer lag exceeds 60 seconds.

Distributed Saga Orchestration

The saga pattern is the central architecture topic for distributed order workflows. Walk through each sequential forward step and its corresponding compensating transaction before detailing service boundaries. For a detailed breakdown of 2PC vs Saga, review Distributed Transactions: 2PC vs Saga and Microservices Patterns: Saga and Outbox.

Step 1 records the initial order entity, Step 2 reserves inventory in the Inventory Management System, Step 3 captures payment, and Step 4 confirms the order. If any step fails, compensating transactions execute in reverse order to release holds and restore consistency.

Placing an order involves multiple services. Use SAGA pattern (not 2PC):

Step 1: Create order (Order Service)
  INSERT order with status = 'PLACED'
  
Step 2: Reserve inventory (Inventory Service)
  For each item: reserve stock at selected warehouse
  If ANY item out of stock --> compensate: cancel order, release other reservations
  
Step 3: Charge payment (Payment Service)
  Authorize + capture payment
  If payment fails --> compensate: release all inventory reservations, mark order PAYMENT_FAILED
  
Step 4: Confirm order (Order Service)
  Update status = 'PAYMENT_CONFIRMED'
  Publish order-confirmed event
  
Step 5 (async): Generate invoice, send confirmation email, update analytics

Saga compensation (rollback):
  If Step 3 fails (payment declined):
    - Undo Step 2: release inventory reservations
    - Undo Step 1: mark order as PAYMENT_FAILED
    - Notify user: "Payment failed. Your items are still in your cart."

  If Step 2 fails (out of stock):
    - Undo Step 1: mark order as CANCELLED
    - Notify user: "Sorry, [item] is no longer available."

Why SAGA (not distributed transaction / 2PC)?
  2PC: requires all services to hold locks simultaneously --> blocks everything if one is slow
  SAGA: each step commits independently; compensating transactions undo on failure
  At e-commerce scale, SAGA is the industry standard (Amazon, Shopify, etc.)

Multi-Warehouse Fulfillment

Multi-warehouse orders represent a common real-world operational requirement. Explain how parent order states derive dynamically from child shipment states, ensuring partial shipments and cancellations compose cleanly.

Split Shipments: Multi-Warehouse Example:

An order with 3 items sourced from different warehouses is automatically split:
- Item A: only available at WH-NYC
- Item B: only available at WH-LAX
- Item C: available at both warehouses, allocated to WH-NYC due to regional proximity

Result: 2 independent shipments:
- Shipment 1 (WH-NYC): Item A + Item C -> FedEx tracking ID 12345
- Shipment 2 (WH-LAX): Item B -> UPS tracking ID 67890

Each shipment has its own tracking, carrier, state machine, and EDD.
Parent order state is derived:
- If any shipment SHIPPED -> order = PARTIALLY_SHIPPED
- All shipments DELIVERED -> order = DELIVERED
- Partial cancellation cancels one shipment independently.

Client-Generated Idempotency Keys

Network timeouts during checkout are guaranteed at massive scale, so interviewers expect client-generated idempotency tokens rather than relying solely on server-side deduplication.

Problem: User clicks "Place Order" and network times out. User clicks again.
  Without idempotency: two identical orders created, charged twice.

Solution:
  Client generates idempotency_key (UUID) on checkout page load.
  Both clicks send same idempotency_key.
  
  Server:
    1. Check Redis: GET idempotency:{key}
       If exists --> return cached order (already processed)
    2. Check PostgreSQL: SELECT order_id FROM orders WHERE idempotency_key = ?
       If exists --> return existing order
    3. If neither exists --> proceed with order creation
    4. After creation: SET idempotency:{key} {order_id} in Redis (TTL 24h)
    
  Result: exactly one order, regardless of retries.