Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

How to use these docs

These docs are the front door to the Soundverse 2.0 fleet — a contract-first polyrepo of ~20 submodules under backend/core/ (Go data plane, Python gateways and queue workers, a Next.js frontend). Rather than one long guidebook, the material is split into seven groups, each answering a different kind of question. Knowing which group holds your answer is most of the skill of using the site.

The rule of thumb: come in through the group that matches your intent, not the chapter number. You’re either trying to do a task, understand why the system is shaped the way it is, or look up a fact. The groups map onto exactly those intents.

The seven groups

Section titled “The seven groups”
Start HereOrientation — what 2.0 is, the 60-second mental model, and the three service shapes.
Get Set UpTutorial — go from a clean machine to the whole stack running locally.
How-To GuidesTask recipes — add a tool, wire an RPC, drive the proto cascade, deploy.
ArchitectureExplanation — why the fleet is built this way, plus a field guide per service.
OperationsRunbooks — deploy, inspect, observe, reconcile billing, and troubleshoot.
ReferenceLookup tables — services, repos, env-var names, proto contract, glossary.
Contributing to DocsHow these pages are authored, badged, diagrammed, and shipped.

Task-first, not chapter-first (Diátaxis)

Section titled “Task-first, not chapter-first (Diátaxis)”

The information architecture follows Diátaxis, which sorts documentation by what the reader is trying to do. Four modes, mapped onto our groups:

Diátaxis mode Group(s) Answers the question You are…
Tutorial Get Set Up “How do I get it running the first time?” learning by doing
How-to How-To Guides, Operations “How do I make this specific change / run this operation?” performing a task
Explanation Start Here, Architecture “Why is it built this way? How does it hang together?” building understanding
Reference Reference “What’s the exact name / port / route / annotation?” looking up a fact

The split is deliberate, and it changes how each page reads:

  • How-To Guides and Operations are task-first. They lead with a goal and a <Steps> recipe. The flagship Add a new generation tool worker is the quality bar — copy the template, write three things, deploy.
  • Architecture explains why. These pages carry the diagrams and the reasoning (the trust boundary, the single data door, the two billing pipelines). Read them when a how-to’s instruction doesn’t make sense yet. Start at System overview.
  • Reference is for lookups, not reading front-to-back. The Service catalog, Repository catalog, and Glossary are tables you’ll return to, not tutorials.

Find anything fast

Section titled “Find anything fast”
  • Search. Press Cmd/K (Ctrl/K on Windows/Linux) or just / to open the Pagefind search box. It’s a static, local index — no external service — so it works even behind the Cloudflare Access gate in front of the site.
  • Sidebar. The seven groups on the left are autogenerated from the directory layout; pages self-order within a group via each page’s sidebar.order frontmatter (flagship guides sit at the top with order: 1).
  • On-page table of contents. The right-hand rail lists the headings on the current page.
  • Light/dark toggle. In the top bar; your choice persists, and Mermaid diagrams re-render to match the active theme.

Conventions to expect

Section titled “Conventions to expect”

A handful of conventions run through every page. Learn them once here.

Deploy-honesty badges. Much of the fleet is built but not yet live, so pages mark the live state of a feature or section inline:

DeployedIn code, not deployed

Planned

Treat an unbadged claim about production as “verify before you rely on it,” and check the Known limitations / risk register for the candid list of current debt.

Every file reference is a real path. If a page names a file, that file exists — usually as a GitHub deep link into the soundversegit org (for example, core-tool-stitch/app/tools/stitch_tool.py). Open it; the code is the source of truth when the prose drifts.

Env vars are named, never valued. Hard rule Docs cite environment-variable names only — INTERNAL_RPC_SECRET, CORE_DATABASE_GRPC, REDIS_ADDR — and never real secrets, hosts, keys, or tokens. A check:secrets gate fails the build if a value slips in.

Diagrams share a 5-tier colour legend. Architecture flowcharts and sequences are authored as Mermaid and colour each node by tier — frontend, gateway, data plane, worker, external. The palette is documented once in Diagram conventions; the authoring mechanics live in Adding a Mermaid diagram.

Suggested reading paths

Section titled “Suggested reading paths”

Old guidebook readers followed numbered sections; here are the same paths as links you can click.

If you want to… Start with
Get the map — repo layout & the contract-first model Mental model · Three service shapes · Repository catalog
Run it locally Prerequisites · Quick start with docker-compose
Understand the running system System overview · core-database · Identity & auth
Actually change it Add a tool worker · Add a data-service RPC · Deploy a service
Ship & operate it CI/CD pipeline · Observability in practice
Fix something that’s broken Troubleshooting FAQ · Observability & tracing model
Section titled “Related”