Skip to content
SoundverseSoundverse 2.0 — Engineering Docs

Glossary

The vocabulary that runs through the rest of these docs. Skim it once now, refer back later. Each term links to the page where it’s explained in full.

Request path & trust boundary

Section titled “Request path & trust boundary”
Term What it means here
BFF Backend-For-Frontend — the server-side /api layer inside soundverse-saas-2.0 (Next.js). It holds the session, attaches the Logto OIDC token, and speaks gRPC to the backend so the browser never does. See Frontend architecture.
consumer gateway core-gateway-consumer — the public entry point and trust boundary for the human-driven path. Runs the authenticate → rate-limit → price → reserve → queue pipeline.
trust boundary The line between untrusted callers and the internal mesh. Everything outside the gateway is suspect; everything past it is authenticated with the shared secret INTERNAL_RPC_SECRET.
single data door core-database is the only Postgres-credentialed service. Every other service reaches data through its gRPC DataServices — no one else holds a DB connection string.
Logto The OIDC identity provider (the fleet migrated off Zitadel). Request an API resource so the access token is a verifiable JWT, not an opaque token. See Configure Logto.

Tools & the fleet

Section titled “Tools & the fleet”
Term What it means here
tool worker A no-ingress queue worker that performs a generation — e.g. core-tool-sansaarm, core-tool-stitch, core-tool-media. It claims tasks off the queue, calls upstream providers, and uploads results. No HTTP. See Add a tool worker.
agent core-tool-agent (Agent One) — the LLM orchestration worker. Runs Anthropic Claude (standard/pro tiers) and Kimi (flash tier) via litellm prefix routing, and drives sub-tools through core-mcp.
WorkerFleet The soundverse-py runtime every Python tool is built on. Self-registers tools (making them MCP-visible), claims tasks, sends heartbeats, emits events, uploads files, and reports usage — so a tool author writes only process().
TaskContext The per-task handle passed into a tool’s process(). Exposes scope (user_id / workspace_id / project_id / task_id) plus helpers: emit_progress, emit_partial, upload_file, report_usage, set_streaming_url, resolve_credentials, log. See the TaskContext reference.
MCP Model Context Protocol — the standard by which an LLM agent discovers and calls tools as structured sub-tools during its reasoning loop.
core-mcp The Go service that hosts the MCP tool registry for agents and re-runs the reserve/price/queue pipeline for agent-invoked sub-tools (the second billing pipeline). It caches tool schemas in memory, so a schema change needs a core-mcp restart. See core-mcp.

Money & billing

Section titled “Money & billing”
Term What it means here
token ledger The append-only money primitive in billing.token_ledger. Every deduct/refund/grant is a row with a unique idempotency index and an immutability trigger — auditable and double-charge-proof. See The token ledger & money path.
base / extra buckets The two balances in billing.token_balances: expiring base_tokens (the plan grant) and non-expiring extra_tokens (purchases / top-ups). Reserve and settle draw from these.
reserve The up-front hold: deduct the estimated token cost before work starts, so a user can’t overspend on inflight jobs.
settle The final true-up after work finishes: deduct the shortfall (idempotency-key suffix :settle-extra) or refund the surplus (:settle-refund) versus the reservation, based on the worker’s reported usage.
idempotency key A stable string (e.g. a task’s billing key) that makes a retried operation a no-op instead of a duplicate charge — the backbone of safe at-least-once settlement.

Queue, leases & live events

Section titled “Queue, leases & live events”
Term What it means here
ClaimNextTask The atomic “give me a job” RPC. Uses SELECT ... FOR UPDATE SKIP LOCKED so many workers pull distinct tasks without contention, and sets a 2-minute lease. See Task queue on Postgres.
lease / heartbeat A claimed task carries claim_expires_at; the worker calls HeartbeatTask to extend it (by 2 minutes). If the lease lapses — the worker died — the reaper makes the task re-claimable.
task:wake The Redis pub/sub channel ({env}:common:task:wake) the gateway publishes to after queueing a task, so a worker’s poll loop wakes immediately instead of waiting for the next tick. Env-namespaced and shared with the fleet.
Redis stream / SSE Workers XADD progress events onto a per-task Redis stream; the gateway reads it and relays each event to the browser as Server-Sent Events, decoupling long work from live updates. See the request lifecycle.

The contract & the platform

Section titled “The contract & the platform”
Term What it means here
proto cascade The chain reaction when soundverse-proto changes: regenerate the SDKs, publish, then update each consuming service in order — two-hop automatic for Python, manual for Go. See The proto contract and Drive the proto cascade.
SAS URL Shared Access Signature URL — a short-lived, signed download link minted by core-storage. It expires fast; the permanent blob URL is never exposed. See Storage & media plane.
JIT provisioning Just-In-Time — core-identity creates a user record (and grants a starting token balance) the first time a valid Logto token is seen, rather than via a separate signup write. See Identity & auth.
ACA Azure Container Apps — the managed runtime the services deploy to (staging / prod), with per-service env-var injection. See the CI/CD pipeline.
Section titled “Related”