Add or extend a consumer-facing API

The browser never speaks gRPC and never holds a bearer token. Everything the SaaS app does — list your library, create a generation, read your balance — is an HTTP call to /api/* on its own origin, which a thin backend-for-frontend (BFF) proxies to core-gateway-consumer, the browser-safe face of the whole system. Adding a new capability to the browser means editing two seams that must move together:

• The gateway (core-gateway-consumer, Python) — a new RPC + a …View projection that drops internal fields, plus a servicer that enforces per-user access.
• The BFF (soundverse-saas-2.0, TypeScript) — a route.ts handler that turns a plain HTTP request into a typed Connect call and serializes the reply to JSON.

This proto is hand-written — not codegen-driven

consumer.proto carries no db_options / SQL annotations. Unlike a data-service RPC (which the DB codegen plugin turns straight into a SQL-backed handler), a consumer RPC has a hand-written servicer that orchestrates one or more internal core-database calls and maps the result into a slim view. The gateway is where authorization and billing live, so it can never be pure codegen.

The plumbing you’ll touch

• Directorysoundverse-proto/proto/soundverse_proto/consumer/v1/

  • consumer.proto add the RPC + the …View message
• Directorycore-gateway-consumer/app/

  • Directorygrpc_server/

    • mappers.py internal message → consumer …View
    • Directoryservicers/ one file per service — implement the method here

      • …
  • main.py register the servicer on the gRPC server
  • update-proto.sh pull the regenerated Python SDK
• Directorysoundverse-saas-2.0/

  • Directoryapp/api/ your-route/route.ts the BFF handler (runProxy)

    • …
  • Directorylib/grpc/ client.ts · proxy.ts · endpoints.ts · auth-metadata.ts

    • …
  • lib/api/consumer.ts browser-side wrapper (ApiError)

Steps

1. Add the RPC + a …View message to consumer.proto — plain proto, no SQL annotations. Model the response on an existing …View (e.g. GenerationView, ToolView, LibraryItemView): it deliberately omits internal-only fields — owner/creator ids, billing ids, raw payloads, blob URLs. The consumer gateway serves five services today — GenerationService, WorkspaceProjectService, AccountService, LibraryService, and NotificationService — so add your RPC to whichever one fits.

2. Add a mapper in mappers.py that projects the internal message onto your view, dropping internal fields by omission. This is the one place a field is allowed to cross the trust boundary:

   app/grpc_server/mappers.py

   def tool_view(tool: tool_pb2.Tool) -> consumer_pb2.ToolView:
       """Consumer-safe projection — no credentials, pricing, or rate-limit
       internals; input_schema_json is forwarded so the AI Tools panel can
       build its form from the registered schema."""
       return consumer_pb2.ToolView(
           id=tool.id,
           name=tool.name,
           operation=tool.operation,
           model=tool.model,
           description=tool.description,
           cost_unit=tool.cost_unit,
           input_schema_json=tool.input_schema_json,
       )

3. Implement the servicer method under app/grpc_server/servicers/ and enforce access yourself. core-database does no per-user authz — the servicer is the guard. Resolve the caller from the auth interceptor, build a RequestContext, call the internal client with metadata=self._clients.auth_metadata, and map the result:

   app/grpc_server/servicers/workspace.py

   async def GetWorkspace(self, request, context):
       caller = current_caller()                      # from AuthInterceptor
       ws = await self._assert_workspace_access(       # PERMISSION_DENIED / NOT_FOUND
           request.workspace_id, caller.user_id, context
       )
       return consumer_pb2.GetWorkspaceResponse(workspace=mappers.workspace_view(ws))

   If your RPC is a servicer on a new service, register it in app/main.py with consumer_pb2_grpc.add_<Name>ServiceServicer_to_server(...). Adding a method to an existing service needs no registration change.

4. Refresh stubs and redeploy the gateway. A consumer.proto change is a proto change, so it rides the proto → deploy cascade: it republishes both soundverse-proto-python (for the gateway) and soundverse-proto-web (for the BFF). In core-gateway-consumer run ./update-proto.sh to pull the new Python SDK (how to refresh stubs), then deploy the gateway.

5. Add the BFF route. Create app/api/<your-route>/route.ts (Node runtime, force-dynamic). It reads a typed Connect client from lib/grpc/client.ts, wraps the call in runProxy, and serializes with toJson(<Response>Schema, resp). A whole route is one line of intent:

   app/api/workspaces/route.ts

   import { toJson } from "@bufbuild/protobuf";
   import { ListWorkspacesResponseSchema }
     from "@soundversegit/soundverse-proto-web/soundverse_proto/consumer/v1/consumer_pb";
   import { getWorkspaceProjectClient } from "@/lib/grpc/client";
   import { runProxy } from "@/lib/grpc/proxy";
   
   export const runtime = "nodejs";
   export const dynamic = "force-dynamic";
   
   export async function GET(req: Request) {
     return runProxy(req, async (opts) => {
       const resp = await getWorkspaceProjectClient().listWorkspaces({ /* … */ }, opts);
       return toJson(ListWorkspacesResponseSchema, resp);   // int64-safe JSON
     });
   }

   If you added a new consumer service (not just a method), also add a get<Name>Client() accessor in lib/grpc/client.ts — it resolves the endpoint from the CORE_GATEWAY_CONSUMER_GRPC env var (name only; the deploy pipeline injects the value) via lib/grpc/endpoints.ts.

