Skip to content

Architecture

The app is a Vue 3 single-page app and one small Node server. The browser does the work — views, pages, scripts, the assistant's loop — and talks to a context's api only through the app server, which holds the contexts and their keys, signs users in, decides who may write, relays the AI chat and keeps two small per-user documents.

flowchart LR
    subgraph B["Browser (app.virtufin.com)"]
        V["Views and pages<br/>(json-render over the catalog)"]
        SR["Scripts (sandboxed iframe, vf.*)"]
        AI["AI assistant loop"]
        OP["Operation catalog"]
        WG["Write gate<br/>(admins; protected contexts ask)"]
        SUB["Subscriptions<br/>(one per topic set, backoff)"]
        V --> OP
        SR --> OP
        AI --> OP
        OP --> WG
        V --> WG
        V --> SUB
    end

    subgraph S["App server (Node, server/main.ts)"]
        AUTH["/auth/*: OIDC sign-in,<br/>session cookie"]
        CTX["/contexts, /ctx/NAME/*:<br/>catalog + HTTP/2 proxy<br/>(read/write by gRPC method)"]
        AIR["/ai/CONTEXT/*: providers (keys sealed),<br/>chat relay, models + prices"]
        CH["/changes: per-user change log"]
        ST["Static app, /schemas/*"]
    end

    IDP["OIDC provider<br/>(Pocket ID)"]
    API["virtufin-api of the context<br/>Gateway / State / Pubsub / Trigger / Health"]
    LLM["AI provider<br/>(OpenAI-compatible)"]
    LIT["LiteLLM price list"]

    B -- "gRPC-Web (text), fetch" --> CTX
    B -- "JSON" --> AIR
    B -- "JSON" --> CH
    B --> AUTH
    AUTH --> IDP
    CTX -- "h2 / h2c + x-api-key" --> API
    AIR -- "native gRPC (State)" --> API
    CH -- "native gRPC (State)" --> API
    AIR --> LLM
    AIR --> LIT

The server

