Build a Delivery Log for a One-Van Courier
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.
Free to start. An account is what keeps track of the checkpoints you finish.
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.
Acceptance criteria
You write a document in your repository that lists the four statuses: at the depot, out for delivery, delivered and returned to the sender. It lists every allowed move as a row: from which status, to which status, what Marta does to cause it, and what gets recorded. There are exactly four allowed moves: depot to out, out to delivered, out to depot after a failed attempt (the number of failed attempts goes up by 1), and out to returned to the sender on the third failed attempt. The document names the four failure reasons: not home, address not found, refused and access denied.
The document also states that delivered and returned to the sender are final. A reader can find every forbidden move by reading what is missing, and the document says so in one sentence.
Two example journeys are written out with a time on every step. One is clean: registered, out, delivered. The other has two failed attempts and then a delivery, so the parcel is registered, out, failed, out, failed, out, delivered. Each step shows the status before, the status after and the number of failed attempts after.
Architectural guidance
Marta has no document that says which moves are legal, so nobody, including her, can tell a legal move from a typo.
Acceptance criteria
Before any parcel exists, the eight shops are there from the first start, each with a name and a contact phone number: Greenleaf Florist, Kees Hardware, Van Dijk Books, De Kaasbode Cheese, Lotte's Yarn Shop, Mill Street Pharmacy, Noordzee Fish Counter and Oak and Anvil Gifts. The phone numbers are made up by you. There is no way to add, edit or remove a shop from the log.
Registering a parcel needs a shop, a recipient name and one delivery address as a single piece of text. The request may also say what time it is, for testing; when it does not, the real clock is used. After a successful registration, one parcel exists with status at the depot, 0 failed attempts and the registration time, and the answer shows all of that with an identifier of your choice. The registration time is shown in Europe/Amsterdam time with its offset, for example 2026-11-10T09:00:00+01:00. The parcel's history shows exactly one entry for it: moved from nothing to at the depot, with the registration time.
Each of these is refused with a message that names the problem, and afterwards the number of parcels and the number of history entries are unchanged: a recipient name that is empty or only spaces, an empty or only-spaces address, and a shop that is not one of the eight. Stopping the program and starting it again keeps every registered parcel.
Architectural guidance
A name made of three spaces looks filled in, and a parcel for a shop that does not exist belongs to nobody. If bad input is accepted, Marta finds out when a driver cannot read the label or a shop asks where its parcel is. A time shown without its offset reads as the wrong hour on any machine that is not in Amsterdam.
Acceptance criteria
Every registration now returns a tracking code instead of the temporary identifier. A code has 8 characters from an alphabet of 31: the digits 2 to 9 and the capital letters A to Z except I, L and O. The alphabet is written in the README.
Registering 1,000 parcels in one run gives 1,000 different codes, and every code has exactly 8 characters from the alphabet. The first 20 codes, read in registration order, are not in alphabetical order, and the code shows nothing about the shop or the date.
A registration that would have been given a code another parcel already holds still succeeds with a different code, and the number of parcels goes up by 1. You show this with a test of your own making. After the 1,000-parcel run, the number of parcels equals the number of different codes, also after the program is stopped and started again.
Architectural guidance
If the next code can be guessed, anyone can type it and read a neighbour's parcel, and there is no login to stop them. Marta writes codes on parcels by hand and reads them over the phone, so a character that looks like another one (0 and O, 1 and I and L) turns into a parcel nobody can find. Two parcels can also be given the same code by chance. If that happens, a shop looks up its parcel and reads someone else's story.
Acceptance criteria
Asking for a registered code returns the code, the current status, the shop's name, the number of failed attempts and the history, oldest first. Each history entry shows the status it moved from, the status it moved to and its time. Times are shown the same way as at registration, in Europe/Amsterdam time with the offset.
Typing the same code in lower case returns the same parcel. An unknown code, and a code that is the wrong length, both get a plain "not found" answer and the program keeps running.
The answer never contains the recipient's name or the delivery address. Register a parcel with a recognisable address, look it up, and search the whole answer for that address: it is not there.
Architectural guidance
A stranger who mistypes a code will hit the unknown-code case first. If the program crashes or answers with an error page, shops stop trusting the log and phone Marta instead. People type what they read off a parcel, in whatever case they like. The code is printed on a parcel that anyone on the street can read, so an address in the answer tells every passer-by where the recipient lives. Marta would hear about that leak when a recipient asks why a stranger knew her address.
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.
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.
Acceptance criteria
Marta sends a parcel out by naming its tracking code. A parcel at the depot becomes out for delivery. The parcel's history gains exactly one entry, from at the depot to out for delivery, with the time of the move, and the number of failed attempts is unchanged. The request may say what time it is, for testing; when it does not, the real clock is used.
Sending out a parcel that is already out for delivery, a delivered parcel and a returned parcel are each refused. The answer names the parcel's current status, and the parcel's status, number of failed attempts and number of history entries are the same as before the request. An unknown tracking code gets a plain "not found" answer.
You stop the program halfway through a move on purpose, by whatever means you choose. After it starts again, the parcel is either at the depot with its old history, or out for delivery with exactly one new entry. It is never out for delivery without the entry, and never at the depot with the entry.
Architectural guidance
If every button carries its own idea of what is allowed, a fix to one leaves the others wrong, and a button written later arrives with no check at all.
Acceptance criteria
Marking a parcel that is out for delivery as delivered needs the name of the person who received it. The parcel becomes delivered, and its history gains one entry, from out for delivery to delivered, with the time and the receiver's name. Looking the parcel up by its tracking code shows delivered and the time, and does not show the receiver's name. Marta can read the receiver's name for a delivered parcel in a place only she uses, and the README says where.
A receiver name that is empty or only spaces is refused, and the parcel stays out for delivery with no new history entry. Marking a parcel at the depot as delivered is refused. Marking a delivered parcel as delivered again is refused, so sending the same request twice leaves one delivered entry and not two. A returned parcel cannot be marked delivered either.
Every refusal names the parcel's current status, and the parcel and its history are the same as before the request.
Architectural guidance
Marta can only tell a shop "delivered" and mean it if nothing later can change that status. The code is printed on the parcel, so the receiver's name does not belong in the public lookup.
Acceptance criteria
Recording a failed attempt on a parcel that is out for delivery needs one reason from the four: not home, address not found, refused or access denied. The first failed attempt puts the parcel back at the depot, sets the number of failed attempts to 1 and adds one history entry from out for delivery to at the depot that carries the reason. The second does the same and sets the number of failed attempts to 2.
The third failed attempt on the same parcel sets the status to returned to the sender, not to the depot, sets the number of failed attempts to 3 and adds one entry that carries the reason. From then on, sending out, marking delivered and recording a failed attempt are all refused, and the number of failed attempts stays at 3.
A failed attempt with no reason, or with a reason that is not one of the four, is refused, and the parcel stays out for delivery with the same number of failed attempts and the same history. A failed attempt on a parcel at the depot, a delivered parcel or a returned parcel is refused. A parcel that failed twice, was sent out again and was then delivered ends as delivered with 2 failed attempts.
Architectural guidance
A parcel that fails a third time must go back to the sender. If the rule is off by one, a parcel gets a fourth trip, and Marta drives past the same locked door again, or it goes back after two failures while the customer could still have received it. The number of failed attempts and the history have to tell the same story, because that is how Marta explains to a shop why its parcel came back.
Acceptance criteria
One command runs an automated test and prints how many cases passed. The test tries each of the 3 moves (send out, mark delivered, record a failed attempt) from each of the 4 statuses, which makes 12 cases. Each case starts with a parcel in that status. The expected result of every case comes from the document written in Phase 1, and exactly 3 cases are allowed: send out from the depot, deliver from out for delivery and a failed attempt from out for delivery.
After each of the 9 refused cases, reading the parcel and its history back shows the status, the number of failed attempts and the number of history entries unchanged. After each allowed case, the history has exactly one new entry.
You then change the product on purpose so that marking a parcel delivered works from the depot, and run the test again. Exactly 1 case fails, the output names it, and the other 11 pass. You undo the change and the test passes again. The README says how to run the test with one command.
Architectural guidance
There are 12 combinations of move and status, and clicking through them by hand misses the ones nobody thinks of. A test that has never failed has not shown that it checks anything. A refused move that quietly changes one history entry is the kind of damage Marta cannot see until a shop calls about a parcel whose story does not add up.
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.
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.
Acceptance criteria
Asking for a calendar day returns how many parcels registered on that day are in each of the four statuses right now. All four statuses are always listed, with 0 where nothing matches. The day is a day in Europe/Amsterdam, and a day with no parcels returns four zeros. A date that is not a real date is refused with a message that says so.
The board counts the current status, so a parcel registered on Monday and delivered on Tuesday appears under delivered on Monday's board and on no other.
Register three parcels with chosen times: one at 09:00 and one at 23:30 on Tuesday 10 Nov 2026, and one at 00:30 on Wednesday 11 Nov 2026, all Amsterdam time. Tuesday's board totals 2 and Wednesday's board totals 1. The Wednesday parcel is still 23:30 on Tuesday 10 Nov 2026 on a clock that ignores time zones, and it appears on Wednesday, not Tuesday.
Architectural guidance
A parcel registered just after midnight in Amsterdam is still on the previous date on a clock that ignores time zones, because Amsterdam is ahead of it. Testing "00:30 on a Wednesday" is impossible if the only way to set the time is to wait for it, which is why the person or the request can name the current time in this brief.
Acceptance criteria
Asking for a shop by name returns every parcel registered for that shop, newest first by registration time. Each parcel shows its tracking code, the recipient's name, its current status and its registration time in Europe/Amsterdam time. It does not show the delivery address or the name of the person who received it.
Register 3 parcels for Van Dijk Books and 2 for Kees Hardware. Van Dijk Books sees its 3 and none of the 2, and Kees Hardware sees its 2 and none of the 3. Two parcels registered at the same time are listed in a consistent order that does not change between requests, for example the one registered later first.
Asking for a shop that is not one of the eight gets a plain "not found" answer. A shop with no parcels gets an empty list and not "not found".
Architectural guidance
There is no login in this brief, so the shop name in the request is the only thing keeping one shop out of another's customers. Two parcels registered at the same moment can swap places between two identical requests, and a shop that sees its list change without cause stops trusting it.
Acceptance criteria
One command starts from empty data, plays a week, and prints the checks below. Running it twice from empty data prints the same result both times. The week is Monday 9 to Friday 13 Nov 2026, with 25 parcels registered per day across the 8 shops, 125 in all, numbered 1 to 125 in registration order. You choose the registration and move times, with two fixed: parcel 50 is registered at 23:30 on Tuesday and parcel 51 at 00:30 on Wednesday, Amsterdam time.
The outcomes are fixed by the parcel number. A multiple of 10 fails three times and is returned to the sender. A multiple of 5 that is not a multiple of 10 fails once and is delivered on the second trip. Parcels 103, 113 and 123 stay at the depot. Parcels 107 and 117 are sent out and stay out for delivery. Every other parcel is sent out and delivered. Failure reasons are used in turn from the list of four.
The script prints these checks and each one passes: every parcel's status equals the status on its last history entry; no parcel has more than 3 failed attempts; every returned parcel has exactly 3 failed-attempt entries in its history, each with a reason; the 12-case test from Phase 2 passes; and the board for each of the five days totals 25. It also prints the final counts, which are 108 delivered, 12 returned to the sender, 3 at the depot and 2 out for delivery, with 49 failed-attempt entries in the histories.
The board for Tuesday shows 22 delivered and 3 returned, and the board for Wednesday shows 23 delivered and 2 returned.
Architectural guidance
A run with outcomes worked out in advance gives the same numbers every time, so a changed number means a changed behaviour. The printed checks are facts that must hold whatever happened, such as a status that matches the last history entry, because they catch the bug nobody wrote a case for. Expected numbers copied from the program's own output prove only that the program agrees with itself, so work them out by hand before the first run.
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.