FibreTrace Business-Logic Knowledge Base
A from-scratch re-derivation of the FibreTrace business logic against everything this repo knows as of 2026-08-19, reconciling the QC Test Script v1.0, today’s Lovable sync, the July walkthrough corpus, the backend specs, ~195 memory records and — as ground truth — the code itself: the Lovable clone at origin/main (ffab85ca), apps/dashboard, the Supabase migrations, .local/frontend-canvas/repo/ and apps/sat. Every existing document was treated as a prior to be re-verified, not as truth; where sources disagree, both sides are recorded and the residue is an open question.
How it was derived
Nine parallel read-only research passes (Supabase schema catalog; Lovable routes/personas; claim lifecycle; capacity/CU/obfuscation rules; canvas REST contract; SAT scan origination; the July business-logic docs; the backend-specs directory; the persona matrix + memory corpus) were synthesised by one session, which resolved conflicts by preferring code at Lovable origin/main, then migrations, then the newest documents, and marked everything else down. The Lovable clone was read exclusively via git show/git grep at origin/main (its working tree is thousands of commits stale) and was never modified.
Confidence-marker legend
| Marker | Meaning |
|---|---|
| VERIFIED | Proven in code or a migration, with a path (and line where possible) |
| STATED | Asserted by Malcolm, the QC script or another document, not yet confirmed in code; the document is cited |
| INFERRED | Reasoning from surrounding evidence; the basis is named |
| UNKNOWN | Genuinely undetermined; listed in 06-open-questions.md rather than guessed |
Citation shorthand used throughout: L: = Lovable clone at origin/main (ffab85ca, 2026-08-19); M: = apps/dashboard; SQL: = Supabase migrations (monet snapshot, or origin/main where noted); QC: = .local/qc-test-script/extracted.txt line; BL: = .local/business-logic/ (demo = 2026-07-08 walkthrough, wt2 = 2026-07-09 walkthrough 2, resolved = 2026-07-16 code-resolved answers); memory = ~/.claude/memory/fibretrace/.
Files
| File | Covers |
|---|---|
00-overview.md |
The whole business in one page: what FibreTrace sells, mass balance, the physical chain and its digital shadow, the tier model, the three codebases |
01-domain-model.md |
Every entity, its fields, relationships and cardinalities, with an inline ERD and a GREEN/AMBER/RED real-backend backing status per entity |
02-lifecycles.md |
The state machines with SVGs: reservation ledger (18-month expiry, negative releases), reserved >= nominated >= claimed, the po_status machine, claim proposal/confirm/revoke/void, scan masking and retirement, certificates and evidence packs |
03-glossary.md |
Every term a newcomer trips on, plus the eight terminology collisions (CU label, PO vs Nomination, Verification Records vs Scan History, programme vs program, Claim vs Activate, audit vs session, Orders vs POs, tier label drift) with which label the newest source uses and whether it is settled |
04-rules-and-invariants.md |
45 rules: the six QC-stated rules tested against the code, then everything the migrations, components, canvas and walkthroughs encode |
persona-00-map.md |
The persona map SVG: who owns what, every handoff, who blocks whom |
persona-01-ft-admin.md … persona-05-tier0-retailer-brand.md |
One detailed file per QC persona: identity, goals, every screen, CRUD and gates, binding rules, dependencies, empty states, failure modes, implementation state |
persona-06-additional-roles.md |
The roles the QC script omits: auditor, the neutral Tier 2/3 “scanner” persona, the public verifier, the team-role axis, demo personas |
05-implementation-state.md |
The Lovable / monet / real-backend matrix per domain area — what is demonstrable today versus aspirational |
06-open-questions.md |
20 ranked open questions with evidence on each side and who can answer, plus quick code checks anyone can run |
portal.html |
Self-contained offline explorable portal over all of the above (open from file://, no network needed) |
Each markdown file also has a standalone rendered .html next to it (same basename). To regenerate after editing any .md: render it with ~/.claude/skills/nf-md2html/scripts/md2html <file>.md, then rebuild the portal with bun build-portal.mjs — the portal is assembled from the rendered files, so it can never diverge from the markdown.
Status of this knowledge base
Snapshot of 2026-08-19. The Lovable app changes daily (781 commits in the last 2.5-day sync window); treat the VERIFIED Lovable citations as verified at ffab85ca specifically. The fastest way to re-verify any claim: git -C .local/lovable-source show origin/main:<path> after a fresh fetch. When the claim-model conflict (open question Q1) is ruled on, 02-lifecycles.md, 04-rules-and-invariants.md and 05-implementation-state.md are the files to revisit first.