FibreTrace · Scanning App guide

FibreTrace Scanning App (SAT): features and business logic

LSAT commit 9331d8e3 · updated 2026-09-24 17:18

The FibreTrace Scanning App, also called the Simple Audit Tool (SAT), as Malcolm builds it in the Lovable project SAT Beta FibreTrace Simple Audit Tool (LSAT). Read from LSAT’s code at commit 9331d8e3 on 2026-09-24, together with the BETA FibreTrace functions it calls (sat-auth, sat-config, sat-scans) and Malcolm’s own rulings in the LSAT chat. Behaviour is read from code; only the scanner firmware notes come from real devices, through the logs Malcolm pasted. Our production app apps/sat is ported from LSAT; section 11 lists where it deliberately differs. The Vietnamese version follows this one.

1. What the app is for

SAT does one job: an auditor standing at a facility scans material with a handheld FibreTrace scanner and records the result as a verification. The scanner reads the tracer pigment’s signature; the app checks it against the fibre program the auditor chose and records only the scans that match.

2. Who can use it

Rule Detail
Who may sign in A FibreTrace account whose company role is admin or auditor, and that is neither blocked nor deleted. Everyone else is refused with “This account can’t use the scanning tool, or it isn’t active.”
How Email and password, checked by BETA’s sat-auth. After a password sign-in the phone can offer face or fingerprint unlock for next time; the saved session is then released only after the device’s own unlock.
Session Kept on the device and refreshed silently. A revoked account loses its session on the next check.
Forgot password Points the user to the FibreTrace site. SAT has no password reset of its own.
No scanner “Don’t have a scanner?” tells the user to contact FibreTrace.

The same access rule guards every BETA call SAT makes, not only sign-in.

3. What the app loads after sign-in

One configuration download from BETA (sat-config /bootstrap) drives every screen. It is cached on the phone and re-downloaded only when its version changes, or when the user taps Reload data in Settings. If it cannot be loaded, home says so and no verification can start.

Item What SAT gets
Company Name and tier (Tier 0 to Tier 4). A company that produces fibre on a program counts as a producer.
Facilities The company’s active facilities, with coordinates when captured.
Scanners The active scanners assigned to each facility, with serial, model and Bluetooth settings. A facility with no scanner cannot be scanned at.
Partners Accepted partner companies, each with its tier and the private reference name the company gave it (for example “Customer”).
Fibre programs Active programs the company takes part in, each with its pigment: TAU value and tolerance, INT value and tolerance (independent since 2026-09-24). A program with no pigment is left out.
Product types The live list from BETA’s System Configuration: label, icon and order (Raw fibre, Yarn, Fabric, Finished product).
Geofence The maximum distance a scan should be from its facility, 5 km by default.

4. Vocabulary

Term Meaning
Verification One scanning session at one facility: a direction, a partner, shipping details, a product type, a program and one or more recorded scans. BETA stores it as a session.
Scan / reading One result from the scanner: TAU and INT values plus the scanner’s serial.
Recorded scan A reading whose signature matches the chosen program. Only these are saved.
Direction Inbound: material arriving at the facility. Outbound: material leaving it.
Partner The sender on an inbound verification, the recipient on an outbound one.
Shipping document ID Waybill, AWB or bill of lading number. On inbound it is what links the two ends of a shipment.
Signature The pigment’s TAU value read by the scanner. “Signature not matched” means FibreTrace pigment was found but not the chosen program’s.
Confidence Moderate, Good or Excellent, from the number of recorded scans.
Unique ID An optional product or bale ID added to one scan, typed or read by camera.
Matched shipment An inbound verification linked to the partner’s outbound verification with the same shipping ID: an implied chain of custody.
Verification number The central number BETA issues on upload, FT- plus eight characters. Before upload the app shows a temporary reference.

5. Before scanning: facility and scanner

Facility. On opening, the app asks for the phone’s location and pre-selects the nearest facility within the geofence radius. If none is close enough, or location is refused, it asks the auditor to pick one. The auditor can always change it. Changing facility disconnects the scanner and asks for that facility’s scanner.

Scanner. Scanners belong to a facility, so the facility comes first. Pairing uses Bluetooth in Chrome, so it works on Android phones and desktop Chrome, not on iPhone. Only the scanners approved for the facility are offered. On connection the app checks the scanner really is the one chosen (by the device name, reported serial or model) and refuses a scanner that is not marked healthy.

The top bar always shows the company on the left and the scanner state on the right:

Top bar Meaning
Red dot, “No scanner connected” Nothing paired.
Green dot, “Scanner connected — 00695” Live link. Battery shows next to it (for example 51%); below 20% it turns red and says Low.
Red dot, “Scanner disconnected — 00695” The scanner dropped (standby or a reload). Reconnect the same scanner to carry on.
Amber dot, “Demo connection — 00695” A DEMO scanner (below). No battery.

