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),/contextsand/ctx/<name>/…(server/contexts.ts);- the built app (
dist, orVIRTUFIN_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…andGet…read;InvokeWorkerCommandwith the commandstatusreads; 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 documentssys.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/Watchstream 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.