Skip to main content

Barcode Matching

Applies to: v3 (Turso)
Purpose
Resolve barcode → company; persist barcode meta
Inputs
barcode, device_id (JWT)
Outputs
company id + isBoycott flag
Tables
barcodes
tip

For the end‑to‑end request/response, start with Flows → Scan Barcode.

Versioning Context​

This document explains how a barcode scanned by the Flutter app is processed and matched to a boycott (or alternative) company.

  • v3 implements barcode storage and matching in Turso (tables under src/lib/dbs/schema/schema.ts).
  • Legacy tables like upc_barcode and whitelist data are used as migration sources.

Summary​

  • Entry point: user scan route receives a numeric barcode.
  • Normalization/validation: barcode is cleaned to digits and validated (EAN-13/8, UPC-A/E logic).
  • Lookup tiers:
    1. Whitelist barcode lookup (barcode → whitelist → company name match).
    2. External enrichment (Go-UPC, Open Food Facts) persisted to barcodes table.
  • On match: return { id, isBoycott }.

Entry Point (Scan)​

  • Route: GET /v3/users/:device_id/scan/:barcode
    • Validates the barcode via ScanParams (numeric string, min 4 digits).
    • Calls lookupBarcode(barcode) which queries the whitelist tables.
    • Schedules cacheBarcodeFromProviders to enrich from external sources asynchronously.
    • Files:
      • src/routes/users.ts
      • src/schemas/user.schema.ts
      • src/services/barcode.service.ts

Normalization & Validation​

  • Non-digit characters are stripped before any lookup.
  • Supported barcodes and check digits:
    • EAN-13 and EAN-8
    • UPC-A (12 digits)
    • UPC-E (6 or 8 digits) via expansion to UPC-A
  • Unsupported lengths throw an error during validation.
  • File: src/utils/barcode.ts

Primary Lookup​

  • Whitelist-based lookup via whitelist_barcodes + whitelists tables.
    • Finds barcode in whitelist_barcodes, joins to whitelists for parentCompanyName.
    • Matches parentCompanyName against boycott_companies or alternative_companies.
    • Returns { id: number, isBoycott: boolean }.
  • External providers (Go-UPC, Open Food Facts) run asynchronously via cacheBarcodeFromProviders.
    • Results cached in single barcodes table for future lookups.
  • File: src/services/barcode.service.ts (lookupBarcode, cacheBarcodeFromProviders)

External Enrichment (Async)​

  • After initial lookup, cacheBarcodeFromProviders(barcode, env) runs asynchronously.
  • Queries configured providers (Go-UPC, Open Food Facts) for product/brand data.
  • On hit, caches result in the unified barcodes table with productName, brandName.
  • File: src/services/barcode.service.ts (cacheBarcodeFromProviders, resolveBarcode)

Open Tasks (WIP)​

  • Add Elasticsearch-based enrichment fallback for unmatched barcodes.
  • Implement user reward point adjustment on successful scan.

Code references​

Last updated on