DEMO scanner. A scanner whose type is DEMO in BETA’s admin connects instantly without Bluetooth and produces random results: a match, a wrong signature or nothing, after 2 to 4 seconds. A banner says results are simulated and can’t be saved. Finish stays off, nothing is uploaded, and the session is not kept after a reload. It exists so the flow can be shown without hardware and without creating false records. It is separate from /demo mode.

6. The verification flow

Step What happens Rules
1. Direction Home shows Inbound and Outbound. A facility and a connected scanner are needed. Producers (Tier 4) see Outbound marked Recommended; Inbound stays available.
2. Partner Pick the sender (inbound) or recipient (outbound). Inbound suggests suppliers (partners of the same or a higher tier number), outbound suggests customers (same or lower). “Show all partners” lists everyone, A to Z, with search. Rows read “Name (Tier n) · reference”. No partners means no way forward.
3. Shipping Outbound: carrier and shipping document ID. Inbound: shipping document ID. Outbound: both required; the last carrier used is filled in for next time. Inbound: optional, “Continue without shipping” is allowed. Either field can be read by camera.
4. Match (inbound with a shipping ID) Shows the partner’s outbound verifications with the same or a similar shipping ID. Confirm one to record the chain of custody, or continue without. In LSAT this lookup is switched off until BETA offers it, so today it always finds nothing.
5. Product type Raw fibre, Yarn, Fabric, Finished product, from the configuration. Required. An empty list blocks the flow.
6. Program Pick the fibre program, A to Z. Required. Chosen automatically when there is only one.
7. Scanning “Awaiting scan…” while the app listens. See section 7.
8. Result Shows the recorded scans and the confidence. Next scan returns to scanning. Each scan can take a Unique ID. Finish needs at least one recorded scan.
9. Reference Notes for the whole verification. Optional text, no Skip button; Submit saves.
10. Summary What was saved. Section 8. Done returns to home.

Back steps through the flow; X on the first step, Cancel, or back from the first step exits and discards the verification. An unsaved verification is kept on the phone until it is saved or exited, so a reload or closing the app returns to the same step (a scan that was listening returns to the program step, or to the result when scans exist).

7. Scanning rules

8. Saving and syncing

Saved on the phone first, then uploaded. Submit keeps the verification on the device, then pushes it to BETA’s sat-scans /submit. Nothing is lost offline.

Upload outcome What the app does
Accepted, or already received (duplicate) Marked uploaded. BETA returns the central verification number FT-XXXXXXXX.
Rejected: facility not allowed, or unknown pigment Marked failed with a red warning in the list and an Activity log line. Never retried. Malcolm expects this to be rare.
Error, or no connection Stays waiting and is retried.

9. Location and risk

Every scan carries the phone’s latitude and longitude. BETA compares them with the facility and its geofence (5 km by default) and flags a wrong scan location to the FibreTrace admin. This is a soft warning: the scan is still recorded, and SAT shows nothing to the auditor (Malcolm, 2026-09-24: a company VPN can place a phone far from the site). A facility that has closed since would reject the upload, which Malcolm also expects to be rare.

10. Settings and support

Item What it does
Help Short guides on location, pairing, scanning, confidence, camera codes and syncing.
Personal details Read-only name, email, phone and company.
Device check Device, browser, scanner support, Bluetooth, internet, FibreTrace servers and location permission, each with advice when it fails.
Reload data Downloads the configuration again. Offline, the app keeps using the copy on the phone.
Activity logs A support log kept only on this phone for 30 days: sign-ins, configuration, facility, scanner, uploads, connection and location events, plus scanner hardware and firmware versions. It never records TAU/INT or personal details. Filter by date and type, download as CSV, send to support@fibretrace.io, or clear.
Language Eleven languages listed; only English is written so far, the others fall back to English.
Debug mode Staff accounts only (section 7).
Log out Ends the session on this phone.

Terms & conditions and the privacy policy are linked from the sign-in screen and from Help.

11. Where our app apps/sat differs from LSAT

apps/sat follows LSAT’s screens and wording, and keeps its own scanner engine, data path and offline queue.

Topic LSAT apps/sat
Saving sat-scans upload; temporary reference until uploaded Writes the verification directly to BETA’s tables, or queues it offline with its final number; real number shown at once
Why LSAT’s current upload loses notes, unique IDs and the matched shipment (below) Kept until sat-scans stores everything SAT collects
Scanner identity Serial may match by its ending Exact serial match, on both the device name and the first packet
Firmware “old” results Any result with a TAU counts, so a repeated previous result can be recorded again Counts only when TAU/INT differ from the value seen before the scan command
INT Not used Sets a High/Low reading confidence with the program’s INT tolerance
Shipment matching Switched off Live: the partner’s outbound verifications are looked up directly

12. Open points