Skip to content

Build a Parcel Delivery Network

Davor Minchorov•Advanced•15 to 23 weekends•November 12, 2026

A regional courier has outgrown the one application it runs on: scans arrive late, the tracking page shows the wrong status, and one slow report stops the whole business. You will build the replacement, from booking a parcel through sorting, routing, delivery attempts, partner handoff and billing, and prove it survives a full simulated day with failures injected.

The brief

The client

I run operations at a regional courier. We deliver about 6,000 parcels a day for 200 online shops, from one sorting hub and 55 vans. Everything runs on one application, built when we handled 300 parcels a day. During one evening sort the hub scanners flooded it, and the merchant portal went down with it for two hours. Our tracking page tells people a parcel is out for delivery after the driver has already handed it over, because scanner uploads arrive late and the page shows whatever came in last.

I need a system where billing can be down without stopping a single booking, where a late scanner upload cannot rewrite what happened, and where I can answer a shop's question about any parcel with the facts instead of a guess.

The problem

The current system shows each parcel's status as whatever was written last. Handheld scanners work offline in the vans and upload in batches when they get signal, so a scan from 09:10 can arrive after one from 14:30 and replace it. Sorting, routing, billing and the merchant portal run inside the same application, so a slow report in one of them stops all four.

Merchants are billed from that same status, which is how one shop paid twice for a parcel that bounced between two statuses. Support spends most of its day answering "where is my parcel" with screenshots of internal screens. The contract with the client's second-largest merchant now carries a penalty for wrong tracking information.

The client's name and figures are invented for this brief; the rules and the failures are ones that real businesses of this kind work with.

The spec

Requirements

  • Let a merchant book a shipment through an API and get back a price, a tracking number and a printable label.
  • Let a merchant cancel a shipment until the parcel is first scanned.
  • Accept scans from handheld scanners that upload in batches, late and sometimes twice, and keep every parcel's history in the order things happened.
  • Show recipients a public tracking page for any tracking number, fast enough for the evening peak.
  • Sort every parcel that arrives at the hub to a delivery area, including parcels the hub was never told about.
  • Plan a daily route for each courier within the van's capacity, give the courier a manifest, and move a route to another courier when someone is out.
  • Run each parcel through up to three delivery attempts, then return it to the sender.
  • Send merchants signed webhooks that carry the same event identifier on every retry and replay, send recipients a delivery-day message, and never send a recipient two messages for the same event.
  • Hand parcels for addresses outside our region to a partner carrier, and show their progress on our tracking page.
  • Invoice each merchant monthly from what actually happened to their parcels, with the merchant's name and address and Dutch VAT shown separately.
  • Let an operator see everything that happened to one parcel, and erase a recipient's personal data on request.
  • Keep booking, tracking and sorting working while billing, notifications or the partner carrier's API are stopped.

Deliverables

  • Your repository starts the whole product with one command, plus a simulator that plays the shops, the hub scanners, the couriers and the partner carrier, moves the clock faster than real time and causes the outside failures this brief names.
  • A README that takes a reviewer from a fresh clone to a booked parcel showing as delivered on the tracking page in 15 minutes, and lists the command that runs each test in this brief.
  • Merchant-facing API documentation for booking, labels and webhooks, including how to verify a webhook signature.
  • A guide for the scanner and tablet makers: the format of a scan upload and of a courier's manifest.
  • A test suite, plus the results of the simulated day from the final Phase committed to your repository.
  • An operations note covering what an operator must be able to do: trace one parcel, retry a message that failed once the cause is fixed, repair a wrong tracking page, erase a recipient's data, and update one capability while the others keep serving.

