Skip to content

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.com and workmanager.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).

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.* and Pubsub.* gRPC RPCs. The other two services use a Virtufin.Api.Client NuGet 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