FibreTrace in one page

Confidence markers: VERIFIED proven in code or a migration, with citation. STATED asserted by Malcolm, the QC script or a document, not confirmed in code. INFERRED reasoning from surrounding evidence. UNKNOWN undetermined, listed in 06-open-questions.md. Citation shorthand: L: = Lovable clone at origin/main (ffab85ca, 2026-08-19), M: = apps/dashboard, SQL: = apps/dashboard/supabase/migrations/, QC: = .local/qc-test-script/extracted.txt line, BL: = .local/business-logic/.

What FibreTrace sells

FibreTrace sells physical traceability: a luminescent tracer pigment that is mixed into raw fibre at the start of the supply chain, handheld Bluetooth scanners (and in-line SDU units) that detect that pigment in later products, and a SaaS platform that turns those detections into auditable, shareable claims about fibre origin and volume. STATED (BL:2026-07-08-malcolm-walkthrough-demo.md; the scanner/pigment mechanics are VERIFIED in the SAT app: apps/sat/src/features/scanner/services/fibreReader.ts:1-4 defines the BLE SCAN_COMMAND and tau response parsing).

The problem it solves: a brand claiming “this product contains X tonnes of traced cotton from programme Y” normally cannot prove it. Regulators (customs, forced-labour and greenwashing enforcement) and buyers increasingly demand evidence. FibreTrace’s answer is a mass-balance model: it proves the movement of marked fibre through facilities and meters claimed volumes against physically scanned volumes, rather than pretending to track an individual bale into an individual t-shirt. Malcolm: “it’s impossible to say this bale ended up in this t-shirt… We’re proving the MOVEMENT of fibre… it’s more of a mass balance concept”. STATED (BL:2026-07-08-malcolm-walkthrough-demo.md:76).

The physical chain and its digital shadow

Physically: pigment is applied at the gin (the entry point — FibreTrace deliberately does not start at the farm), the marked fibre is baled, spun, woven, dyed, cut and sewn, and every shipment between facilities is scanned outbound at the sender and inbound at the receiver. STATED (BL:demo:32-33,72-75). Digitally, each of those physical events has a record:

The tier model

Tiers count backwards from the shelf: Tier 0 is the retailer/brand, Tier 1 the final manufacturer (cut-make-trim), Tier 2 fabrics and components, Tier 3 material processing (spinning), Tier 4 the raw fibre producer (gin); Tier 5 would be the farm and is out of scope. STATED (BL:demo:32-35). The platform’s running example: Sundown Gin (Tier 4, Australia) to ACME Spinning (Tier 3) to ACME Fabrics (Tier 2) to ACME Apparel (Tier 1, Vietnam) to Target (Tier 0, US). STATED (BL:flow-explained.md:33). A company’s tier is self-declared in Settings (company_details.supply_chain_tier, free text), not derived — Malcolm himself flagged that company-level tiering may prove wrong for vertically integrated suppliers. STATED (BL:wt2:43-44). Note the signup wizard’s tier labels drift from these definitions (“Tier 3 — Fibre producer”, “Tier 4 — Raw material”) VERIFIED (L:src/lib/signup.ts:5-19); see 06-open-questions.md.

Crucially, tier is cosmetic; behaviour comes from data-derived personas. A company is a Fibre Producer because it has a programme_producers registration, a Manufacturer because it has incoming shared nominations, a Retailer because its company type is brand/retailer and it participates in a programme. VERIFIED (L:src/hooks/usePersonaContext.ts:36-41). The QC script’s rule 3 canonises exactly this (“A company is a Fibre Producer only if registered as a producer on a programme”) STATED (QC:8), which retires the older hook that also counted an SDU module as producer VERIFIED (L:src/hooks/usePersona.ts:34).

How the money-shaped objects connect

A fibre programme is the commercial container: a fibre type, a pigment, registered producer companies each with a production ceiling, participant brands, one owner company, and optional certificates/documents. VERIFIED (L:src/pages/admin/AdminProgrammes.tsx:103-114,264-272). Producers’ scanned production raises the programme’s Activated volume; FT Admin grants brands capacity reservations (defaulting to an 18-month expiry, negative release entries allowed); brands raise nominations against manufacturers; manufacturers link scans and propose claims; brands confirm, consuming reservation and producing evidence. The intended reconciliation invariant is reserved >= nominated >= claimed. STATED (QC:11 — a new first-class statement; the code enforces parts of it, see 04-rules-and-invariants.md rule R-20).

Units: 1 Claim Unit (CU) = 1 kg, 1000 CU = 1 MT. CU for a product line = quantity x net weight x blend % x an internal loss multiplier, with blend defaults coming from admin-configured product categories, never hard-coded. VERIFIED (L:src/lib/claimUnits.ts:1-11, L:src/pages/admin/AdminProductCategories.tsx:144). Note the QC script states the formula without the loss multiplier STATED (QC:6) — a real discrepancy, see 06-open-questions.md.

The three codebases and one backend

The Lovable app (fibre-trace-studio, live, Supabase-backed) is the design and behaviour source of truth for the MVP and is what the QC script tests — 30 of its 31 routes exist there. VERIFIED (.local/qc-test-script/analysis.md route census). apps/dashboard in monet is the production port: same UI, but every Supabase read is routed through a fake client (M:src/lib/apiAdapter.ts) to the real Fibretrace Laravel REST API; only 12 of 50 registered tables have real mappers, all writes through the shim throw MutationNotImplementedError. VERIFIED (M:src/lib/apiAdapter.ts:109-128,835-858). The real backend today covers identity, team, partners, facilities, scanners and a newly deployed but partial fibre-programs/claim-positions/claims namespace — and has no purchase-order, evidence-pack, product-category or obfuscation concept at all. VERIFIED (.local/backend-specs/fibre-program/README.md:52-76; sync-20260819 API resolution: EXISTS=0 across the window). apps/sat is the field scanning PWA where physical verifications originate. The Lovable Supabase database is a demo/spec scratchpad, never the production backend. STATED (memory: project_lovable_backend_role).

The practical consequence: everything in this knowledge base about programmes, reservations, nominations, claims and evidence describes behaviour that is real in the Lovable MVP and specified for the future backend, but is an empty shell in monet today. 05-implementation-state.md carries the exact matrix.