Out of scope

  • Optimal route planning. The vehicle routing problem is a research field of its own; grouping parcels by delivery area and ordering them by postcode is enough here.
  • A courier mobile app. An HTTP API and a simulator stand in for the handhelds and the vans.
  • Other tax cases. Every merchant is in the Netherlands and every charge carries Dutch VAT at the standard rate of 21%. Reverse charge, other rates and the client's VAT return are left out.
  • Collecting payment from merchants. Billing ends at the issued invoice; our accounting system collects.
  • Live GPS tracking or maps. Recipients see scan events, not a moving dot.
  • Kubernetes or cloud deployment. Everything runs on one machine.
  • Recipient accounts. The tracking number is the only access a recipient needs.
  • International shipping and customs. Parcels for addresses outside our region go to the partner carrier, and that is where our responsibility ends.

Architectural constraints

  • Amounts are exact to the cent. Money is whole cents and weight is whole grams, and no invoice's net total differs from the sum of its lines by even one cent. Prices, surcharges and charges exclude VAT. An invoice's VAT is 21% of its net total, worked out once per invoice and rounded half up to the whole cent.
  • A parcel's history is always in the order things happened, never the order messages arrived.
  • Receiving the same scan, message or request twice changes nothing the second time.
  • Every retry and every replay of a webhook carries the same event identifier, so a shop can drop a copy it already has. A recipient never receives two messages for the same event.
  • A capability that is stopped may delay the others. It never makes them fail, and nothing it missed is lost when it returns.
  • No partner status code or partner field name is ever shown to a shop or a recipient.
  • A recipient's name, address and email are erased on request, while shipment, scan, delivery and billing records stay, identified by tracking number.
  • The courier's day runs on Europe/Amsterdam time: routes are planned at 05:00, vans leave at 07:00, and working days are Monday to Friday.

Prerequisites

You should have finished an intermediate project or have equivalent experience: you have built an application with a database, handled a request that arrives twice, and called an outside HTTP API. Any language and stack works. You do not need prior experience running several cooperating parts, and you do not need to know how a parcel courier works; the first Phase explains the business and the words the brief uses. Having once chased a bug caused by two systems disagreeing about the same record will make most of this brief feel familiar.

Create a free accountSign in

Free to start. An account is what keeps track of the checkpoints you finish.

Phase 1

Learn the courier's day

Produces the parcel's journey, the late-scan cases worked by hand, and a product that starts with one command and has a day driver that can move the clock and cause outside failures. Leaves all business behaviour for later Phases.

Research

Research

Implementation

Architectural walkthrough

How a regional courier gets a parcel to a door

The courier delivers about 6,000 parcels a day for 200 online shops, which the brief calls merchants. It runs one sorting hub and 55 vans. A merchant books a shipment through an API and gets back a price, a tracking number and a printable label to stick on the parcel. The merchant can cancel until the parcel is first scanned.

Parcels arrive at the hub, where each one is scanned and sorted to a delivery area. Routes are planned at 05:00 for each courier within the van's capacity, and the vans leave at 07:00 on working days, Monday to Friday. Each courier carries a handheld scanner and a manifest, the list of parcels for the day. The courier scans each parcel at the door. A parcel that is not delivered gets up to three delivery attempts, and then goes back to the sender. Parcels for addresses outside the region go to a partner carrier.

Recipients follow their parcel on a public tracking page and get a message on the day it is due. Merchants receive webhooks about their parcels and an invoice each month for what happened to them.

The words this brief uses:

  • Merchant: an online shop that sends its parcels with the courier.

  • Tracking number: the identifier a parcel carries from booking to delivery. A recipient needs nothing else to follow it.

  • Hub: the sorting site where parcels arrive and are sorted to delivery areas. It can receive a parcel nobody told it about.

  • Scan: a handheld reading a parcel's label to record what happened to it and when. A scanner in a van can stay offline for up to 8 hours and then uploads up to 500 scans every 5 minutes.

  • Delivery area: a part of the region that one courier's route covers.

  • Manifest: the courier's list of parcels for the day.

  • Delivery attempt: one try to hand a parcel over. A parcel gets up to three.

  • Return to sender: sending the parcel back to the merchant after the third failed attempt.

  • Partner carrier: another courier that takes the parcels for addresses outside the region.

  • Webhook: a message the courier sends to a merchant's server when something happens to a parcel. It is signed so the merchant can check who sent it.