One Node process (server/main.ts, bundled to dist-server/main.mjs by npm run build; the container image src/VirtufinApp/Dockerfile, listening on port 3000 or PORT) serves:

  • /healthz (for the probes);
  • /ai/<context>/… (server/ai.ts), /changes… (server/changes.ts);
  • /auth/… (server/auth.ts), /contexts and /ctx/<name>/… (server/contexts.ts);
  • the built app (dist, or VIRTUFIN_APP_STATIC_DIR) and /schemas/*.

The Vite dev and preview servers run the same middleware as a plugin (server/dev.ts), so development behaves like the deployment; sign-in is on there only when its settings are set. The deployed server refuses to start without the sign-in settings (cannot start: missing setting(s): …). The routes are on The app's API.

The proxy over HTTP/2

The browser calls a context's api with gRPC-Web (text mode) at /ctx/<name>/<Service>/<Method>. The server reads the catalog (contexts.toml) on each request, and forwards the call over HTTP/2 — h2c without TLS, h2 with — on one reused session per api, adding the context's api_key (or VIRTUFIN_API_KEY) as x-api-key. A context may therefore name the api's gRPC port directly (in-cluster), as the TUI's contexts do. Response headers are sent at once and the body streams unbuffered: a quiet subscription has no body, and the api says it is live only by its headers. Requests above 16 MiB are refused.

The WorkManager is called with typed protobuf through Gateway.Invoke (schemas from @virtufin/workmanager); JSON only where people type it (page invoke sources for other backends, the service explorer) through Gateway.InvokeJson. Pubsub.Subscribe runs over fetch, because only fetch reports the api's headers as they arrive.

The server's own calls to a context (the AI providers and change log documents) speak native gRPC over HTTP/2 (@connectrpc/connect-node), for the same reason.

Sign-in

OIDC authorization code flow with PKCE (openid-client) against the provider (Pocket ID on medusa), scopes openid profile email groups, redirect <public URL>/auth/callback. The session is an encrypted JWT (jose, A256GCM, key derived from VIRTUFIN_APP_SESSION_KEY) in the HttpOnly cookie vf_session holding the user's subject, name, email and admin flag: nothing is kept on the server, so any replica answers. A user is an admin when the provider's groups claim holds VIRTUFIN_APP_ADMIN_GROUP at sign-in.

Authorization by gRPC method

Signed out, only the sign-in page loads: /contexts, /ctx/, /ai/ and /changes answer 401. Signed in, everyone reads; only admins write. The server decides per forwarded call (server/authorize.ts):

  • Reads by method: grpc.health.v1.Health/Check, /Watch; virtufin.Gateway/ListServices, ListMethods, GetMethodSchema; virtufin.Config/ListServices, GetService; virtufin.Pubsub/Subscribe, ListTopics; virtufin.State/GetState, GetBulkState, QueryState; virtufin.Trigger/GetTrigger, ListTriggers.
  • Gateway.Invoke / InvokeJson: by the backend method inside the request: List… and Get… read; InvokeWorkerCommand with the command status reads; everything else writes.
  • Anything else writes.

A non-admin's write gets 403 only admins may write; a /ctx/ request from another Origin gets 403. The browser's write gate applies the same rule earlier, so the buttons are disabled and the reason is shown, but the server is the one that enforces it.

Per-user storage on the server side

Two documents per user and context, in the context's state store (statestore), keyed by a UUID derived from the sign-in subject (<USER>), names from @virtufin/domain-devkit:

Key Holds
cfg.ai.provider.<USER> The user's AI providers: name, base URL, model, the key sealed with AES-256-GCM (key derived by HKDF from the session key) and its last 4 characters; the default provider.
cfg.changelog.<USER> The user's change log: the newest 500 writes, appended by compare-and-swap on the etag.

Everything else a user keeps (the active context, own pages, own navigation and profile, scripts, followed topics, column widths) is in the browser's localStorage; shared documents (pages cfg.page.*, navigation cfg.navigation, feed definitions cfg.feed.*, scenarios cfg.scenario.*, strategies cfg.strategy.*) are in the context's state store, written through the write gate.

Push, not poll

The app follows changes through subscriptions, not polling:

  • Every event-followed list (page sources, the navigation, shared registries, Triggers, States, alerts) uses one subscription per topic set however many follow it (src/services/subscription.ts), reopened with backoff (1 s up to 30 s); only while it is down are the lists read every 2 s.
  • Workers, Connections, Feeds and EventStores follow the WorkManager lifecycle topic and the feeds' and stores' metrics topics; Triggers sys.api.trigger.scheduled/deleted; States and the shared documents sys.api.state.saved/deleted; Instruments, Order Book and Indicators the api's topic catalog (sys.api.topic.catalog.added).
  • Context health is one grpc.health.v1.Health/Watch stream per context.
  • States is the exception: it also reads every 2 s, only while it is shown.

Settings

Environment of the app server; the deployed server refuses to start without the first five.

Setting Meaning
VIRTUFIN_APP_OIDC_ISSUER The OIDC provider.
VIRTUFIN_APP_OIDC_CLIENT_ID, VIRTUFIN_APP_OIDC_CLIENT_SECRET Its client (redirect <public URL>/auth/callback, scopes openid profile email groups).
VIRTUFIN_APP_PUBLIC_URL Where users reach the app (the callback, the Origin check).
VIRTUFIN_APP_SESSION_KEY Encrypts the cookies and derives the AI key seal (32+ characters). Rotating it signs everyone out and makes saved AI keys unreadable.
VIRTUFIN_APP_ADMIN_GROUP The provider group of admins (default virtufin-admins).
VIRTUFIN_APP_SESSION_HOURS How long a sign-in lasts (default 12).
VIRTUFIN_CONTEXTS_FILE, VIRTUFIN_CONTEXT The catalog (default ~/.config/virtufin/api/contexts.toml) and the default context.
VIRTUFIN_API_KEY The api key for contexts without their own api_key.
VIRTUFIN_APP_AI_BASE_URL, VIRTUFIN_APP_AI_MODEL, VIRTUFIN_APP_AI_API_KEY The optional org AI provider (all three).
VIRTUFIN_APP_LLM_PRICES_URL Where the LLM price list is loaded from (default LiteLLM's model_prices_and_context_window.json on GitHub; kept a day).
VIRTUFIN_APP_AI_DOCS_SITES The docs sites the assistant reads (comma-separated base URLs; default every Virtufin docs site, reloaded daily).
VIRTUFIN_APP_STATIC_DIR, PORT The built app's directory (default ./dist) and the port (default 3000).

The dev server (npm run dev) signs no one in unless the provider settings are set; then everyone is an admin. The image is published by CI only (.github/workflows/app-image.yaml) when versions.env changes; the deployment is the k3s-common role virtufin_app.