FibreTrace business logic

The product as it runs on BETA FibreTrace, the Lovable project where Malcolm and the team now make every Dashboard and business-logic change. Read from BETA’s code and live database on 2026-09-22 (commit 39ae45a9) and re-checked on 2026-09-23. BETA holds no business data yet, so every behaviour below is read from code and database rules, not watched running. Product terms are written as the screens show them, including the spelling “program”; the database tables still say “programme”. The Vietnamese version follows this one.

1. What FibreTrace proves

FibreTrace sells physical traceability. A luminescent tracer pigment is mixed into raw fibre at the gin. Handheld Bluetooth scanners, plus in-line SDU units at the gin, detect that pigment further down the supply chain. The platform turns those scans into claims about fibre origin and volume that can be audited and shared.

It is mass balance, not item-level trace. The platform proves that marked fibre moved through facilities, and it meters claimed volume against scanned and produced volume. It never says “this bale became this t-shirt”.

2. Tiers and personas

Tiers count back from the shop shelf:

A company declares its own tier in Settings, and the tier is only a label. What a company can do comes from its data, never from its tier:

• Fibre producer: registered as a producer on a fibre program.
• Manufacturer: has at least one purchase order sent to it. “Link Purchase Orders” appears in its menu only after the first PO arrives.
• Retailer / brand: company type is brand or retailer, it participates in a program, and it is not a producer.
• Program owner: owns a program. Its Home page is the owner dashboard.
• Tier 2/3 companies: scan inbound and outbound shipments to build the chain of custody, and never claim.
• Auditor: a scan-only field role. Auditors sign in to the FibreTrace Scanning App, not the Dashboard.
• FibreTrace admin: platform staff. They create programs, register producers and participants, grant reservations, configure product categories, issue licences and scanners, and approve sign-ups.

3. Vocabulary

Use these words. They are the terms BETA’s own screens use.

4. How Claim Units are calculated

For each PO line, CU per piece = effective net weight (kg) x blend % x an internal loss multiplier, and the line’s CU = CU per piece x quantity. Blend percentages come from product categories that FibreTrace admin configures; they are never hard-coded. Category values prefill each line. A line that deviates from its category is flagged and reported on the admin overrides page. CU and MT are kept in step by the database (CU = MT x 1000) on purchase orders, claims and reservations. A PO’s total CU is the sum of its non-excluded lines, recalculated on every line change.

5. Program capacity

Rules on the production side:

• Production counts only after approval, on screen. Every screen adds manually logged production to program volume only after FibreTrace admin approves it; drafts, submitted, pending, rejected and cancelled records never count there. The ceiling check inside the database ignores approval status, so unapproved production still counts there (see section 12).
• The ceiling is a warning when admin approves, not a block. Admin sees an “Over ceiling” warning and may continue, because the real limit is how much pigment was physically added to the fibre, which is controlled outside the system.
• A producer’s produced volume is capped at its ceiling.
• Scans required per production record: 1 when the data comes from an SDU or an EWR import. For manual records: 5% of the quantity, rounded up, with a minimum of 1.
• Records lock about 30 days after creation.
• One pigment per facility per time window. A facility cannot serve two active programs that use the same pigment in overlapping date windows.

Both the capacity figures on screen and the database ceiling count only claims that are neither proposed, rejected nor revoked. Proposed claims do not use up capacity until the brand confirms them.

6. The flow: from purchase order to Fibre Verification Record

brand creates PO ──► shared ──► manufacturer links scans ──► linked
                                                              │
                              manufacturer proposes a claim ──► proposed
                                                              │
                 brand confirms ──► partially_claimed ⟲ ──► fully_claimed ──► closed
                 brand rejects  ──► links removed, back to shared

