Components
The moving parts, each with its own sub-site. Click through for the full reference; the sketches here are the architecture overview at one zoom level deeper. The Ecosystem page lists every repo.
api — the gateway
The single public entry point (gRPC only). Aggregates the backends' gRPC reflection, forwards calls to them, and brokers pub/sub and state on behalf of the rest of the platform.
flowchart LR
subgraph VirtufinApi["api"]
GW[GatewayService]
REF[AggregatedReflectionService]
PS[PubSubService]
ST[StateService]
CFG[ConfigService]
end
GW --> REF
PS <--> DAPR1[(Dapr PubSub)]
ST <--> DAPR2[(Dapr State)]
CFG --> Files[services.json]
- Repo: virtufin/api
- Sub-site: api.docs.virtufin.com
- Spec: api-gateway spec
WebSocketFeed — upstream connections as workers
The platform's upstream WebSocket connections to exchanges and data
feeds are workers: one
WebSocketFeed
worker (general-workers) per connection. It opens the socket when the
Runtime starts it, logs in (Alpaca from worker secrets), subscribes,
and publishes every frame as a CloudEvent v1.0 envelope
(com.virtufin.websocketfeed.message) on act.exchange.<venue>.*
topics (the live market world) through the Runtime's outbox, only
while it holds the worker's lease. The rest of the platform never
talks to an exchange directly.
A feed serves topics: it is told which topics to fill (the serve
command), maps each one to a venue item with rules its venue preset renders
from the naming fragments, and routes every frame to its topic. A worker
that needs market data names only its input topics; an orchestrator (a
notebook, a script, the TUI) opens the feeds that serve them with
market-data-devkit's FeedResolver/FeedOrchestrator. Nothing in the
platform matches topics to feeds, and workers and feeds start in any order.
flowchart LR
EX[Upstream feed<br/>Binance, Alpaca, etc.]
F[WebSocketFeed worker<br/>in the WorkManager Runtime]
API[API gateway]
EX <-->|WebSocket| F
F -->|CloudEvent<br/>act.exchange.<venue>.*| API
- Repo: virtufin/general-workers (
WebSocketFeed,WebSocketDevKit) - Docs: general-workers.docs.virtufin.com/websocketfeed
- Spec: websocket-feed spec
A feed is managed like any worker: CreateWorker + StartWorker to
connect, ListWorkers and the tag RPCs to find it, the WorkManager's
InvokeWorkerCommand for send, publish, unpublish and status,
DeleteWorker to disconnect. Its status (connected, reconnecting,
degraded, …) arrives as worker lifecycle status events. It
replaced the WebSocketManager service, retired and removed from the
deployment on 2026-10-31
(workmanager#103).
workmanager — the worker catalog and runtime
The WorkManager owns each worker's identity, configuration and lifecycle, and exposes the worker-management gRPC interface. It runs no worker code: the WorkManager Runtime hosts every worker in a per-engine Dapr actor, loads its code, subscribes to its topics through the gateway and publishes its output.
flowchart TB
WM[WorkManager<br/>catalog and router]
subgraph RT["WorkManager Runtime"]
E1[DotNetDllEngine<br/>in-process]
E2[PythonEngine<br/>child process]
E3[NativeDllEngine<br/>in-process]
E4[CSharpSourceEngine<br/>child process, Roslyn]
E5[TypeScriptEngine<br/>child process, Node]
end
WM --> RT
E1 --> W1[Worker DLL]
E2 --> W2[Python worker]
E3 --> W3[Native .so]
E4 --> W4[C# source]
E5 --> W5[TypeScript worker]
Two delivery behaviours shape how you run workers:
- Shard groups. By default every worker on a topic gets every event. A worker that joins a shard takes one slot, and an event goes to the slot its subject hashes to, so several copies split a topic.
-
Input replay. A worker's inputs survive a move: the Runtime keeps a cursor per topic and catches the worker up from what the topic's stream still retains. Delivery is at least once.
-
Repo: virtufin/workmanager
- Sub-site: workmanager.docs.virtufin.com
- Spec: worker-management spec
Workers and devkits
Workers are built with the
Worker DevKit and the
domain devkits on top of it (strategy, execution, indicator, market
data), and live in one workers repo per domain.
general-workers holds
the small, cross-domain samples (GetTime, Hello, HttpGet);
the Ecosystem page lists the others.
openspec — the spec
The single source of truth for every cross-cutting contract on the platform. Specs are merged via the OpenSpec workflow (propose / continue / apply / verify / archive). The services above link back to the relevant spec page.
flowchart LR
SPEC[openspec<br/>specs/*.md]
API[API gateway] -.implements.-> SPEC
WM[WorkManager] -.implements.-> SPEC
WK[Workers] -.implements.-> SPEC
- Repo: virtufin/openspec
- Sub-site: specs.docs.virtufin.com
- Workflow:
opsx-propose/opsx-continue/opsx-apply/opsx-verify/opsx-archive