Build a Parcel Delivery Network
A regional courier has outgrown the one application it runs on: scans arrive late, the tracking page shows the wrong status, and one slow report stops the whole business. You will build the replacement, from booking a parcel through sorting, routing, delivery attempts, partner handoff and billing, and prove it survives a full simulated day with failures injected.
The brief
The client
I run operations at a regional courier. We deliver about 6,000 parcels a day for 200 online shops, from one sorting hub and 55 vans. Everything runs on one application, built when we handled 300 parcels a day. During one evening sort the hub scanners flooded it, and the merchant portal went down with it for two hours. Our tracking page tells people a parcel is out for delivery after the driver has already handed it over, because scanner uploads arrive late and the page shows whatever came in last.
I need a system where billing can be down without stopping a single booking, where a late scanner upload cannot rewrite what happened, and where I can answer a shop's question about any parcel with the facts instead of a guess.
The problem
The current system shows each parcel's status as whatever was written last. Handheld scanners work offline in the vans and upload in batches when they get signal, so a scan from 09:10 can arrive after one from 14:30 and replace it. Sorting, routing, billing and the merchant portal run inside the same application, so a slow report in one of them stops all four.
Merchants are billed from that same status, which is how one shop paid twice for a parcel that bounced between two statuses. Support spends most of its day answering "where is my parcel" with screenshots of internal screens. The contract with the client's second-largest merchant now carries a penalty for wrong tracking information.
The client's name and figures are invented for this brief; the rules and the failures are ones that real businesses of this kind work with.
The spec
Requirements
- Let a merchant book a shipment through an API and get back a price, a tracking number and a printable label.
- Let a merchant cancel a shipment until the parcel is first scanned.
- Accept scans from handheld scanners that upload in batches, late and sometimes twice, and keep every parcel's history in the order things happened.
- Show recipients a public tracking page for any tracking number, fast enough for the evening peak.
- Sort every parcel that arrives at the hub to a delivery area, including parcels the hub was never told about.
- Plan a daily route for each courier within the van's capacity, give the courier a manifest, and move a route to another courier when someone is out.
- Run each parcel through up to three delivery attempts, then return it to the sender.
- Send merchants signed webhooks that carry the same event identifier on every retry and replay, send recipients a delivery-day message, and never send a recipient two messages for the same event.
- Hand parcels for addresses outside our region to a partner carrier, and show their progress on our tracking page.
- Invoice each merchant monthly from what actually happened to their parcels, with the merchant's name and address and Dutch VAT shown separately.
- Let an operator see everything that happened to one parcel, and erase a recipient's personal data on request.
- Keep booking, tracking and sorting working while billing, notifications or the partner carrier's API are stopped.
Deliverables
- Your repository starts the whole product with one command, plus a simulator that plays the shops, the hub scanners, the couriers and the partner carrier, moves the clock faster than real time and causes the outside failures this brief names.
- A README that takes a reviewer from a fresh clone to a booked parcel showing as delivered on the tracking page in 15 minutes, and lists the command that runs each test in this brief.
- Merchant-facing API documentation for booking, labels and webhooks, including how to verify a webhook signature.
- A guide for the scanner and tablet makers: the format of a scan upload and of a courier's manifest.
- A test suite, plus the results of the simulated day from the final Phase committed to your repository.
- An operations note covering what an operator must be able to do: trace one parcel, retry a message that failed once the cause is fixed, repair a wrong tracking page, erase a recipient's data, and update one capability while the others keep serving.
Out of scope
- Optimal route planning. The vehicle routing problem is a research field of its own; grouping parcels by delivery area and ordering them by postcode is enough here.
- A courier mobile app. An HTTP API and a simulator stand in for the handhelds and the vans.
- Other tax cases. Every merchant is in the Netherlands and every charge carries Dutch VAT at the standard rate of 21%. Reverse charge, other rates and the client's VAT return are left out.
- Collecting payment from merchants. Billing ends at the issued invoice; our accounting system collects.
- Live GPS tracking or maps. Recipients see scan events, not a moving dot.
- Kubernetes or cloud deployment. Everything runs on one machine.
- Recipient accounts. The tracking number is the only access a recipient needs.
- International shipping and customs. Parcels for addresses outside our region go to the partner carrier, and that is where our responsibility ends.
Architectural constraints
- Amounts are exact to the cent. Money is whole cents and weight is whole grams, and no invoice's net total differs from the sum of its lines by even one cent. Prices, surcharges and charges exclude VAT. An invoice's VAT is 21% of its net total, worked out once per invoice and rounded half up to the whole cent.
- A parcel's history is always in the order things happened, never the order messages arrived.
- Receiving the same scan, message or request twice changes nothing the second time.
- Every retry and every replay of a webhook carries the same event identifier, so a shop can drop a copy it already has. A recipient never receives two messages for the same event.
- A capability that is stopped may delay the others. It never makes them fail, and nothing it missed is lost when it returns.
- No partner status code or partner field name is ever shown to a shop or a recipient.
- A recipient's name, address and email are erased on request, while shipment, scan, delivery and billing records stay, identified by tracking number.
- The courier's day runs on Europe/Amsterdam time: routes are planned at 05:00, vans leave at 07:00, and working days are Monday to Friday.
Prerequisites
You should have finished an intermediate project or have equivalent experience: you have built an application with a database, handled a request that arrives twice, and called an outside HTTP API. Any language and stack works. You do not need prior experience running several cooperating parts, and you do not need to know how a parcel courier works; the first Phase explains the business and the words the brief uses. Having once chased a bug caused by two systems disagreeing about the same record will make most of this brief feel familiar.
Free to start. An account is what keeps track of the checkpoints you finish.
Learn the courier's day
Produces the parcel's journey, the late-scan cases worked by hand, and a product that starts with one command and has a day driver that can move the clock and cause outside failures. Leaves all business behaviour for later Phases.
Acceptance criteria
You document one parcel's journey in your repository, from the shop's booking to its end, in numbered steps. Each step names who acts (shop, handheld at pickup, hub scanner, courier, recipient, partner carrier) and what gets recorded. All eight scan types (picked_up, arrived_at_hub, sorted, loaded, out_for_delivery, delivered, delivery_failed, returned) appear at least once.
The document shows the three ways a parcel ends: delivered, returned to the sender after the third failed attempt, and handed to the partner carrier. The failed-attempt path lists the four reason codes (not_home, address_not_found, refused, access_denied) and says that a failed attempt is retried on the next working day, Monday to Friday.
Every step says when it happened as well as what happened. For each of the three endings the document says what the recipient, the shop and the courier see.
Architectural guidance
The client's tracking page shows whatever was written last, and every wrong page in the client's story starts there. A journey written only as a list of labels has no answer for a scan that arrives after a later one. Writing it as things that happened at a time is what lets every later Checkpoint ask the same question of a late scan.
Acceptance criteria
You work five cases by hand and write them in a file in your repository. For each case the file says what a page that shows the last scan to arrive would display, what the history should show, and what the recipient should see.
The first case is a delivered scan with the time 14:30 that reaches the client at 15:00, followed by an out-for-delivery scan with the time 09:10 that reaches it at 16:00. The second is the same upload of scans arriving twice. The third is the scans of one parcel arriving in reverse order. The fourth is a parcel with three failed attempts. The fifth is a handheld that held a batch of 500 scans for 8 hours and uploads it after other scans for the same parcels.
The document states the rule in one sentence: the page and the history follow the time on the scan, never the order of arrival. For every case the wrong answer is written next to the right one.
Architectural guidance
A product built before these cases are worked out tends to treat them as bugs to patch later, while the client's second-largest merchant has a penalty clause for each wrong tracking page. The answers worked out here are the ones every later Phase is checked against.
Acceptance criteria
On a fresh clone, one command starts the whole product and a second command reports that it is healthy. The README states how many minutes this takes and a reviewer who follows it gets there in that time. Stopping the product and starting it again on the same machine works without manual cleanup. Later Phases extend the README so that a reviewer reaches a booked parcel showing as delivered on the tracking page within 15 minutes.
A day driver plays shops, hub scanners, couriers and the partner carrier. It can move the product's clock forward by hours: after a jump of 8 hours the product reports a time 8 hours later without waiting. The README lists how to ask the driver for each outside failure the brief names later: a scan batch uploaded twice, a scan batch uploaded late, a shop endpoint that hangs, a partner carrier that answers late, twice, out of order or not at all, and one capability of the product stopped and started again. For each one, the driver reports that it caused the failure.
The README lists the command for each test this brief asks for, and marks the ones that cannot run yet.
Architectural guidance
A reviewer who cannot start the product in a few minutes never gets to see anything else work. A product that can only be tested in real time cannot be tested at all, so causing the outside failures on demand is what makes the rest of the brief checkable.
Architectural walkthrough
How a regional courier gets a parcel to a door
The courier delivers about 6,000 parcels a day for 200 online shops, which the brief calls merchants. It runs one sorting hub and 55 vans. A merchant books a shipment through an API and gets back a price, a tracking number and a printable label to stick on the parcel. The merchant can cancel until the parcel is first scanned.
Parcels arrive at the hub, where each one is scanned and sorted to a delivery area. Routes are planned at 05:00 for each courier within the van's capacity, and the vans leave at 07:00 on working days, Monday to Friday. Each courier carries a handheld scanner and a manifest, the list of parcels for the day. The courier scans each parcel at the door. A parcel that is not delivered gets up to three delivery attempts, and then goes back to the sender. Parcels for addresses outside the region go to a partner carrier.
Recipients follow their parcel on a public tracking page and get a message on the day it is due. Merchants receive webhooks about their parcels and an invoice each month for what happened to them.
The words this brief uses:
Merchant: an online shop that sends its parcels with the courier.
Tracking number: the identifier a parcel carries from booking to delivery. A recipient needs nothing else to follow it.
Hub: the sorting site where parcels arrive and are sorted to delivery areas. It can receive a parcel nobody told it about.
Scan: a handheld reading a parcel's label to record what happened to it and when. A scanner in a van can stay offline for up to 8 hours and then uploads up to 500 scans every 5 minutes.
Delivery area: a part of the region that one courier's route covers.
Manifest: the courier's list of parcels for the day.
Delivery attempt: one try to hand a parcel over. A parcel gets up to three.
Return to sender: sending the parcel back to the merchant after the third failed attempt.
Partner carrier: another courier that takes the parcels for addresses outside the region.
Webhook: a message the courier sends to a merchant's server when something happens to a parcel. It is signed so the merchant can check who sent it.
Why the day comes before the code
This Phase builds no business behaviour. Starting to code before you understand the courier's day usually produces one status for each parcel, with the latest message overwriting it. The client's tracking page already works that way.
A handheld in a van holds its scans for up to 8 hours without signal. With signal it uploads up to 500 scans every 5 minutes, and it sends a batch again after any answer that is not a success or after a timeout. So a scan from 09:10 can reach the client after one from 14:30, and the same scan can reach it twice.
A page that follows arrival tells a recipient the parcel is out for delivery after the courier has handed it over, and it tells the shop the same. The contract with the client's second-largest merchant carries a penalty for wrong tracking information. Working the cases by hand now gives every later Phase answers to check against.
The failures in this brief also take the client's hours and days to play out: 8 hours without signal, 48 hours without a scan, a partner carrier that is down for 6 hours. A product that can only be tested in real time is hardly tested at all, and a reviewer who cannot start it in a few minutes will not see any of it work.
Accept a shipment
Produces quotes, bookings, tracking numbers, labels and cancellation for shops. Leaves scans and everything that happens to a parcel after pickup for later Phases.
Acceptance criteria
A shop with an API key asks for a quote by sending the weight in grams, the length, width and height in millimetres, and a destination postcode. The answer holds a quote ID, the billable weight in grams, the weight band, the zone, the surcharge in cents and the price in cents, both excluding VAT, all as whole numbers. A request without a valid API key is refused. A quote can be fetched again by its ID and shows the same answer.
The rate card is documented in your repository: a price in cents for each of the five weight bands (up to 2, 5, 10, 20 and 30 kg) in each of the four zones (local, regional, remote, partner), the postcode prefixes of the first three zones, and the postcode format the product accepts. A valid postcode outside the region is the partner zone. Only a malformed postcode is refused.
Billable weight is the larger of the actual weight and the volumetric weight, which is length x width x height in cm divided by 5,000, in kg. A parcel of 3,000 g measuring 600 x 400 x 300 mm has a billable weight of 14,400 g and is priced in the up to 20 kg band. A parcel of exactly 2,000 g is in the up to 2 kg band and 2,001 g is in the up to 5 kg band. A side of 1,201 mm adds a surcharge of 500 cents and a side of exactly 1,200 mm adds nothing.
A billable weight of 30,000 g is accepted and 30,001 g is refused, including a light parcel of 1,000 x 600 x 600 mm whose volumetric weight is 72 kg. A weight or a side of 0 or less is refused. A refused request leaves no quote that can be fetched.
The rate card has versions, and the README says how to publish a new one. Every quote shows the version it was priced from. After a new version with a changed price is published, an earlier quote still shows its old price and old version, and a new quote shows the new price and version.
Architectural guidance
The price a shop was quoted is a promise about that booking. If a new rate card reprices parcels that are already booked, the invoice shows an amount nobody told the shop, and the client's sales lead takes the call. Rounding drift in prices also shows up later as invoice totals that disagree with their own lines by a cent.
Acceptance criteria
A shop books a shipment with its API key, an Idempotency-Key header, a quote ID and a recipient: name, address lines, postcode and email. The first request creates one shipment, and the answer holds the shipment ID, the quote ID and the quoted price. A missing recipient name, a malformed email, a missing header, or a recipient postcode that differs from the quote's destination postcode is refused and creates no shipment. A quote that belongs to another shop is reported as not found.
The shop chooses the key for one booking and repeats it on every retry. The same key with the same body within 24 hours returns the same status and the same body, and there is still one shipment. The same key with a different body is refused and creates nothing. Two different shops using the same key book two separate shipments.
A test sends many identical requests with one key at the same instant, states how many, and ends with one shipment and the same shipment ID in every answer. After the product's clock is moved forward by 24 hours and one second, the same key books a new shipment.
Architectural guidance
A shop that times out cannot tell a lost request from a lost answer, so it sends the request again, and a booking without protection books a second parcel for the same order. The retry often arrives while the first request is still being handled, so the protection has to hold when two copies run at the same moment.
Acceptance criteria
Every booking returns a tracking number of 12 characters next to the shipment ID. The characters come from a 31-character alphabet: the digits 2 to 9 and the uppercase letters except I, L and O. The alphabet is written in the README.
A test books thousands of shipments and states how many. Every number matches the alphabet and the length and none repeats. Nothing in a number tells which shop booked it or on what date: consecutive bookings from one shop show numbers in no order and with no shared pattern. A booking that happens to draw a number already in use still succeeds with a different one, and a test forces that case.
Repeating a booking with the same Idempotency-Key returns the number from the first answer.
Architectural guidance
A number that counts up or carries the date or the shop lets anyone read other recipients' parcels, or work out how many parcels a competitor's shop ships in a day. Characters that people misread on a printed label, such as 0 and O or 1 and I, turn into calls to support when a recipient types the number in wrong.
Acceptance criteria
A shop fetches the label of a shipment it booked as a PDF page of 100 x 150 mm. The label shows the tracking number as text and as a Code 128 barcode, the recipient's name and address lines, and the destination postcode.
A test reads the PDF, extracts the text and decodes the barcode. The decoded value equals the tracking number, and the text holds the name, the address lines and the postcode. Fetching the label twice gives the same text and the same barcode, and the label shows no time of printing. A tracking number that does not exist and one that belongs to another shop get the same answer, and a request without a valid API key is refused.
Architectural guidance
The label is printed once and stuck on a box, and the hub scanner reads whatever sticker ended up on it. A label that changes between two fetches lets a shop print two different labels for one parcel, and a barcode that cannot be read sends the parcel to the pile of exceptions at the hub. A shop that can fetch another shop's label sees the name and address of a stranger.
Acceptance criteria
A shop cancels its own shipment and gives a reason. Until the parcel's first scan, the cancel succeeds and the shipment shows as cancelled. Cancelling a cancelled shipment succeeds and changes nothing. After the first scan, the cancel is refused with 409 and changes nothing. A shipment of another shop is reported as not found. Asking for the label of a cancelled shipment is refused, and a cancelled shipment is never billed.
Scan intake arrives in the next Phase. Until then a test stands in for the first scan with whatever means you chose, and the next Phase repeats the check with real uploads.
A test sends the first scan and the cancel for the same parcel at the same instant, for many parcels, and states how many. Every cancel is answered with success or 409, and the answer matches what the shipment shows afterwards: a shipment answered with success shows as cancelled, and a shipment answered with 409 does not.
Architectural guidance
A shop may cancel only while the parcel is still its own, and the first scan is the moment it becomes the courier's. A cancelled parcel that is billed anyway is the kind of invoice line shops phone about.
Acceptance criteria
A named test, with its command in the README, books thousands of shipments and states how many: every tracking number has 12 characters from the 31-character alphabet and none repeats, and a forced collision still books with a different number. Many identical requests with one Idempotency-Key sent at the same instant end with one shipment, the same key with a different body creates nothing, and after 24 hours and one second the key books a new shipment. The label for each shipment is a PDF page of 100 x 150 mm whose Code 128 barcode decodes to the tracking number, and fetching it twice gives the same label. A stand-in for the first scan and a cancel for the same parcel, sent at the same instant for many parcels with the count stated, always end with an answer that matches the shipment's state afterwards. A tracking number of another shop gets the same answer as one that does not exist.
Architectural guidance
A shop that retries a booking and gets two shipments pays twice and sends two parcels. A cancel that is answered with success for a parcel that was already scanned leaves the shop believing it did not ship.
Architectural walkthrough
A shop's system books a parcel by calling the client's API. If the answer takes longer than the shop's timeout, the shop cannot tell whether the booking happened, so it sends the request again. A retry that creates a second parcel means two labels, two pickups and a double charge, and the shop finds out from the invoice.
The second copy often arrives while the first is still being handled. A product that only recognises requests it has already finished sees nothing to match and books twice. Two identical requests sent at the same instant show this failure, and two requests sent one after the other do not.
A price is a promise. The shop is quoted a price, books at that price and expects the invoice to say the same. If the client publishes a new rate card in between and the booked parcel is repriced, the shop pays an amount nobody told it and the client's sales lead takes the call. Money in whole cents keeps invoice totals from disagreeing with their own lines by a cent.
There are no recipient accounts, so the tracking number is the only thing between a stranger and a parcel's history. A number that can be guessed or counted lets a stranger read other people's parcels, or lets a competitor work out how many parcels a shop ships in a day.
A shop may cancel until the parcel's first scan, and the cancel and the first scan can happen in the same second. If both succeed, the shop believes it will not be charged while the courier carries the parcel, and the client either delivers for nothing or argues with the shop.
Ingest scans
Produces the intake of scanner uploads and a correct history of every parcel, with a test that shuffles, delays and repeats the uploads. Leaves the public tracking page for the next Phase.
Acceptance criteria
A handheld uploads up to 500 scans in one batch. Each scan carries a scan ID the handheld created, the tracking number, one of the eight scan types, a location code, a device ID, the time on the scan and the source. The time on the scan is in UTC with milliseconds, and a time with another offset is listed as bad. A delivery_failed scan carries one of the four reason codes (not_home, address_not_found, refused, access_denied) and no other scan type carries one. A delivered scan from a handheld carries a proof reference, the signature or photo reference taken at the door.
A batch of 500 valid scans is accepted, and the answer says 500 accepted, 0 duplicated and 0 rejected. A batch of 501 is refused whole. A batch with bad scans (an unknown scan type, a reason code on a scan that is not a failed delivery, a handheld delivered scan with no proof reference) is still answered with success. The answer lists each bad scan by its position in the batch and says why, and the good scans in the same batch are accepted. A scan for a tracking number the product has no booking for is accepted too.
The product records when each scan arrived and never takes that from the handheld. When the answer says success, the scans are safe: a test that stops the product right after the answer and starts it again finds every accepted scan.
The day driver plays handhelds. It builds scans for many parcels by following the documented journey and uploads them in batches of up to 500, and the accepted counts in the answers add up to the number of scans the driver says it sent.
Architectural guidance
A handheld repeats any upload that gets an error or no answer, so a success answer has to mean the scans are safe. Support also needs to know how late an upload was, which only the difference between when a scan happened and when it arrived shows.
Acceptance criteria
Uploading the same batch of 500 scans a second time succeeds, and the answer reports 500 duplicated and 0 new. The product still holds exactly 500 scans for those parcels, and each scan keeps the arrival time of its first upload.
The same scan ID twice inside one batch counts once. A repeated scan ID with a different time on it keeps the first scan and counts as a duplicate. A batch that is half new and half repeated adds only the new half.
A test stops the product halfway through a batch and uploads the whole batch again, and afterwards exactly 500 scans exist. A second test sends the same batch twice at the same instant and also ends with 500.
Architectural guidance
Handhelds repeat uploads on any failure, so the same scan arrives twice in ordinary operation. Two copies of one upload can also arrive at the same moment, and a check that only looks at uploads already finished misses the second.
Acceptance criteria
Support can look up a parcel's current status by tracking number. The status is the scan with the latest time on it, never the latest upload. An unknown tracking number is reported as not found.
The client's own case passes as a test. A first upload holds a delivered scan with the time 14:30. A second upload, sent afterwards, holds an out-for-delivery scan with the time 09:10. After the second upload the status is still delivered at 14:30, and the 09:10 scan is kept. Uploading the two in the opposite order gives the same status. A scan with a later time than the current status replaces it.
Two scans for one parcel with exactly the same time give the same status whichever arrives first, and the rule that decides between them is written in the README.
Architectural guidance
The client's page said out for delivery after the parcel was handed over, because it treated the scan that arrived last as the scan that happened last. A handheld that spent hours without signal uploads its morning scans in the afternoon. Two scans with the same time to the millisecond must still give the same answer on every run, or support gives different answers to the same question.
Acceptance criteria
Support also sees a parcel's full history: every scan, ordered by the time on it, oldest first. Scans with the same time appear in a stable order that the README documents. Each entry shows the scan type, the location code, the time on the scan, when the scan arrived and, for a failed delivery, the reason code. A parcel with three failed attempts shows all three, each with its reason.
The booking is part of the history. It appears first, with the time of the booking, and a booking that is recorded after the first scans arrived still appears first. The booking is not a scan: the current status from the previous Checkpoint is still the scan that happened last.
Architectural guidance
When a shop asks where a parcel is, support needs a list of what happened in the order it happened, with the reason for each failed attempt. A history in arrival order puts the delivery before the pickup and makes support doubt every line. The attempts and their reasons are what the client needs to settle a dispute over a parcel that went back to its sender.
Acceptance criteria
One command, listed in the README, replays the scans of many parcels in shuffled, delayed and repeated orders. It prints the number of runs, the number of parcels and 0 differences, then exits with code 0. The parcels cover delivered on the first attempt, failed attempts followed by a delivery, and returned to the sender.
A reference run delivers every scan once, in the order of the time on the scan. The other runs use a fixed seed and vary the arrival: batches are shuffled, 5% of batches are uploaded twice, 10% of batches are held back by 6 hours of the product's clock, and some scans are held for the full 8 hours a handheld may hold them. For every parcel the test compares the current status and the full history with the reference run, ignoring only when the scans arrived. Each run also checks that the number of scans the product holds equals the number of distinct scan IDs sent.
You have run the test once with the history deliberately ordered by arrival and seen it fail. The output of that run, with its number of differences, is saved in your repository.
Architectural guidance
Late, repeated and out-of-order uploads happen together in a van, and a check per rule does not show that the rules hold together. The claim the client cares about is that any arrangement of the same scans gives the same history. A test that has never been seen to fail proves nothing, so it has to fail once on purpose.
Architectural walkthrough
A courier scans a parcel at pickup, at the hub and at the door. The vans have stretches with no signal, so a handheld holds its scans for up to 8 hours and uploads up to 500 of them every 5 minutes when it has signal. If an upload gets any answer other than a success, or times out, the handheld sends the same batch again.
So scans arrive late, twice and out of order as a matter of routine. A product that treats the order of arrival as the order things happened in replaces a delivered scan from 14:30 with an out-for-delivery scan from 09:10 that happened to arrive later. The recipient is told the parcel is out for delivery after it was handed over, the shop is told the same, and the contract with the second-largest merchant carries a penalty for each wrong answer.
Counting also goes wrong. A batch of 500 that arrives twice and is counted twice shows a parcel with two failed attempts after one. A later Phase sends a parcel back to its sender after the third failed attempt, so the parcel goes back after only two real tries.
A handheld cannot fix a bad scan. If one bad scan makes the client refuse a whole batch, the handheld sends it again forever and the good scans in it never arrive. The last Checkpoint of this Phase shuffles, delays and repeats the same scans many times over, because a check per rule does not show that the rules hold together.
Serve the tracking page
Produces the public tracking page for recipients, one that stays up when scan intake is stopped and holds the client's load target. Leaves partner carrier progress and delivery attempt details on the page for later Phases.
Acceptance criteria
Anyone with a tracking number sees the parcel's current status in plain words and its timeline, each entry with a time and a label a recipient understands. A tracking number that does not exist gets a not-found answer that says nothing about other parcels. The page for one tracking number never shows anything about another parcel.
A parcel with an arrived-at-hub scan at 14:30 and a picked-up scan at 09:10 that arrives afterwards shows the 14:30 status, and its timeline lists 09:10 before 14:30. The page is the same when the second scan arrives twice.
The page is right after scans arrive twice, late or out of order. A test plays the cases from the Checkpoint on working out what a late scan should show and compares the page with the answers written there.
Architectural guidance
A recipient who sees out for delivery after the parcel was handed over phones support, and the second-largest merchant's contract carries a penalty for each wrong page. The page has to be right however the scans arrived, because a recipient cannot tell the client that a scan was late. A not-found answer that explains too much tells a stranger which tracking numbers exist.
Acceptance criteria
A document in your repository lists the eight scan types and every field of a scan, and marks each one public or internal. Scan types that describe work inside the hub or the van are internal, at least sorted and loaded. The scan ID, the device ID, the source, the arrival time and the raw reason code are internal fields.
After the day driver has played a day, searching everything a recipient can fetch for each device ID the driver used finds no match, and no internal field name appears. A parcel whose scans include an internal type shows a timeline without that entry, and its status is the newest public scan. A failed delivery shows a reason in plain words, for example that nobody was home, and never the raw reason code.
Architectural guidance
Scans carry data a recipient has no business seeing: which handheld scanned, which hub step ran, and why a courier could not deliver in the courier's own codes. A recipient who sees sorted and loaded lines phones support to ask what they mean. Device IDs and internal codes on a public page give strangers details of how the hub works and nothing a recipient can use.
Acceptance criteria
With scan intake stopped, the tracking page keeps answering for every parcel with what the product knew before the stop. The answer for a tracking number is the same as before the stop, and the page shows zero errors while intake is stopped. A test requests 100 tracking numbers during the stop and states how many were answered.
Scan intake is started again without restarting anything else. Scans that handhelds held during the stop are accepted when they retry, and they appear on the pages of their parcels.
Architectural guidance
During one evening sort the hub scanners flooded the client's old application and the shops lost the merchant portal for two hours. A tracking page that fails whenever scan intake is slow or stopped fails in the same hour as the flood. Recipients need an answer even when it is a few minutes behind.
Acceptance criteria
An operator can repair the tracking pages of all parcels, or of one tracking number, from the recorded scans after a mistake showed wrong statuses. The steps are in the operations note, with the time a day's worth of scans takes.
After the day driver has played a day of 6,000 parcels, save what the page shows for every tracking number. Make the pages wrong on purpose, for example by making every page show a wrong status, then run the repair and compare. The difference is empty. Run the repair a second time and the difference is still empty. A repaired page equals what a fresh upload of the same scans would show.
While the repair runs, the tracking page keeps answering with no errors, and the repair changes no recorded scan.
Architectural guidance
An operator who cannot repair the pages from what was recorded has to choose between leaving wrong pages up and taking the page down.
Acceptance criteria
A script committed to your repository and listed in the README sends 200 requests per second for 60 seconds, 12,000 requests in total, to the tracking page on a laptop, with scan intake stopped. The tracking numbers are drawn at random from the simulated day's 6,000 parcels, so the run does not ask for one parcel over and over.
The script prints the number of requests, the number of errors and the p95 response time. It exits with a failure if the p95 is 200 ms or more or the error count is above zero. The run passes with p95 under 200 ms and zero errors. The printed result, the machine it ran on and the date are saved in your repository.
Architectural guidance
A response time that nobody measures drifts upward until the evening it matters. Stopping scan intake during the run takes the scanner flood out of the measurement, so a pass shows the page itself is fast. Asking for one tracking number repeatedly measures how fast one answer is, not how fast 6,000 different ones are.
Architectural walkthrough
A recipient opens the tracking page with a tracking number and nothing else. The client's old application served the page from the same machine that took the scanners' uploads. During one evening sort the scanners flooded it, and the merchant portal went down with it for two hours.
A page that fails when scan intake is slow or stopped fails in the same hours the scanners are busiest, and that is when recipients look. Every failed page view is a call to support. The page can be a few minutes behind and still be useful, and it cannot be an error.
The page also shows too much when nobody looks. Scans carry the device that took them, the hub steps the parcel went through and the reasons couriers type. A recipient has no use for any of it, and a stranger with a guessed tracking number has no business seeing it.
A mistake in how the product works out a status will one day show a wrong page for thousands of parcels at once. Fixing 6,000 pages by hand is not possible, and nobody can say afterwards which ones were touched. The client sets the target for the page in numbers: 200 requests per second for 60 seconds, p95 under 200 ms, zero errors.
Sort at the hub
Produces the sorting of parcels to delivery areas at the hub, including parcels nobody expected, bookings that survive a crash and a hub that keeps sorting while booking is stopped. Leaves routing and vans for the next Phase.
Acceptance criteria
The hub's sorter submits the text read from a label, the parcel's weight in grams and its length, width and height in millimetres from the measuring station. For a booked parcel the answer is its delivery area, A01 to A25, worked out from the destination postcode. A parcel in the partner zone gets the partner handoff instead of an area. The measured weight and sides are kept in whole grams and millimetres.
The map from postcode to area is documented in your repository. Every postcode the day driver uses belongs to exactly one of the 25 areas, every area has at least one postcode, and a test shows that all 25 areas can be reached. A postcode in a region zone that matches no area is refused with a clear answer.
Submitting the same parcel twice gives the same answer. A test makes the hub learn of the same booking twice, by whatever means you chose, and the hub still expects one parcel and gives the sorter one answer for it.
Architectural guidance
The sorter handles parcels as they arrive on a belt, and every second spent waiting for an answer holds up the parcels behind. A parcel sorted to the wrong area rides the wrong van, and nobody finds out until the recipient has not received it. The measurements from the station are later compared with what the shop declared, so it has to stay exact.
Acceptance criteria
A test books many shipments through the shops' API while the product is killed from outside at random moments and restarted. It states how many bookings it sent, how many a shop was told succeeded and how many a shop was told failed.
Afterwards every booking a shop was told succeeded is known to the hub exactly once, and the sorter gets its delivery area from the label text. The hub expects no parcel for any booking a shop was told failed. The number of parcels the hub expects equals the number of bookings the shops were told succeeded, with none missing and none extra. The test prints the counts and exits with code 0 only when all of this holds.
Architectural guidance
A booking can be confirmed to a shop and the product then stop before the hub hears of it. If that happens, a shop holds a label for a parcel nobody at the hub expects, and nobody finds out until the parcel is on the belt. The opposite failure also happens: the hub expects a parcel the shop was told did not book.
Acceptance criteria
When the sorter submits label text that gives no sortable parcel, the answer says so with one of three reasons: not expected (a well-formed tracking number with no booking), unreadable label (text that is not 12 characters from the tracking-number alphabet), or cancelled (the shipment was cancelled). The sorter's call itself does not fail, and no delivery area is given for these parcels.
An operator can list the parcels the hub did not expect, each with its tracking number, or the raw label text when no tracking number can be read, and the reason.
A tracking number with no booking is refused as not expected. Its booking reaches the hub afterwards and the sorter submits the same label again. The parcel is now sorted without restarting anything, and the earlier refusal is still in the operator's list. A cancel that reaches the hub before the booking it cancels still leaves the shipment cancelled.
Architectural guidance
A parcel can reach the belt before its booking reaches the hub, or with a label too damaged to read. If the hub treats that as an error the sorter is stuck with a parcel in hand, and if it guesses an area the parcel rides the wrong van. A parcel from a cancelled shipment should not be loaded at all, and the shop wants to know it turned up.
Acceptance criteria
A script committed to your repository and listed in the README books parcels across several delivery areas, some in the partner zone, and waits until the hub expects all of them. It then stops booking, restarts the hub's sorting, and has the sorter submit every booked parcel plus one tracking number that was never booked.
The script prints the counts and exits with a failure unless every booked parcel got its delivery area (the partner handoff for the partner-zone ones), the parcel that was never booked was refused as not expected, and every call of the sorter was answered. With booking stopped, the hub keeps sorting.
Booking is then started again. Parcels booked after it returns reach the hub, and the count of sorted parcels is not changed by booking's return. The printed result is saved in your repository.
Architectural guidance
Restarting the hub's sorting during the stop checks that the hub knew its parcels on its own, and not only while booking was there to ask.
Architectural walkthrough
Parcels reach the hub on a belt. A sorter reads each label and needs the delivery area at once, because every second spent waiting holds up the parcels behind it.
A booking can be confirmed to a shop while the hub never hears of it.
Some surprises are routine. A parcel can arrive before its booking, or with a label too damaged to read, or from a shipment the shop has cancelled. If the hub refuses such a parcel without a reason the sorter is left guessing, and a wrong guess puts the parcel on the wrong van.
Booking will be stopped at some point, for an update or a fault. A hub that waits for booking before it sorts each parcel idles every sorter in that time, and the vans still leave at 07:00.
Plan routes and dispatch
Produces a daily route for each courier within van capacity, the move of a route when a courier is out, and a manifest for each courier. Leaves delivery attempts for later Phases, and route optimisation is not part of the brief.
Acceptance criteria
At 05:00 Europe/Amsterdam the product plans the day's routes. Every in-region parcel sorted before then is on exactly one route of one courier, from the 55 couriers. A route never mixes delivery areas, and its stops are in postcode order, ascending, with ties broken by tracking number. A parcel for the partner handoff is on no route. No courier has more than one route on a date. For this Checkpoint a day on which no area holds more than 120 parcels is enough.
An area with no sorted parcels gets no route. Planning the same date twice leaves the same routes and the same couriers on them. A parcel sorted after the plan has run is on no route until the next date's plan.
A test plans a day with the product's clock at 05:00, prints for each route the courier, the delivery area and the number of stops, and checks that every in-region sorted parcel appears on exactly one route.
Architectural guidance
A plan that changes when it is run a second time, for example after a restart at 05:00, can change a courier's stops under their feet at 07:00.
Acceptance criteria
No route holds more than 120 parcels or more than 600 kg of measured weight. When an area's parcels pass either limit, the area is split into several routes, each for its own courier and each an unbroken stretch of the area's postcode order. Routes still never mix delivery areas.
Two tests show it. An area with a few more than 120 parcels of 1 kg each gives two routes, neither above 120 parcels, with the stop order running across both in postcode order. An area of 7 kg parcels, enough of them that weight binds first, gives routes of at most 85 parcels each, because 85 parcels of 7 kg are 595 kg and 86 are 602 kg.
If the routes needed exceed the 55 couriers, the parcels that do not fit are on no route. An operator can list each of them with the reason over capacity, and none is dropped quietly. The next date's plan takes them first.
Architectural guidance
A van loaded past 120 parcels or 600 kg leaves parcels at the depot, and the courier finds out at the van door at 07:00. The two limits bind at different times: 120 parcels of letters never reach 600 kg, and 70 heavy parcels never reach 120. A parcel that fits no route and appears on no list is a parcel nobody knows is late.
Acceptance criteria
An operator marks a courier unavailable for a date. If the courier holds a route on that date, it moves to an available courier who has no route that date, lowest courier ID first. The route keeps its stops in the same order, and the new courier has the same capacity because the vans are identical. The shops' tracking pages are not affected. Marking the same courier unavailable again changes nothing, and marking a courier who has no route moves nothing. A plan made for that date afterwards gives that courier no route.
When no available courier is free, the request is refused with a clear answer, the route stays with the unavailable courier, and it appears in a list of routes with no available courier.
A test marks two couriers who each have a route unavailable at the same instant while exactly one spare courier is free. Exactly one route moves to the spare, the other request is refused, and no courier ends with two routes. The test repeats this many times and states how many.
Architectural guidance
If two sick calls reach the product at the same moment and both see the same spare courier, one person is given two routes and half of those parcels are late. The person at the phone often repeats the request, unsure whether the first went through, so the repeat must not move anything again.
Acceptance criteria
A courier with a credential of their own fetches their manifest for a date. The manifest holds the route ID, the date, and the stops in order, each with its position, tracking number, postcode, and the recipient's name and address. A request with no credential is refused, and so is one courier's credential used to ask for another courier's manifest. A courier with no route that date gets an empty list of stops, not an error. Asking twice returns the same manifest.
The stops match the route planned for that courier, in the same order, and a test compares them. After a reassignment, the courier who lost the route gets an empty manifest and the courier who received it gets the route with the same route ID.
When the manifest is not ready, the answer is 503 with a Retry-After header in seconds. The day driver's vans ask again after that delay and get the manifest once it is ready. A manifest is never served with a stop missing its name or address because something it needed was slow or stopped; it answers 503 instead.
The day driver's 55 vans fetch their manifests at the simulated 07:00 departure and log how many stops each one received. The manifest format is written in the guide for scanner and tablet makers.
Architectural guidance
Handhelds can spend up to 8 hours without signal, so a van has to be able to ask again at any time and get the same plan, apart from a reassignment.
Acceptance criteria
A named test, with its command in the README, plans a day at 05:00 Europe/Amsterdam with the 55 couriers, then marks two couriers who hold routes unavailable at the same instant while exactly one spare is free. Every in-region sorted parcel is on exactly one route and then on exactly one manifest, no route holds more than 120 parcels or 600 kg, and parcels that do not fit are listed as over capacity with none dropped quietly. Exactly one route moves to the spare, the other request is refused, and no courier ends with two routes. The 55 vans fetch their manifests at the simulated 07:00 departure and the test prints how many stops each received. A manifest that is not ready answers 503 with Retry-After, and no manifest is served with a stop missing its name or address.
Architectural guidance
A parcel on two routes is delivered twice or lost between couriers, and a parcel on none waits at the depot while the shop is told it is on its way. A manifest served with a missing address sends a courier out without a place to go.
Architectural walkthrough
Routes are planned at 05:00 and the vans leave at 07:00. A plan that is wrong is found out at the van door, by a courier standing next to a van with too many parcels or parcels nobody assigned. A parcel on no route is a parcel nobody delivers that day, and a parcel on two routes is delivered once and then reported missing by the other courier.
A van holds 120 parcels and 600 kg, and a route can be within one limit and over the other. A route that is too big for its van leaves parcels at the depot, and those parcels miss their day.
A courier calls in sick at 06:30. Their route has to move to someone else before 07:00 or a day of parcels waits.
The manifest is the courier's list for the day, and it holds the names and addresses of recipients. A courier who gets half a manifest does not know which parcels they are missing until a recipient calls. Those names and addresses are personal data that the client must erase on request, wherever the product has put them.
Deliver, retry and return
Produces proof of delivery, a second attempt on the next working day, a return to the sender after the third failure, and a flag for parcels that stop moving. It does not notify anyone or bill anyone yet.
Acceptance criteria
When a handheld uploads a delivered scan with a proof reference for a parcel on its first attempt, the parcel's journey ends as delivered. Support's lookup of the parcel shows it as delivered on attempt 1, with the time on the scan and the proof reference from the scan, and the tracking page shows it as delivered.
The negative cases pass. A handheld delivered scan with no proof reference is rejected in the upload answer with a reason, and the parcel stays as it was. The same delivered scan uploaded twice, including twice at the same instant, leaves one delivery. A parcel that failed once and is delivered on the next working day shows as delivered on attempt 2. A delivered scan that reaches the network before the out for delivery scan of the same attempt, because the batch holding the earlier scan was held for 8 hours, still shows one delivery with the right attempt number.
Architectural guidance
A delivery is the fact the recipient, the shop and the invoice all rely on. Handhelds retry an upload after a timeout, so the same delivered scan reaches the network twice as a matter of routine. A parcel counted as delivered twice is reported twice to the shop and can be billed twice, and a delivery with no proof leaves the client with nothing to show when a recipient says the parcel never came.
Acceptance criteria
After a failed-delivery scan on a parcel with fewer than 3 failures, support's lookup and the tracking page show the parcel as waiting for the next attempt, with the date of that attempt and the reason from the scan. The date is the next working day on the Europe/Amsterdam calendar, Monday to Friday, so a failure on Friday waits for Monday. All four reason codes (not_home, address_not_found, refused, access_denied) behave the same way.
The courier manifest for that next working day lists the parcel. The manifest for the day of the failure, and for any day before the next working day, does not.
The negative cases pass. The same failed-delivery scan uploaded twice, or twice at the same instant, counts as one attempt. A failed-delivery scan that reaches the network after the delivered scan of the same parcel changes nothing, and the parcel stays delivered.
Architectural guidance
Each parcel has only three attempts, so an attempt counted twice or counted after the parcel was delivered takes one away from a parcel that still needs it. A parcel promised for Monday that is missing from Monday's manifest sits at the hub for another day, and one scheduled for a Saturday goes on no van at all. The client pays a penalty for wrong tracking information, and a wrong next-attempt date is exactly that.
Acceptance criteria
The third failed attempt sends the parcel back to its sender. Support's lookup and the tracking page show it as returning to the sender, with no date for a next attempt, and no courier manifest lists it again. The parcel's history shows three attempts, each with its own reason.
The negative cases pass. A fourth failed-delivery scan for the same parcel changes nothing. The third failed-delivery scan uploaded twice, or late, still leaves one return. Three failed-delivery scans that reach the network in reverse order give the same three attempts in the same order and one return. A parcel with only two failed attempts is never shown as returning.
Architectural guidance
Sending a parcel back is the most expensive thing the network does to a shop: the shop pays a 350 cent return charge, and its customer does not get the goods. A return triggered by a repeated scan, or one that happens twice, charges the shop for a failure that did not happen. A parcel that makes a fourth attempt after the client has told the shop it is coming back contradicts what the shop was told.
Acceptance criteria
A parcel that is not delivered, returned or handed to the partner carrier, and whose latest scan has a time more than 48 hours ago, is flagged as stalled. An operator can list the stalled parcels with their tracking numbers and the time of each parcel's latest scan. The flag is raised once per parcel however many times the product checks, and the product checks at least every 15 minutes on its own clock. With the clock moved forward, a parcel whose latest scan is 47 hours old is not flagged and the same parcel is flagged within 15 minutes of passing 48 hours.
The negative cases pass. A scan with an older time that is uploaded late never makes a parcel look more recent than its latest scan. A newer scan clears the flag and starts the 48 hours again. A parcel that is delivered after being flagged is no longer listed as stalled. Delivered, returned and partner-handled parcels are never flagged however old their last scan. Restarting the product at any moment leaves the same parcels flagged and flags none a second time.
Architectural guidance
Counting the 48 hours from when a scan reached the network instead of the time on it flags parcels late after a delayed upload, or hides a lost parcel behind an old scan that arrived recently. The shop finds out when its customer phones, before the client does.
Acceptance criteria
One command, listed in the README, plays scripted journeys: a parcel delivered on the first attempt, a parcel that fails once and is then delivered, and a parcel that fails three times and is returned. It repeats scans, delays them by up to 8 hours and sends them out of order, while the simulator kills the product at random moments and restarts it.
The command takes a seed, and the same seed gives the same journeys, kills and result. It runs over many seeds and prints, for each, the number of kills, the number of parcels and the number of attempts counted per parcel. It ends by printing 0 parcels with a wrong attempt count and 0 parcels with two endings. It exits with 0 only when both numbers are 0 and exits with a non-zero code otherwise.
Architectural guidance
A crash while a failed attempt is being dealt with can leave a parcel that has failed three times and is still waiting for a fourth, or one that was sent back twice. Neither shows in a normal run, because the product has to stop at one unlucky moment, so the test has to cause the crash itself. The cost lands on the shop: a wrong return charge, or a parcel that is lost between two decisions.
Architectural walkthrough
A parcel gets at most three delivery attempts, and the number of attempts decides what happens to it. After the third failure it goes back to its sender. Scans reach the network late, twice and out of order, so the count has to be right under all three.
Take a handheld that uploads a failed-attempt scan and gets no answer in time. It uploads the same scan again, as it is built to. If the second upload counts as another attempt, one real failure looks like two, and two such repeats send a parcel back to its sender after a single try. The shop gets a return it did not expect and later pays the 350 cent return charge for a parcel nobody tried hard enough to deliver.
Order causes the opposite mistake. A courier fails an attempt in a street with no signal and delivers the parcel later the same afternoon. If the batch holding the failure is held for 8 hours and the batch holding the delivery arrives first, a count that follows arrival decides the parcel failed last. A parcel the recipient already holds is then rescheduled or sent back.
A parcel that has vanished is the quietest failure. It produces no scan, so nothing arrives to say anything is wrong. The shop finds out when its customer phones, and the client's contract with its second-largest merchant carries a penalty for wrong tracking information.
The last Checkpoint of the Phase, Count Each Delivery Attempt Once However the Scans Arrive, kills the product at random moments. A crash in the middle of dealing with a failed attempt must neither lose the attempt nor act on it twice.
Notify merchants and recipients
Produces signed webhooks to shops with a fixed retry schedule, one delivery-day email per parcel, and a replay of the last 7 days of webhooks. It leaves the partner carrier and invoices for later Phases.
Acceptance criteria
A shop registers an endpoint URL and sees its signing secret once. Asking for the secret again does not show it. When a parcel is delivered, a delivery attempt fails, a parcel waits for its next attempt, a parcel is returned to its sender, or a parcel is flagged as stalled, each of the shop's endpoints receives one webhook. The body names the tracking number, says in plain words what happened and when, and carries an identifier of the happening that stays the same on every retry and every replay. The shop never receives webhooks about another shop's parcels.
Every request carries two headers: X-Parcel-Timestamp with the send time and X-Parcel-Signature with an HMAC-SHA256 over the timestamp and the raw body, keyed with the endpoint's secret. The merchant API documentation states the exact format of the timestamp, of the signed text and of the signature, and shows how a shop verifies it: against the raw body, and rejecting a timestamp older than 5 minutes. The simulator's shop receiver verifies with whatever the documentation says.
The call times out after 5 seconds. Any error answer, timeout or connection failure is a failure, and the webhook is retried 1, 5, 30 and 120 minutes after the previous failed attempt. After the fourth retry fails it is marked failed. Every attempt is recorded with its number, the answer or the timeout, and the time it took.
The negative cases pass. A receiver that always answers with an error sees 5 attempts in total and the webhook ends as failed. A receiver that takes 6 seconds to answer counts as failed at 5 seconds. A captured request sent again 6 minutes later is rejected by the simulator's receiver, and changing one byte of the body breaks the signature. The same happening reported twice produces one webhook per endpoint. Restarting the product between two retries keeps the schedule. While one shop's endpoint hangs, other shops' webhooks arrive before the hanging call has timed out.
Architectural guidance
A receiver checks the signature against the bytes it received. If the sender signs a differently formatted copy of the body, genuine webhooks are rejected at random and the shop cannot tell why. A signature that does not cover the time lets anyone who captured one request send it again later.
Acceptance criteria
When a parcel goes out for delivery, the recipient receives one email on that morning in the simulator's mailbox. It names the tracking number and links to the tracking page, and the link opens the page of that parcel. No other scan sends the recipient anything. A parcel on its second attempt produces one email on the morning of that attempt.
The negative cases pass. An out for delivery scan uploaded twice, uploaded twice at the same instant, or uploaded late sends nothing more, so a parcel never produces more than one message per day. An out for delivery scan that reaches the network after the parcel was delivered sends nothing. When the recipient's details are not available at the moment the message is due, no email goes out without an address.
Architectural guidance
A recipient who receives two emails on delivery morning stops opening them, and one who receives an email for a parcel the courier delivered hours earlier is told something false. Scanners repeat uploads as a matter of routine, so a message sent for every scan that arrives sends several for one parcel. An email with no address, or to the wrong one, is also personal data that went somewhere it should not.
Acceptance criteria
A shop lists its own webhooks from the last 7 days, filtered by endpoint and by status (waiting, delivered or failed). It opens one and sees the body that was sent and every attempt, with the time and the answer or the timeout. It replays one webhook, or every failed webhook of one endpoint since a time it names. The merchant API documentation describes all of this.
A replayed webhook carries the same body and the same identifier of the happening as the original, with a fresh timestamp and a fresh signature that pass the verification the documentation describes. Replaying with no failed webhooks in range replays nothing and says so.
The negative cases pass. A webhook older than 7 days is neither listed nor replayable. A shop asking for another shop's webhook gets the same answer as for one that does not exist. A replay of a webhook that was delivered does not change the record of the original.
Architectural guidance
A replay signed with the old timestamp is rejected by the shop's own check, and a replay with a different body looks like a different happening, so the shop may act on it twice.
Acceptance criteria
A named test, listed in the README, registers at least three endpoints for one shop and feeds in many distinct happenings (deliveries, failed attempts, returns). It reports each happening more than once, and some at the same instant. It kills the product at random moments and restarts it. One endpoint answers with errors for part of the run, so retries are happening during the kills.
The test groups the webhooks the simulator's receivers received by endpoint and happening. Copies of one webhook are allowed, because a retry after a kill can arrive twice. It passes when every pair has at least one copy the receiver answered successfully, so the number of pairs received equals the number of happenings times the number of endpoints, when every copy of a pair carries the same event identifier, and when no recipient received two messages for the same parcel on the same day. It prints the number of happenings, endpoints, expected pairs, pairs received, copies received, pairs with more than one event identifier and missing pairs, and exits with 0 only when the pairs with more than one identifier and the missing pairs are both 0.
Architectural guidance
Two events for the same news come from two things happening at once, or from a restart at the wrong moment. A normal run with no kills and no repeated reports shows neither, so a shop finds out by shipping two replacements. A product stopped just after a call to a shop went out cannot tell whether the shop heard it, so it may send the call again. The test has to hit that moment on purpose, and the second call must be recognisable to the shop as a copy.
Architectural walkthrough
Shops act on the webhooks they receive: they tell their own customers, release stock and ship a replacement for a parcel that came back. A shop that cannot tell a retry from a new event sends two customer emails or ships two replacements. The client's rule is that every retry and every replay of a webhook carries the same event identifier, so a shop can drop a copy it already has.
A webhook is a call to a machine the client does not run, and the call times out after 5 seconds. A shop whose endpoint hangs makes every call to it take the full 5 seconds. With 200 shops, if one hanging shop delays the news for the others, then one slow shop turns into late news for everyone, and the recipient emails that follow behind it are late too.
A product that stops in the middle of sending has two bad outcomes. If it stops after the call went out, the next start may tell the shop again as if it were news. If it stops before the call, the shop may never hear. The last Checkpoint of the Phase, Prove No Shop or Recipient Is Told the Same Thing Twice, kills the product at random moments to find out which of these it does.
The recipient's email has its own version of the problem. A recipient who gets three emails on delivery morning stops opening them, and a recipient who gets one for every repeated scan sees a client that cannot count. The client's rule is one email on the morning a parcel goes out for delivery, and at most one per parcel per day.
A shop whose endpoint was down overnight misses news the client has already given up on. Without a way to get that news back, the shop phones support, and support cannot say what was sent or when.
Hand off to the partner carrier
Produces the hand-over of parcels outside the region to the partner carrier, and their progress shown on our own tracking page. It leaves invoices for a later Phase.
Acceptance criteria
A parcel sorted for the partner handoff (any valid postcode outside the region) is given to the partner carrier with its tracking number and the recipient's name, address lines and postcode. The partner answers with a reference for it. The tracking page shows the parcel as handed to the partner carrier, the shop's endpoints receive one webhook saying so, and no courier manifest for any date lists the parcel.
Your fake partner can cause four behaviours: it answers late, it times out after accepting the parcel, it rejects the parcel, and it is unreachable. The negative cases pass under each. If the hand-over times out after the partner accepted it and the product tries again, the partner's own list holds that parcel once. Two hand-over requests for the same parcel at the same instant also leave one. A parcel the partner rejects is visible to an operator as not handed over, with the partner's reason, and the shop is never told it was handed over.
Architectural guidance
Trying again blindly can leave two parcels at the partner, and not trying again can leave none while the shop has been told the parcel is on its way. The recipient pays for the confusion, because no one is carrying their parcel or two people are.
Acceptance criteria
A document in your repository has one row for each of the partner's six status codes (ACC, TRN, OFD, DLV, ATT and RTS). OFD shows as out for delivery and DLV as delivered. ATT shows as a failed delivery with the reason code from the client's four that the document states. RTS shows as returned to the sender. ACC and TRN show nothing new, and their rows say why. The document states which statuses end the follow-up of a parcel.
When the simulator's partner reports each status for a parcel, the tracking page shows the words from the document. A parcel the partner delivered produces the same delivered webhook, in the same words, as a parcel the client's own couriers delivered.
The negative cases pass. A search of the tracking page, every webhook body and every answer a shop can fetch finds none of the six codes as a status. A failed delivery reported by the partner is not one of the client's three delivery attempts: it does not send the parcel back to its sender and does not change the attempt count.
Architectural guidance
The partner's codes belong to the partner. If they reach shops and recipients, every shop has to learn them, and the day the partner changes one, shops that parse it break without the client knowing. A failed delivery by the partner's courier counted as one of the client's three attempts sends the parcel back to its sender after fewer real attempts, or never.
Acceptance criteria
Progress the partner reports for a handed-over parcel appears on the tracking page within 10 minutes of the partner reporting it, on the product's clock. The product asks the partner about every handed-over parcel that has not reached a finishing status once every 10 minutes. The simulator records each question the product asks, with the time on the product's clock, and shows a round starting every 10 minutes and no question about a parcel after its finishing status.
The negative cases pass. When the partner takes longer than 10 minutes to answer a round, the next round does not start on top of it. A status the partner repeats, or reports out of order, leaves the tracking page showing the right history in the order things happened, with each status once.
Architectural guidance
The partner has no way to tell the client when something happens, so the client's only way to know is to ask. Asking too rarely leaves recipients looking at a page that is hours behind. Asking while the previous round is still running doubles the load on the partner exactly when it is slow, and asking about parcels the partner has finished wastes goodwill the client needs.
Acceptance criteria
A script listed in the README books parcels for the partner zone and for the region, with the simulator's partner in several states (answering, late, repeating, out of order). It makes the partner unreachable for 6 hours on the product's clock, kills the product once during the outage and restarts it, and then lets the partner return.
It exits with 0 only when all of the following hold. In-region parcels booked during the outage still reach delivered, and shops see zero errors on booking and tracking throughout. Tracking pages for partner parcels keep answering during the outage. Hand-overs requested during the outage complete once each after the partner returns. After the partner returns, every status it recorded appears once on the tracking page, in the order it happened. The script prints these counts.
Architectural guidance
When the partner returns, a hand-over sent twice or a status shown out of order puts the wrong information on exactly the pages of the parcels that waited longest.
Architectural walkthrough
Parcels for addresses outside the region go to one partner carrier. The partner has no webhooks, so the only way to know what happened to a parcel is to ask. It answers late, repeats a status, reports statuses out of order, sometimes accepts a request and then times out, and can be unreachable for 6 hours.
A hand-over that times out does not say whether the partner accepted the parcel.
The partner speaks its own language: six status codes (ACC, TRN, OFD, DLV, ATT and RTS). If those codes reach a shop's webhook or a recipient's page, 200 shops have to learn them, and when the partner renames one the shops break. The client's rule is that no partner code is ever shown to a shop or a recipient.
A 6 hour partner outage must not become the client's outage. About 6,000 parcels a day move through the network and only some belong to the partner. If tracking or delivery for the rest waits for the partner to answer, a few partner parcels stop the whole day.
The partner also reports attempts that its own couriers made. Those are not the client's three delivery attempts, and counting them as such sends a parcel back to its sender early, or never.
Bill the merchants
Produces prices, surcharges and monthly invoices that match what actually happened to each parcel. It leaves the operator's tools and the full simulated day for the last Phase.
Acceptance criteria
Each booked parcel is billable at exactly the price it was quoted, in whole cents. Publishing a new rate card version with different prices after a booking changes nothing about that parcel's billable price. An operator can look up a parcel by tracking number and see its billable price and what it is made of: the quote, the band, the zone and any oversize surcharge.
The negative cases pass. A test that repeats or delays, in any order, the information billing relies on leaves each parcel billable once at its quoted price. A cancelled shipment is never billable, including when the news of the cancellation reaches billing before the news of the booking. A price shown by the operator's lookup never differs by even one cent from the shop's quote.
Architectural guidance
A price recomputed at billing time from today's rate card differs from the price the shop saw when it booked. The shop compares its invoice with its quotes line by line, and a difference of one cent on a parcel it never changed becomes a dispute. A cancelled shipment that appears on an invoice is a refund and a complaint.
Acceptance criteria
A parcel whose measured billable weight at the hub puts it in a higher weight band than the one it was booked in is billed the difference between the two bands' prices, taken from the rate card version and the zone it was booked in. The measured billable weight is the larger of the measured weight and the volumetric weight (length x width x height in cm divided by 5,000, in kg). A parcel measured at 2,000 g in the 2 kg band gets no correction and one measured at 2,001 g does. A parcel measured in the same band, or a lighter one, adds nothing. A return to the sender adds 350 cents. An operator's lookup of the parcel shows each surcharge as its own line with the reason.
The negative cases pass. A parcel that is measured twice, with different weights, gets at most one correction, decided by the measurement with the later time. Repeating or delaying the information that causes a surcharge, in any order, leaves each surcharge on the parcel once. A parcel that gets a correction and is later returned shows both lines.
Architectural guidance
A surcharge that appears twice charges the shop for the same thing twice, and one that is missing is revenue the client never sees. The information that causes a surcharge arrives late and in any order, so a correction applied after a parcel was already billed, or applied against today's rate card, produces a total the shop cannot reproduce from its quote.
Acceptance criteria
Closing a month, such as September 2026, issues one invoice for each shop that has at least one parcel whose final result (delivered, returned to the sender or handed to the partner carrier) has a time inside that month on the Europe/Amsterdam calendar. A shop with no such parcel gets no invoice. A shop can fetch its own invoices, and cannot fetch another shop's.
Invoice numbers run in sequence for the year with no gaps, in the form 2026-000001. Each invoice has one line for each parcel with its tracking number and the quote it was priced from, one line for each surcharge, and a net total equal to the sum of its lines to the cent. Below the net total the invoice shows the VAT at 21%, worked out once on the net total and rounded half up to the whole cent, and the invoice total, which is the net total plus the VAT. The invoice also shows the date of issue, the client's name, address and VAT number, and the shop's name and address. A cancelled shipment is on no invoice.
The negative cases pass. Closing the same month twice issues nothing new. Two closes of the same month at the same instant produce neither a gap nor a duplicate number. Two closes of different months at the same instant also leave the numbers in sequence with no gap.
Architectural guidance
An accountant who finds a missing invoice number asks where it went, and an invoice number used twice is a tax problem for the shop. Two people closing a month at once, or a close repeated after a failure, are exactly the moments when gaps and duplicates appear. A net total that differs from the sum of its lines by one cent makes the whole invoice untrustworthy. 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 VAT rounded by a rule the client never stated leaves a cent to argue about on every invoice.
Acceptance criteria
A script listed in the README compares a closed month's invoices with the simulator's own record of what happened, without reading anything the product stores. It prints the number of parcels that reached a final result, the number billed, the tracking numbers missing from invoices, the tracking numbers billed more than once, the difference in net cents before VAT, and the number of invoices whose VAT is not 21% of the net total rounded half up. It exits with 0 only when the missing count, the doubled count, the difference and the VAT count are all 0.
The script is run once with billing stopped for 1 hour during the month. During that hour, shops can still book and track parcels with zero errors. After billing returns, nothing is missing and nothing is doubled on the invoices.
Architectural guidance
A plausible invoice is the hardest kind to find wrong. A parcel missing from it is revenue lost with no complaint, and a parcel on it twice is a complaint from the shop's accountant. The two mistakes can cancel out in the total, so a check has to compare parcel by parcel and not only add up. The hour in which billing was stopped is where parcels go missing.
Architectural walkthrough
An invoice is the one place where every earlier mistake becomes money. The client's own history includes a shop that paid twice for one parcel because its status bounced between two values. The contract with the second-largest merchant now carries a penalty for wrong information, and an invoice that disagrees with the tracking page is wrong information with a total on it.
A shop checks its invoice against the price it was quoted at booking. If the rate card changes in between and the invoice uses today's prices, the shop sees a difference on a parcel it never changed, and every dispute that follows costs support more than the difference. A shipment the shop cancelled must never appear on an invoice at all.
The information billing relies on arrives late, twice and out of order, like every other outside input. A return counted twice charges 350 cents too much, and a weight correction applied after the parcel was already billed at the higher band charges twice for the same thing.
Invoice numbers are sequential per year with no gaps, because an accountant who finds 2026-000014 missing asks where it went. Two people closing the same month at the same instant must not produce two invoices with the same number, or leave a number unused.
Billing is also the capability most likely to be stopped. If it is stopped for an hour while parcels are delivered, those parcels must be on the invoice afterwards, and shops must still be able to book and track meanwhile.
Operate the network
Produces what an operator needs to answer for any parcel, an erasure on request, an update with nothing lost, and the full simulated day with every failure at once. It leaves nothing for later.
Acceptance criteria
Given a tracking number, an operator sees, in the order it happened, everything the product did for that parcel: the booking and its quoted price, every scan, the sort and delivery area, the route and courier, each attempt, the emails and webhooks sent with their results, the partner's statuses and the billing lines. Each entry shows its time and what caused it: a shop's request, a scan, the partner's answer or the clock. An entry that arrived late appears in its place by the time it happened, and also shows when it arrived.
A reviewer following the operations note answers a shop's question about where its parcel is in under a minute, for a parcel from the simulated day that had three delivery attempts. An unknown tracking number gives not found. For a parcel whose recipient's data was erased, the view shows no name, address or email.
Architectural guidance
A shop's question about one parcel needs facts from everything the product does: bookings, scans, routes, messages, partner answers and billing. A wrong answer to the second-largest merchant counts under the client's penalty for wrong tracking information.
Acceptance criteria
A test makes the handling of one scan fail every time, then does the same for one webhook to a shop and for one partner status. After the item has failed 5 times in a row, it is set aside with its error. Every item behind it is handled normally, so the tracking pages, webhooks and invoices of the other parcels are right. An operator can list what was set aside, with the parcel, what it was and the last error.
After the test removes the fault, the operator retries the set-aside item and it is handled exactly once, with the same result as a normal handling: the tracking page changes once and the shop receives the webhook, whose event identifier is the same on every copy. Retrying it a second time changes nothing. The spacing between the 5 attempts is stated in the operations note.
Architectural guidance
One malformed scan, or one shop endpoint that always errors, can keep failing and hold up everything that arrives after it, so a single bad item stops tracking for 6,000 parcels. Retrying it forever hides the problem in noise. Dropping it silently leaves a hole in a parcel's history that nobody knows about until a shop asks.
Acceptance criteria
On request, an operator erases a recipient's name, address and email by tracking number. Afterwards none of them appears in the label, the courier manifest, the trace of the parcel, any email still waiting to be sent, or any log. A text search over everything the product has stored or logged for that recipient's name, address lines and email finds nothing.
Shipment records, scans, delivery results, webhooks already sent and invoices stay, identified by tracking number, and no invoice total changes. An email waiting to go to the erased recipient is never sent. Erasing the same recipient twice is harmless. A request for a parcel that is still on a van gets a clear answer for the operator that says whether the erasure was done or refused and why. The steps are in the operations note.
Architectural guidance
A recipient has the right to ask that their name, address and email be removed. Copies of that data end up in places that are easy to miss, such as manifests, emails waiting to go and logs, and one copy left behind is a breach. The shipments, delivery results and invoices that the client's accounting and tax records need must stay intact, so an erasure that removes whole parcel records breaks a shop's invoice.
Acceptance criteria
A script replaces the running tracking capability with a new version that changes what the tracking page shows for every parcel, including parcels recorded before the update. You choose the change, such as one more line on each history entry. During the update the simulator keeps booking shipments and uploading scans at the rates of the simulated day.
The script exits with 0 only when all of the following hold. No booking fails. Every scan the simulator uploaded appears in its parcel's history exactly once. The tracking page answers every request the simulator makes during the update. After the update, the tracking pages of all parcels equal what a fresh repair from the recorded scans would show. The script prints these counts. With tracking being replaced, shops can still book and handhelds can still upload.
Architectural guidance
Shops that book during the update meet errors, and a tracking page that changes shape for old parcels but not new ones shows recipients two different answers.
Acceptance criteria
One command, listed in the README, runs the whole day on the product's clock from a recorded seed, so the same seed gives the same failures. The day holds 6,000 parcels from 200 shops, each shop booking at least one, and about 45,000 scans. The parcels end in every way: delivered on the first attempt, delivered on the second, returned to the sender after three failures, handed to the partner carrier and delivered by it, and one returned by the partner.
Failures happen in the same day. 5% of scan batches are uploaded twice and 10% are delayed by 6 hours. Each capability is killed once mid-run and restarted. The partner carrier is unreachable for 2 hours and billing is stopped for 1 hour.
At the end the reconcile script from Bill the Merchants prints 0 missing, 0 doubled, 0 net cents of difference and 0 invoices with wrong VAT. Every parcel's tracking page matches the simulator's record of what happened. Every endpoint and happening owed a webhook shows at least one received copy, all copies of one happening carry the same event identifier, and no recipient received two messages for one parcel on one day. Shops saw zero errors on booking and tracking during the partner outage and the billing stop. The results, with the seed, the counts and a pass or fail for each check, are committed to your repository.
Architectural guidance
In production the failures overlap: a partner outage during a duplicated batch, a billing stop while the product is restarted. The problems that appear only in combination are the ones that reach the client, and the one place to find them before a shop does is a day that has all of them.
Architectural walkthrough
At 06:40 a shop phones about a parcel. The operator needs the facts from everything the product has done for it, and the contract with the second-largest merchant has a penalty for wrong tracking information. If the answer is spread over several places that the operator has to read and match by hand, it takes an hour and may be wrong.
One bad item can stop a whole day. A scan the product keeps failing to handle, or a shop endpoint that always errors, can hold up everything that arrives after it. If it is retried forever, thousands of parcels' tracking waits on it. If it is dropped silently, a parcel's history has a hole and nobody was told.
An update during the evening peak is when scanners flood in. An update that refuses or drops uploads for even a minute loses scans that handhelds believe were accepted, or makes them retry into duplicates. Shops that book during the update meet errors, and the client has promised them bookings are always accepted.
A recipient can ask to be forgotten. Their name, address and email are copied into labels, manifests, emails waiting to be sent, traces and logs, and one copy left behind is a breach. The shipments, scans, delivery results and invoices that tax and traceability require must stay, identified by tracking number.
Every failure in the earlier Phases was tested alone. In production they arrive together, and the problems that appear only in combination are the ones that reach the client. The last Checkpoint of the Phase runs them all in one day.
Architectural walkthrough
A late scan is not the latest scan
The old system showed whatever had been written last. A handheld in a van with no signal holds its scans for up to 8 hours, so a scan from 09:10 can reach the server after one from 14:30. The page then tells a recipient the parcel is out for delivery after the driver has already handed it over, and the shop that sent it is told the same. Every wrong tracking page in the client's story comes from this. The contract with the second-largest merchant puts a penalty on each one.
The same trouble shows up in smaller places. The partner carrier reports statuses when you ask for them, so an outage leaves a gap that fills with old news. A courier's scanner retries an upload when it gets no answer, so the same 500 scans arrive twice. Check your build against a parcel whose scans arrive in the worst order you can invent, and against the same upload sent three times.
Nothing happens twice, nothing is lost
A shop that cannot tell a retried webhook from a new event may ship a second parcel. A recipient who gets three emails in a morning stops opening them. A merchant billed twice for one parcel calls the client's sales lead, which is how the double charge in the client's story was found. A product that stops halfway through a booking leaves a shop told "booked" while the hub has never heard of the parcel, and nobody finds out until a van is short of one.
These failures happen at the moment two things must agree and the machine stops between them. Checking only the quiet path will not find them. Kill things at random moments, send requests at the same instant, and count what the shops, the recipients and the invoices actually show afterwards.
One stopped part must not stop the rest
The client lost the merchant portal for two hours because a scanner flood slowed the shared application. The cost is not the two hours. Shops that cannot book send their parcels to a competitor that day, and some do not come back. Billing, notifications, the partner carrier's API and the scan intake will each be down at some point. What the client needs to know in advance is which work continues: with billing stopped, shops can still book and track parcels; with the partner carrier unreachable for 6 hours, in-region parcels still reach their recipients; with scan intake stopped, recipients can still open their tracking page.
An update is a planned outage. Replacing one capability while shops keep booking and scanners keep uploading must cost the client no booking and no scan.
Where it shows if you cut a corner
The simulated day in the last Phase brings 6,000 parcels from 200 shops and about 45,000 scans, with some scan uploads sent twice, others held back by 6 hours, the product killed mid-run, the partner carrier unreachable for 2 hours and billing stopped for 1 hour. If a late upload rewrites a newer fact, the invoices do not match what the simulator delivered. If a stopped capability makes another one fail, the day shows errors on the shops' side while it is down. If anything is sent twice, the simulator's receivers count it. Each of these is cheaper to find in your own run than in a merchant's penalty claim.
Related Links
- GDPR Article 17, right to erasurea recipient's name, address and email are erased on request while shipment, scan, delivery and billing records stay.
- Stripe: webhook signaturesa shop verifies a webhook with a signature over the timestamp and the raw body.
- Stripe: idempotent requestsbooking again with the same Idempotency-Key returns the number from the first answer.
- GLS: recipient not reacheda failed attempt sends the parcel back to the depot and the sender gets it back after the third.
- Shipping label sizes guidethe label is 100 x 150 mm with the tracking number as text and as a Code 128 barcode.