Skip to content

Build a Same-Day Courier Service

Davor Minchorov•Intermediate•7 to 8 weekends•November 12, 2026

A city courier runs on one application, and riders' phones upload their scans late and twice. You will build the product from booking a parcel through scans, delivery attempts and messages to the monthly invoice, and prove it on a simulated day with every failure at once.

The brief

The client

I run a same-day courier for the independent shops of one city: florists, bookshops, a few bakeries. Twelve couriers, ten on e-cargo bikes and two in vans, carry about 400 parcels a day for 30 shops, out of one depot. A bike carries up to 50 parcels or 100 kg on a run and a van up to 120 parcels or 600 kg. A parcel booked before 10:00 is delivered the same day: the depot plans runs at 08:00 and again at 13:00. Each rider scans parcels on a phone app, and the phone holds its scans until it finds signal, because half our drop-offs are in basements and car parks.

Last month a florist's customer got a "your order is on its way" message three hours after the bouquet was on their doorstep, because a rider's phone uploaded its morning scans at 15:00 and the system believed the last thing it heard. The same upload made the system schedule a second delivery attempt for a parcel that was already delivered, and I billed the florist for it. I need one place where a parcel's story is true in the order it happened, and where a shop's invoice, a customer's message and a rider's day all come from that same story.

The problem

The current system is a spreadsheet plus a small web form. A parcel has one status cell, and the phone app writes the cell when it uploads, so the cell holds whatever uploaded last. Three things read that cell: the message sender, the rider's run list and the monthly invoice script. When an upload arrives late, all three act on an old fact as if it were new.

Two shops have been refunded for deliveries that were charged twice. The first hour of every day goes to answering "where is my parcel" by reading phone screenshots. A shop that left for a competitor named the wrong tracking messages as the reason.

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 shop get a price quote and book a parcel through an API, and get back a price and a tracking number.
  • Book the same request once, however often a shop sends it, even when two copies arrive at the same moment.
  • Accept scans from riders' phones that upload in batches, late and sometimes twice, and keep every parcel's history in the order things happened.
  • Show a recipient a public tracking page for any tracking number, with the status concluded from the scans.
  • Plan the day's runs at 08:00 and again at 13:00 for every rider within the rider's capacity, and give each rider the stops for the day.
  • Allow at most two delivery attempts, list the parcels that go back to the shop after the second failure, and take a second attempt off the plan when a late scan shows the parcel was delivered.
  • Message the recipient at most once per delivery day when the parcel goes out for delivery, and never after it was delivered.
  • Erase a recipient's personal details on request and keep the scans and billing records.
  • Show each shop its charges for the month, and invoice each shop monthly from what actually happened, with one charge per finished parcel, the shop's name and address, Dutch VAT shown separately, and invoice numbers that never skip.
  • Lose nothing and double nothing when the product is killed at any moment, including right after it told a shop or a phone that something worked.

Deliverables

  • Your repository starts the product with one command, with 30 shops (each with a name and address), 12 riders (R01 to R10 on bikes and R11 and R12 in vans, each with a vehicle type), the client's own name, address and VAT number, and rate card version 1 loaded, and the message provider stand-in and the simulator started with documented commands.
  • A README that takes a reviewer from a fresh clone to a simulated day's report in 15 minutes, and lists the command for each test.
  • Shop API documentation: how a shop gets a quote, books and retries with an Idempotency-Key, reads its statement and invoices, and erases a recipient.
  • A phone upload guide: the shape of a scan, the shared upload token, what each answer to a batch means, and how a phone asks for a rider's stops.
  • A test suite. The tests of requests that overlap send them so they truly run at the same moment, and a setup that handles one request at a time does not count.
  • A simulator that plays the client's day faster than real time, with the late and repeated uploads, the provider failures and the kills the brief names, each switchable.
  • The comparison result from Phase 3 and the report of the final simulated day, both committed to your repository.
  • An operations note: how the client adds a rate card, how an operator plans a date and a wave by hand and sees how many parcels did not fit, finds failed messages and sends them again, reads the depot's return list, closes a month again without issuing anything twice, and reads the late-change list.