Why the day comes before the code

This Phase builds no business behaviour. Starting to code before you understand the courier's day usually produces one status for each parcel, with the latest message overwriting it. The client's tracking page already works that way.

A handheld in a van holds its scans for up to 8 hours without signal. With signal it uploads up to 500 scans every 5 minutes, and it sends a batch again after any answer that is not a success or after a timeout. So a scan from 09:10 can reach the client after one from 14:30, and the same scan can reach it twice.

A page that follows arrival tells a recipient the parcel is out for delivery after the courier has handed it over, and it tells the shop the same. The contract with the client's second-largest merchant carries a penalty for wrong tracking information. Working the cases by hand now gives every later Phase answers to check against.

The failures in this brief also take the client's hours and days to play out: 8 hours without signal, 48 hours without a scan, a partner carrier that is down for 6 hours. A product that can only be tested in real time is hardly tested at all, and a reviewer who cannot start it in a few minutes will not see any of it work.

Phase 2

Accept a shipment

Produces quotes, bookings, tracking numbers, labels and cancellation for shops. Leaves scans and everything that happens to a parcel after pickup for later Phases.

Implementation

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

A shop's system books a parcel by calling the client's API. If the answer takes longer than the shop's timeout, the shop cannot tell whether the booking happened, so it sends the request again. A retry that creates a second parcel means two labels, two pickups and a double charge, and the shop finds out from the invoice.

The second copy often arrives while the first is still being handled. A product that only recognises requests it has already finished sees nothing to match and books twice. Two identical requests sent at the same instant show this failure, and two requests sent one after the other do not.

A price is a promise. The shop is quoted a price, books at that price and expects the invoice to say the same. If the client publishes a new rate card in between and the booked parcel is repriced, the shop pays an amount nobody told it and the client's sales lead takes the call. Money in whole cents keeps invoice totals from disagreeing with their own lines by a cent.

There are no recipient accounts, so the tracking number is the only thing between a stranger and a parcel's history. A number that can be guessed or counted lets a stranger read other people's parcels, or lets a competitor work out how many parcels a shop ships in a day.

A shop may cancel until the parcel's first scan, and the cancel and the first scan can happen in the same second. If both succeed, the shop believes it will not be charged while the courier carries the parcel, and the client either delivers for nothing or argues with the shop.

Phase 3

Ingest scans

Produces the intake of scanner uploads and a correct history of every parcel, with a test that shuffles, delays and repeats the uploads. Leaves the public tracking page for the next Phase.

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

A courier scans a parcel at pickup, at the hub and at the door. The vans have stretches with no signal, so a handheld holds its scans for up to 8 hours and uploads up to 500 of them every 5 minutes when it has signal. If an upload gets any answer other than a success, or times out, the handheld sends the same batch again.

So scans arrive late, twice and out of order as a matter of routine. A product that treats the order of arrival as the order things happened in replaces a delivered scan from 14:30 with an out-for-delivery scan from 09:10 that happened to arrive later. The recipient is told the parcel is out for delivery after it was handed over, the shop is told the same, and the contract with the second-largest merchant carries a penalty for each wrong answer.

Counting also goes wrong. A batch of 500 that arrives twice and is counted twice shows a parcel with two failed attempts after one. A later Phase sends a parcel back to its sender after the third failed attempt, so the parcel goes back after only two real tries.

A handheld cannot fix a bad scan. If one bad scan makes the client refuse a whole batch, the handheld sends it again forever and the good scans in it never arrive. The last Checkpoint of this Phase shuffles, delays and repeats the same scans many times over, because a check per rule does not show that the rules hold together.

Phase 4

Serve the tracking page

Produces the public tracking page for recipients, one that stays up when scan intake is stopped and holds the client's load target. Leaves partner carrier progress and delivery attempt details on the page for later Phases.

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

