The one-page mental model. The founding decisions live in WATTROOM.md; the research behind them in RESEARCH.md; changes since in decisions/.
+---------------------+ WebSocket +---------------------------+
| Client (SvelteKit) | <--------------------> | wattroom-server (Go) |
| | /ws/channels/{id} | |
| - Web Bluetooth | metrics up, | - REST /api/* |
| trainer drivers | 1 Hz ticks down | - hub: goroutine/channel |
| - Workout engine | | - serves embedded SPA |
| - YT IFrame player | WebRTC (SFU) | - /metrics (Prometheus) |
| - LiveKit SDK | <--------------------> | |
+---------------------+ voice/video/screen | PostgreSQL LiveKit |
+---------------------------+
1. The client owns the trainer. ERG targets are computed and written to the trainer locally — a network hiccup never drops your watts mid-interval. Two drivers behind one Trainer interface: FtmsTrainer (standard, Kickr Core etc.) and SimulatedTrainer (dev/CI, no hardware); WcpsTrainer for the pre-FTMS Kickr v2 is backlog (#4, ADR-0007), so a CPS-only unit gets an empty chooser today. Trainer control-point writes are strictly serialized behind their response indications — both protocols reject concurrent writes.
2. The server owns shared truth, in memory. One goroutine per voice channel holds who is in it, the jukebox queue+position, and the running session — its synchronized interval timer and game-mode state, at most one per voice channel (ADR-0058). Riders send ~1 Hz samples; the hub coalesces all riders into one tick message per voice channel per second (n in, 1 out — never n²), bursting to 4 Hz during sprint moments. Live state never touches the database; if the process restarts, live channels re-form from reconnecting clients (which hold the ride data — see seam 3). An open ride (ADR-0076) runs in an open-ride room of its own, one per ride, with the same shape: it sits beside the voice channels and never messages them, and it sends one nameless frame a second to all its riders.
3. Postgres owns durable data only. Users, crews and their channels, workouts, and completed rides (summary columns + the raw 1 Hz stream as one compressed blob per ride, ~50 KB/h). Rides survive anything: samples stream to the server and buffer in IndexedDB with sequence numbers; either side can reconstruct after a crash — though a session ride the server loses comes back from the browser as a .fit, not as a saved ride (ADR-0052): the hub writes nothing about a session until the session closes. Stats (power curve, execution score, medals, XP) are computed server-side on ride completion, in one transaction.
The crew is the only object with an identity (ADR-0058, which took the room apart and superseded most of ADR-0038): crews (name, icon, picture, owner, a six-character join code), crew_roles (member / admin / banned — membership is a row, the owner holds none), and below it channels, text or voice — a name, an order and a gate, private, with channel_members naming whom a private channel admits. A channel belongs to one crew for good and has no owner. The crew itself carries nothing live: the hub holds voice channels, a session is live state inside one, and so the hub never sees a crew. May this rider enter that channel is answered in exactly one place, mayEnter in channels/access.go — the crew's owner and admins enter every channel, a member enters an open one or a private one they are named into, a banned rider and a stranger enter none — and every door asks it: the page, the socket, the AV token, presence. SQL asks the same question through the visible_channels view, which is mayEnter word for word, and every person-visibility join reads the view rather than spelling role != 'banned' by hand, which is how #1109 and #1114 happened: who may see, hear and find whom follows the channels two riders may both enter. Who may change a gate is the second question, and the only one a crew role answers: the crew's owner and admins (administers) create, rename, order, gate and delete channels. Nothing makes a hand-written join fail to compile: what catches one is crew_invariants_test.go's table, which runs the person-visibility queries it lists over one fixture and asserts both directions across the crew boundary, a private channel and a ban — a new one is caught only once it has a row there. The rest are pinned through the handlers that read them — riders for ListCrewsInCommon and ListSharedRides, crews for ListCrewPeople and ListCrewRecaps — and ListCrewRecaps still restates the gate by hand. A crew has one door, its six-character code and the /c/{code} link a member hands out. A listed crew (ADR-0039, as amended) puts that link in the public directory — a name, a mark and the door, nothing past it. An old /r/{slug} address opens nothing: it is looked up once to find what the room became (#2458), and entering that still asks mayEnter.
A rider's device holds one ride (ADR-0093), owned by the app shell. It holds at most two live connections, a call and a crew session (SESSIONS.md), and the ride rides on one of them: the session's while one is open on this device, else the call's. Opening a place moves the ride there still running; navigation never ends it, and no page asks "End the ride?". Only End ride ends it, or leaving the last place it rides on, which saves it. rideFrame (ride-frame.svelte.ts) is the one answer to "is the frame the ride" for the root layout, the now bar, the desktop HUD and the lounge.
| Place | Address | Shows | Who joins | Back |
|---|---|---|---|---|
| Voice channel (the lounge) | /crew/[id]/v/[channel] |
The call: stage, lounge, music, and a bike badge on whoever rides, with the session's name and Join. Never anyone's numbers. | Opening it puts you in the call. A ride you have moves here and stays private. Opening another voice channel moves the call and the ride. | The page before. The call stays until Leave. |
| The call's ride | /crew/[id]/v/[channel]/training |
Your free ride or your own workout on the riding screen. | Nobody: it is yours. | The page before; the ride goes on in the dock. |
| Crew session | /crew/[id]/s/[session] |
The session's timeline and its riders' numbers. | Opening it watches, and your ride's numbers stay yours. Join (the page's Join, a "Join the ride" link, the coach's own Start) puts you on its timeline; a road session's start line has its own Join. Leave the ride watches again and the page never re-joins you. | The page before. The now bar's Leave closes the session and hands the ride back to the call. |
| Ride alone | /ride, /ramp |
The ride alone, or the call's ride on its Training page. | Nobody. | The page before; the ride goes on in the dock. |
| Anywhere else | The ride dock in the sidebar, the call in its foot. |
Defined once as Go structs in server/internal/protocol/; make protocol generates web/src/lib/protocol.ts via tygo. JSON on the wire (readable in devtools). Never edit the TS file by hand.
A mode = a rule module plugged into a session in the hub: the workout engine keeps producing targets; the mode adds per-tick rule evaluation (eliminations, lives, scores), UI states, and an end condition. Everything is %FTP-relative. Elimination modes give a 30 s reconnect grace window.
- No Redis/NATS — one instance handles hundreds of voice channels; revisit when it measurably can't.
- No job queue — ride-completion stats are <100 ms of math in the request path.
- No ORM, no framework — sqlc + pgx + net/http.
- No iOS path — Web Bluetooth is Chromium-only and Safari refuses; locked decision.
Single Go binary with the SPA embedded (make build). Production is deliberately boring (ADR-0002): one VM, one docker compose stack — wattroom-server, Postgres, LiveKit (host network — WebRTC UDP is trivial on a VM, awkward on k8s), Caddy for TLS. Deploy is a tagged release the VM converges on by itself (ADR-0019): a five-minute timer reads the tag pinned in the homelab repo, refuses to interrupt a ride in progress, pg_dumps, rolls forward, and retags to the previous image if the new one does not report itself healthy. Rollback is an image tag, never a database restore — which holds only because migrations are expand/contract. Prod looks like the dev compose file on purpose. Local dev: make infra + two hot-reload processes.