Skip to content

How to read this wiki

This wiki is organized so you can read it top to bottom and come away understanding the whole system. But depending on why you're here, some paths are faster.

Suggested reading paths

  1. Welcome / 60-second model
  2. Glossary — skim it, then keep it in a tab
  3. Architecture → Overview
  4. Architecture → The three surfaces
  5. Architecture → A request, end to end

Stop there for day one. That's enough to follow most conversations.

  1. Architecture → Overview
  2. Surfaces → Voice
  3. Edge → Onboarding & pairing
  4. Edge → Audio devices
  5. Edge → Wake-word training
  1. Architecture → Overview
  2. Architecture → Per-user provisioning
  3. Architecture → Auth model
  4. Operations → Deploy
  5. Contributing → Repo layout
  1. Operations → Deploy
  2. Operations → Observability
  3. Operations → Runbooks
  4. Operations → Secrets

Conventions used here

  • Box colors in diagrams are consistent across the wiki:
    • 🟦 Blue = a long-lived Docker container (always running).
    • 🟧 Orange = a per-user container, spawned on demand (one per family).
    • 🟩 Green = a native process (no container) — sudoedge on the Pi, caddy on the VPS.
    • 🟪 Purple = an external service we don't run (Supabase, OpenRouter, Twilio…).
  • code font is used for service names, file paths, and commands.
  • Admonitions call out the important bits:

Watch out

These flag the sharp edges — things that have bitten us before.

Source of truth

When this wiki and the code disagree, the code wins. Each page points at the real files so you can check. ARCHITECTURE.md in the repo root is the canonical topology; this wiki is the friendly version of it.

Where this content comes from

This wiki is hand-written for newcomers, drawing on the repo's own docs (ARCHITECTURE.md, CLAUDE.md, README.md, RELEASE.md, and docs/*.md). Those original docs still live in the repo as terse engineering reference; this is the guided tour. The wiki source lives at cloud/wiki/ and is built with MkDocs Material.