Package tracking - scan events and the promised date

Why this design

Every online shop, marketplace and tracking aggregator has to turn scans from carriers it does not control into one honest page: where is my parcel and when will it arrive. It looks like a status column, and it is really an event-ordering problem. Scans come from dozens of carriers in different formats, arrive minutes to hours after they happened, are sometimes sent twice, and occasionally contradict each other. Interviewers use it to see whether you separate event time from arrival time, make ingestion idempotent, and know the difference between a status (derived) and a scan (a fact).

What you will learn

• Why ingest acknowledges in 50 ms and queues, and why the queue is partitioned by tracking number.
• Normalising 1,200 carrier event codes into 14 statuses, and the timezone bug hidden in "2026-11-27 14:05" with no offset.
• The dedup key that makes a resent webhook and a duplicate EDI line the same event.
• Projecting status by sorting on scanned_at and applying a precedence rank, so a late scan lands in the past.
• An ETA model per lane, and notifying the customer only when the predicted day changes.
• Why polling carriers without webhooks runs into their rate limits, and adaptive poll cadence.

How to read this board

1. Press Play. CARRIERS on the left, INGEST in the middle, TIMELINE on the right, then TELLING PEOPLE along the bottom.
2. 1 · Requirements - what "accurate" can mean when you do not own the scanner.
3. 2 · Capacity and 3 · Storage - events, active parcels and the polling bill.
4. 4 · Availability - what happens when a carrier goes quiet for six hours.
5. 5 · How it works, 6 · Deployment plan, then the DATA MODEL.

Ask these before drawing anything

• How many carriers, and which of them push? The large ones offer webhooks; many regional and last-mile carriers offer only polling APIs or batch files.
• Whose promised date is shown - the carrier's, the merchant's checkout promise, or our own prediction? They disagree, and showing two dates is worse than showing one.
• Is the page allowed to be minutes stale? It almost always is; the scans themselves are.
• Who gets notified, on what changes, and by which channel?
• Does a merchant need the same events by webhook to trigger their own flows (refunds on lost parcels, review requests on delivery)?

Functional

• Register a shipment by carrier and tracking number at label creation.
• Accept scan events by webhook, poll, or batch file, normalise them, and show one timeline ordered by when each scan happened.
• Show a current status and a predicted delivery date, updated on every new scan.
• Notify the customer on out for delivery, delivered, exception, and when the predicted delivery day moves.

Non-functional

• A scan received by any route is on the page within 60 seconds of arrival.
• Duplicate or re-sent events never produce a duplicate timeline entry or a duplicate notification.
• A late or out-of-order scan never moves the status backwards past a terminal state.
• Tracking page p99 under 150 ms; it is the most refreshed page the merchant has.
• ETA within the predicted day for 90 percent of parcels on an ordinary week.