6. Expose it to the UI. Add a thin wrapper in lib/api/consumer.ts so components call listWorkspaces(), never a raw fetch. That module is the single seam the SPA imports; it also throws ApiError (carrying friendlyMessage + traceId) so every call site gets a clean, copyable error.

The runProxy pattern

Every /api/* handler funnels through one wrapper — lib/grpc/proxy.ts — which does three things so each route stays a one-liner:

1. Authenticate. authCallOptions(req) resolves the upstream bearer — from an explicit Authorization: Bearer header (native/mobile clients, forwarded verbatim), else off the encrypted Auth.js session cookie — and returns the call options, or throws UnauthenticatedError → HTTP 401. The bearer stays server-side; the browser never sees it (see Identity & auth).
2. Continue the trace. It extracts the inbound W3C traceparent and runs the call under it, and the gRPC OTel interceptor injects it into the outbound metadata — linking browser → BFF → gateway → worker into one trace.
3. Map the reply. A success becomes Response.json(...); a ConnectError is translated to a real HTTP status plus a structured JSON body.

Connect code → HTTP status

runProxy faithfully maps each Connect Code to a real HTTP status (the error-handling overhaul stopped collapsing everything to a blanket 500), so the browser sees the true outcome. Genuinely-unknown codes fall back to 500.

Connect Code	HTTP	Connect Code	HTTP
InvalidArgument	400	ResourceExhausted	429
Unauthenticated	401	FailedPrecondition	412
PermissionDenied	403	Unimplemented	501
NotFound	404	Unavailable	503
AlreadyExists	409	DeadlineExceeded	504
Canceled	499	(unknown)	500

The error body unpacks the gateway’s structured ErrorDetail into { error, code, friendlyMessage, retryable, requestId, traceId }. The browser-side ApiError class in lib/api/consumer.ts reads that same shape back out, so a component gets a friendly message and a copyable trace id that opens the exact SigNoz trace. For the upstream half of this map — the DB-error → Connect-code translation — see the proto contract reference.

Representative routes → RPCs

A verified sample of the current map (the full table lives in the BFF routes reference):

HTTP route	Verb(s)	consumer.v1 RPC
/api/account	GET	AccountService.GetCurrentUser
/api/account/balance	GET	AccountService.GetTokenBalance
/api/generation	POST	GenerationService.CreateGeneration
/api/generation/[taskId]/stream	GET (SSE)	GenerationService.StreamGeneration
/api/tools	GET	GenerationService.ListTools
/api/library	GET	LibraryService.ListLibrary
/api/library/upload	POST	LibraryService.UploadFile (client-streaming)
/api/library/mint-url, /api/library/stream-url	POST	LibraryService.MintDownloadUrl
/api/workspaces	GET / POST	WorkspaceProjectService.ListWorkspaces / CreateWorkspace
/api/projects	GET / POST	WorkspaceProjectService.ListProjects / CreateProject
/api/projects/[projectId]/messages	GET / POST / PATCH	ListProjectMessages / CreateMessage / UpdateMessage
/api/notifications	GET	NotificationService.ListNotifications

The traps that will actually bite you

core-database has no per-user authz — your servicer is the guard

The data plane trusts the internal caller. It does not check whether this user owns this workspace/project/file. If your servicer forwards a client-supplied id to core-database without an ownership check, you’ve built an IDOR. Follow the existing pattern: _assert_workspace_access / assert_project_owner before any read, aborting with PERMISSION_DENIED or NOT_FOUND. Never trust a client-sent workspaceId — adopt the scope the server resolves.

Serialize with toJson(<Response>Schema, resp), not JSON.stringify

Consumer messages carry int64 fields (token amounts, sizes) that JavaScript can’t hold as a number. toJson(SomeResponseSchema, resp) emits them as strings and omits empty defaults; a bare JSON.stringify silently corrupts large integers. The browser wrapper normalizes omitted array fields back to [].

Two SDKs, refreshed two different ways

A consumer.proto change must reach both consumers. The gateway pulls soundverse-proto-python via ./update-proto.sh (Python side of the cascade); the frontend pulls @soundversegit/soundverse-proto-web (pinned to #staging). If the BFF still imports an old descriptor, your new field is simply absent from the JSON — deploy them together.

Some capabilities need no new route at all

If your feature is a new tool, you get its UI for free — the AI Tools panel is schema-driven off ListTools, so a clean Pydantic input model is the form. See Wire a tool into the AI Tools panel. Only reach for a new consumer RPC when you need a genuinely new capability the existing services don’t cover.

Related

• BFF routes → RPC map — the full route catalog
• core-gateway-consumer — the trust boundary in depth
• Frontend architecture (SPA + BFF) — why the browser never speaks gRPC
• Drive the proto → deploy cascade — shipping the contract change
• Add a field or RPC to a data service — the codegen-driven other half
• Identity & auth — how the bearer stays server-side