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.

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.

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.

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