Out of scope

  • A partner carrier and the translation of its statuses. This client delivers inside one city.
  • Signed webhooks to shops. They teach request signing and replay windows, and this brief spends that weight on the late-upload problem.
  • A hub, sort areas and weight correction. This client has one depot and no sorting operation.
  • Route optimisation and real maps. Grouping parcels by zone and filling each rider up to capacity is enough.
  • Detecting parcels that stop moving. A parcel with no scans after its planned date stays as it was.
  • A load test of the tracking page. At 400 parcels a day the page does not need to be built for traffic.
  • Keeping some features running while others are stopped, and updating without downtime. Build a Parcel Delivery Network covers them.
  • Collecting payment. Billing ends at the issued invoice, and the client's accountant collects.
  • Other tax cases. Every shop is in the Netherlands and every charge carries Dutch VAT at the standard rate of 21%. Reverse charge, other rates, foreign shops and the client's VAT return are left out, and this brief gives no tax advice.
  • Automatic erasure after a retention period. Erasure happens on request only. Dutch law requires the client to keep its business records for 7 years, so the invoices and the charges behind them stay, identified by tracking number and shop id. The client's own adviser sets any other period.
  • A credit line for a scan that changes a parcel's outcome after its month closed. The invoice stays as issued and the case is listed as a late change.
  • A rider mobile app and per-phone sign-in. The simulator stands in for the phones, and one shared upload token stands in for their credentials.

Architectural constraints

  • Amounts are exact to the cent, and every amount in an answer is a whole number of cents. Weights are whole grams. Prices, fees and lines exclude VAT. VAT is worked out once per invoice, as 21% of the invoice's net total rounded half up to the whole cent.
  • Times shown to people, and the day, working day and month a scan, an attempt or a charge belongs to, are read in Europe/Amsterdam time.
  • A parcel's status is what its scans say in the order they happened. The last upload received never decides it.
  • A shop is charged the price it was quoted at booking, whatever the rate card says later.
  • A recipient is never messaged more than once for one parcel on one delivery day, and never about a parcel already delivered.
  • No page, message log, charge line or invoice shows a recipient's name, address, phone, email or postcode, except the message to the recipient and the rider's stop list.
  • Personal fields are erased on request, while scans, prices, charges and invoices stay, identified by tracking number and shop id.
  • Invoice numbers never skip and never repeat.
  • A shop sees only its own parcels, statements and invoices.
  • The way the simulator sets the product's moment is refused in a live installation.

Prerequisites

You have built one application with a database, in any language and stack. You do not need to know how a same-day courier moves parcels for city shops; the first Phase explains the business and the words the brief uses. You do not need to have built any other Codyssey project. Having once chased a bug where two parts of a system disagreed 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

Work out the rules and play a day

Produces a table of the seven scans and the moves allowed between them, with worked examples, and a way to play the courier's day faster than real time with its failures on demand. Leaves every behaviour of the product for later Phases.

Research

Implementation

Architectural walkthrough

How a same-day courier moves parcels for city shops

The client is a same-day courier for the independent shops of one city: florists, bookshops and a few bakeries. Thirty shops book about 400 parcels a day. The courier works from one depot with twelve riders, ten on e-cargo bikes and two in vans. A bike carries up to 50 parcels or 100 kg on a run and a van up to 120 parcels or 600 kg.

A shop books a parcel before 10:00 and the parcel is delivered the same day. The depot plans the runs at 08:00 and again at 13:00, and each rider gets the stops for the day. A rider collects parcels from the shops, brings them to the depot, loads them, takes them out and delivers them. At each step the rider scans the parcel on a phone app. The phone holds its scans until it finds signal, because half the drop-offs are in basements and car parks.