1. The brand creates a PO for one Tier 1 partner. It starts as shared; the draft step is never used. PO references are unique per brand and partner while the PO is not archived. POs go only to partners, and one PO never spans two manufacturers.
2. The manufacturer links scans to the PO. A scan can be linked when its facility belongs to the manufacturer or when it was shared with them. A scan the manufacturer owns can be linked even if it was addressed to someone else (the sub-tier import case).
3. The manufacturer proposes a claim and states the amount, because only the manufacturer knows the actual production figures. The one limit at this step is the PO’s remaining balance. BETA shows the program balance for reference only and no longer blocks on it.
4. The brand confirms or rejects. All reservation and program ceilings are checked here, by the database.
5. Confirmation creates the Fibre Verification Record. It also records the claimed volume on the PO, commits the line quantities, moves the PO to partially_claimed or fully_claimed, creates public share links for the record (switched on by default), and locks the linked scans and reveals their hidden verification IDs. The database does not cap the claimed volume at what is left on the PO: a larger claim raises the PO’s volume to fit. The only cap is the propose screen.
6. Partial claims repeat until every line is complete. One PO can carry several claims, each with its own evidence.

Rules that govern the flow:

• A scan belongs to at most one PO, ever.
• A scan can only evidence a PO on the same fibre program. A pigment from one program cannot back a claim on another.
• Evidence is single-use across all claims, whichever company created the claim. A claim uses only its own linked scans and never inherits another claim’s scans.
• A claim cannot be proposed with zero linked scans.
• Linking is blocked only once a PO is closed. A fully_claimed PO can still take links.
• A claim belongs to the brand. The claim’s company is the company that issued the PO, because the reservation the claim consumes belongs to the brand.
• After confirmation, neither side can edit. A rejection stores its reason, removes the PO’s scan links and sends the PO back to shared, so the manufacturer can pick scans again. In practice the rejected claim’s own scans stay blocked (see section 12).
• Retirement is tier-scoped. Only the Tier 1’s linked scans are retired (marked as used) on confirmation. Sub-tier scans never retire and never appear on the claim.
• Admin revoke and admin void differ. Revoke invalidates the claim and certificate and keeps the scans linked; the admin screen says it returns no Claim Units, but the capacity checks stop counting a revoked claim (see section 12). Void deletes the claim, its evidence and its bindings, and frees the CU and the scans.
• Bulk approval: unchanged proposals are selected automatically, and rows with a variance must be selected by hand. If a group goes over capacity, “Deselect to fit” drops the smallest items first. Confirms run one PO at a time, with no rollback across the batch.
• Scans link to a PO automatically when a new scan session’s free-text PO reference matches exactly one open, not fully claimed PO of that facility’s company. This happens in the database, with no screen involved.

7. Sharing, exclusivity and hidden verification IDs

• Every share must declare exclusivity. When sharing, the user must answer “Is this scan exclusive?”: “Yes — exclusive to one partner” or “Non-exclusive — also supplied to others”. Exclusive means exactly one recipient: once a scan has an exclusive share, the partner picker closes.
• Evidence requests ask the same question. A supplier answering an evidence request (a request for scans, under “Requests”) now chooses exclusive or non-exclusive, and non-exclusive is preselected. This is new on BETA.
• When a verification ID is shown: verification and blockchain IDs are hidden by default. They are revealed only when the scan is linked to a claim and no non-exclusive share exists on it. One non-exclusive share keeps the ID hidden for everyone downstream. The help centre describes this hidden state as hard to undo; in code, however, deleting the non-exclusive share resets it.
• Unsharing is meant to cascade. Malcolm’s rule: removing a share also removes that scan from whatever the recipient built on it (claim bindings and PO links). In practice, unsharing detaches the scan only from records the receiving company owns; because the brand owns claims and POs, the usual case is missed (see section 12). Ending a partnership leaves existing shares in place.
• Supply Chain map: it shows only companies on the brand’s shipment path, joined by the shipment references on the scans. Partners show with name and location. A company on the path that is not yet a partner shows as “Identity hidden for commercial confidentiality”, with an invite option.
• Public access: the public sees a claim only through an enabled public link. A revoked claim shows a Revoked banner. What the product calls a “webhook” is a JSON page that the receiving side fetches; the platform never pushes data out.

8. Sign-in, roles and access (new on BETA)

