Build a Same-Day Courier Service
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.
Free to start. An account is what keeps track of the checkpoints you finish.
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.
Acceptance criteria
You write a state table in your repository for a parcel, from a shop's booking to either a delivery or a return to the shop. It lists the seven scan types in the order a parcel normally meets them (picked_up, arrived_at_depot, loaded, out_for_delivery, delivered, delivery_failed, returned), the four failure reasons (not_home, address_not_found, refused, access_denied) and the client's delivery rule: at most two attempts, the second on the next working day (Monday to Friday), and a return to the shop after the second failure. For each scan type the table shows which scan can follow it and what causes the move.
An attempt is a delivery day. You work two cases in the document. A failure at 11:00 and a delivery at 15:30 on the same day count as one attempt that succeeded. Two failures on one day count as one failed attempt, because phones repeat themselves.
For every scan, the document shows who takes it, when it was taken and when the server could first have heard of it. These are two different times. You then work one late upload through with clock times. A phone takes an out_for_delivery scan at 09:10 and uploads it at 15:00. Another phone takes a delivered scan at 11:40 and uploads it at 11:41. The document shows what the parcel's page would say after each upload if the page showed whatever arrived last, and what it should say.
Finally you answer three questions for that parcel by hand and write the answers in the document: what message the recipient receives and when, which parcels a rider carries the next morning, and what the shop owes for the month. Each answer names the scans it came from, and each is worked twice, once trusting the last upload and once using the order things happened. A reader who has never seen a courier can say, after reading it, why the three answers go wrong together when the last upload wins.
Architectural guidance
Three people act on a parcel's story: the recipient gets a message, the rider gets a run and the shop gets a bill. Working the three answers out by hand shows that they go wrong together, and it gives every later test an answer that does not come from the product being tested.
Acceptance criteria
A command named in the README plays the courier's day. Given a seed, a parcel count and a number of days (default 1), it produces the day's uploads for 12 riders (R01 to R12: R01 to R10 on bikes and R11 and R12 in vans), each with one phone (D01 to D12). In later Phases the same command books the parcels for 30 shops through the product's shop API and uploads the scans to it, as the shops and phones would. Your repository starts the product with one command, and the README says how to run the simulator against it.
The client's phone app sends each scan with these fields: scan_id (a new UUID), tracking_number, scan_type (one of the seven), occurred_at (when the scan was taken, in UTC with milliseconds, for example 2026-03-09T09:10:42.000Z), rider_id, device_id, and reason_code on delivery_failed scans only. Phones upload in batches of at most 100 scans.
The simulated day is Monday 9 Mar 2026. A parcel's scans follow the journey: A parcel rides one of two waves, and by default 70 percent ride the morning wave. In the morning wave picked_up falls between 06:00 and 07:15 Europe/Amsterdam time, arrived_at_depot by 07:45, loaded by 08:55 and out_for_delivery from 09:00. In the midday wave, for parcels a shop booked in the morning, picked_up falls between 10:00 and 12:15, arrived_at_depot by 12:45, loaded by 13:55 and out_for_delivery from 14:00. In both waves delivered or delivery_failed follows by 17:30, with at least 10 minutes between two scans of one parcel. By default 10 percent of first attempts fail, with a reason from the four codes. With two or more days, a failed parcel gets a second attempt on the next working day, and a second failure produces a returned scan.
The failures are switches with these defaults: a phone with signal uploads every 10 minutes; 10 percent of batches are uploaded twice; 10 percent of batches are held back by 1 to 6 hours; and some phones' clocks run ahead by 0 to 5 minutes, so their occurred_at is later than the moment the scan was taken. Each switch can be set to 0 for a clean run. The same seed and settings produce the same day, byte for byte. The simulator also records, for each parcel, the order in which its scans were really taken. It prints a summary of scans, batches, repeated batches and delayed batches. The scan count equals the scans in the batches counted once, and a clean run has 0 repeated and 0 delayed batches.
The simulator can set the moment the product believes it is, and read it back from the running product. After it sets 2026-03-09T15:00:00.000Z, the product reports that moment and then moves on from it. A live installation refuses both requests. Every later Checkpoint that depends on time, such as the 08:00 and 13:00 planning, the 24 hours for which a shop's retried booking is recognised and the rate card change on 1 Apr 2026, is tested by setting this moment.
Architectural guidance
A product that gets the order of scans wrong still agrees with itself, so comparing two runs of the same product proves nothing without a record of what really happened.
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.
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.
Acceptance criteria
A shop asks for a quote by sending its own credentials with the weight in grams, the length, width and height in centimetres and the destination postcode. The answer holds the zone, the billable weight in grams, the billable band, the price in euro cents excluding VAT and the rate card version. Volumetric weight is length x width x height in cm divided by 5, in grams, rounded up, so a 40 x 30 x 20 cm box is 4,800 g. Billable weight is the larger of the actual and the volumetric weight. There are three bands: up to 2 kg (up to 2,000 g), up to 10 kg (up to 10,000 g) and up to 25 kg (up to 25,000 g).
The zone comes from the first four digits of the postcode: 3511 to 3515 and 3521 are the inner zone, and 3541 to 3544 are the outer zone. Rate card version 1 prices in euro cents, excluding VAT: inner 590, 890 and 1,490; outer 790, 1,190 and 1,890. A 1,000 g parcel to 3512 costs 590. A 2,000 g parcel to 3512 costs 590 and a 2,001 g parcel costs 890. A 1,000 g parcel in a 40 x 30 x 20 cm box to 3542 has billable weight 4,800 g and costs 1,190. A 25,000 g parcel to 3511 costs 1,490.
A billable weight of 25,001 g is refused with a reason that names the maximum weight. A postcode outside the table is refused with a reason that says it is outside the delivery area. A missing or unknown shop credential is refused. A weight or dimension that is zero, negative or not a whole number is refused. Every price in every answer is a whole number of cents.
The client changes prices by adding a new rate card that takes effect at a stated moment, and never by editing the old one. A second rate card gives the inner zone's up-to-2-kg band 640 from 2026-04-01T00:00:00.000Z. With the product's moment set one second before that instant a quote answers 590 on version 1, and at that instant it answers 640 on version 2. The operations note says how the client adds a rate card.
Architectural guidance
A shop that was quoted 590 and is invoiced 640 disputes the invoice, and the client has nothing that shows what the shop saw. A price edited in place also reprices parcels that are already in the depot. A total that is a cent out is a disputed invoice, and the client invoices to the cent.
Acceptance criteria
A booking request creates a parcel from the quote fields plus the recipient's name, address, phone and email. Shops send an Idempotency-Key header with it, and a request without the header is refused. The answer holds the tracking_number, the price in euro cents, the zone, the billable band and the rate card version, and the price equals the quote for the same fields at that moment. The shop API documentation describes the request and the answer.
A repeat of the same request with the same key from the same shop answers with an identical body, and the shop still has one parcel for it. The same key with a different body is refused as a conflict and creates nothing. Two shops using the same key create two parcels. A key is remembered for 24 hours: with the product's moment set 24 hours and 1 minute after the first request, the same key books a new parcel.
Two requests with the same new key, sent at the same moment from two clients, end with one parcel, and both answers carry the same tracking_number. A product killed after a booking was made and before the answer reached the shop, then retried with the same key, gets the same body and the shop has one parcel. The overlapping requests must truly run at the same moment, so a setup that handles one request at a time does not count.
The simulator books N parcels for 30 seeded shops, each with its own credentials, and plays the day for the parcels it booked. Booking 400 parcels leaves 400 parcels and 400 distinct tracking numbers.
Architectural guidance
A shop's client retries when it times out, so the same booking will arrive twice in normal operation, and a product that creates a parcel for every arrival bills the shop twice. Two copies of one request that arrive at the same moment both look new unless the product notices the other. A race test run on a setup that handles one request at a time passes even when the product has the bug.
Acceptance criteria
Every parcel gets a tracking number of 12 characters from the 31-character alphabet 23456789ABCDEFGHJKMNPQRSTUVWXYZ, which leaves out 0, O, 1, I and L. The README states how many numbers are possible: 31 to the power of 12, about 7.9 x 10^17.
Numbers do not follow booking order or the clock. Booking 400 parcels in a row gives 400 different numbers, and the first four characters of those numbers take at least 390 different values, so numbers that follow booking order or the clock fail. Booking 400 parcels from 8 shops at the same moment also gives 400 different numbers.
A booking still succeeds when its number would clash with one already issued: the test arranges a clash however you choose, and the booking ends with one parcel and a different number. No booking fails because of a clash, and no two parcels ever share a number.
Architectural guidance
A tracking number is the only credential a recipient has, so whoever holds one can read that parcel's story. If numbers follow booking order, a visitor who changes the last character of their own number reads the next customer's parcel, including when nobody was home. The alphabet leaves out 0, O, 1, I and L because a number printed on a label or read over the phone gets mistaken for its look-alikes. Numbers that look random can still clash eventually, and a clash that fails a booking or hands one number to two parcels sends one recipient another recipient's story.
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.
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.
Acceptance criteria
A phone uploads up to 100 scans in one batch, in the shape the simulator plays, and presents the shared upload token (one value the operator sets, sent with each upload). reason_code is required on delivery_failed and refused on every other type. The moment a batch arrives is the product's own, and the phone cannot set it. A request without the token is refused and stores nothing. The phone upload guide describes the batch, the token and what each answer means.
A batch of 100 valid scans adds 100 scans to the parcels' histories. A batch of 101 is refused and adds nothing. A scan with an unknown scan_type, an occurred_at that is not UTC with milliseconds (such as 2026-03-09T10:10:42+01:00), a malformed tracking_number or a missing reason_code on a failed scan is listed in the answer with its position in the batch and a reason. The valid scans in the same batch are kept and the answer is still a success.
Each scan_id counts once. Uploading the same batch again answers with 100 duplicates and 0 accepted, and the 100 scans are unchanged. The same scan_id twice inside one batch counts as one scan. A repeated scan_id with a different occurred_at keeps the first scan and counts as a duplicate. Two uploads of the same batch at the same moment from two phones end with 100 scans. A product killed while it was taking in a batch, followed by a re-send of the whole batch, ends with exactly 100 scans. The overlapping uploads must truly run at the same moment, so a setup that handles one request at a time does not count.
A scan for a tracking number nobody booked is kept and listed in the answer as belonging to an unknown parcel. By the time a phone gets its answer, a visit to the public page already shows every accepted scan.
The simulator's play step sets the product's moment to each batch's upload time and uploads the day. The number of scans the product holds equals the distinct scans the simulator reports.
Architectural guidance
A phone retries any answer that is not a success and any request that times out, so a success has to mean the scans are safe, and a failure after they were taken in means the next upload repeats scans that are already there. A bad scan reported as an error makes the phone retry the whole batch forever, and the 99 good scans in it never get through. When a scan was taken and when the server heard of it are two different facts, and a late upload can only be understood with both.
Acceptance criteria
The public tracking page for a tracking number is an HTML page reachable without a login. It shows the tracking number, the status in words, and one row per scan. The status words are Picked up, At depot, Loaded, Out for delivery, Delivered, Delivery failed and Returned to shop. Each row shows its time in Europe/Amsterdam, so a scan taken at 2026-03-12T10:10:42.000Z shows 11:10, and a failed scan shows its reason in words, such as "Recipient not home" for not_home. A booked parcel with no scans shows "Booked" and no rows. Rows appear in time order, and two scans with the same time appear in the same order on every visit.
The page contains no recipient name, address, phone, email or postcode, no rider_id and no device_id. A tracking number nobody booked and a malformed one (lowercase, shorter or longer than 12 characters, or holding a character outside the alphabet) both get the same not-found answer with the same body.
A scan uploaded after the first visit shows on the next visit, with no waiting and nothing for the operator to run.
Architectural guidance
A recipient has no account, so the tracking number is the whole credential. A page that shows a name or an address hands that data to anyone who holds or guesses a number. A page that answers differently for a number nobody booked and a malformed one tells a guesser how close the guess was. A page that is hours behind tells a recipient the parcel is on its way when the bouquet is already on the doorstep.
Acceptance criteria
The page and everything else that reads a parcel's story put scans in the order they happened. A scan counts as taken at the time the phone gave, unless that time is later than the moment the server received the scan. A scan whose phone claims a time later than the moment of arrival counts as taken at the moment of arrival. Two scans that count as taken at the same time keep the same order on every read. The status is "Booked" with no scans, and otherwise it is the status of the last scan in that order.
Take three scans for one parcel: arrived_at_depot taken 07:30 and received 07:31, delivered taken 11:40 and received 11:41, out_for_delivery taken 09:10 and received 15:00. After the first two have arrived the page says Delivered. After the third arrives the rows read depot, out for delivery, delivered, and the page still says Delivered. A product where the last scan received wins says Out for delivery.
A scan whose phone claimed a time three days after it was received shows at the time it was received, and a real delivered scan taken and received two hours later shows after it. A phone whose clock is 5 minutes ahead never pushes its scan behind a scan that really happened later.
Architectural guidance
The order scans arrive in describes the network, and the time a scan was taken describes the parcel. A story sorted by arrival lets the last upload win, which is the bug in the client's story: the message, the run list and the invoice all believed whatever was uploaded last. Phone clocks in this client's fleet run ahead by up to 5 minutes, so trusting the phone's time without a limit lets one wrong clock put its scan at the end of a parcel's story for good.
Walkthrough aid: draw the three scans on a time line twice, once in arrival order and once in the order they happened, before writing anything. Write the example above as the test first.
Acceptance criteria
A test runs the simulator against the real product three times from a fresh installation, each time with seed 7 and 400 parcels booked for 30 shops, about 2,000 scans per run. Run A is clean: repeats, delays and clocks ahead are all 0. Run B uses the defaults: 10 percent of batches uploaded twice, 10 percent held back 1 to 6 hours, and clocks ahead by 0 to 5 minutes. Run C doubles the faults to 20 percent repeated and 20 percent delayed, and the product is killed and restarted 3 times at random moments while batches are being processed.
For every one of the 400 parcels, the ordered list of scans the product presents is the same in all three runs and equals the order the simulator recorded as really taken, and the status is the same. The number of scans the product holds is the same in all three runs and equals the distinct scans the simulator reports.
The test prints how many batches were uploaded twice and how many were delayed in each run, and these counts are above 0 in runs B and C, so the test cannot pass because the faults never happened. In a copy of your product that trusts arrival order, the same test fails and lists at least one differing parcel by tracking number; restoring the copy makes it pass. The counts for each run and the number of differing parcels, 0, are committed to your repository as the convergence result.
Architectural guidance
Two runs of the same product agree even when both are wrong, so the oracle is the record of the order scans were really taken. A test whose faults never fired proves nothing, and a test that has never been seen to fail guards nothing. A parcel can end on the right status with its middle scans in the wrong order, and a check on the status alone hides that, so compare the full order for each parcel before comparing statuses.
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.
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.
Acceptance criteria
The product plans that day's runs twice, at 08:00 and at 13:00 Europe/Amsterdam. With the product's moment set to 2026-03-09T06:59:59.000Z the stop list for 9 Mar 2026 is empty, and at 2026-03-09T07:00:00.000Z it holds the morning parcels. A parcel that reached the depot at 12:40 is on no run at 2026-03-09T11:59:59.000Z and is on a run at 2026-03-09T12:00:00.000Z. On Monday 30 Mar 2026, after the clocks have gone forward, the morning plan appears at 2026-03-30T06:00:00.000Z and the midday plan at 2026-03-30T11:00:00.000Z, neither an hour later. An operator can also plan any date and wave by hand.
The plan covers every booked parcel whose latest status is At depot and that is on no run yet. A parcel that is Booked, Picked up or Delivered is left out. Each run belongs to one of the 12 riders R01 to R12, and a rider takes at most one run in each plan, so a rider can have a morning run and a midday run on one date. Every rider has a vehicle type: R01 to R10 ride bikes and R11 and R12 drive vans. A plan gives its runs to bikes first, so the 11th and 12th run of a plan go to the vans. Each run holds parcels of one zone. A bike run holds at most 50 parcels and at most 100,000 g, and a van run holds at most 120 parcels and at most 600,000 g. A bike run of exactly 100,000 g is allowed and one of 100,001 g is not, and a van run of exactly 600,000 g is allowed and one of 600,001 g is not. Whichever limit binds first closes the run, so heavy parcels fill a run before its parcel limit is reached. A test of the bike limits plans fewer than 11 runs, so only bikes are used: 51 parcels of one zone give a bike run of 50 and a bike run of 1. A test of the van limits first gives the ten bikes a run each, then adds 121 parcels of the same zone: they give a van run of 120 and a van run of 1. Parcels of two zones never share a run, so a few inner and a few outer parcels give two runs, not one.
When the parcels need more runs than the 12 riders can take, the rest stay unplanned: the plan tells the operator how many, and the next plan takes them. Planning the same date and wave twice leaves the same runs and stops. Two plans for the same date and wave started at the same moment by two operators, with 51 parcels of one zone at the depot, end with one bike run of 50 parcels, one bike run of 1 parcel and no parcel on two runs. The overlapping plans must truly run at the same moment, so a setup that handles one request at a time does not count.
A rider's phone asks for the rider's stops for a date, presenting the shared upload token, and gets that rider's stops for the whole day numbered from 1, morning run first, each with the tracking number, zone, weight in grams and the recipient's name, address and phone as the shop booked them. Without the token the request is refused, an unknown rider is not found, and a date with no plan gives an empty list. The phone upload guide describes the request.
A booking that the shop was told succeeded is planned once its parcel reaches the depot, even when the product was killed at any moment after the shop got its answer. A test books 100 parcels while the product is killed and restarted 3 times at random moments, and every parcel a shop was told was booked appears on exactly one run. A booking that ended in an error appears on none.
Architectural guidance
A wrong stop list sends a rider to a parcel that was delivered yesterday or leaves a parcel at the depot overnight. A plan is started twice whenever an operator reruns it after a failure or two people start it together, and two riders must never be sent to one parcel or one bike rider given 51. A product that dies right after telling a shop its booking worked can leave a parcel that exists and that nobody plans, and the shop finds out when the recipient phones.
Acceptance criteria
A parcel whose first delivery day ends on a delivery_failed scan is planned again on the next working day, Monday to Friday, after the failed date in Amsterdam. A failure on Monday 9 Mar 2026 puts the parcel on Tuesday 10 Mar 2026's stop list. A failure on Friday 13 Mar 2026 puts it on Monday 16 Mar 2026's. A failure at 2026-03-12T23:30:00.000Z is 00:30 on Friday 13 Mar 2026 in Amsterdam, so it goes to Monday 16 Mar 2026 and not to Friday. Each of the four reason codes, not_home, address_not_found, refused and access_denied, gives exactly one second attempt.
A stop for a second attempt says it is attempt 2. It is planned in the 08:00 plan ahead of new arrivals and inside the same limits as any other run: 50 parcels and 100,000 g on a bike, 120 parcels and 600,000 g on a van. When the depot holds more parcels than the day's runs can carry, every second attempt due that date is planned and the new arrivals are the ones left unplanned.
An attempt is a delivery day, as worked out in the first Phase. Two delivery_failed scans on the same day, uploaded in any order and any number of times, give one second attempt. The same failure scan uploaded five times gives one stop on the next working day, not five. A parcel whose first day ends in a delivery, or has only an out_for_delivery scan so far, is not planned a second time.
A product killed right after it took in a failed scan still ends with the parcel on the next working day's stop list exactly once. A test kills the product at 3 random moments around that upload.
Architectural guidance
A product that counts failure scans decides wrongly as soon as an upload repeats or arrives late. A rider who fails at 11:00 and delivers at 15:30 made one attempt that worked, and a product that counted two failure reports schedules a second visit to a recipient who has the parcel. Working days counted in UTC put a failure scanned at half past midnight local time on the wrong day, and the recipient waits an extra weekend. A second attempt lost in a crash is a parcel nobody collects from the depot.
Acceptance criteria
The second delivery day decides the outcome. A parcel whose second day ends on a delivered scan is delivered on attempt 2 and appears on no later stop list. A parcel whose second day ends on a delivery_failed scan is returned to the shop: it appears on the depot's return list for the Amsterdam date of that failure, with its tracking number and shop id, and on no later stop list. The depot can read the return list for any date, and the operations note says how.
There is no third attempt. A returned parcel is planned on no later date. The parcel goes on the return list when the second failure scan arrives and does not wait for the returned scan. A returned scan that arrives later shows on the public page, leaves the return list as it was and adds no second entry.
Attempts are days, not scans. Two delivery_failed scans on the first day leave the parcel planned for a second attempt, not returned. Failures on Monday 9 Mar 2026 and Wednesday 11 Mar 2026 return the parcel, because the second attempt does not have to happen on the day it was planned for. A second day that has only an out_for_delivery scan so far changes nothing. If the planned date passes with no scans at all, the parcel stays planned for a second attempt, because this brief does not detect stalled parcels.
The simulator run with seed 7, 400 parcels and two days plays second attempts on the next working day and a returned scan after each second failure. The test works out each parcel's outcome separately from the simulator's record, and the product's stop lists and return list agree with it for all 400 parcels, 0 differing. The test prints how many parcels were delivered on attempt 1, delivered on attempt 2, returned and still planned for a second attempt.
Architectural guidance
A returned parcel that is still planned wastes a rider's morning, and a parcel sent back too early is one the recipient was still expecting. The shop should not wait on a phone that is offline for hours to upload the returned scan. A cap of two attempts that counts scans returns a parcel after two failure scans that one phone uploaded twice.
Acceptance criteria
Take three scans for one parcel on Monday 9 Mar 2026: out_for_delivery taken 09:10, delivery_failed with not_home taken 11:00, and delivered taken 15:30. Upload them in each of the 6 possible arrival orders, one scan per batch, each received at a different later time. In all 6 orders the end state is the same: the parcel is delivered on attempt 1, it is on no stop list for any later date and it is on no return list.
A withdrawal reaches the plan. The failure is uploaded Monday at 11:05, and the plan for Tuesday 10 Mar 2026 puts the parcel on a run as a second attempt. The delivered scan taken Monday at 15:30 is uploaded Tuesday at 09:30. The parcel no longer appears in the rider's stop list for 10 Mar 2026, and that run lists one parcel fewer.
A late scan can also undo a return. A parcel fails on Monday 9 Mar 2026 and again on Tuesday 10 Mar 2026 at 11:00, so it is on the return list for 10 Mar 2026. A delivered scan taken Tuesday at 15:30 and uploaded Wednesday arrives. The parcel is now delivered on attempt 2, and it is no longer on the return list.
Two uploads that change one parcel's story run at the same moment from two phones. The parcel ends with the outcome its scans give in the order they happened. A test kills the product at 3 random moments right after it takes in the late scan, and the stop lists and return list still end correct. The overlapping uploads must truly run at the same moment, so a setup that handles one request at a time does not count.
Architectural guidance
A second attempt arranged on a failure report stays on a rider's list unless the late delivery takes it off, and the client's story shows the cost: a rider is sent back to a parcel that was delivered, and the shop is billed for the second attempt. Two uploads for one parcel at the same moment can each see only part of the story and leave a result that matches neither order. The late scan arrives about 2,000 times a day in some form, so the product meets this case every day.
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.
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.
Acceptance criteria
A stand-in for the client's email provider has its own documented start command and keeps its held messages while the product is killed and restarted. How it is built and called is yours to decide. This Checkpoint fixes what it can do.
It behaves like the provider the client will use. It accepts a message for a recipient address with a subject and a body, and tells the product it accepted it after 0.2 to 2 seconds, drawn from a seeded generator. It then sends the product a receipt for "sent" and one for "delivered", each with its own id. The sender can ask whether it accepted a particular message and gets the provider's own id for it. It does not remove duplicates: two identical messages are two messages. A test can list every message it holds.
Each failure can be switched on and off while it runs, for the next N messages or for every Nth message. There are five. It accepts the message and then answers only after 8 seconds, so a client with a 5-second timeout gives up, and asking about that message afterwards says it was accepted. It fails with a server error without accepting, and asking about that message says it was not. It sends the "delivered" receipt twice with the same id. It sends a receipt before it has answered the product's request. It sends the "delivered" receipt before the "sent" one.
Two settings give the rates for the final test: a timeout on every 50th message and a duplicate receipt on every 50th. Sending 500 messages with both set leaves exactly 10 timeouts and 10 duplicate receipts in its fault log. Two runs with the same seed and the same requests give the same delays, the same fault log and the same held messages. A test sees each receipt arrive as described, including the early, duplicate and out-of-order cases.
Architectural guidance
Message-sending code that has never met a slow provider has never been tested. A fake that throws a canned error inside the product skips what a slow provider really does to the product, which is silence. The costly case is a provider that accepted the message and answered too late: the product cannot tell whether it acted, and a second email follows. Because the provider does not remove duplicates, only the product can make sure a recipient gets one message.
Acceptance criteria
When a parcel's out_for_delivery scan arrives, the recipient gets one email that day. The email says the parcel is out for delivery and contains a link to the parcel's public tracking page. The recipient's name comes from what the shop booked.
A parcel gets at most one message per delivery day, where the delivery day is the Amsterdam date of the moment the scan counts as taken. Handling the same scan twice, two out_for_delivery scans for one parcel on one day, and the same batch uploaded twice each leave one message for that day. A parcel that failed on Monday 9 Mar 2026 and goes out again on Tuesday 10 Mar 2026 has two messages in total. An out_for_delivery scan counted as taken at 2026-03-09T23:30:00.000Z belongs to delivery day 10 Mar 2026.
Nothing is sent for a parcel that is already delivered. The client's case: a parcel's delivered scan taken 11:40 is uploaded first, and its out_for_delivery scan taken 09:10 is uploaded at 15:00. The stand-in provider holds 0 messages for that parcel. A message that failed at first and is tried again 30 seconds later is not sent if a delivered scan arrived in between, and a test shows this with the failure switched on and the delivered scan uploaded inside the 30 seconds.
An operator can read a message log that lists each message with its tracking number, delivery day and where it stands, in plain words: waiting, sending, accepted, sent, delivered, failed, not sent because the parcel was delivered, or not sent because the recipient was erased.
Architectural guidance
The florist's customer was told "on its way" three hours after the bouquet arrived. The message went out on the strength of a scan that was hours old, and nobody looked at what had happened to the parcel since. A second message for the same parcel on the same day teaches the recipient to ignore the courier. A message cannot be taken back, so every doubt has to be settled before it is sent.
Acceptance criteria
The product gives up on the provider after 5 seconds. With the timeout failure on, the product does not send the message again. It asks the provider whether it accepted the message, finds that it did, and the log shows the message as accepted. The provider holds 1 message.
With the server-error failure on, asking says the provider has no such message, and the product tries again 30 seconds later, up to 5 attempts in all. After the failure is cleared the next attempt sends, and the provider holds 1 message. After the fifth failed attempt the log shows the message as failed, it stays visible, and it does not hold up any other message. An operator can send a failed message again once the cause is fixed, and the provider ends with 1 message. If the question "did you accept it" cannot be answered, the product asks again later and sends nothing in the meantime.
A product killed after the provider accepted a message and before the product learned that, then started again, ends with 1 message at the provider. A product killed before it contacted the provider ends with the message sent once. A test kills the product at each of these moments and reads the provider's held messages afterwards.
The operations note says how an operator finds failed messages and sends them again.
Architectural guidance
A timeout says the call took too long. It does not say whether the provider acted. Trying again blindly sends the recipient a second email, and giving up blindly leaves a recipient who was never told. A crash at any moment between deciding to send and learning the answer leaves the same doubt. One message that keeps failing must not stop the other 399.
Acceptance criteria
The provider sends a receipt for "sent" and then one for "delivered", and each receipt carries its own receipt id. The product takes these receipts in and the message log shows how far each message got.
A receipt with the same id arriving twice changes nothing the second time, and the product answers it as a success. A receipt that names a message nobody sent is refused and changes nothing. A "delivered" receipt followed by a "sent" receipt leaves the message at delivered. A receipt that arrives before the provider has answered the product's request is applied, and the answer that arrives afterwards does not move the message back to accepted. The log never shows a message further back than it has been.
Architectural guidance
The provider's receipts are as unordered as the phones' uploads. A "sent" that arrives after "delivered" and moves the message back tells the operator that a delivered message is still in flight, and the operator sends it again. A receipt repeated by the provider's own retry must not be counted as a second delivery.
Acceptance criteria
A shop's request to erase a recipient's details, made with the credentials of the booking shop, succeeds. The name, address, postcode, phone and email are gone, the time of erasure in UTC is recorded, and the parcel stays. Repeating the request succeeds again with the erasure time unchanged. Another shop's credentials and a number that does not exist are both refused as not found and change nothing, and a request with no credentials is refused.
After erasure the product still has the parcel's weight in grams, zone and price in euro cents. The public tracking page returns a body identical to the one before, 0 bytes different, and the parcel's scans are unchanged in count and content. The rider's stop list for that parcel still shows the tracking number and the zone, and shows the name, address and phone as erased.
A message due when the erasure happens is not sent. The message log shows it as not sent because the recipient was erased, the provider holds 0 messages for it, and the product does not keep retrying it or show an error that stays visible.
A parcel booked for "Marta Visser, Lindelaan 4, 3512AB, 0612345678, marta@example.test" goes through booking, planning and a message. Before erasure, a text search for each of the five strings over everything the product keeps on disk, its log files included, finds them only in the booking's own record, and the test names that place. After erasure the same search finds 0 matches. The stand-in provider plays the provider's copy and is outside the search. The search also covers anything kept so that a shop's retried booking is recognised.
The README says three things. Erasure happens on request only and nothing is erased automatically. 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 stand-in provider plays the provider's copy of each message, and a real provider keeps its own copy that erasure here cannot reach. The tracking page keeps working after erasure because it never showed a name.
Architectural guidance
Every place that holds a copy of a recipient's address is a place erasure has to find, and the one nobody remembers is the legal exposure the client discovers when asked. Copies hide in stop lists, in the text of messages, in logs and in records kept so a retried booking is recognised. The scans, the price and the zone stay because billing and a dispute need them long after the person is gone, and none of them say who the recipient was. A message that was due before the erasure comes due after it, and a product that treats that as an error keeps retrying a message that can never go out.
Acceptance criteria
A test runs the simulator against the real product from a fresh installation with seed 7, 400 parcels booked for 30 shops and two days, so that second attempts happen on the next working day. The simulator keeps its default failures: 10 percent of batches uploaded twice, 10 percent held back 1 to 6 hours, clocks ahead by 0 to 5 minutes. The stand-in provider runs with a timeout on every 50th message and a duplicate receipt on every 50th message. The product is killed at 3 random moments. The test erases some recipients before their parcels go out for delivery.
Once the product has caught up, the stand-in provider holds at most 1 message per reference, and the log holds at most 1 message per tracking number and delivery day. A parcel that failed on the first day and went out on the second has 2 messages, one for each day. No message is left waiting or sending.
For every message, the test works out the parcel's story from the scans the product had received at the moment the message was sent, and finds the parcel was not delivered. The erased parcels have messages not sent because the recipient was erased and 0 messages at the provider. At least one parcel whose out_for_delivery scan was uploaded after its delivered scan has a message not sent because the parcel was delivered, and the test builds one such case by hand, so the check cannot pass because the run never produced one.
Every message the stand-in provider logged as a timeout after accepting has exactly 1 held message and is accepted or further on in the log. Every message with a duplicate or out-of-order receipt ends at the furthest stage any of its receipts reached. No message is left failing.
The test prints the counts it relies on: messages sent, timeouts after accepting, duplicate receipts, messages not sent because the parcel was delivered, messages not sent because of erasure, and product kills. Each is above 0. In a copy of your product that sends again after a timeout without asking the provider, the same test fails and names at least one reference that appears twice at the provider.
Architectural guidance
Two runs of the same product agree even when both are wrong, so the oracle here is the provider's own list of held messages, which counts what a recipient would have received. The test works out each parcel's story from the scans the product had at send time and not from the final truth, because a message can legitimately go out before a late delivered scan reaches the server, and a test that demands otherwise asks for something no system can know. Printing the failure counts and breaking the retry on purpose are what show the test could have failed.
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.
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.
Acceptance criteria
A shop asks for its statement for a month, presenting its own credentials, and gets one line for each of its finished parcels: the tracking number, the price, the return fee, the line total, all in cents and excluding VAT, and a month total. A parcel is finished when it is delivered or returned. A parcel still in progress has no line. A request with no credentials is refused, and one shop never sees another shop's statement. No line holds a name, address, phone, email or postcode.
The price on a line is the price quoted when the shop booked the parcel. The return fee is 300 when the parcel is returned and 0 otherwise. A delivered parcel in the inner zone's up-to-2-kg band gives 590, 0 and 590. The same parcel returned gives 590, 300 and 890. A parcel booked at 2026-03-31T10:00:00.000Z for 590 under rate card version 1, with version 2 (640 for that band, effective 2026-04-01T00:00:00.000Z) in force when it is delivered on 2 Apr 2026, is charged 590 and not 640. The line belongs to the Amsterdam month of the moment the parcel was delivered or returned: a parcel delivered at 2026-03-31T22:30:00.000Z is 00:30 on 1 Apr 2026 in Amsterdam and belongs to April.
There is one line per parcel. The same delivered scan uploaded twice, a parcel that fails and is then delivered, and an operator who asks for the statement several times each leave 1 line. Two uploads that finish the same parcel at the same moment from two phones leave 1 line. The overlapping uploads must truly run at the same moment, so a setup that handles one request at a time does not count.
A line follows the parcel's story. A parcel is returned and its line reads 590, 300 and 890. A late delivered scan turns the outcome into delivered, and the same line now reads 590, 0 and 590, and the parcel still has 1 line.
A parcel finished moments before the product was killed has its line once the product is running again. A test kills the product at 3 random moments around finishing parcels, and every finished parcel ends with exactly 1 line.
Architectural guidance
A charge written every time an outcome is reported bills whichever report came last, which is how the florist was billed twice. A shop accepted the price on the booking day, and a later rate card must not reach back to a parcel that is already in the depot. The invoice covers a calendar month in the client's city, so a parcel delivered at 00:30 on 1 Apr 2026 belongs to April although the clock in UTC still says March. A product that dies between finishing a parcel and charging for it loses revenue that nobody notices until the month is closed.
Acceptance criteria
Each month closes by itself at the first moment at or after midnight Europe/Amsterdam on the 1st, and an operator can also close a given month by hand. With the product's moment set to 2026-03-31T21:59:59.000Z nothing is closed, and at 2026-03-31T22:00:00.000Z the March invoices exist.
Each shop with at least one line in the month gets one invoice, and a shop with none gets none. Take a shop S01 with three lines: 590 for a delivered parcel in the inner zone's up-to-2-kg band, 1,190 for a delivered parcel in the outer zone's up-to-10-kg band, and 1,790 for a returned parcel in the inner zone's up-to-25-kg band, which is 1,490 plus the 300 cent fee. Its net total is 3,570, its VAT is 750 (21% of 3,570 is 749.70, which rounds to 750) and its invoice total is 4,320. The invoice shows its number, the date of issue, the client's name, address and VAT number, the shop's name and address, the shop id, the month, each line's tracking number, price, return fee and line total, the net total, the VAT rate and amount, and the invoice total. VAT is worked out once on the net total and not per line, and rounds half up to the whole cent: a shop with five delivered outer-zone up-to-2-kg parcels at 790 has a net total of 3,950, VAT of 830 (829.50 rounds up) and an invoice total of 4,780. A shop that asks for its invoices for 2026-03 with its credentials gets only its own invoices, a request with another shop's credentials does not return them, and a request with no credentials is refused.
Invoice numbers have the form YYYY-NNNN, with the Amsterdam year of issue and a count that starts at 0001 in each year. Thirty invoices issued in March run from 2026-0001 to 2026-0030 with no gap and no repeat. Closing December 2026 on 1 Jan 2027 issues 2027-0001 first. A close killed halfway, while the third of the 30 invoices is being issued, and then run again ends with the 30 invoices numbered 2026-0001 to 2026-0030 with no gap and no repeat.
Closing March a second time issues 0 invoices and changes no number. Two closes of the same month started at the same moment by two operators issue one invoice per shop with unique, gap-free numbers. The overlapping closes must truly run at the same moment, so a setup that handles one request at a time does not count.
Every parcel finished in the month is on its shop's invoice once, including parcels finished just before the product was killed. A test kills the product at 3 random moments during the month's last deliveries and then closes the month.
An invoice stays as issued. A returned parcel at 890 on an issued invoice that later becomes delivered at 590 leaves the invoice unchanged, and the case appears in a list of late changes with the tracking number, the month, the net total on the invoice and the net total now. The operations note says how an operator closes a month again, reads the late-change list and decides what to do with it.
Architectural guidance
A gap in invoice numbers looks like a missing invoice to anyone who checks the sequence, and a number that is reused looks like a duplicate. Operators rerun a month that failed halfway, so the second close must change nothing. The shop holds the invoice, and a total that moves after issue is a document the shop can no longer trust. A correction after issue needs a credit line, which this brief leaves out, so the late change has to be visible to the operator. A shop's accountant sends back an invoice that lacks the client's VAT number, the shop's name and address or a separate VAT amount, and a VAT amount rounded by a rule the client never stated leaves a cent of difference to argue about.
Acceptance criteria
A test runs the whole product twice from a fresh installation, each time with seed 7, 400 parcels booked for 30 shops, 12 riders and two days, starting Monday 9 Mar 2026. After the second day the moment moves to 2026-03-31T22:00:00.000Z and the March close runs. Run A is clean: no repeated or delayed batches, clocks ahead 0, no provider failures and no kills. Run B has every failure at once: 10 percent of batches uploaded twice, 10 percent delayed up to 6 hours, clocks ahead 0 to 5 minutes, one provider timeout and one duplicate receipt per 50 messages, and the product killed 3 times at random moments. In both runs the test erases the details of 5 recipients at the same points in the script, after booking and before their parcels go out for delivery.
The test then checks seven things against the simulator's record and between the two runs, in this order.
- Stories: for all 400 parcels the ordered list of scans the product presents is the same in run A and run B and equals the order the simulator recorded as really taken, 0 parcels differing.
- Outcomes: the stop lists and the return list are the same in both runs for all 400 parcels and equal what the test works out separately from the simulator's record. No parcel that was delivered appears on a stop list for a later date.
- Messages: in run B no parcel has two messages for one delivery day, no message went out for a parcel that the scans received by then showed as delivered, none is left waiting or sending, and the 5 erased parcels have 0 messages at the provider.
- Statements: every parcel that is delivered or returned has exactly 1 line, no other parcel has one, each line equals the quoted price plus 300 for a returned parcel, and the lines are the same in both runs.
- Invoices: there is one invoice per shop with at least one line, numbered
2026-0001upward with no gap, the invoices are the same in both runs, and the sum of the invoices' net totals equals the sum of the line totals and the sum the test works out from the simulator's record and the rate card. Each invoice's VAT is 21% of its net total rounded half up, and the sum of the invoice totals equals the sum of the net totals plus the sum of those VAT amounts. - Erasure: for the 5 erased recipients the product answers erased, their scans, lines and invoice entries equal those of run A, and a text search of everything the product keeps on disk, its log files included, for their details finds 0 matches.
- Late change: after the close the test uploads one scan that turns a returned parcel into delivered. The line and the invoice are unchanged, and the parcel is listed under late changes.
Nothing is left waiting or failing once the product has caught up.
The test writes a report of the simulated day and the report is committed. It lists the parcels, scans taken in, batches repeated and delayed, messages sent, provider timeouts and duplicate receipts, product kills, planned stops, lines, invoices with their number range, net total, VAT and total, the late changes and, for each of the seven checks, the number of parcels differing, which is 0.
Three deliberate breakages of your own product each make a different check fail by name: a parcel's story that trusts the last upload fails the first, a message sent again after a timeout without asking the provider fails the third, and a second charge for a parcel that was already charged fails the fourth. The README takes a reviewer from a fresh clone to this report in 15 minutes, and the time you measured is written in it.
Architectural guidance
Each check reads the one before it, so a difference in invoices usually starts as a difference in outcomes, and an outcome difference usually starts in the stories. Comparing in that order names the first thing to look at. Messages are checked against rules and not against run A, because a message legitimately goes out before a late delivered scan reaches the server and the two runs differ in timing. A check that has never failed guards nothing, which is why the breakages are part of the Checkpoint. Print the first differing parcel for each check with its tracking number and the two values side by side, and fix the earliest check first.
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.
Related Links
- Belastingdienst, keeping your business recordsbacks the 7 years invoices and charges stay after a recipient is erased.
- GDPR Article 17, right to erasurebacks erasing a recipient's personal fields on request while scans and invoices stay.
- Belastingdienst, invoice requirementsbacks invoice numbers that never skip and never repeat.
- Stripe API reference, repeating a request safelythe model for the Idempotency-Key a shop sends so a retried booking is made once.