Service wiring
How the API Gateway, the WorkManager and its Runtime are wired together. To deploy them, see Cross-Service Integration Guide.
Related specs
- cross-cutting spec — the architectural rule (api is the only service that talks to Dapr directly; per-service pubsub topics; per-service state)
- worker-management spec — worker lifecycle event contract
- websocket-feed spec — the WebSocketFeed worker: one WebSocket connection per worker
Topic ownership
Per the cross-cutting spec, each service owns one lifecycle topic:
| Service | Topic | Defined in |
|---|---|---|
| WorkManager | sys.workmanager.worker.lifecycle |
naming/virtufin.service.workmanager.yaml (WorkManagerNames.WorkerLifecycleTopic) |
A WebSocket connection's status (connecting, connected,
reconnecting, disconnected, degraded, released) is its
WebSocketFeed worker's lifecycle status event on this topic; its
frames go out as com.virtufin.websocketfeed.message on the topic the
feed is configured with (virtufin.worker.websocketfeed fragment,
general-workers WebSocketDevKit).
The API itself does not own a lifecycle topic — it is the
messaging substrate, not a participant. Workers do not own
topics either; they receive commands on the topic assigned at
deployment time by the WorkManager (e.g. wrk.httpget.command.{worker_id}, expanded to the new worker's id).
Wiring diagram
┌──────────────────────────┐
│ api │
│ (only Dapr-aware svc) │
└────┬──────────┬──────────┘
│ │
State.* gRPC │ │ Pubsub.* gRPC
│ │
┌────────────────┼──────────┼─────────────────┐
│ │ │ │
v v v v
┌────────────────────┐ ┌────────────────────┐
│ virtufin-work- │ │ external clients │
│ manager │ │ (browser, SDKs) │
│ - owns: sys.work- │ │ - talk via api │
│ manager.worker. │ │ gRPC │
│ lifecycle │ └────────────────────┘
│ - deploys workers │
└─────────┬──────────┘
│
│ deploys
v
┌────────────────────────┐
│ worker processes │
│ (DotNetDLL, Native, │
│ Python, CSharpSrc), │
│ WebSocketFeed: one │
│ venue socket each │
└────────────────────────┘
Reading the diagram: Solid arrows are gRPC + Dapr-backed calls. The API is the only service that holds Dapr components; the WorkManager routes everything through the API gRPC interface. Workers are spawned by the WorkManager and have no direct Dapr access.
Shared Dapr components
The services share a single Dapr installation and a single set of components. Per the cross-cutting spec §Per-service State Service Names, each service uses its own state service entry but the underlying state store is shared.
Shared components
| Component | Type | Owner | Notes |
|---|---|---|---|
statestore |
state.redis (Valkey backend) |
API only — the other services call State.* gRPCs against the API |
single backing instance |
pubsub |
pubsub.redis (Valkey streams) |
API only — same model | single backing instance |
kubernetes-secrets |
secretstores.kubernetes |
API only | Dapr resolves keys; services read via DaprClient.GetSecretAsync |
daprd (sidecar) |
per-pod | every service | each service has its own sidecar with app-protocol: grpc |
Per-service components
None. The services do not declare their own Dapr components — they share the API's components via gRPC indirection.
Service-to-service gRPC contracts
| Caller | Callee | RPC surface | Purpose |
|---|---|---|---|
| WorkManager | api | State.*, Pubsub.*, Gateway.* |
worker registry + gateway calls for worker backends |
| Worker (via DevKit) | api | Gateway.* |
service-to-service calls from worker code |
| Worker (via DevKit) | WorkManager | (none — WM owns the worker) | workers are spawned by WM |
| TUI, notebooks, scripts | WorkManager | CreateWorker, StartWorker, InvokeWorkerCommand, DeleteWorker |
open a WebSocketFeed, send / publish / unpublish / status, close it |
All gRPC contracts are exposed via the Virtufin.Api.Client and
Virtufin.WorkManager.Client NuGet packages — never call them via raw gRPC stubs unless you're
writing a new client in a language that doesn't have a SDK yet.