A delivery that fails is tried once more, on the next working day. After a second failure the parcel goes back to the shop. The recipient can follow a parcel on a tracking page and gets a message when it goes out for delivery. At the end of the month each shop is invoiced for its finished parcels. Every shop is in the Netherlands, so Dutch VAT at 21% is added to the price.

The words this brief uses:

  • Depot: the courier's base where parcels arrive, are loaded and planned.

  • Run: one rider's trip with a set of parcels.

  • Scan: a rider's record that something happened to a parcel, such as picked up, loaded or delivered. A scan has the time it was taken and the time the product received it.

  • Delivery attempt: one try at handing a parcel over. There are at most two.

  • Tracking number: the number a recipient uses to follow a parcel.

  • Zone: the part of the city a parcel goes to, inner or outer, which sets its price.

  • Rate card: the price list for zones and weight bands, in euro cents without VAT.

  • Return to the shop: sending a parcel back after its second failed attempt.

  • Invoice number: the number of a shop's monthly invoice. Numbers never skip.

Why the right answers come before the product

This Phase has no product behaviour, and it exists because of one failure. A rider's phone takes a scan at 11:40 in a basement with no signal and uploads it at 15:00. By then the product has heard other things about the same parcel, and every part of the client's business that trusted the last thing it heard acts on an old fact. That is how a florist's customer was told "on its way" three hours after the bouquet arrived, and how the same upload scheduled a second delivery attempt that was billed.

Two things are missing before any of that can be fixed. The first is the right answer, worked by hand: what the recipient should be told, which parcels a rider should carry and what a shop should owe, for a parcel whose scans arrive out of order. Without it, a test can only check the product against itself, and a product that gets the order wrong is still consistent with itself.

The second is a day that can be replayed. A six-hour delay cannot be tested by waiting six hours, and a failure that appears on one random day and not the next never gets fixed. The simulator plays the same day from the same seed, causes the uploads that arrive late and twice, and records the order scans were really taken, which later Phases compare the product against.

Phase 2

Book a parcel

Produces a quote from a versioned rate card, a booking that is safe to retry and an unguessable tracking number. Leaves scans, runs, messages and invoices for later.

Implementation

Implementation

Testing

Architectural walkthrough

A booking is a write that shops retry. A shop's client times out and sends the same request again, and a product that creates a parcel for every arrival gives the shop two parcels and two prices from one order. The shop is then billed twice, and the client refunds it, as happened to two shops already. The same duplicate can also arrive at the same moment as the original, when both requests look new to a product that handles them one at a time without looking at the other.

A rate card edited in place and a tracking number someone can guess are the other two failures, and the duplicate that arrives at the same moment as the original only shows in a test where requests really overlap.

Phase 3

Record what happened

Produces accepted scan uploads, a public tracking page and scans shown in the order they happened, then proves that late and repeated uploads give the same story. Leaves delivery attempts, messages and invoices for later.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

This Phase turns on what "latest" means. The order in which uploads arrive is a fact about the network, and the time a scan was taken is a fact about the parcel. The old system went by arrival, so a phone that uploaded at 15:00 beat a scan taken at 11:40, and the recipient's page, the message sender and the invoice all believed it.

Phones repeat their uploads, report one bad scan in a batch of 100, and run their clocks up to 5 minutes ahead. The last Checkpoint puts all of it under one test against the record of what really happened.

Phase 4

Run the delivery day

Produces the day's runs, planned at 08:00 and 13:00 and filled within a rider's capacity, a second attempt after a failure, a return to the shop after the second failure and a second attempt withdrawn when a late scan shows delivery. Leaves messages and invoices for later.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

This Phase turns on one rule: a parcel's delivery outcome follows from its scans in the order they happened, and never from the uploads the product has received so far. The failure is the one in the client's story. A phone uploads a morning failure at 11:05, the product plans a second attempt for tomorrow, and the same phone uploads the afternoon delivery at 17:00. A product that acts on the failure when it arrives sends the rider back to a parcel that was delivered, and the shop is billed for the visit.