• Real sign-in. The old MVP had none: it picked a user from the browser, with a default account. BETA uses Supabase Auth with real sessions.
• Staff sign in at /admin through their own gate, which has hashed passwords, a country lock (currently GB and VN) and rate limiting. A successful staff sign-in also creates a normal account session and a platform-admin role.
• Two role systems exist side by side. Customer accounts use the company role (admin, auditor, pending). Staff and the new server-side access rules use a separate role table (platform_admin, company_admin, member). The two do not overlap and nothing reconciles them yet.
• Scanner sign-in: BETA’s scanner sign-in service (sat-auth) admits only customer accounts whose company role is admin or auditor and that are not blocked or deleted. It checks the company role only, so staff accounts are refused.
• Data access today: anonymous access is closed. The planned per-company isolation has not reached the commercial core yet. Purchase orders, claims and scan sessions are open to any signed-in user, which the database’s own migration describes as a deliberate interim floor. Because BETA holds no customer data, this is a design question about what ships, not a live exposure.
• Pigment IDs are readable by everyone, which the Scanning App depends on. Only staff can change them.

9. Email notifications (new on BETA)

10. What BETA changed compared with the old MVP

Every database function that carries business logic is identical to the MVP’s, and so is almost all of the frontend logic. The complete list of rule changes:

1. The manufacturer’s propose step is capped only by the PO balance; the program-balance cap was removed.
2. Six email notifications were added; two of them cannot be turned off.
3. Evidence requests gained the exclusivity choice, with non-exclusive preselected.
4. Real sign-in replaced the demo login, and each persona now uses its own company.

Product wording moved into the admin CMS (/admin/cms), so changing wording is now an admin action, not a code change. Vietnamese did not carry over: BETA has 330 Vietnamese strings, mostly on admin screens.

11. Still open

• Which claim model is canonical. BETA runs the two-step propose/confirm flow; the Fibretrace backend API offers only a single-step claim.
• Per-company data isolation for POs, claims and sessions: still planned, or dropped?
• Which role system is authoritative for customer accounts and for the Scanning App.
• Whether non-exclusive should be the default on evidence requests, and whether the screen should warn that it keeps IDs hidden.
• Is reservation a hard limit? Malcolm argues it is a finite physical quantity. The current concept lets a PO go above reservation as a signal to buy more.
• Tier labels. The sign-up wizard’s tier names (“Tier 3 — Fibre producer”) differ from the definitions above.

12. Gaps an operator should know

Found by reading BETA’s code on 2026-09-23 from a business operator’s point of view. Full evidence: operator-review-20260923.m3max.md. None has been seen happening, because BETA holds no data yet.

• Rejecting a claim blocks its scans for good. The rejected claim keeps its scan bindings, and the propose check refuses any scan that has ever been bound to a claim. The manufacturer cannot re-propose with the same scans, which is the opposite of what rejection is for.
• Rejecting one proposal strips the whole PO. It removes every scan link on the PO and sets it back to shared, even when the PO already carries a confirmed claim.
• Revoke frees capacity even though the screen says it does not. A revoked claim stops counting against the brand’s reservation and the program’s produced volume, so the same capacity can back a new claim.
• The database counts unapproved production. The screens count production only after admin approval, but the claim ceiling in the database counts every production record that is not excluded, whatever its approval status, and additionally counts the producers’ scanned volume.
• Confirming is not all-or-nothing. It is several separate steps. A failure part-way can leave a claim confirmed and the PO advanced without the rest.
• Unsharing detaches the scan from the wrong records. It looks for claims and POs owned by the share recipient, but claims and POs are owned by the brand. A scan unshared from a manufacturer stays in the brand’s claim; a scan unshared from a brand is removed even from confirmed claims.
• Confirmed records are public immediately. Public links are switched on for every confirmed claim; the brand has to turn them off.
• Most flow rules live only in the screens. With data access open to any signed-in user, only the database rules hold against a direct API call: the confirm-time ceilings, one PO per scan, no claim without scans, no linking to a closed PO, CU always equal to MT x 1000, and reservations within the program ceiling. The propose cap, same-program linking, single-use evidence, single-recipient exclusivity and the reject/revoke/void steps are screen-only.