Fibretrace Monet docs/Walkthroughs and notes/UX findings for Malcolm

UX & logic findings for Malcolm — Lovable dashboard walkthrough

Drafted 2026-07-17 from the full GUI walkthrough (gui-walkthrough/, 11 recorded journeys + a real E2E claim). This is the T75 deliverable. Each finding is triaged into who acts on it. Rendered/interactive view: gui-walkthrough/walkthrough-report.html (UX Findings + Q&A sections mirror this file).

Split of sources: RESOLVED business-logic questions (answered from source code, with citations) live in 2026-07-16-code-resolved-open-questions.md. This file carries the FINDINGS plus the questions still needing Malcolm. Walkthrough transcripts: 2026-07-08-malcolm-walkthrough-demo.md, 2026-07-09-walkthrough-2-linking-retirement-rules.md.

Triage key

  • Bug — confirmed defect, verified live in the GUI.
  • Fix in monet — our code (apiAdapter / RTK Query / UI); we own it.
  • Fix in Lovable — Lovable-generated (routing, layout); fix upstream so it flows down on the next sync — never patch it only in monet.
  • Verify — needs re-checking before we treat it as a bug.
  • Out of scope — admin / system surfaces not in the monet dashboard MVP (context only).
  • Ask Malcolm — a business-logic / design decision only Malcolm (or the team) can settle.

Findings (triaged)

# Triage Persona Route Finding Action Screenshot
1 Bug · Fix in Lovable Program Owner /owner → /owner/programme-uptake Owner “View details” navigates to a 404 — the link points at /owner/programme-uptake (typo); the registered route is /owner/program-uptake. Reproduced live. Fix upstream in Lovable (routing is Lovable-generated) so the correction flows down. gui-walkthrough/screenshots/po-02-programme-uptake-404-BUG.jpg
2 Out of scope System / Admin /admin, /admin/settings Admin console opens with no login gate; Global Settings shows “Authentication Login Bypass” ON — the root of the no-auth prototype behaviour. Out of monet scope (admin is FibreTrace-internal, Supabase-backed). Context only — do not port. gui-walkthrough/screenshots/admin-02-global-settings-auth-bypass.jpg
3 Verify Tier4 Producer / (producer Home) Producer Home tiles all read 0 (Volume produced / Verifications / Facilities / Operators) while Production Records shows 274 MT + 11 records for the same company (SUNDOWN). Re-verify whether Home is a “today” metric vs cumulative before calling it a bug; if a data-scope bug, fix in monet. gui-walkthrough/screenshots/t4-01-gin-home.jpg
4 Ask Malcolm Tier0 Brand /supply-chain Non-partner suppliers with scans DO appear, masked as “Non partner company” + city/country + “Invite partner”. Confirms the code source but CONTRADICTS Malcolm’s demo claim (“they don’t appear — I need to check the logic”). Ask Malcolm for the intended FINAL visibility rule. gui-walkthrough/screenshots/t0-02-supply-chain-tiers.jpg
5 Ask Malcolm Tier4 rPET /owner (from producer persona) rPET producer is a hybrid: producer sidebar but its Home resolves to the owner dashboard at /owner. Producer-nav vs owner-content mismatch. Confirm this is intended for a producer that also owns a programme. gui-walkthrough/screenshots/t4rpet-01-home-hybrid-owner.jpg
6 Ask Malcolm Tier0 Brand /claim-position A direct (non-PO) claim path is live for the brand: Claim Position → “Make a claim” retires capacity directly (PO optional, scan session required), nuancing the “PO is the only path” reading. Ask Malcolm which path is canonical (PO-driven vs direct capacity retirement). gui-walkthrough/screenshots/t0-06-claim-position-capacity-model.jpg
7 Fix in Lovable System (any, on persona switch) Switching persona does not reset the route — switched to rPET while on /owner and it kept /owner, briefly showing mismatched content. Minor, Lovable-owned UI. Low priority — flag to Lovable if it persists. —
8 Fix in monet Tier0 Brand / (brand Home) Brand Home briefly flashes a zeroed “No active programmes yet” layout before the rich dashboard loads. Cosmetic loading-state nit, NOT a data reset (data intact afterwards). Add a proper loading skeleton/guard in monet (or confirm Lovable handles it on sync). —

