Behavision: face recognition for retail, edge to head office

Five components that ship as one product:

- behavision/  the recognition engine. RTSP ingest, YuNet detection, IoU
               tracking, ArcFace embeddings, a FAISS/SQLite gallery, and a
               FastAPI dashboard. Identity is decided once per TRACK from an
               average of at least three embeddings, never per frame.
- agent/       the Go edge agent: supervises the engine, holds a durable
               spool, and drains it to MQTT. Nothing is acked before the
               broker confirms.
- desktop/     the shop PC application (Wails + React + tray).
- server/      the cloud API, MQTT consumer, reports and assistant.
- web/         platform.loyaly.ai, the head-office app, embedded in the
               server binary.

The gallery stores 512-float embeddings and timestamps - no images unless
`app.store_faces` is switched on. Those embeddings are biometric personal
data under GDPR and India's DPDP: template inversion reconstructs a
recognisable face from an ArcFace vector, so data/behavision.db is treated
as a biometric database and DELETE /api/visitors/{id} is a real erasure.

CLAUDE.md carries the reasoning behind every non-obvious decision here,
including the ones that were measured and the ones that were wrong first.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HViLj9gYNRtSr7YVZmW5sn

desktop/frontend/src/bridge.js

@@ -0,0 +1,64 @@
+// The single seam between React and Go.
+//
+// Wails injects bound methods at window.go.main.App.*. Calling them through
+// here rather than importing generated bindings means `npm run build` works
+// without running `wails generate`, and it gives one place to handle the
+// "engine not running yet" case that every screen has to survive.
+const app = () => window?.go?.main?.App
+
+export const isDesktop = () => Boolean(app())
+
+async function call(name, ...args) {
+  const a = app()
+  if (!a || typeof a[name] !== 'function') {
+    throw new Error(`${name} is unavailable — run this inside the Behavision app`)
+  }
+  return a[name](...args)
+}
+
+// Every binding the UI uses, named as the UI thinks of them.
+export const api = {
+  session:            () => call('Session'),
+  login:              (email, password) => call('Login', email, password),
+  logout:             () => call('Logout'),
+  // The one-shot installation code that links this PC to a shop.
+  claim:              (code) => call('Claim', code),
+  // Set this PC up on its own, with no head office at all.
+  runStandalone:      () => call('RunStandalone'),
+
+  engineStatus:       () => call('EngineStatus'),
+  startEngine:        () => call('StartEngine'),
+  stopEngine:         () => call('StopEngine'),
+
+  cameras:            () => call('Cameras'),
+  testCamera:         (cam) => call('TestCamera', cam),
+  saveCamera:         (id, cam) => call('SaveCamera', id, cam),
+  deleteCamera:       (id) => call('DeleteCamera', id),
+  startPlacement:     (id, seconds) => call('StartPlacementCheck', id, seconds),
+  placementResult:    (id) => call('PlacementResult', id),
+  streamURL:          (id) => call('StreamURL', id),
+
+  live:               () => call('Live'),
+  pipelineStatus:     () => call('PipelineStatus'),
+  localIdentities:    (n) => call('LocalIdentities', n),
+  localSightings:     (n) => call('LocalSightings', n),
+
+  footfall:           (from, to, bucket) => call('Footfall', from, to, bucket),
+  sites:              () => call('Sites'),
+  visitorHistory:     (id, limit) => call('VisitorHistory', id, limit),
+  visitorPhoto:       (id) => call('VisitorPhoto', id),
+  forgetCustomer:     (id) => call('ForgetCustomer', id),
+  sales:              (from, to) => call('Sales', from, to),
+  customers:          (q, limit) => call('Customers', q, limit),
+  saveProfile:        (p) => call('SaveProfile', p),
+  recordPurchase:     (id, amount, items, notes) =>
+                        call('RecordPurchase', id, amount, items, notes),
+}
+
+// Errors from Go arrive as strings or Error objects depending on the path.
+// Normalising here keeps every catch block in the UI to one line.
+export function message(err) {
+  if (!err) return 'Something went wrong.'
+  if (typeof err === 'string') return err
+  return err.message || String(err)
+}