System Design

Package Tracking

Design a package tracking system like FedEx, UPS, or Amazon's track package feature.

Functional requirements

• Facilities, sorting hubs, and drivers submit scan events for a package (e.g., picked up, arrived at hub, out for delivery, delivered) with an event time and location.
• Anyone with a tracking number can look up the package's current status, estimated delivery date, and the full ordered history of scan events.
• Customers can subscribe to a tracking number and receive an email or push notification whenever the package's status changes.
• Shippers like Amazon register a shipment and get a tracking number before the first scan, and can query many tracking numbers in one call.
• The timeline shown to a customer is in true chronological order and never shows the same event twice, even though scanners send events late or more than once.

Non-functional requirements

• Status lookups are the critical path: p99 lookup latency under 200ms, since customers refresh the page repeatedly while waiting for a delivery.
• Availability over freshness for reads: a status page may lag the newest scan by up to 60 seconds, but it must never show an event that did not happen, show events out of order, or move a delivered package back to in transit.
• Every acknowledged scan is durable: once a scanner receives a success response the event can never be lost, because it is the only record of custody for the package.
• Ingestion keeps accepting scans when downstream components are slow or down; a hub's scan guns cannot queue events for long.
• Lookups are unauthenticated and must be rate limited per client to deter bulk scraping, and responses show only city-level locations, never the recipient's street address.

Scaling & constraints

• 5M new shipments per day; about 20M packages are in transit at any moment.
• Each package produces ~15 scan events over its life: ~75M events per day, ~900/sec on average and ~5,000/sec during the evening hub sort.
• Read:write ratio is about 20:1 (roughly 1.5B status lookups per day, ~17,000/sec average and ~50,000/sec at peak); a package out for delivery is looked up ~10x more than one sitting in a hub, and a high-profile shipment can draw tens of thousands of lookups per minute against a single tracking number.
• A scan event is ~300 bytes; a package's full timeline with metadata is ~5 KB.
• About 5% of scan events arrive out of order (a hub uploads a batch hours late after losing connectivity) and ~2% are exact duplicates from scanner retries.
• Full tracking history is retained for 2 years; shipment volume grows ~15% per year.

Out of scope

• Route planning, driver dispatch, and delivery time estimation models.
• Label printing, rate quotes, and shipper billing.
• Customs clearance, returns, and claims for lost or damaged packages.
• Scanner hardware and the on-device scanning app.