A verdict before she puts the bottle down

Scan, then answer. The rules that shape the product are written down as fourteen numbered lines in the repo’s CLAUDE.md, and the ones about verdicts, uncertainty and money are the reason the app looks the way it does. A rule that only lives in someone’s head gets relitigated every time a screen is built.

A plum-charcoal ink on a pale mauve ground, one fuchsia accent, Gabarito for display and Hanken Grotesk for text, both self-hosted. Verdict colour is deliberately separate from the accent — clear is a deep teal, skip a slate-indigo rather than a red, because “not for your curls” is not an error — and it is never the only signal: always a colour, an icon and a word. Every colour is defined in the base :root block first, so nothing can exist in one theme and vanish in the other.

Barcodes are read from a live stream — she points the phone and the answer arrives, with no shutter button in between. The label path keeps a plain file input instead, because the phone’s own camera app focuses on six-point print far better than a video preview does. The reticle is short and wide for a barcode, tall for a paragraph, and the stream is torn down whenever the tab goes to the background.

OCR takes a few seconds, so the wait is narrated with the real steps and a live count of ingredients found — and it shows the cleaned list forming, never the raw OCR string with its typos in it. Three failures are told apart and worded differently: a partial read, no text at all, and Vision being down. Only the second one gets a framing hint, because that is the only place a hint is actionable.

No confidence badges, no warning icons, no wavy underlines. How sure the matcher is about one word is a database concern, and dressing the list in yellow triangles would make a correct verdict look unreliable. One sentence covers all of it: computers misread small print — change anything that’s wrong. The single exception is a word we couldn’t read whose two candidates disagree about the verdict; then, and only then, she is asked to pick between them.

On the optional list screen she sees resolved names — if OCR read “Cetearyl Alcohoi” and the matcher landed on cetearyl alcohol, that is what shows. Rows can be corrected, deleted, or inserted, and an insert has to say where: label order is roughly concentration, so a sulfate the photo missed is a different bottle at #2 than at #22. Appending everything would have broken the one thing that screen is claiming to show.

A read that catches fewer than ten ingredients gets no verdict and offers to let her type the list instead. That path publishes from five, not ten — she is reading the bottle rather than a camera guessing at it — and from there it is the photo path exactly: same matcher, same verdict function, same page at the end.

Normalisation and lookup are Postgres functions — normalize_ingredient and match_ingredient — rather than TypeScript. The app, the Open Beauty Facts backfill script and any query typed by hand then apply exactly the same rules, which is the only way the numbers agree. What is left in the app is the one thing that genuinely isn’t a matching problem: deciding where one ingredient ends and the next begins.

• scans — one row per read, append-only, with the verdict it produced
• scan_ingredients — the raw token, the resolved name, the position, how it matched
• ingredients — the judgement dictionary: the flagged groups and their aliases
• products — barcode, brand, name, type, and the stored list with the date it was last confirmed

Exact match first, then a recorded alias, then the two cheap repairs that cover most of what OCR does to a label: the same letters with the spacing moved (DIMETH ICONE), and the glyphs a camera confuses — l/i, 0/o, 1/l, 5/s (DIMETHIC0NE). Trigram similarity is the last resort, at a threshold of 0.62. Each tier scores below the one above it, so a real alias always wins over a repaired guess.

compute_verdict in Postgres decides Clear or Skip, and nothing in the app is allowed a second opinion. There is one display-only mirror of the rule in TypeScript — it labels the two candidates on the pick card with what each would mean — and it is commented as a mirror so the next person knows it has to move when the SQL does.

An edit doesn’t update a scan, it forks one. The pair that leaves behind — what the machine read, what a person corrected — is the training data for the alias dictionary, and it is how a misread that happens on a thousand bottles gets fixed once. She never sees any of that; she sees her corrected list and a recomputed verdict.

The barcode lookup works on day one because tens of thousands of rows were imported from Open Beauty Facts — crowdsourced, ODbL, and only as current as whenever somebody last looked. Every one is written as a seed row, and product_confidence() reports it as seed_only, which means no verdict pill at all: we have a list, nobody has checked it, read the label. Confidence is asked for before anything renders, and a failed lookup counts as no.

After a label scan the app can ask 36 of 37 ingredients identical — is this Smooth Shine Shampoo? Each product’s list is stored pre-normalised and kept in step by a trigger, so the comparison is one pass rather than 60,000 normalisations per scan. Scoring is symmetric — matched over the longer of the two lists — so a product doesn’t win by having a longer list, and a reformulated bottle drops out rather than being named wrongly.

Barcodes are decoded on the device, so the cheap path is also the free one; Vision is only called when there is a label to read, and the photo is downscaled to 2048px on the phone first, which is most of the wait on a mobile connection. Writes hash the IP with a salt before anything is stored, rate-limit against that hash, and the hard ceiling is a daily quota cap set on the Vision API itself — the in-process limiter is a speed bump, and is commented as one.