Single-page map of the Valeron platform. Use the tabs below to flip between the goal, the data flow, the current state of each component, the build plan, schema, role model, gotchas, and backlog. This is a living doc — regenerate it from a Claude session when the picture shifts.
A real user signs up, pairs with a tracker and robot at a course, plays a Janice-driven round, sees videos in app, ends session, opens app.valeron.ai, logs in, sees the same data.
Beyond the demo loop, Platform Readiness (Feature #1) builds multi-tenant infrastructure for pilot deployments with role-based access, admin consoles, and production hardening.
Cloud once at pairing, then dark for the round. Ferry syncs at end of day. Expect zero connectivity during play.
Session is cloud-created at start (via start-session edge function). Robot owns play-time data locally. Ferry syncs at end of day.
Robot's devices.course_id is the source of truth. Admin updates it when robot moves. No user selection.
app.valeron.ai — sign up, pair, play, view rounds and videos.
admin.valeron.ai — manage fleet, view sessions, user oversight for one course.
admin.valeron.ai — fleet-wide view, all accounts, all courses, provisioning.
High-level containment view. Both Jetsons physically live inside the Robot. Cloud holds auth, 9 edge functions, and Postgres. Ferry runs at end-of-day to sync offline rounds. For the full data-flow with labelled edges, see the Data Flow tab.
Full edge-labelled pipeline — cloud orchestrates pairing (ADR-014), robot runs the round, Capture Jetson handles vision. Per ADR-015, the Capture API is a standalone FastAPI service on the Capture Jetson; golfer pipeline stays untouched. User scans everything; robot has no display and does not scan QR codes. Dense by design — use fullscreen + zoom to trace a specific flow.
robot-capture-service is a standalone FastAPI service on the Capture Jetson (separate systemd unit). It bridges Janice HTTP requests to the shot-tracker pipeline via two Unix sockets:
Grouped by repo. Each row tells you what works, what is planned, and what is drifting.
Platform Infrastructure Readiness — Feature #1, sequential phases (Phase 0 → 8). 59/65 IN PROGRESS
Platform Foundation Polish — Feature #4, post-PIR plateau work across three phases: Docs & Contracts, Testing Infrastructure, Developer Hygiene. IN PROGRESS · 6/17
Demo Loop — unphased post-PIR follow-ons migrated from AWE-* (ace_supervisor multi-session + desktop-ferry-app upload/Tauri). NOT STARTED · 0/4
Current Supabase tables as of 2026-04-14. Lane indicates the data domain.
| Table | Lane | Status | Notes |
|---|---|---|---|
| accounts | Lane 1 | OK | B2B customer accounts |
| courses | Lane 1 | OK | 8 courses, content thin |
| course_features | Lane 1 | OK | ~40 rows, 2 courses only |
| publish_log | Lane 1 | OK | Snapshot history for rollback |
| devices | Lane 1 | OK | 1 device |
| trackers | Lane 1 | OK | 2 trackers |
| profiles | - | OK | 2 users |
| sessions | Lane 2 | OK | 14+ incl 1 real (2026-04-11) |
| shots | Lane 2 | OK | Seed data |
| device_associations | - | OK | UUID migration landed in Phase 1 (ACL-7) |
| memberships | - | OK | User ↔ account role map (ACL-3) |
| device_heartbeats | - | OK | Robot health pings (ACL-16) |
| audit_log | - | OK | Mutation history via triggers (ACL-18) |
| incidents | - | OK | Anomaly alerts (ACL-17) |
| appearance_vectors | Lane 2 | OK | Per-user, per-session Re-ID (ACL-39) |
| map_sessions | - | OK | From web-mapper-app |
| captures | - | OK | From web-mapper-app |
Planned role model for multi-tenant access. Roles narrow from full platform access down to individual golfer data.
All accounts, all courses, fleet-wide. Provisioning, user management, incident response.
One account, all its courses. Fleet management, session oversight, user management for their org.
One account, one course. Day-to-day operations — start/end sessions, view active rounds.
Own data only. No membership needed. Signs up via Supabase Auth, pairs at course, views own rounds and videos.
Roles are stored in the memberships table (ACL-3, shipped), linking a user to an account with a role enum.
The get_user_role() database function (ACL-4, shipped) resolves the effective role for RLS policy evaluation.
Golfers have no membership row — they access data through golfer-scoped RLS policies.
Admin-aware RLS (ACL-5, shipped) widens access for valeron_admin; course_admin and course_employee rows will activate once multi-tenant pilot ramps.
Things that surprised us, broke us, or are worth remembering. Newest first.
Phase 0 through Phase 7 all complete. Admin-aware RLS, memberships, admin console MVPs, production hardening, canonical pairing support (ACL-34 connect edge fn, ACL-39 appearance_vectors), and edge function hardening (ACL-56/58/63) all shipped. Program rolls into "Platform Foundation Polish" for capture bridge and remaining seams.
Supersedes ADR-001 (derived PIN) and PAIRING_FLOW.md v3. User scans everything with phone — robot has no display and does not scan QR codes. New connect edge function creates session + returns WiFi creds. Appearance vector captured per session. No PIN, no HMAC-derived codes.
Two prior attempts to build the API inside the golfer repo diverged from Brandon's field-tested capture_king branch. robot-capture-service now lives standalone in ace_devel/bridge/api/, runs as its own systemd unit on the Capture Jetson, and bridges to the pipeline via two Unix sockets (cmd + events). ACL-38.
Robot Jetson (ace00) runs Janice + nav stack + golfer web app. Capture Jetson (ace00-capture) runs shot-tracker pipeline + robot-capture-service. They communicate over LAN/Tailscale via bearer-authed HTTP webhooks. Janice is the sole comms hub — phones only talk to Janice, Capture Jetson never serves the golfer directly.
cloud-platform-service (renamed from ace_cloud 2026-04-18, ADR-022 Phase E/10) is the cross-cutting kanban for platform infrastructure work. All AWE-* references in older docs refer to the same work items under new ACL-* identifiers. Linear `ACL` prefix retained across the rename.
47 docs reviewed, 18 updated, SUPABASE.md rewritten from scratch, SCHEMA.md corrected to match production. This was Phase 0 of the build plan.
Derived-PIN, cloud-validated PIN, pro-shop pre-pairing, and robot-scans-phone-QR are all retired. ADR-014 is the single source of truth. If you see references to "pro-shop flow" or PIN derivation in old docs, ignore them.
Session 87a654f8-ea14-4316-bcf3-b1bb1d63035a created 2026-04-11 19:27 UTC. Full Janice start-session path with real user, real tracker FK, real device UUID.
start-session schema drift (status='ended' vs 'completed'), JWT algorithm mismatch (RS256 vs ES256), sb_secret_ key format, pair gateway 401 (verify_jwt), robot_id contract ("robot-00" vs UUID). All fixed.
Legacy TEXT type was mismatched with devices.id (UUID). Resolved in Phase 1 when device_associations was rebuilt with the proper migration.
ACL-* tickets grouped by phase. Platform Infrastructure Readiness (Phase 0–7) closed out 2026-04-13.
Status as of 2026-04-14. See Build Plan tab for program-level progress.
Reconciled against Sidespace 2026-04-14. ACL-38 appears under Phases 5–7 (canonical pairing); ACL-26/27/28/29 are unfinished AWE-* migrations awaiting ace_supervisor + desktop-ferry-app work.