Skip to content

Build a Delivery Log for a One-Van Courier

Davor Minchorov•Beginner•1 to 2 weekends•November 12, 2026

A courier with one van keeps her parcels in a notebook and a spreadsheet, and one wrong word in one wrong row once told a shop that a parcel had been delivered when it was back in her garage. You will build the delivery log that registers each parcel, moves it through its journey under fixed rules, and lets anyone look it up by tracking code, so that a status is always one the parcel really earned. It runs on your own machine, in the language and with the interface you choose.

The brief

The client

I'm Marta. I run a one-van courier in a small town and bring parcels from eight local shops to people's doors, about 25 a day. I keep it all in a notebook and a spreadsheet that the shops can see.

Once a shop told a customer her parcel was delivered, because someone had typed "delivered" into the wrong row. I had actually brought that parcel back to my garage, which I call the depot, after the third time nobody answered the door. The customer waited for a parcel that was never coming, and the shop owner phoned me, annoyed. I need a log where every parcel has one honest status, where I can see how it got there, and where the shops can check it themselves without calling me.

The problem

The spreadsheet lets anyone type any status into any cell, so nothing stops a parcel from jumping to "delivered" without ever leaving the depot. Nothing records who changed a status or when, so after a mistake Marta cannot say what happened.

The shops sell on the promise that a parcel arrives, and the status Marta gives them is the only proof they have. Every wrong status costs a phone call from an annoyed shop owner, and every "where is my parcel" call takes her out of the van.

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

  • Register a parcel for one of the eight shops and get back a tracking code.
  • Look up any parcel by its tracking code and see its current status and its history, oldest first.
  • Send a parcel out for delivery, mark it delivered, or record a failed attempt, and refuse every move the rules do not allow.
  • Return a parcel to its sender automatically on its third failed attempt.
  • Keep every change in the parcel's history, and never edit or delete a past change.
  • Refuse bad input, such as a missing name or an unknown shop, and change nothing when you do.
  • Show Marta, for one day, how many parcels registered that day are in each status.
  • Show a shop every parcel it has handed to Marta, newest first, with the current status.

Deliverables

  • A working log you can start on your own machine, with the eight shops already in it, behind an interface of your choice: a web page, an API that other programs call by sending requests, or a command-line tool.
  • A README that takes a reviewer from a fresh copy to a parcel registered, sent out, failed once and then delivered, in 10 minutes.
  • A document in your repository that lists the four statuses, every allowed move and two example journeys, for Marta and the shops to read.
  • A test suite, code that drives the log and checks its answers against what you expect, that runs with one command and tries all three moves from all four statuses.
  • A script that plays a week of 125 parcels and prints the checks listed in the last Checkpoint.

Out of scope

  • Prices, fees and invoices. Billing is a problem of its own and the money rules would double the size of this project.
  • Routes, stop order and van capacity. Marta drives one van and knows her town.
  • Scanners and uploads that arrive late or twice. Every change here happens when Marta presses a button, in the order she presses it. Out-of-order and repeated messages belong to the next step up, Build a Same-Day Courier Service.
  • Emails, text messages and anything that tells people automatically. Marta still phones.
  • A label or a barcode. Marta writes the code on the parcel by hand.
  • Logins and user accounts. There is one user and the log runs on your own machine. Do not put it on the internet as it stands, because anyone who can reach it can change any parcel.
  • Adding or editing shops. The eight shops are loaded once and stay as they are.
  • Correcting a "delivered" that was entered by mistake. Delivered is final.
  • Partner carriers and parcels outside the town. Marta only delivers locally.

Architectural constraints

  • A parcel only ever reaches a status through a move the rules allow.
  • A move either happens completely, with its history entry, or leaves no trace, even if the program is stopped halfway.
  • A refused move leaves everything exactly as it was.
  • History is never edited or deleted. The parcel's current status always equals the status on its last history entry.
  • Times are shown in the town's time zone, Europe/Amsterdam, with their offset, and a parcel counts for the Amsterdam day it was registered on.
  • The person or the request can supply the current time, for testing.
  • Nobody can work out a parcel's tracking code from another parcel's code.
  • The lookup by tracking code shows the status and the history but no address and no names of people.

Prerequisites

You can write a small program in the language of your choice and you have saved data to a database or a file at least once. You do not need to know any web framework, and you do not need to have written an automated test. You do not need to know how a one-van courier gets parcels to doors; the first Phase explains the business and the words the brief uses. Having once typed a wrong value into a spreadsheet and watched it spread will make the problem familiar.

Create a free accountSign in

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

Phase 1

Register parcels and look them up

Produces the written status rules, the eight shops, registered parcels that each carry an unguessable tracking code and a first history entry, and a lookup that answers from the code alone. Leaves every move between statuses for later.

Research

Implementation

Implementation

Implementation

Architectural walkthrough

How a one-van courier gets parcels to doors

Eight local shops in a small town sell to people who live nearby. The shops hand their parcels to one courier, Marta, who brings them to people's doors in her van, about 25 a day. She keeps the parcels in her garage, which she calls the depot, between the moment she takes them and the moment she drives them out.

