Repo layout¶

A map of the repo, focused on the non-obvious bits. The authoritative version is in sudo/CLAUDE.md.

Top level¶

Path	What it is
`ARCHITECTURE.md`	Source-of-truth topology. Keep it current when you change the shape of the system.
`CLAUDE.md`	Working guidance + the architecture cheat-sheet.
`README.md`	Quickstart + stand-up sequence.
`RELEASE.md`	Pi release + auto-update playbook.
`compose.prod.yaml`	The canonical stack.
`Makefile`	The `dev` / `prod` / `lint` targets.

Path	What it is
`cloud/api/main.py`	The aiohttp app: page routes, `/v1/me/`, `/v1/internal/`, `/v1/admin/*`.
`cloud/api/provisioner.py`	The per-user container lifecycle. `ensure_runtime()`, `_spawn()`, `_SEED_AND_EXEC`, `api_key_for()`. Not a separate service.
`cloud/api/templates/`	Vanilla HTML + ES modules + Supabase JS. No build step; `{{key}}` substitution.
`cloud/api/Dockerfile`	Builds the `sudo-api` image (and, now, the wiki — see below).
`cloud/voice_bridge/main.py`	The `livekit-agents` worker: STT → hermes → TTS.
`cloud/hermes/Dockerfile`	A 2-line retag of upstream hermes. No fork.
`cloud/hermes/plugins/{twilio_whatsapp,sudo_chat,sudo_voice}/`	Our three platform adapters, bind-mounted into each per-user container.
`cloud/_shared/`	Just three modules: JWT util, Supabase auth, Supabase DB pool.
`cloud/wiki/`	This wiki's source (MkDocs Material). Lives under `cloud/` so it ships in the image and triggers the deploy.

Path	What it is
`sudoedge/lk_client.py`	LiveKit client + conversation cues.
`sudoedge/wake.py`, `sudoedge/models/hey_sudo.onnx`	Wake detection (forces ONNX backend).
`sudoedge/audio_devices.py`	USB-preferring device picker.
`sudoedge/announce.py`	Lifecycle audio cues.
`sudoedge/telemetry.py`	Ring buffer + flusher + panic reporter.

Path	What it is
`caddy/Caddyfile`	Host reverse-proxy config (installed on the VPS, not a container).
`supabase/migrations/`	Manual-apply SQL — also doubles as schema docs.
`deploy/`	`.env`, `livekit.yaml`, `grafana/` provisioning, deploy scripts.
`docs/`	The original terse engineering docs this wiki is built from. Not in the image and not auto-deployed.
`tools/softap-repro/`	Docker harness reproducing the SoftAP networking layers.
`.github/workflows/deploy-cloud.yml`	The auto-deploy workflow (fires on `cloud/`, `compose.prod.yaml`, `caddy/`, `deploy/**`).

If you see these referenced, the doc predates the pivot: