Requirements

Functional Requirements:

A customer can view all or individual order statuses in real time

A business can view all or individual order statuses in real time

A business or customer can view granular statuses from order placement to shipping and location estimates to delivery notices or issues.

Non-Functional Requirements:

The system should have the capacity to provide a mostly read service to ~1000's of companies, ~1M's of customers

High Availability and reliability - if real time information experiences latency or goes down, the user must be presented with 'as close to' real time data as possible. AP wins here over C

Users must be shown graceful updating UI if not real-time to retain trust in the user.

Capacity Estimation

Businesses - ~1000-3000 DAU

Customers - ~100K to ~1M DAU (3M peak?)

A status snapshot - uncompressed - ~3KB x 3M = ~8.5 GB of egress network data. Compression techniques like GZip at CDN edges are a must to save on costs

A Redis DB can easily fit this footprint for fast lookups without having to hit the primary DB.

Realistic daily usage -> Daily order volume is ~50K-100K orders/day or more if e-commerce

Each order generate multiple status events (placed -> confirmed -> packed -> shipped -> out for delivery -> delivered, plus exceptions). With updates, that's 500K-1M status writes/day.

Concurrent websocket connections is ~10-20% of DAU -> 100K-200K concurrent connections and each connection holds ~10-20KB for buffers -> ~2-4 GB just for connection state.

orders @ ~1-2 KB ea, status history and notification logs. At 100K orders/day, that's ~100 GB/year for orders alone.

Peak loads (scalability) -> Horizontal Pod Autoscalling. Use a load balancer to distribute traffic.

API Design

POST /orders

Request: { "product_id": "prod_123", "details": "{...}", "quantity": 10, "price": 15, "ship_address": "

High-Level Design

• Write - a courier app or business calls the API -> service writes the status change to PG.
• Publish - after commit, the service publishes an event to Kafka/SNS.
• Fan-out - the real-time/tracking service consumes the event, updates Redis (cache key order:{id}:status) so dashboard reads are fast, and hands it to the WebSocket gateway.
• Push - the gateway looks up which clients subscribed to order_id and pushes the event to their open connections.
  • WS map: order_id -> [connections_ids] backed by Redis

Single point of failure - if event publishing or event consumer fails, we need to mitigate this with multiple instances of consumers and use retry + at-least-once deliver).

Server-side fallbacks - Use a DLQ for Kafka events and a Multi-AZ replication for PostgreSQL so a DB node crash doesn't bring down

the write path.

In-flight updates - We need a robust retry algo if Redis write fails. Add a retry or DLQ on the consumer

Database Design

Users

• user_id (PK)
• name
• email
• phone
• role

Orders

• order_id (PK)
• user_id (FK->users)
• shipping_address
• status
• estimated_delivery
• created_at

OrderItems

• item_id (PK)
• order_id (FK->orders)
• product_id
• quantity
• price

StatusEvents

• event_id (PK)
• order_id (FK->orders)
• status
• updated_at

Detailed Component Design

WebSocket Notification Engine

• Mechanisms
  1. Client subscribes via ws://.../tracking?order_id=x
  2. Gateway stores order_id connections in Redis
  3. Status changes in Kafka and pushed to Redis Pub/Sub
• Scaling
  1. Horizontal gateway pool
  2. Redis Pub/Sub for cross-node fan-out
• Failure
  1. Socket drops
  2. client reconnects with backoff
  3. re-syncs latest status from cache
• Trade-off: Pub/Sub is at-most-once; mitigated by cache re-sync on connect

Database Layer

• Idempotency
  • carriers retry webhooks, so a unique key on (order_id, status, timestamp)
  • prevents duplicate rows
• Optimistic locking
  • a version column on orders so two concurrent updates can't corrup the state sequence
• Cache-aside
  • on cache miss, read PG, repopulate Redis with TTL