Design Shipment Tracking

Problem Statement: Multi-Carrier Shipment Tracking

A shipment tracking system turns the physical journey of a package into a reliable, queryable timeline. Every time a parcel is physically handled — picked up, scanned into an origin hub, loaded onto a linehaul truck, sorted at the destination facility, handed to a courier, delivered — the carrier emits a scan event. Our job is to ingest those events from dozens of carriers, normalize them into one consistent vocabulary, store them as an immutable history, and serve a tracking page that answers a single question fast: where is my package, and when will it arrive?

The first defining constraint is that we do not own the data source. FedEx, UPS, DHL, USPS, and a long tail of regional carriers each expose movement differently. Some push a webhook on every scan; others only let us poll a batch API every few minutes. Each speaks its own status codes — PU/OD/DL for one carrier, PICKED_UP/ON_VEHICLE/DELIVERED for another. A single Amazon order may ship as three boxes across two carriers, yet the customer expects one coherent view. The hard part is not storing events; it is reconciling many noisy, out-of-order, vendor-specific feeds into one source of truth.

The second defining constraint is the read/write ratio. A package accumulates only 5–15 scans over its entire life, but an anxious customer refreshes the tracking page dozens of times, merchants poll it for SLA dashboards, and where is my order is one of the highest-volume self-service pages on any retail site. Across all carriers that is on the order of 80 million parcels a day — FedEx and UPS alone each move 20–25 million — and at roughly 6 scans per parcel it is a modest write stream (tens of thousands of scans per second at peak) feeding an enormous read stream (hundreds of thousands of tracking reads per second at peak). This asymmetry is the entire reason the design leans on event sourcing plus a read-optimized projection (CQRS): we append raw scans to an immutable log, then continuously fold them into a denormalized current-status document that the tracking page can read in a single lookup.

What makes this interview-worthy

The interesting failures all live in the seams between carriers. A hub scan can be delivered twice during a backlog drain, so ingestion must be idempotent on (carrierId, externalScanId). A DELIVERED event can be followed by RETURN_TO_SENDER, so the projection cannot assume milestones only ever move forward. International hubs report timestamps with clock skew, so we order by the carrier sequence number where one exists and treat wall-clock arrival as a tiebreaker, never as the source of truth. And a regional carrier failover can unleash a webhook retry storm that replays hours of scans in seconds — the pipeline must absorb that burst without double-counting or falling behind.

Scope

We focus on the tracking read path and the ingestion pipeline that feeds it: per-carrier adapters, milestone normalization, the append-only event store, the projection that powers the tracking page, and the webhook fan-out that notifies merchants when a milestone changes. The carriers' internal sortation and the physical logistics network are upstream systems we observe, not systems we control.