Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Allergen checker series ~6 min read

An allergen checker on AWS for a few dollars a month

A recipe has not changed in two years. Last month the supplier of one ingredient reformulated it and the new specification includes mustard. Nothing in the kitchen changed, nothing in the recipe changed, and the dish now contains an allergen it did not contain before. There is no event anywhere that catches this, which is what this post is about.

a white building with a blue trash can in front of it
Photo by Matthew Thompson on Unsplash

Key takeaways

  • Unknown is never treated as absent. It is reported as unknown, prominently.
  • Supplier specification changes are the largest real risk and need an explicit check.
  • The system reports what is declared; it never declares a dish safe.
  • A substitution changes the allergen profile and must be caught before service.
  • 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: allergen declarations rolled up to dishes with changes watchedThree boxes across the top sit outside the AWS account. On the left, Supplier specs, holding what each ingredient declares. In the middle, Recipes and substitutions. On the right, Whoever is asked by a customer. Each connects by an arrow to the AWS account container below. Specifications flow down into the account. What is in what feeds in. Declared and unknown go back out. Inside the AWS account are three components in a row. On the left, Declarations, covering contains, may contain and unknown. In the middle, the Roll-up from ingredient to dish, dated. On the right, Change watch, following specifications and substitutions. A note at the bottom says the output has two lists, and there is no third list called safe.AWS ACCOUNTSupplier specswhat each ingredientdeclaresRecipesand substitutionsWhoever is askedby a customerDeclarationscontains, may contain,unknownRoll-upingredient to dish,datedChange watchspecs andsubstitutionsspecificationswhat is in whatdeclared andunknownThe output has two lists. There is no third list called 'safe'.
Fig 1. Three things outside the account, three pieces inside it. The output is deliberately two lists rather than a verdict.
  • Security & identity
  • Management
  • Analytics
  • Front-end & mobile
  • People

What this system is not

It is not a safety decision. Whether a particular dish is appropriate for a particular person depends on the severity of their allergy, on what else is being prepared on the same surfaces, on whether the fryer is shared, and on a hundred things that exist in a kitchen and not in a database.

What a data system can genuinely do is make sure that the declared information is accurate and current, that gaps in it are visible rather than silent, and that a change somewhere in the supply chain does not go unnoticed for a year. That is a narrower claim and it is a real one.

What runs (the inside)

  • Declarations. What each ingredient states, in three categories rather than two. Part 2.
  • The roll-up. Combining ingredient declarations into a dish-level statement with a date. Part 2.
  • Change watch. Supplier reformulations and kitchen substitutions, which are the two ways a dish changes without anybody deciding it should. Parts 3 and 5.

One change, end to end

One supplier specification change traced through to affected dishesA horizontal row of five boxes joined by arrows. New spec arrives, same product code. Compared: mustard added. Nine dishes affected, listed by name. Flagged, not fixed: a person reviews. Menu updated, with a date. A note says without the second box this change is invisible until somebody reacts to it.ONE SUPPLIER CHANGE, END TO ENDNew spec arrivessame product codeComparedmustard added9 dishes affectedlisted by nameFlagged, not fixeda person reviewsMenu updatedwith a dateWithout the second box this change is invisible until somebody reacts to it.
Fig 2. The same system as one line. The comparison in the second box is the entire mechanism, and it only works if specifications are stored rather than read once.
  • Machine learning
  • Management
  • Analytics
  • Front-end & mobile

In plain words

A supplier sends an updated specification for a stock base. The product code is the same and the delivery looks identical. The system compares the new declaration against the stored one and finds that mustard has been added to the formulation.

Nine dishes use that stock base. All nine are flagged, by name, with the ingredient that caused it and the date the specification changed. Nothing is automatically corrected: the menu, the allergen matrix and the staff briefing are all things a person updates, and the flag stays open until they do.

The important property is that this is an event. In most kitchens a reformulation produces no event at all — the specification arrives in an email, or does not arrive, and the dish quietly contains something it did not contain last month.

Design rules that shaped every decision

  • Three states per allergen per ingredient: contains, may contain, unknown. Never two.
  • Unknown is prominent. It is not absence and must never render as a blank.
  • Every specification is stored with its date, so a change can be detected.
  • The system flags; a person updates the menu and the briefing.
  • It never outputs a safety verdict for a person.
  • A substitution changes the dish and must be recorded before service.

Why this shape

Allergen management fails in two characteristic ways, and neither is a failure of intention. The first is that the information goes stale: a matrix produced accurately in March describes a menu that has changed by September. The second is that unknowns are rendered as absences, so a gap in the data looks exactly like a confirmed negative.

Both are addressable by a small system that stores declarations with dates, compares them when they change, and refuses to collapse three states into two. Neither requires sophistication and both are difficult to maintain by hand across a menu of any size.

The next four posts walk through each piece: how an ingredient declares what it contains, what happens when a supplier changes a recipe, why the system never says safe, and how a substitution gets caught. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts