Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Product recall tracer series ~6 min read

A product recall tracer on AWS for a few dollars a month

The notice arrives on a Tuesday afternoon. One product, four batch codes, a date range. Somebody walks the shelves with a printout. Two hours later the honest answer is that nobody can tell which of the units on the shelf came from those batches, so everything of that line goes in the skip, and the customer notice has to say everything too.

A grocery store aisle with shelves stocked with cereal boxes
Photo by Nathalia Rosa on Unsplash

Key takeaways

  • A recall costs what your records let it cost. The expensive part is not finding stock.
  • Batch capture happens at goods-in or it never happens at all.
  • One step back and one step forward is the legal floor, not the useful answer.
  • Count the customers you cannot name. That number is the point, not an embarrassment.
  • Designed on AWS for about $2 a month.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: deliveries, a recall notice and sales joined into three listsThree boxes across the top sit outside the AWS account. On the left, Deliveries: notes, labels and batch codes. In the middle, The notice: one product, four batch codes. On the right, Sales: tills, orders and accounts. Each connects by an arrow to the AWS account container below, labelled each delivery, rare, and continuous respectively. Inside the AWS account are three components in a row. On the left, Batch register: what arrived, when, and from whom. In the middle, Forward trace: stock on hand and units sold. On the right, Three lists: quarantine, notify, and cannot name. A note says the notice is the cheap part and arrives complete, while the batch register is the expensive part and has to already exist on the day the notice lands.AWS ACCOUNTDeliveriesnotes, labels,batch codesThe noticeone product, fourbatch codesSalestills, orders,accountsBatch registerwhat arrived, when,from whomForward tracestock on hand,units soldThree listsquarantine, notify,cannot nameeach deliveryrarecontinuousThe notice is the cheap part and it arrives complete. The batch register is the expensive part and it has to already exist on the day the notice lands.
Fig 1. Three things outside the account, three pieces inside it. Only one of the three inputs is urgent, and it is the one you cannot prepare for.

Why the notice is never the hard part

Recall notices are unusually good documents. They are written to be acted on by strangers under time pressure, so they name the product, the pack size, the batch or lot codes, the best-before dates and the reason, in roughly that order, and they are published in a consistent format. Reading one is a solved problem.

The hard part is on your side of the counter. The notice says batch L4127. Your stock system says you have forty-one of that product. It does not say which batch they came from, because nothing ever asked. So the question the notice poses is one your records were never built to answer, and the only safe answer is the widest one.

What runs (the inside)

  • Batch register. Every delivery line recorded with its batch code, its supplier and its date, in about fifteen seconds. Part 2.
  • The notice, read. A recall notice turned into the exact products, batches and date ranges it names, and nothing wider. Part 3.
  • Forward trace. Those batches followed into what is still on the shelf and what has already left. Part 4.
  • Three lists. Quarantine, notify, and the honest count of people you cannot identify — plus the file you hand an inspector. Part 5.

One notice, one small chain

One recall notice traced from delivery through stock to customersA horizontal row of five boxes joined by arrows. One notice naming four batch codes on one product. Two thousand one hundred and eighty units received across the date window. Sixty-one units still in stock across three sites, quarantined. Seven hundred and four units sold from those batches. Two hundred and eight of those buyers can be named and four hundred and ninety-six cannot be identified. A note says that without batch codes at goods-in the third box would read two thousand one hundred and eighty and the fifth would read everyone, which is the whole value of the system and is decided at delivery.ONE NOTICE, THREE SITES, ONE WEEK1 notice4 batch codes,one product2,180 receivedacross thedate window61 in stock3 sites,quarantined704 soldfrom thosebatches208 nameable496 cannotbe identifiedWithout batch codes at goods-in, the third box reads 2,180 and the fifth reads everyone. That is the whole value of the system, and it is decided at delivery.
Fig 2. The same system as one line. Every number narrows except the last one, which is the number most systems refuse to report.

In plain words

At goods-in, each delivery line is recorded with three things that stock systems routinely throw away: the batch or lot code printed on the case, the supplier it came from, and the date it arrived. That is the one-step-back half of traceability, and it is the half almost everybody already has on paper somewhere and nowhere in a database.

Sales are joined to batches by the oldest rule in stock control: first in, first out. This is an assumption, not an observation, and the system says so on every report it produces. Where a site scans a batch code at the till the assumption is replaced by a fact, and where it does not, the trace is a defensible estimate with its own confidence attached.

When a notice arrives it is read into a structured claim: these product identifiers, these batch codes, this date range, this reason. Then that claim is run against the batch register in both directions — forward into stock and sales, backward into which supplier and which delivery — and three lists come out.

The third list is the one that makes this system honest. Most retail sales are anonymous, and a recall system that only reports the customers it found is quietly reporting a fraction as if it were a total. This one reports both numbers, because the gap between them decides whether you also need a notice at the door.

Design rules that shaped every decision

  • The batch code is captured at goods-in or the system admits it does not know.
  • First-in-first-out is an assumption and is labelled as one on every output.
  • The unmatched customer count is reported as prominently as the matched one.
  • A notice is read into codes, never into a product name alone.
  • Nothing is deleted after a recall. The evidence file is the deliverable.
  • The system quarantines on paper; a human moves the stock.

What it does not do

It does not decide whether to recall. That is a judgement about safety made by people with a duty to make it, and often it has already been made by somebody else and sent to you. It does not contact your customers either; it produces the list and the wording, and a person sends it.

It also does not pretend to trace a cash sale. If somebody paid with coins and took the item away, that unit is in the fifth box and no amount of engineering moves it into the fourth. The value of saying so plainly is that it turns a vague worry into a number you can put in a public notice.

The next four posts walk through each piece: how fifteen seconds at goods-in decides what a recall costs, how a notice becomes a set of codes, how the forward trace works and where it is honest about guessing, and what the evidence file has to contain. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts