Backend at a glance — the three service shapes

The backend is a contract-first polyrepo: ~20 git submodules under backend/core/ (enumerated in .gitmodules). That sounds like a lot to hold in your head — but you don’t have to. Every service is one of exactly three physical shapes. Once you know which shape a service is, you know how it boots, how it’s reached over the wire, and how to debug it. This is the single most useful lens for the whole fleet.

~20 repos, but not ~20 services

Most repos are services; several are not. The contract repos (soundverse-proto, soundverse-proto-web), the shared SDK (soundverse-py), and the two frontends (soundverse-saas-2.0, UI2.0) don’t fit the three shapes — see Not a service at the bottom. For the full, row-per-repo list use the Repository catalog.

The three shapes

Go data plane

A Connect/gRPC service over cleartext HTTP/2 (h2c). Speaks the DB contract. No TLS in-process. core-database, core-mcp.

Python service

A long-lived server with ingress — either grpc.aio or FastAPI+Hypercorn. Clients connect to it. core-gateway-consumer, core-identity, core-storage, core-billing, core-conversion.

Python queue worker

No ingress. A poller built on the soundverse-py WorkerFleet. It claims tasks off the queue, runs them, and drains on SIGTERM. All the core-tool-* repos.

Go data plane

Who: core-database and core-mcp.

How it serves. One HTTP port speaking h2c (cleartext HTTP/2) + Connect, wired with h2c.NewHandler(...). There is no TLS in-process — the platform (Azure Container Apps, or a local proxy) terminates TLS in front. Both listen on the port named by LISTEN_ADDR (:8080 in-container).

How it’s reached. Other services dial it by its published *_GRPC address (CORE_DATABASE_GRPC, CORE_MCP_GRPC) and present the shared secret INTERNAL_RPC_SECRET as a bearer token on every call. core-database is the single door to Postgres — it mounts every proto-defined DataService (chat, identity, storage, generation task + tool, billing, DNA, notifications, the compat trio, and more) behind one registry.RegisterAllDBServices(...) call, and nobody else opens a DB connection. core-mcp is the MCP tool registry the agent calls, and it runs the second billing pipeline.

How to debug it. GET /healthz. Boot lives in core-database/cmd/server/main.go and core-mcp/cmd/server/main.go. Run locally with go run ./cmd/server.

core-mcp caches tool schemas in memory

Redeploying a tool worker updates the DB registry row, but a changed input/output schema is not picked up until core-mcp is restarted. Easy to miss — see the add-a-tool-worker guide.

Python service

Who: core-gateway-consumer, core-identity, core-storage, core-billing, and core-conversion.

How it serves. A long-lived server with ingress — clients connect to it. Two sub-flavours share the shape:

• grpc.aio (native gRPC + a gRPC health service): core-gateway-consumer, core-storage, core-conversion. These add_insecure_port(...) and let the platform terminate TLS, same as the Go services.
• FastAPI + Hypercorn (HTTP/REST): core-identity, core-billing. Served with hypercorn app.main:app.

How it’s reached. core-gateway-consumer is the consumer trust boundary — the only service the browser’s BFF talks to. Its request pipeline is authenticate → rate-limit → price → reserve → queue; everything downstream trusts that it ran. The others are internal: the gateway and workers dial them by their *_GRPC / service-discovery names.

How to debug it. gRPC services expose a gRPC health service (liveness/readiness); FastAPI services expose GET /healthz. Run locally with make run (which is uv run python -m app.main) or, for the FastAPI ones, uv run hypercorn app.main:app -b 0.0.0.0:80. make check (ruff + pyright + pytest) is the exact CI gate.

Python queue worker

Who: every core-tool-* repo — core-tool-agent, core-tool-sansaarm, core-tool-stitch, core-tool-media, core-tool-gpu, core-tool-dna — plus the template-core-tool starter they’re all copied from. See the other tool workers page for the non-flagship ones.

How it serves — it doesn’t. No ingress There is no HTTP port, no gRPC server, no health endpoint you curl. A worker is a long-running poller built on the soundverse-py WorkerFleet. app/main.py does exactly three things: set up telemetry, build the gRPC client, then WorkerFleet(ALL_TOOLS).start() and block in the poll loop. The fleet:

• self-registers each tool in the DB registry (so core-mcp can expose it),
• claims tasks off the Postgres queue, runs process() in a thread pool, heartbeats the lease,
• uploads file outputs, assembles the GenerationOutput, reports raw usage,
• drains gracefully on SIGTERM (ACA sends SIGTERM on scale-down / redeploy).

How to debug it. Watch the logs / traces — the worker announces which tasks it claims. Run locally with make run (needs Redis + core-database + core-storage + core-mcp reachable). Adding one of these is the most common change you’ll make: see Add a new generation tool worker.

The worker never bills, and never adds HTTP

process() only calls ctx.report_usage(units) — pricing and settlement happen upstream in core-mcp / the gateway. Keep process() synchronous (it runs in a thread pool) and never add FastAPI / HTTP / ingress to a worker; that would make it a different shape.

Quick reference

Shape	Language	Serves via	Ingress?	Reached by	In the fleet
Go data plane	Go	Connect/gRPC over h2c	Yes	*_GRPC addr + INTERNAL_RPC_SECRET bearer	core-database, core-mcp
Python gRPC service	Python	grpc.aio + gRPC health	Yes	*_GRPC addr (gateway = BFF entry)	core-gateway-consumer, core-storage, core-conversion
Python HTTP service	Python	FastAPI + Hypercorn	Yes	GET /healthz, REST	core-identity, core-billing
Python queue worker	Python	nothing — polls the queue	No	not reached; claims tasks	every core-tool-*

Tip

The two Python service sub-flavours (grpc.aio and FastAPI) are the same shape for onboarding purposes: a long-lived server with ingress, make run to start, make check to validate, a health probe to poll. The distinction only matters when you’re inside one.

The outlier: a batch job, not a service

core-migration is the one repo that isn’t a long-lived service at all. It’s a run-to-completion job (an ACA Job) that re-ingests 1.0 users, billing, and library content into 2.0, then exits. Think of it as a fourth, rare shape: it boots, does a bounded amount of work, and stops.

Not a service — the supporting cast

Several repos are load-bearing but aren’t any of the shapes above:

• Directorybackend/core/

  • Directorysoundverse-proto/ the contract — proto + SQL-in-proto annotations (source of truth)

    • …
  • Directorysoundverse-proto-web/ the generated web/TypeScript SDK the frontend imports

    • …
  • Directorysoundverse-py/ the Python SDK every worker is built on (WorkerFleet + TaskContext)

    • …
  • Directorysoundverse-saas-2.0/ the Next.js studio + BFF (proxies consumer/v1, Logto auth)

    • …
  • DirectoryUI2.0/ a standalone, backend-less in-browser studio (package agent-synth)

    • …
  • Directorytemplate-core-tool/ the copy-me starter for a new queue worker

    • …

soundverse-py gets special mention: it’s not a service, but its WorkerFleet / TaskContext API is the contract every tool author lives inside — read the SDK deep-dive. The proto repos anchor the contract cascade that keeps all the shapes in sync.

Why the lens works

Because the shape is the operational contract:

• Boot & run — Go: go run ./cmd/server. Python service: make run / hypercorn. Worker: make run (it just starts polling).
• Reached over the wire — data plane and gRPC services: a *_GRPC address (internal ones want INTERNAL_RPC_SECRET). Worker: never dialled — it pulls work.
• Debugging first move — service: hit its health probe and read its logs. Worker: read its logs/traces and check it’s claiming tasks (an unpriced tool won’t; an unpriced tool fails callers with NotFound).

Related

• The 60-second mental model — the whole request flow in one diagram
• System overview — the trust boundary and the single data door
• Service catalog — every service in one table (shape, port, health path)
• Repository catalog — every submodule and its role
• Add a new generation tool worker — build a shape-three service
• The soundverse-py SDK — the worker contract
• Glossary — BFF, WorkerFleet, h2c, lease, and the rest