Skip to content

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]

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

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:

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