Order Management System

Domain: a pickup-first local marketplace (“QuickMart”). A customer fills one cart from several nearby shops, pays once, and collects each shop’s part when it is ready.

1. Problem and requirements

The multi-shop model

One customer action produces several orders, and they must be modelled separately:

Checkout CHK-1001 (customer pays once: ₹208)
├── ShopOrder SO-1 · Fresh Basket    · 3 items · ₹173 → pickup when READY
└── ShopOrder SO-2 · Corner Pharmacy · 1 item  · ₹35  → pickup when READY

Functional requirements

Non-functional requirements

Out of scope

Delivery logistics (pickup only in this version), shop settlement and payouts (consumes our events), product search and catalogue management, and promotions engine design (we consume a computed price).

2. Capacity estimation

Assumptions: 300,000 checkouts a day; 1.5 shop orders and 4.5 lines per checkout on average; sale events reach 10× the average for an hour; flash deals concentrate demand on a few SKUs; about 8 events per checkout over its life; about 5 KB of rows per checkout including history.

What this says: aggregate volume is modest for one PostgreSQL primary. The hard part is contention on hot rows during flash deals and correctness across the payment boundary, not throughput. The design spends its complexity there.

3. Architecture and APIs

High-level architecture

flowchart LR
  APP[Customer app] --> GW[API gateway: auth, rate limits]
  SHOP[Shop app] --> GW
  GW --> OMS
  subgraph OMS [Commerce service · modular monolith]
    CK[Checkout module + saga orchestrator]
    OR[Order module]
    IN[Inventory module]
    PY[Payment module]
    CT[Catalog read model]
  end
  OMS --> PG[(PostgreSQL)]
  PY <-->|create intent, webhooks, refunds| PSP[Payment provider]
  PG --> OBX[Outbox relay]
  OBX --> K[[Kafka: order.events, payment.events]]
  K --> NT[Notification platform]
  K --> AN[Analytics]
  K --> ST[Settlement]
  K --> SH[Shop dashboard projector]
  RD[(Redis: cart, idempotency cache, flash-sale tokens)] --- OMS
  REC[Reconciliation job] --> PG
  REC --> PSP

Modules talk through Java interfaces inside one process and own their tables. That boundary is what allows extracting Inventory or Payment later (stage 4).

Which call creates the durable order

POST /checkouts is the only call that creates orders. It creates the checkout, every shop order (state AWAITING_PAYMENT) and every stock reservation in one transaction, and returns a payment session. There is no public POST /orders; that ambiguity is removed on purpose. Payment confirms orders; it never creates them.

API contracts

POST /checkouts
Authorization: Bearer <customer token>
Idempotency-Key: 5c0e…  (generated by the app when the user taps "Pay")

{
  "cartVersion": 14,
  "lines": [
    { "shopId": "S-FB", "sku": "MILK-1L", "qty": 2, "unitPrice": 6400 },
    { "shopId": "S-FB", "sku": "BREAD-W", "qty": 1, "unitPrice": 4500 },
    { "shopId": "S-CP", "sku": "PARA-500", "qty": 1, "unitPrice": 3500 }
  ],
  "couponCode": null,
  "pickupWindow": "TODAY_EVENING"
}

201 Created
{
  "checkoutId": "CHK-1001",
  "status": "PENDING_PAYMENT",
  "total": 20800, "currency": "INR",
  "shopOrders": [
    { "id": "SO-1", "shopId": "S-FB", "status": "AWAITING_PAYMENT", "amount": 17300 },
    { "id": "SO-2", "shopId": "S-CP", "status": "AWAITING_PAYMENT", "amount": 3500 }
  ],
  "payment": { "intentId": "pi_3Px…", "clientSecret": "…", "expiresAt": "2026-10-22T10:15:00Z" },
  "reservationExpiresAt": "2026-10-22T10:15:00Z"
}