The shops sell on the promise that a parcel arrives, so the status she gives them is their only proof. A delivery can fail, for example when nobody answers the door. After the third failed attempt the parcel goes back to its sender. Each parcel carries a tracking code that Marta writes on it by hand, and the shops use it to check where a parcel is instead of phoning her.

The words this brief uses:

  • Shop: one of the eight businesses that hand parcels to Marta.

  • Depot: Marta's garage, where parcels wait between deliveries.

  • Tracking code: the code written on a parcel, used to look it up.

  • Status: where a parcel is in its journey right now.

  • History: the list of every change a parcel has been through, oldest first.

  • Failed attempt: a try at the door that did not end in a delivery.

  • Return to sender: sending a parcel back to the shop it came from.

Why the rules come first

Marta's spreadsheet had no rules, so a status could be anything and nobody could say how a parcel got there. This Phase gives the log its rules in writing and then lets parcels exist under them.

If the rules are not written before the first parcel, they end up as whatever the first buttons happened to allow. A parcel that can reach "delivered" from the depot is then a matter of which button you wrote first.

A parcel with a status but no story is a parcel Marta cannot explain. Every parcel needs its first history entry the moment it is registered, so the current status always has a last entry to match.

The tracking code is the only thing between a stranger and a parcel's history, because there are no logins and the code is written on the parcel for anyone on the street to read.

Phase 2

Move a parcel along its journey

Produces the three moves (send out, deliver, record a failed attempt), the return to sender on the third failure, and a test that tries every move from every status. Leaves the day board and the shop view for later.

Implementation

Implementation

Implementation

Testing

Architectural walkthrough

This Phase is where Marta's wrong row becomes impossible. A parcel that jumps from the depot to "delivered" means a shop promises a customer something that is not true.

A move that changes the status but not the history, or the history but not the status, leaves a parcel Marta cannot explain. If the program stops between the two, she is guessing again.

A refused move must change nothing at all, including the number of failed attempts. A count that rises for a move that was refused makes the third-failure rule fire early.

The third failed attempt is the part most likely to be off by one.

Pressing a button twice happens. If delivering a parcel twice records two deliveries, the history says something that never happened.

Phase 3

Give Marta and the shops their views

Produces the day board for Marta, the view each shop gets of its own parcels, and a script that plays a whole week of parcels from registration to the end and checks the result. Leaves everything automatic for later.

Implementation

Implementation

Testing

Architectural walkthrough

Marta and the shops read the log, and each asks a different question. Marta asks how her day is going. A shop asks where its own parcels are.

Marta's day is a day on the clock in Amsterdam, and for an hour or two around midnight that day and the calendar date on a clock that ignores time zones disagree. A parcel registered at 00:30 on Wednesday counted under Tuesday makes Tuesday's total wrong by one, and nothing reports an error.

A shop must see its own parcels and nobody else's. A shop that sees another shop's recipients has been handed customers it did not earn, and the shops sell on trust.

A new shop with no parcels yet must not look broken, and a name that is not one of the eight must not look like an empty shop.

The week of parcels is the proof. A log that is right for one parcel can still go wrong across 125, and the totals Marta reads only help her if they add up.

Architectural walkthrough

A status nobody earned

Marta's wrong row happened because a parcel's status was a piece of text that anyone could overwrite with anything. A parcel reached "delivered" without ever leaving the depot, so the status said nothing about what had happened. The shop told the customer her parcel had arrived, the customer waited, and the shop owner phoned Marta. Every refused move you build is one of those calls that no longer happens.

The same mistake gets worse when the rules are written down more than once. If the buttons each carry their own idea of what is allowed, a fix in one leaves the others wrong, and the wrong status comes back through the button nobody fixed.

A story that does not match the status

A parcel whose status changed while its history did not leaves Marta with a status she cannot explain. If the program stops halfway through a move, she is back to guessing what happened, which is the spreadsheet again. The same holds for a refused move that leaves a trace behind, such as a failed-attempt count that went up for a move that never happened.

The wrong day near midnight

A parcel registered at 00:30 on Wednesday in Amsterdam is 23:30 on Tuesday on the clock that ignores time zones. If the day board uses that clock, the parcel lands on Tuesday and Marta reads a wrong total with no error anywhere. The mistake shows only for an hour or so around midnight, which is when nobody checks.

Strangers and the printed code

The tracking code is written on a parcel that anyone on the street can read. If the next code can be guessed, a stranger reads a neighbour's parcel. If the lookup shows an address or a name, the code hands that to every passer-by. A shop that can see another shop's recipients is the same leak from the other side.

Where it shows if you cut a corner

The test that tries every move from every status and the week of 125 parcels find the shortcuts. A rule that exists in two places passes one test and fails the other once you change it. A move that updates the status first and the history second shows up when the week checks that every parcel's status equals its last history entry. A day board that uses the wrong clock fails on the two parcels registered either side of midnight.