docs

Architecture

How the pieces fit together.

System overview

┌─────────────────────────────┐        ┌─────────────────────────────┐
│         iOS app              │        │          Web apps            │
│  SwiftUI · SwiftData          │        │  Next.js · Turborepo (bun)   │
│  On-device OCR (Vision)       │        │  apps/web (marketing)        │
│  Keychain-held device token   │        │  apps/docs (this site)       │
└───────────────┬───────────────┘        └───────────────────────────────┘
                │ HTTPS, Authorization: Bearer <device token>
                ▼
┌───────────────────────────────────────────────────────────────────┐
│                     Rust backend (Axum + Tokio)                    │
│  routes/ → handlers/ → services/ → models/ · auth.rs · middleware/ │
└──────────┬───────────────────┬───────────────────┬─────────────────┘
           │                   │                   │
           ▼                   ▼                   ▼
     ┌───────────┐       ┌───────────┐       ┌─────────────────┐
     │  Postgres  │       │   Redis    │       │  Open Food Facts │
     │  products, │       │  rate      │       │  (barcode lookup  │
     │  users,    │       │  limits +  │       │  fallback, search  │
     │  verifica- │       │  cache     │       │  top-up)           │
     │  tions,    │       │            │       │                     │
     │  ocr_subs  │       │            │       │                     │
     └───────────┘       └───────────┘       └─────────────────────┘

No image storage, no third-party OCR service. Product images are Open Food Facts' own CDN URLs (image_url is a link, nothing is re-hosted). Label OCR runs on-device in the iOS app (Apple's Vision framework, live multi-frame), not through a cloud vision API — the backend only ever receives the text the client already extracted, plus what the user confirmed after reviewing it. See OCR submission for how the backend cross-checks that against the original text.

Request flow: scanning a known product

Request flow: a product nobody's added yet

Design decisions worth knowing

DecisionWhy
Device tokens, not accountsNo account is required to use the app. A device registers once (POST /api/v1/auth/device), gets a bearer token, and that's the identity for everything — verifications, contributions, profile, Plus. Sign in with Apple is additive, not required. See Authentication.
On-device OCRApple's Vision framework runs locally on the phone — no photo or cloud OCR request leaves the device until the user chooses to submit the reviewed text. Cheaper, faster, and it means the backend never handles raw label photos.
Postgres as the source of truth, not a cache of Open Food FactsA product fetched from Open Food Facts is written to Postgres and served locally from then on; a periodic refresh (on read, if the local copy is 30+ days stale) keeps OFF-sourced fields in step, but verified, verification_count, and lookup_count are always ours and never overwritten by a refresh.
Fail-open rate limitingIf Redis is unreachable, requests are allowed through rather than the API going down — the limiter exists to blunt abuse, not to be a single point of failure.
TrueLabel Plus is free right nowThe users table and /me/subscription endpoints are shaped so a real payment step (App Store Server API, receipt verification) can be added later without changing the response contract — see Plus / Subscription.

On this page