An attempt is a delivery day, at most two of them, then a return to the shop. Planning has its own failures: a plan started twice, a parcel nobody plans after a crash, and working days counted in UTC.

Phase 5

Message the recipient and erase on request

Produces a message provider stand-in that fails on demand, at most one message per parcel per delivery day, messages that survive timeouts and crashes, and erasure of a recipient's details. Leaves invoices for later.

Implementation

Implementation

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

This Phase turns on what a timeout means. When the provider takes longer than 5 seconds to answer, the product knows the answer did not arrive. It does not know whether the provider did nothing. The provider may have accepted the message and been slow to say so, and a blind retry then sends the recipient a second email. Giving up blindly has the opposite cost, a recipient who is never told. A product that dies between deciding to send and learning the answer is left with the same doubt.

A message sent on old information, receipts that arrive twice or out of order, and an erasure that has to find every copy of an address are the rest of the Phase.

Phase 6

Bill the shops and prove the day

Produces one charge per finished parcel and gap-free numbered monthly invoices, then runs a simulated day with every failure at once. Leaves collecting payment and tax lines out of the brief.

Implementation

Implementation

Testing

Architectural walkthrough

This Phase turns on charging once per parcel. A returned parcel is billed its price plus the 300 cent return fee, a late scan then shows it was delivered, and a product that charges on every report now bills two lines for one parcel. The shop pays 890 plus 590 for a parcel that cost 590, which is what the client's florist saw.

The price is the one the shop saw at booking, the month is read in Amsterdam time, and invoice numbers never skip or repeat. The last Checkpoint runs the simulated day twice, once clean and once with every failure, and compares the layers in order: stories, outcomes, messages, statements, invoices.

Architectural walkthrough

The last upload is not the latest fact

The old system kept one status cell per parcel and let every part of the business overwrite it. A phone that held its morning scans until 15:00 replaced a fact from 11:40 with one from 09:10, and the message sender, the run list and the invoice script all acted on a fact that had stopped being true. None of them could tell the order uploads arrived in from the order things happened.

Check your own build with the three scans from the client's story: a depot scan taken at 07:30, a delivery taken at 11:40 and uploaded at 11:41, and an out_for_delivery scan taken at 09:10 and uploaded at 15:00. The page must still say Delivered, the recipient must get no message, and the shop must be billed once. Then check what a phone with a clock 5 minutes ahead does to the order.

The same thing twice

Phones retry anything that does not look like a success, shops retry a booking that timed out, and the email provider repeats its own receipts. Each repeat is normal operation. A repeated booking costs the client a refund. A repeated scan can schedule a second delivery attempt, a second message or a second charge. A repeated receipt can make a delivered message look as though it is still in flight.

Check your own build by sending every kind of input twice, five times and in a different order, and counting what exists afterwards.

Two things at the same moment

An operator who reruns a plan, two operators who start the same month close together, a shop that sends its retry before the first answer comes back: each puts two copies of one request in the product at the same moment. Overfilled runs, a parcel on two riders' lists and two invoices with one number all come from this. A test that sends one request at a time cannot show any of it, because every one of those failures needs two requests to overlap.

Check your own build with requests that really overlap, and check that your tests would fail on a setup that handles one request at a time.

The product dies at the wrong moment

A shop is told its booking worked and the product dies right after, so the parcel is never planned. A provider accepts a message and the product dies before it learns that, so a restart sends it again. A parcel is delivered and the product dies before it is charged, so the revenue is missing and nobody notices until the month is closed. The client sees each one as a person phoning to ask where something is.

Check your own build by killing it at random points during the simulated day and comparing the result with a day that had no kills.

Where it shows if you cut a corner

If the last upload decides, the stories test in the final Phase shows a parcel whose scans are out of order. If a timeout is treated as a failure, the provider holds the same message twice. If every report of an outcome adds a charge, one parcel has two lines on the invoice. Each of those tests finds the problem before a shop's invoice does.