A recipient opens the tracking page with a tracking number and nothing else. The client's old application served the page from the same machine that took the scanners' uploads. During one evening sort the scanners flooded it, and the merchant portal went down with it for two hours.

A page that fails when scan intake is slow or stopped fails in the same hours the scanners are busiest, and that is when recipients look. Every failed page view is a call to support. The page can be a few minutes behind and still be useful, and it cannot be an error.

The page also shows too much when nobody looks. Scans carry the device that took them, the hub steps the parcel went through and the reasons couriers type. A recipient has no use for any of it, and a stranger with a guessed tracking number has no business seeing it.

A mistake in how the product works out a status will one day show a wrong page for thousands of parcels at once. Fixing 6,000 pages by hand is not possible, and nobody can say afterwards which ones were touched. The client sets the target for the page in numbers: 200 requests per second for 60 seconds, p95 under 200 ms, zero errors.

Phase 5

Sort at the hub

Produces the sorting of parcels to delivery areas at the hub, including parcels nobody expected, bookings that survive a crash and a hub that keeps sorting while booking is stopped. Leaves routing and vans for the next Phase.

Implementation

Testing

Implementation

Testing

Architectural walkthrough

Parcels reach the hub on a belt. A sorter reads each label and needs the delivery area at once, because every second spent waiting holds up the parcels behind it.

A booking can be confirmed to a shop while the hub never hears of it.

Some surprises are routine. A parcel can arrive before its booking, or with a label too damaged to read, or from a shipment the shop has cancelled. If the hub refuses such a parcel without a reason the sorter is left guessing, and a wrong guess puts the parcel on the wrong van.

Booking will be stopped at some point, for an update or a fault. A hub that waits for booking before it sorts each parcel idles every sorter in that time, and the vans still leave at 07:00.

Phase 6

Plan routes and dispatch

Produces a daily route for each courier within van capacity, the move of a route when a courier is out, and a manifest for each courier. Leaves delivery attempts for later Phases, and route optimisation is not part of the brief.

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

Routes are planned at 05:00 and the vans leave at 07:00. A plan that is wrong is found out at the van door, by a courier standing next to a van with too many parcels or parcels nobody assigned. A parcel on no route is a parcel nobody delivers that day, and a parcel on two routes is delivered once and then reported missing by the other courier.

A van holds 120 parcels and 600 kg, and a route can be within one limit and over the other. A route that is too big for its van leaves parcels at the depot, and those parcels miss their day.

A courier calls in sick at 06:30. Their route has to move to someone else before 07:00 or a day of parcels waits.

The manifest is the courier's list for the day, and it holds the names and addresses of recipients. A courier who gets half a manifest does not know which parcels they are missing until a recipient calls. Those names and addresses are personal data that the client must erase on request, wherever the product has put them.

Phase 7

Deliver, retry and return

Produces proof of delivery, a second attempt on the next working day, a return to the sender after the third failure, and a flag for parcels that stop moving. It does not notify anyone or bill anyone yet.

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

A parcel gets at most three delivery attempts, and the number of attempts decides what happens to it. After the third failure it goes back to its sender. Scans reach the network late, twice and out of order, so the count has to be right under all three.

Take a handheld that uploads a failed-attempt scan and gets no answer in time. It uploads the same scan again, as it is built to. If the second upload counts as another attempt, one real failure looks like two, and two such repeats send a parcel back to its sender after a single try. The shop gets a return it did not expect and later pays the 350 cent return charge for a parcel nobody tried hard enough to deliver.

Order causes the opposite mistake. A courier fails an attempt in a street with no signal and delivers the parcel later the same afternoon. If the batch holding the failure is held for 8 hours and the batch holding the delivery arrives first, a count that follows arrival decides the parcel failed last. A parcel the recipient already holds is then rescheduled or sent back.

A parcel that has vanished is the quietest failure. It produces no scan, so nothing arrives to say anything is wrong. The shop finds out when its customer phones, and the client's contract with its second-largest merchant carries a penalty for wrong tracking information.

