Cross-Service Integration Guide
This guide walks a developer from a clean machine to a working Virtufin backend: the API Gateway and the WorkManager (with its Runtime). It covers deploy order, the Dapr components they share, topic ownership, and a minimal single-node deployment.
Scope: The services covered here are documented at
api.docs.virtufin.comandworkmanager.docs.virtufin.com; this guide focuses on the wiring between them. WebSocket connections to venues are not a service of their own: each one is a WebSocketFeed worker (general-workers), created and started through the WorkManager like any other worker. The WebSocketManager service it replaced is retired (workmanager#103).
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
Deploy order
The services have a strict startup dependency:
1. api (must be first — every other service talks to it)
|
v
2. virtufin-workmanager (subscribes to api state + pubsub, plus deploys workers,
+ workmanager-runtime WebSocketFeed connections included)
Why this order?
- api is the only service that talks to Dapr pubsub
and the state store directly. Per the
cross-cutting spec §Per-service Pubsub Topics,
all state and pubsub operations go through the API's
State.*andPubsub.*gRPC RPCs. The other two services use aVirtufin.Api.ClientNuGet wrapper that calls those RPCs. - virtufin-workmanager talks only to the API for state, pubsub, and gateway calls (workers route their backend service calls through the API Gateway). A WebSocketFeed worker publishes its frames through its Runtime's outbox under the worker lease, which is the API's publication fence keyed by the worker id.
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.
Health-check sequence at startup
Each service has a IHostedService (or equivalent) that gates
its readiness probe. Recommended Kubernetes probe config:
readinessProbe:
httpGet:
path: /health
port: 5001
initialDelaySeconds: 5
periodSeconds: 10
livenessProbe:
httpGet:
path: /health/live
port: 5001
initialDelaySeconds: 30
periodSeconds: 30
Service readiness gates:
| Service | Readiness gates |
|---|---|
api |
Dapr sidecar healthy + state store reachable + pubsub broker reachable |
virtufin-workmanager |
none of its own (/ready is always healthy; it keeps no worker state). The Runtime is ready once its DotNetDll bridge is warm. |
The dependency order matters: do not mark a downstream service ready until the API gRPC handshake succeeds. If the API is restarted, downstream services will need to re-handshake; they should fail their liveness probe and the orchestrator will restart them.
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.
Minimal single-node deployment
Run the whole backend (API, WorkManager and Runtime) on one machine
with virtufin/deploy-local:
each service built from source and started natively with dapr run, configured by
rendering the helm chart (scripts/deploy.sh, which runs scripts/render.sh). Only
Redis runs in Docker. See its README for the ports and the per-service commands.
Minimal Kubernetes deployment
For a single-node Kubernetes deployment (kind, minikube, or
a small cluster):
apiVersion: apps/v1
kind: Deployment
metadata: { name: api }
spec:
replicas: 1
selector: { matchLabels: { app: api } }
template:
metadata:
labels: { app: api }
annotations:
dapr.io/enabled: "true"
dapr.io/app-id: "api"
dapr.io/app-port: "5001"
dapr.io/app-protocol: "grpc"
dapr.io/enable-app-health-check: "false"
spec:
containers:
- name: api
image: virtufin/api:0.13.1
ports: [{ containerPort: 5001 }, { containerPort: 5002 }]
env:
- { name: ASPNETCORE_URLS, value: "http://+:5001" }
- { name: VIRTUFIN_GRPC_PORT, value: "5002" }
---
apiVersion: v1
kind: Service
metadata: { name: api }
spec:
selector: { app: api }
ports:
- { name: http, port: 5001, targetPort: 5001 }
- { name: grpc, port: 5002, targetPort: 5002 }
The WorkManager and Runtime deployments are identical
except for app-id and image, with one extra env var:
env:
- { name: VIRTUFIN_API_HOST, value: "api" }
- { name: VIRTUFIN_API_GRPC_PORT, value: "5002" }
The dependency chain is enforced by Kubernetes' normal pod scheduling — the API pod just needs to be ready before the downstream services start their gRPC handshake.
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.
Verifying the deployment
After the services report Healthy, run this sanity check
from any pod with grpcurl available:
# API health
grpcurl -plaintext api:5002 grpc.health.v1.Health/Check
# Subscribe to the worker lifecycle topic via the API (leave it running)
grpcurl -plaintext -d '{"topics":["sys.workmanager.worker.lifecycle"]}' \
api:5002 virtufin.Pubsub/Subscribe
# In a second shell: publish a test event via the API (it reaches the subscriber)
grpcurl -plaintext -d '{"topic":"sys.workmanager.worker.lifecycle","cloudevent":{"id":"smoke-1","source":"urn:test","specVersion":"1.0","type":"com.virtufin.workmanager.worker.lifecycle","textData":"{\"state\":\"status\",\"worker_id\":\"smoke\",\"status\":\"connected\"}"}}' \
api:5002 virtufin.Pubsub/PublishEvent
If the subscriber prints the event, the wiring is functional. Stop the subscription with Ctrl-C.
See also
- Getting Started — single-service WM quick start
- Architecture — WM-specific architecture details
- Worker.Host — the worker runtime contract; authoring is in Worker.DevKit
- Security — Dapr mTLS, content-source allow-list, audit logging
- WebSocketFeed — WebSocket connections as workers