# Barcode lookup behind an adapter

The repository's architectural decision, rationale and consequences.

# Barcode lookup behind an adapter

**Status:** accepted · **Date:** 2026-11-06 · **Related:** [ADR-0005](0005-effect-boundary.md), [ADR-0015](0015-household-data-lives-on-the-device.md)

**Enforcement:** contract tests that run against both the fake and the live adapter's recorded fixtures; a test that a learned-code row has no household column.

The kit is built by scanning barcodes. Product data comes from outside, and scanning must work in development and tests without a network.

## Decision [#decision]

1. **One adapter interface**, `lookup(ean) → product | not found`, with two implementations: Open Food Facts for production and a deterministic fake for development and tests.
2. **Open Food Facts data is ODbL.** The app shows the attribution ("Contains information from Open Food Facts, available under the ODbL") and share-alike obligations are met for any derived database we publish.
3. **Learned codes are anonymous.** When a household corrects or adds a product, the server stores the code, name and suggested area, with no household id, device id or timestamp finer than a day.
4. **The lookup sends only the code.** Nothing identifies the household; requests go through our API, not straight to a third party from the phone, so the user's IP does not reach it.

## Consequences [#consequences]

- Free tier limits scans to 30 a month; the adapter is called only when a scan misses the local cache.
- If Open Food Facts changes terms or is unavailable, the adapter is replaced without touching the kit.