Amounts are integers in the smallest currency unit (paise). The client sends the prices it showed; if the server’s price differs, it answers 409 PRICE_CHANGED with the new prices rather than silently charging a different amount.

Deployment

flowchart LR
  LB[Load balancer] --> A1[commerce #1]
  LB --> A2[commerce #2]
  LB --> A3[commerce #3]
  A1 --> PB[PgBouncer]
  A2 --> PB
  A3 --> PB
  PB --> P[(PostgreSQL primary)]
  P -.-> S[(Sync standby)]
  P -.-> RR[(Read replica: order history, dashboards)]
  A1 --> KF[[Kafka]]
  REL[outbox-relay, leader-elected] --> P
  REL --> KF

A synchronous standby is used because this database records money: a failover must not lose committed payments.

4. Internal design and workflows

Class diagram

classDiagram
  class Checkout {
    +id
    +customerId
    +status CheckoutStatus
    +total Money
    +shopOrders List~ShopOrder~
    +markPaid(paymentId)
    +expire()
  }
  class ShopOrder {
    +id
    +checkoutId
    +shopId
    +status OrderStatus
    +lines List~OrderLine~
    +amount Money
    +transition(OrderEvent) ShopOrder
  }
  class OrderLine {
    +sku
    +qty
    +unitPrice Money
    +discountShare Money
    +status LineStatus
  }
  class Reservation {
    +id
    +shopOrderId
    +sku
    +qty
    +expiresAt
    +status ReservationStatus
  }
  class Payment {
    +id
    +checkoutId
    +amount Money
    +status PaymentStatus
    +providerIntentId
  }
  class Refund {
    +id
    +paymentId
    +shopOrderId
    +amount Money
    +idempotencyKey
    +status
  }
  class CheckoutSaga {
    +start(cmd) Checkout
    +onPaymentSucceeded(evt)
    +onPaymentFailed(evt)
    +onReservationExpired(evt)
  }
  class InventoryService {
    <<interface>>
    +reserve(lines, ttl) List~Reservation~
    +commit(reservationIds)
    +release(reservationIds)
  }
  class PaymentService {
    <<interface>>
    +createIntent(checkout, key) PaymentSession
    +refund(shopOrder, amount, key) Refund
  }
  class OrderService {
    +confirm(checkoutId)
    +cancel(orderId, actor, reason)
  }
  class OutboxWriter {
    +append(aggregate, eventType, payload)
  }
  Checkout "1" *-- "1..*" ShopOrder
  ShopOrder "1" *-- "1..*" OrderLine
  ShopOrder "1" --> "0..*" Reservation
  Checkout "1" --> "0..*" Payment
  Payment "1" --> "0..*" Refund
  CheckoutSaga --> InventoryService
  CheckoutSaga --> PaymentService
  CheckoutSaga --> OrderService
  CheckoutSaga --> OutboxWriter

Shop order state machine

stateDiagram-v2
  [*] --> AWAITING_PAYMENT: checkout created
  AWAITING_PAYMENT --> CONFIRMED: payment succeeded
  AWAITING_PAYMENT --> EXPIRED: reservation timed out
  AWAITING_PAYMENT --> CANCELLED: payment failed or customer abandoned
  CONFIRMED --> ACCEPTED: shop accepts
  CONFIRMED --> REJECTED: shop rejects or no response in 10 min
  ACCEPTED --> PREPARING: shop starts
  PREPARING --> READY: shop marks ready
  READY --> COMPLETED: picked up (OTP or QR verified)
  READY --> NOT_COLLECTED: pickup window ended
  CONFIRMED --> CANCELLED: customer cancels
  ACCEPTED --> CANCELLED: customer cancels
  REJECTED --> REFUNDED: full refund settled
  CANCELLED --> REFUNDED: refund settled (if paid)
  NOT_COLLECTED --> REFUNDED: partial refund per policy
  COMPLETED --> [*]
  REFUNDED --> [*]
  EXPIRED --> [*]

Terminal states are COMPLETED, REFUNDED, EXPIRED and CANCELLED (when nothing was paid). A customer can cancel until the shop starts preparing; after that, only the shop can cancel. Transitions live in one table-driven class, and every transition is a conditional update, so concurrent actions (customer cancels as shop accepts) resolve to exactly one winner:

UPDATE shop_order SET status = :to, version = version + 1, updated_at = now()
WHERE id = :id AND status = ANY(:allowedFrom) AND version = :expectedVersion;

Checkout state machine

stateDiagram-v2
  [*] --> PENDING_PAYMENT
  PENDING_PAYMENT --> PAID: payment succeeded
  PENDING_PAYMENT --> PAYMENT_FAILED: provider declined (customer may retry with a new attempt)
  PAYMENT_FAILED --> PENDING_PAYMENT: new attempt before expiry
  PENDING_PAYMENT --> EXPIRED: reservation expiry
  PAYMENT_FAILED --> EXPIRED: reservation expiry
  PAID --> CLOSED: every shop order terminal
  EXPIRED --> [*]
  CLOSED --> [*]

Data model and indexes

erDiagram
  CHECKOUT ||--|{ SHOP_ORDER : contains
  SHOP_ORDER ||--|{ ORDER_LINE : has
  SHOP_ORDER ||--o{ RESERVATION : holds
  INVENTORY ||--o{ RESERVATION : "reserved from"
  CHECKOUT ||--o{ PAYMENT : "paid by"
  PAYMENT ||--o{ PAYMENT_EVENT : "provider events"
  PAYMENT ||--o{ REFUND : refunds
  SHOP_ORDER ||--o{ ORDER_HISTORY : history
  CHECKOUT {
    uuid id PK
    uuid customer_id
    text idempotency_key
    text status
    bigint total_minor
    timestamptz expires_at
    bigint version
  }
  SHOP_ORDER {
    uuid id PK
    uuid checkout_id FK
    uuid shop_id
    text status
    bigint amount_minor
    bigint version
  }
  ORDER_LINE {
    uuid id PK
    uuid shop_order_id FK
    text sku
    int qty
    bigint unit_price_minor
    bigint discount_share_minor
    text status
  }
  INVENTORY {
    uuid shop_id PK
    text sku PK
    int available
    int reserved
    int sold
  }
  RESERVATION {
    uuid id PK
    uuid shop_order_id FK
    uuid shop_id
    text sku
    int qty
    text status
    timestamptz expires_at
  }
  PAYMENT {
    uuid id PK
    uuid checkout_id FK
    text provider_intent_id UK
    bigint amount_minor
    text status
  }
  PAYMENT_EVENT {
    text provider PK
    text event_id PK
    uuid payment_id FK
    text type
    jsonb body
    timestamptz received_at
  }
  REFUND {
    uuid id PK
    uuid payment_id FK
    uuid shop_order_id FK
    bigint amount_minor
    text idempotency_key UK
    text status
  }
  ORDER_HISTORY {
    bigint id PK
    uuid shop_order_id FK
    text from_status
    text to_status
    text actor
    timestamptz at
  }
  OUTBOX {
    bigint id PK
    text aggregate_id
    text event_type
    jsonb payload
    timestamptz published_at
  }

-- Overselling is impossible: stock can never go negative
ALTER TABLE inventory ADD CONSTRAINT stock_non_negative CHECK (available >= 0 AND reserved >= 0);
-- One checkout per customer action
CREATE UNIQUE INDEX checkout_idem ON checkout (customer_id, idempotency_key);
-- Duplicate webhooks are recorded once
-- (PRIMARY KEY (provider, event_id) on payment_event)
-- Expiry sweeper
CREATE INDEX reservation_expiring ON reservation (expires_at) WHERE status = 'HELD';
-- Shop dashboard: live orders for a shop
CREATE INDEX shop_live_orders ON shop_order (shop_id, status) WHERE status IN ('CONFIRMED','ACCEPTED','PREPARING','READY');

Reserving stock without overselling

Each line is one conditional update; all lines of a checkout are in one transaction, so the checkout either reserves everything or nothing:

UPDATE inventory
SET available = available - :qty, reserved = reserved + :qty
WHERE shop_id = :shop AND sku = :sku AND available >= :qty;   -- 0 rows: out of stock

@Transactional
public Checkout start(StartCheckout cmd) {
    var existing = checkouts.findByIdempotencyKey(cmd.customerId(), cmd.key());
    if (existing.isPresent()) return existing.get();                 // retry of the same tap

    var priced = pricing.verify(cmd.lines());                        // 409 PRICE_CHANGED if different
    var lines = priced.sorted(comparing(Line::shopId).thenComparing(Line::sku)); // fixed lock order: no deadlocks
    var shortages = new ArrayList<Line>();
    for (var l : lines) if (!inventory.tryReserve(l.shopId(), l.sku(), l.qty())) shortages.add(l);
    if (!shortages.isEmpty()) throw new OutOfStock(shortages);       // whole transaction rolls back

    var checkout = Checkout.create(cmd, priced, clock.instant().plus(RESERVATION_TTL));
    checkouts.save(checkout);                                         // checkout + shop orders + reservations
    outbox.append(checkout.id(), "CheckoutStarted", checkout.toEvent());
    return checkout;
}
// After commit (outside the transaction): payment.createIntent(checkout, key = checkout.id())

Sorting lines by (shop, sku) gives every transaction the same locking order, which rules out deadlocks between two checkouts that share items. The CHECK constraint is the backstop: even a buggy path cannot drive stock below zero.

Reservations last 15 minutes. A sweeper (every 30 s, FOR UPDATE SKIP LOCKED in batches) releases expired ones: available += qty, reserved -= qty, and expires the checkout. On payment success, reservations are committed: reserved -= qty, sold += qty.

Checkout and payment sequence (the saga)

sequenceDiagram
  participant C as Customer app
  participant CK as Checkout saga
  participant IN as Inventory
  participant DB as PostgreSQL
  participant PY as Payment module
  participant P as Payment provider
  participant K as Outbox → Kafka
  C->>CK: POST /checkouts (Idempotency-Key)
  CK->>IN: reserve all lines
  IN->>DB: conditional UPDATEs (one transaction with checkout + orders + outbox)
  DB-->>CK: commit
  CK->>PY: createIntent(checkout, key=checkoutId)
  PY->>P: create payment intent (idempotency key = checkoutId)
  P-->>PY: intent + client secret
  CK-->>C: 201 checkout + payment session
  C->>P: customer pays in provider UI
  P--)PY: webhook payment_intent.succeeded
  PY->>DB: INSERT payment_event (provider, event_id) ON CONFLICT DO NOTHING
  PY->>DB: payment SUCCEEDED, outbox PaymentSucceeded (same transaction)
  K--)CK: PaymentSucceeded
  CK->>DB: checkout PAID, shop orders CONFIRMED, reservations committed, outbox OrderConfirmed x N
  K--)K: Notification platform tells each shop and the customer

Compensation paths

Transaction boundaries and data ownership

Each module writes only its own tables, even inside a shared transaction. That discipline is what keeps extraction possible.

5. Failure modes and consistency

The four scenarios that prove the design:

1. Payment succeeds, but our update fails or times out

The customer paid; our webhook handler crashed before recording it, or the database was failing over.

• The provider retries webhooks until it gets a 2xx; our handler is idempotent on (provider, event_id).
• The reconciliation job runs every 5 minutes: it lists provider payment intents updated in the last hour, compares them with our payment rows, and applies any missing succeeded event through the same code path as the webhook.
• Result: the order is confirmed late (within minutes), never lost. N2 is met.

2. Payment succeeds after the reservation expired

The customer took 20 minutes in their bank’s app; the sweeper already released the stock.

• On PaymentSucceeded for an EXPIRED checkout, the saga tries to re-reserve the lines.
• If stock is still there: confirm normally (the customer never notices).
• If any line is gone: confirm what can be fulfilled, mark the rest UNAVAILABLE, and refund those lines automatically, with a notification explaining why. A fully unfulfillable checkout is refunded in full.

3. Duplicate webhook

The provider sends payment_intent.succeeded twice (retries, or two event types for one payment).

• INSERT ... ON CONFLICT (provider, event_id) DO NOTHING records the event once.
• Even with different event IDs for the same fact, the status transition PENDING → SUCCEEDED is conditional, so the second one changes nothing and emits no second PaymentSucceeded.

4. Stock race on the last unit

Two customers reserve the last pack of PARA-500 within a millisecond.

• Both run UPDATE ... WHERE available >= 1. PostgreSQL row locking serialises them; the second re-evaluates the condition after the first commits and matches 0 rows.
• The first gets 201, the second gets 409 OUT_OF_STOCK. No overselling, no lost update.

5. Kafka consumer crashes mid-processing

The notification consumer crashed after sending the shop alert but before committing its offset.

• On restart, it receives OrderConfirmed again. Consumers keep a processed_event(consumer, event_id) table, or use the notification platform’s idempotency key (order-SO-1-confirmed), so the shop is alerted once.
• The outbox relay itself can publish an event twice (crash between produce and marking published). Every event carries a unique ID, and every consumer must de-duplicate. This is documented as the system’s contract: events are delivered at least once.

Other scenarios

Security and abuse

• Customers see only their checkouts and orders; shops see only their own shop orders (row-level checks in the service, not only in the UI).
• Webhooks are verified by provider signature and timestamp tolerance; events are re-fetched from the provider API before money-affecting transitions when the signature scheme is weak.
• Coupons are validated server-side with per-customer usage limits enforced by a unique constraint.
• Checkout creation is rate-limited per customer and per device, which stops scripted stock hoarding through endless reservations.

6. Scaling evolution

7. Operations and validation

Metrics and SLOs

Test plan (to build)

Load test (to measure)

A k6 scenario mixes normal checkouts with a flash deal (one SKU, 200 units, 5,000 virtual users). To be recorded: checkout p95 and p99, success versus out-of-stock counts (must sum correctly, with zero oversell), lock wait times, and outbox lag. Results will be published only after they have been measured.

8. Decision records

DR-1: Orchestrated saga inside a modular monolith

• Context: checkout spans inventory, orders and payment, and the payment provider can never join our transaction.
• Decision: one orchestrator (the checkout saga) issues commands and compensations; in stage 1 the participants are in-process modules sharing one database transaction where possible.
• Rejected: choreography (each service reacting to others’ events): the workflow becomes implicit and hard to trace; compensation logic scatters. Microservices on day one: turns local transactions into distributed ones for no scaling need at 35 checkouts/s.

DR-2: Reserve stock at checkout, not at payment

• Decision: reserve when the checkout is created, with a 15-minute expiry.
• Rejected: decrement on payment success (customers would pay for items already sold out, forcing refunds at scale); reserve when added to cart (hoarding, and most carts are abandoned).

DR-3: Transactional outbox, not dual writes

• Decision: events are written to the outbox table in the same transaction as the state change, then relayed to Kafka.
• Rejected: writing to the database and then to Kafka (a crash between the two loses or invents events); Kafka transactions (do not include our PostgreSQL write).

DR-4: One payment per checkout

• Decision: collect once; refund per shop order.
• Rejected: a payment per shop (several authorisations for one tap; partial failures leave the customer half paid).

9. Limitations, and implemented versus proposed

Known limitations

• Payment confirmation is eventually consistent: in the worst case an order is confirmed minutes after payment, by reconciliation.
• A late payment after expiry can produce a partial order; the customer is refunded automatically but may be disappointed.
• Flash-deal tokens (stage 5) add a second store whose count must be reconciled with the database after the deal.

Status