Open questions — need Malcolm / team / a design decision

  1. Is tier company-level or facility-level? Today it’s company-level (company_details.supply_chain_tier, self-declared). Malcolm: one company can be tier-1 to one partner and tier-2 to another (Sitex). Why open: Malcolm — “the model I’ve put in might transpire to be wrong”; no facility-level schema exists yet.
  2. What is the FINAL rule for non-partner suppliers with scans? Source shows they DO appear (masked); in the demo Malcolm said they DON’T. Why open: source and Malcolm’s stated intent contradict — “I do need to check the logic on this one.” (Same as finding #4.)
  3. Retirement scope edge cases (recursive mark-claimed, cross-platform double-claim marker)? Malcolm wants to recursively mark shared sessions claimed; Shannon wants a marker for which traceability solution used each piece of evidence. Why open: design not settled.
  4. Sub-tier certificate / connected-sub-tiers inheritance model? Shannon raised how certificates work for connected sub-tiers; Malcolm had not catered for it. Why open: still being reworked at demo time.
  5. Multiple-certificates-per-transaction data model? Conceptually a transaction can now carry N certificates, but the exact schema is undefined. Why open: flagged “more for Jamie”; the 1:N implication for BE is unresolved.
  6. Does verification-sharing fold into data connections? Legacy share-links predate Connections. Why open: Malcolm is “still figuring out whether sharing is part of a data connection or not” — his call, pending.
  7. Bale-ID tracking / serializing scan data? Currently buggy, to be fixed; Malcolm has improvement ideas. Why open: no committed data model yet.
  8. Admin / CMS scope for monet? Admin overrides programme logo/wording; currently OUT of dashboard MVP scope per feedback_dashboard_mvp. Why open: which admin functions belong in monet is undecided.
  9. Vu’s “updated APIs for Nghia to integrate” — what’s covered? Mentioned only as a standup action item. Why open: no list shared yet.
  10. Hardcoded apparel-only model — settled for the business, open for monet’s BE? Malcolm confirmed it’s deliberate: hard-coded to the tiered + PO model, “cannot be reused to trace other things.” Why open: whether monet’s backend mirrors this or builds in extensibility is unaddressed.

Resolved (for reference)

Full answers + code citations are in 2026-07-16-code-resolved-open-questions.md. One-line summary of what is settled:

  1. Non-partner suppliers appear masked (“Confidential supplier” + Invite CTA; city/country always shown). — useRetailerSupplyChain.ts / RetailerSupplyChain.tsx (§1.3-1.4)
  2. Chain-of-custody: inbound shipping_doc_id matched to the partner’s outbound with the same doc ID; tiers walked from there. — chainWalk.ts (§1.1-1.2)
  3. validate_po_verification() flips po_status to ready on link; apply_po_evidence_pack() tracks volume_mt/volume_claimed_mt and sets partially/fully claimed. — migration ...c3a12d9b... (§2.1-2.2)
  4. Claim without a PO: DB allows it (nullable purchase_order_id), but retailers no longer see those menus. — ...20260618105600... (§2.3)
  5. 3 DB pack_types (trade/sustainability/procurement) vs 8 UI packs; LEGACY_PACK_REDIRECTS maps trade→regulator; 5 catalogue packs unbacked. — evidencePacks.ts (§2.4)
  6. Public URL/QR is real (/c/:token → PublicClaim.tsx, QR via api.qrserver.com); webhook is a JSON-preview page pointing at a non-existent /api/v1. — WebhookPreview.tsx, useConnections.ts (§2.5)
  7. Only tier-1’s linked scans retire on confirm; sub-tier pairs never retire. — Malcolm, walkthrough-2
  8. A manufacturer may attach any scan at its own facility regardless of addressee — deliberate, not a bug. — Malcolm, walkthrough-2
  9. Tier-1 (manufacturer) sets the claim amount, not tier-0. — Malcolm, walkthrough-2
  10. Pre-claim rejection lets tier-1 re-pick scans; after the retailer confirms, links are locked (must cancel to unlink). — Malcolm, walkthrough-2
  11. Claim creation is checked against reservations by validate_production_claim_limits(). — §2.3 / Malcolm walkthrough-1
  12. Programme-details CRUD “bug” is a deliberate split (owner edits logo + program-items; core fields admin-only). — OwnerProgramRecord.tsx / AdminProgrammes.tsx (§3)
  13. Attached certificates flow onto evidence packs (tier-1 at link time; owner certs/wording too) — exact multi-cert model still open (see open Q4-Q5). — Malcolm, walkthrough-1