The last Checkpoint of the Phase, Count Each Delivery Attempt Once However the Scans Arrive, kills the product at random moments. A crash in the middle of dealing with a failed attempt must neither lose the attempt nor act on it twice.

Phase 8

Notify merchants and recipients

Produces signed webhooks to shops with a fixed retry schedule, one delivery-day email per parcel, and a replay of the last 7 days of webhooks. It leaves the partner carrier and invoices for later Phases.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

Shops act on the webhooks they receive: they tell their own customers, release stock and ship a replacement for a parcel that came back. A shop that cannot tell a retry from a new event sends two customer emails or ships two replacements. The client's rule is that every retry and every replay of a webhook carries the same event identifier, so a shop can drop a copy it already has.

A webhook is a call to a machine the client does not run, and the call times out after 5 seconds. A shop whose endpoint hangs makes every call to it take the full 5 seconds. With 200 shops, if one hanging shop delays the news for the others, then one slow shop turns into late news for everyone, and the recipient emails that follow behind it are late too.

A product that stops in the middle of sending has two bad outcomes. If it stops after the call went out, the next start may tell the shop again as if it were news. If it stops before the call, the shop may never hear. The last Checkpoint of the Phase, Prove No Shop or Recipient Is Told the Same Thing Twice, kills the product at random moments to find out which of these it does.

The recipient's email has its own version of the problem. A recipient who gets three emails on delivery morning stops opening them, and a recipient who gets one for every repeated scan sees a client that cannot count. The client's rule is one email on the morning a parcel goes out for delivery, and at most one per parcel per day.

A shop whose endpoint was down overnight misses news the client has already given up on. Without a way to get that news back, the shop phones support, and support cannot say what was sent or when.

Phase 9

Hand off to the partner carrier

Produces the hand-over of parcels outside the region to the partner carrier, and their progress shown on our own tracking page. It leaves invoices for a later Phase.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

Parcels for addresses outside the region go to one partner carrier. The partner has no webhooks, so the only way to know what happened to a parcel is to ask. It answers late, repeats a status, reports statuses out of order, sometimes accepts a request and then times out, and can be unreachable for 6 hours.

A hand-over that times out does not say whether the partner accepted the parcel.

The partner speaks its own language: six status codes (ACC, TRN, OFD, DLV, ATT and RTS). If those codes reach a shop's webhook or a recipient's page, 200 shops have to learn them, and when the partner renames one the shops break. The client's rule is that no partner code is ever shown to a shop or a recipient.

A 6 hour partner outage must not become the client's outage. About 6,000 parcels a day move through the network and only some belong to the partner. If tracking or delivery for the rest waits for the partner to answer, a few partner parcels stop the whole day.

The partner also reports attempts that its own couriers made. Those are not the client's three delivery attempts, and counting them as such sends a parcel back to its sender early, or never.

Phase 10

Bill the merchants

Produces prices, surcharges and monthly invoices that match what actually happened to each parcel. It leaves the operator's tools and the full simulated day for the last Phase.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

An invoice is the one place where every earlier mistake becomes money. The client's own history includes a shop that paid twice for one parcel because its status bounced between two values. The contract with the second-largest merchant now carries a penalty for wrong information, and an invoice that disagrees with the tracking page is wrong information with a total on it.

A shop checks its invoice against the price it was quoted at booking. If the rate card changes in between and the invoice uses today's prices, the shop sees a difference on a parcel it never changed, and every dispute that follows costs support more than the difference. A shipment the shop cancelled must never appear on an invoice at all.

The information billing relies on arrives late, twice and out of order, like every other outside input. A return counted twice charges 350 cents too much, and a weight correction applied after the parcel was already billed at the higher band charges twice for the same thing.

Invoice numbers are sequential per year with no gaps, because an accountant who finds 2026-000014 missing asks where it went. Two people closing the same month at the same instant must not produce two invoices with the same number, or leave a number unused.

Billing is also the capability most likely to be stopped. If it is stopped for an hour while parcels are delivered, those parcels must be on the invoice afterwards, and shops must still be able to book and track meanwhile.

