Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

Welcome — what is Soundverse 2.0

Soundverse 2.0 is an AI music and audio generation platform, built as a contract-first polyrepo. Read that phrase twice — it is the single decision that shapes almost everything you will touch. A user types a prompt; the platform authenticates them, prices and reserves the work, runs a model on a background worker, and streams back a finished, streamable master. These docs explain how each of those steps is wired, and how to change any of them safely.

Contract-first polyrepo, in one breath

Section titled “Contract-first polyrepo, in one breath”

The backend is a super-repo — backend/core — that wires 20 git submodules (enumerate them yourself from .gitmodules) into a single make up. Three languages, one contract:

  • One Protobuf repo is the source of truth. soundverse-proto defines every service API and message. buf code-generates the language SDKs (Go, Python, Connect-ES TypeScript, Swift, Kotlin) and the SQL-backed data layer — no service invents its own wire format.
  • Go runs the data plane (core-database, core-mcp). Python runs the gateway and every tool worker. TypeScript runs the frontend + backend-for-frontend (soundverse-saas-2.0).
  • One service holds the database keys. core-database is the sole owner of Postgres credentials; everything else reaches data through its RPCs.

The product journey: prompt → generated master

Section titled “The product journey: prompt → generated master”

1. Prompt

The user types in the chat / studio in soundverse-saas-2.0, which is both the browser SPA and a thin BFF that proxies to the gateway.

2. Trust boundary

core-gateway-consumer authenticates the user (a Logto OIDC token, validated by core-identity), then runs one pipeline: authenticate → rate-limit → price → reserve → queue.

3. Heavy lifting

A tool worker claims the queued task — core-tool-sansaarm for songs, core-tool-agent for the Agent One assistant, and the rest of the core-tool-* fleet — calls model providers, and uploads the finished master to core-storage.

4. Stream + settle

Progress flows back to the browser over SSE (relayed from Redis); on the terminal event the gateway settles the reserved tokens against the ledger.

Everything runs on Azure Container Apps. Internal calls are gRPC; service-to-service auth is a shared bearer secret (INTERNAL_RPC_SECRET).

Who these docs are for

Section titled “Who these docs are for”

Anyone who wants to understand, run, or change the 2.0 backend or frontend — whether you are picking up a single service, debugging an incident, or mapping how the whole thing fits together. No prior context is assumed: not the architecture, not the repo layout, not the deploy story. We lead with the why behind each design choice, because the “contract-first polyrepo” decision explains most of the what.

What you’ll be able to do

Section titled “What you’ll be able to do”

By the end of these docs you should be able to:

  • Trace a single user request end-to-end across services.
  • Know which of the 20 repos owns a given concern.
  • Bring the whole stack up locally with one command.
  • Change a Protobuf contract and regenerate every consumer.
  • Build a new generation tool worker from the template and get it priced and deployed.
  • Debug a stuck or failing generation.

Start here

Section titled “Start here”
The 60-second mental modelThe whole request flow across the polyrepo, in one diagram.
Backend at a glanceEvery service is one of three shapes: Go data plane, Python gateway, or Python queue worker.
Quick start with docker-composeOne command to bring the whole backend up locally.
Add a new generation tool workerThe most common change you'll make to the fleet — copy the template, write three things, deploy.
Section titled “Related”