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

agent/pkg/paths/paths.go

@@ -0,0 +1,79 @@
+// Package paths mirrors behavision/paths.py.
+//
+// The two processes must agree on where state lives or they will quietly use
+// different databases: the engine would write footfall into one file while the
+// agent reads another and reports an empty store. The rule is the same on both
+// sides — BEHAVISION_DATA_DIR wins, then %PROGRAMDATA%\Behavision on Windows —
+// and `behavision paths` prints the engine's answer so the two can be compared
+// on a real machine rather than assumed equal.
+package paths
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+)
+
+const AppName = "Behavision"
+
+// StateRoot is the writable root: database, logs, spool, agent config.
+func StateRoot() string {
+	if v := os.Getenv("BEHAVISION_DATA_DIR"); v != "" {
+		if abs, err := filepath.Abs(v); err == nil {
+			return abs
+		}
+		return v
+	}
+	if runtime.GOOS == "windows" {
+		base := os.Getenv("PROGRAMDATA")
+		if base == "" {
+			base = `C:\ProgramData`
+		}
+		return filepath.Join(base, AppName)
+	}
+	home, err := os.UserHomeDir()
+	if err != nil {
+		return "."
+	}
+	if runtime.GOOS == "darwin" {
+		return filepath.Join(home, "Library", "Application Support", AppName)
+	}
+	if v := os.Getenv("XDG_DATA_HOME"); v != "" {
+		return filepath.Join(v, "behavision")
+	}
+	return filepath.Join(home, ".local", "share", "behavision")
+}
+
+// InstallRoot is the directory holding this executable.
+func InstallRoot() string {
+	exe, err := os.Executable()
+	if err != nil {
+		return "."
+	}
+	if resolved, err := filepath.EvalSymlinks(exe); err == nil {
+		exe = resolved
+	}
+	return filepath.Dir(exe)
+}
+
+func AgentConfig() string { return filepath.Join(StateRoot(), "agent.json") }
+func SpoolDir() string    { return filepath.Join(StateRoot(), "spool") }
+func EngineLog() string   { return filepath.Join(StateRoot(), "engine.log") }
+
+// APICredentials is the file the engine writes when it generates its own
+// Basic credentials. The agent reads it rather than storing a second copy,
+// so a regenerated credential does not silently break the tray.
+func APICredentials() string {
+	return filepath.Join(StateRoot(), "data", "api_credentials.txt")
+}
+
+// EnsureState creates the writable tree. Called before anything opens a file
+// under it, so a first run on a fresh machine does not fail on a missing dir.
+func EnsureState() error {
+	for _, d := range []string{StateRoot(), SpoolDir()} {
+		if err := os.MkdirAll(d, 0o700); err != nil {
+			return err
+		}
+	}
+	return nil
+}

agent/pkg/paths/paths_test.go

@@ -0,0 +1,43 @@
+package paths
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+func TestDataDirEnvWins(t *testing.T) {
+	// The override is what lets one machine run two instances, and what makes
+	// the installed layout testable from a checkout - on both sides.
+	dir := t.TempDir()
+	t.Setenv("BEHAVISION_DATA_DIR", dir)
+	if got := StateRoot(); got != dir {
+		t.Fatalf("StateRoot() = %q, want %q", got, dir)
+	}
+}
+
+func TestEverythingLivesUnderTheStateRoot(t *testing.T) {
+	dir := t.TempDir()
+	t.Setenv("BEHAVISION_DATA_DIR", dir)
+	for name, got := range map[string]string{
+		"agent config": AgentConfig(),
+		"spool":        SpoolDir(),
+		"engine log":   EngineLog(),
+		"credentials":  APICredentials(),
+	} {
+		if !strings.HasPrefix(got, dir) {
+			t.Errorf("%s resolved outside the state root: %s", name, got)
+		}
+	}
+}
+
+func TestEnsureStateIsIdempotent(t *testing.T) {
+	dir := filepath.Join(t.TempDir(), "fresh")
+	t.Setenv("BEHAVISION_DATA_DIR", dir)
+	if err := EnsureState(); err != nil {
+		t.Fatal(err)
+	}
+	if err := EnsureState(); err != nil {
+		t.Fatalf("second call failed: %v", err)
+	}
+}