Phase 11

Operate the network

Produces what an operator needs to answer for any parcel, an erasure on request, an update with nothing lost, and the full simulated day with every failure at once. It leaves nothing for later.

Implementation

Implementation

Implementation

Testing

Testing

Architectural walkthrough

At 06:40 a shop phones about a parcel. The operator needs the facts from everything the product has done for it, and the contract with the second-largest merchant has a penalty for wrong tracking information. If the answer is spread over several places that the operator has to read and match by hand, it takes an hour and may be wrong.

One bad item can stop a whole day. A scan the product keeps failing to handle, or a shop endpoint that always errors, can hold up everything that arrives after it. If it is retried forever, thousands of parcels' tracking waits on it. If it is dropped silently, a parcel's history has a hole and nobody was told.

An update during the evening peak is when scanners flood in. An update that refuses or drops uploads for even a minute loses scans that handhelds believe were accepted, or makes them retry into duplicates. Shops that book during the update meet errors, and the client has promised them bookings are always accepted.

A recipient can ask to be forgotten. Their name, address and email are copied into labels, manifests, emails waiting to be sent, traces and logs, and one copy left behind is a breach. The shipments, scans, delivery results and invoices that tax and traceability require must stay, identified by tracking number.

Every failure in the earlier Phases was tested alone. In production they arrive together, and the problems that appear only in combination are the ones that reach the client. The last Checkpoint of the Phase runs them all in one day.

Architectural walkthrough

A late scan is not the latest scan

The old system showed whatever had been written last. A handheld in a van with no signal holds its scans for up to 8 hours, so a scan from 09:10 can reach the server after one from 14:30. The page then tells a recipient the parcel is out for delivery after the driver has already handed it over, and the shop that sent it is told the same. Every wrong tracking page in the client's story comes from this. The contract with the second-largest merchant puts a penalty on each one.

The same trouble shows up in smaller places. The partner carrier reports statuses when you ask for them, so an outage leaves a gap that fills with old news. A courier's scanner retries an upload when it gets no answer, so the same 500 scans arrive twice. Check your build against a parcel whose scans arrive in the worst order you can invent, and against the same upload sent three times.

Nothing happens twice, nothing is lost

A shop that cannot tell a retried webhook from a new event may ship a second parcel. A recipient who gets three emails in a morning stops opening them. A merchant billed twice for one parcel calls the client's sales lead, which is how the double charge in the client's story was found. A product that stops halfway through a booking leaves a shop told "booked" while the hub has never heard of the parcel, and nobody finds out until a van is short of one.

These failures happen at the moment two things must agree and the machine stops between them. Checking only the quiet path will not find them. Kill things at random moments, send requests at the same instant, and count what the shops, the recipients and the invoices actually show afterwards.

One stopped part must not stop the rest

The client lost the merchant portal for two hours because a scanner flood slowed the shared application. The cost is not the two hours. Shops that cannot book send their parcels to a competitor that day, and some do not come back. Billing, notifications, the partner carrier's API and the scan intake will each be down at some point. What the client needs to know in advance is which work continues: with billing stopped, shops can still book and track parcels; with the partner carrier unreachable for 6 hours, in-region parcels still reach their recipients; with scan intake stopped, recipients can still open their tracking page.

An update is a planned outage. Replacing one capability while shops keep booking and scanners keep uploading must cost the client no booking and no scan.

Where it shows if you cut a corner

The simulated day in the last Phase brings 6,000 parcels from 200 shops and about 45,000 scans, with some scan uploads sent twice, others held back by 6 hours, the product killed mid-run, the partner carrier unreachable for 2 hours and billing stopped for 1 hour. If a late upload rewrites a newer fact, the invoices do not match what the simulator delivered. If a stopped capability makes another one fail, the day shows errors on the shops' side while it is down. If anything is sent twice, the simulator's receivers count it. Each of these is cheaper to find in your own run than in a merchant's penalty claim.