Pages and navigation¶
What the app shows is data, in two layers kept apart:
- the navigation structure — what exists and how it is grouped: a tree of entries, each opening a built-in view or a page, or holding children. It means the same to every client (the TUI reads the same structure).
- the representation profile — how this browser draws each level: tab bars, sidebar sections, links, nested entries. It never goes into the structure.
And the views themselves are mostly pages: JSON documents rendered from a fixed catalog of components over declared data sources.
The navigation structure¶
{
"$schema": "https://app.virtufin.com/schemas/navigation.v1.schema.json",
"version": 1,
"nodes": [
{ "id": "home", "label": "Home", "view": "home" },
{ "id": "trading", "label": "Trading", "children": [
{ "id": "feeds", "label": "Feeds", "view": "feeds" },
{ "id": "overview", "label": "Workers overview", "page": "workers_overview" }
] }
]
}
| Field | Meaning |
|---|---|
version |
1. A structure of a newer version is refused (this structure needs a newer client). |
nodes |
The top level: at least one node. |
id |
Lower-case letters, digits and _ (at most 32, with a letter); unique among its siblings. The node's part of its route: /trading/feeds. |
label |
What the app shows. |
exactly one of view, page, children |
view: a built-in View Id; page: a page name; children: at least one node. |
emphasis |
primary or secondary: a hint (tabs drawn bold or muted). |
protected |
true: an editor may move this node but not remove it, nor a group holding it. |
At most 4 levels deep. View Ids: home, feeds, instruments, orderbook,
indicators, portfolio, pnl, risk, strategy, scenario, workers,
connections, triggers, states, eventstores, alerts, changes, events,
services, scripts, ai, pages, navigation. An unknown View Id or a page that does
not exist is not an error: the entry shows a placeholder.
Which structure is used, first valid one wins:
- Yours: saved in this browser (
localStorage, keyvirtufin.navigation) from Config > Navigation. - The context's shared one:
cfg.navigationin the context's state store (domain-devkitvirtufin.pages), shared by an admin. - The built-in default (
src/navigation/default.json, the same as@virtufin/domain-devkitships): Home; Trading; Infra; Config; Settings.
A structure that does not validate is skipped and Config > Navigation lists its errors.
Always reachable: Pages and Navigation are added under Config when a structure lacks
them, so you can always repair it. The built-in default marks them protected.
Routes are the node ids along the path (/config/pages); a group goes to its first
entry; a path the structure does not have goes to the node that opens the view of that name
(an old bookmark), else Home with a notice.
The representation profile¶
{version: 1, levels: [...]}: the kind of each depth, deeper levels using the last.
| Kind | Drawn as |
|---|---|
tabs |
A tab bar under the header (the first level; at the second, a sub-tab bar below it). Only the first one or two levels, and with a level below them. |
sections |
Headings in the sidebar. |
links |
Entries in the sidebar. |
nested |
Entries indented under their parent. |
The default is ["tabs", "links", "nested"]: the top level as tabs, the rest in the
sidebar. Presets in Config > Navigation: Tabs and sidebar (the default), Tabs and
sub-tabs (["tabs", "tabs", "nested"]), Sidebar with sections
(["sections", "links", "nested"]), Sidebar tree (["nested"]). Kept in this browser
(virtufin.navigation.profile). The tabs are a Reka UI NavigationMenu (arrow keys between
tabs), the sidebar a Reka UI Tree.
The navigation editor¶
Config > Navigation:
- In use: which structure is used (yours, shared, built-in) and the errors of a structure that was skipped; whether the context has a shared structure.
- Your structure: one draft, validated as it changes.
- Drag and drop: drag by ⠿ to reorder or nest (within and between levels, into
groups); the Add palette on the right holds New group, every view and every page
(built-in, shared, yours) — drag one into the tree; labels edit in place; ⊞ turns an
entry into a group (keeping what it opens as its first entry); ✕ removes. 🔒 entries
(
"protected": true) move but cannot be removed, nor a group holding one. - JSON: the same draft as text.
- Save keeps it as your structure in this browser (refused while invalid, or when it drops or unprotects a protected entry). Reset discards your structure: back to the shared one or the default.
- Share (Share (replaces the shared one)) saves the draft as the context's shared structure for everyone; Unshare removes it. Admins only, writes through the write gate.
- Drag and drop: drag by ⠿ to reorder or nest (within and between levels, into
groups); the Add palette on the right holds New group, every view and every page
(built-in, shared, yours) — drag one into the tree; labels edit in place; ⊞ turns an
entry into a group (keeping what it opens as its first entry); ✕ removes. 🔒 entries
(
- Profile (this browser): the presets, Default, or the JSON and Apply.
Pages¶
A page is a JSON envelope:
{
"version": 1,
"name": "workers_overview",
"title": "Workers overview",
"sources": {
"workers": {
"invoke": {
"service": "workmanager",
"method": "ListWorkers",
"refreshOn": [{ "entity": "virtufin.service.workmanager/worker", "event": "lifecycle" }]
}
},
"lifecycle": {
"topic": {
"name": { "entity": "virtufin.service.workmanager/worker", "event": "lifecycle" },
"keep": { "last": 20 }
}
}
},
"spec": {
"root": "page",
"elements": {
"page": { "type": "Stack", "props": { "direction": "vertical", "gap": 12 }, "children": ["title", "running", "events"] },
"title": { "type": "Heading", "props": { "text": "Workers overview", "level": 2 }, "children": [] },
"running": { "type": "WorkerTable", "props": { "source": { "$state": "/sources/workers" }, "filter": "status:running", "tableId": "overview-running" }, "children": [] },
"events": { "type": "ValueStream", "props": { "source": { "$state": "/sources/lifecycle" }, "title": "Lifecycle events" }, "children": [] }
}
}
}
| Field | Meaning |
|---|---|
version |
1. |
name |
Lower-case letters, digits and _ (at most 32, with a letter). What a navigation page entry names. |
title |
Shown in the Pages list and the palette. |
sources |
The page's data, by id (letters, digits, _): see below. |
spec |
A @json-render spec: root and elements, each with type (a catalog component), props and children. |
Data sources¶
A page gets data only from its declared sources. Each source's result is at
/sources/<id> as {status, data, error, since} (status: loading, ready, stale,
failed; a failed read keeps the last data and says it is stale); a prop binds it with
{"$state": "/sources/<id>"}.
| Source | Shape | Reads |
|---|---|---|
invoke |
{service, method, request?, refreshOn?} |
A backend read: the method must start with List or Get (e.g. workmanager ListWorkers). Read again on each event of the refreshOn topics. For the WorkManager the request is checked against its schema. |
state |
{key, service?} |
One state key (service default statestore). |
topic |
{name, keep} |
A topic's events: keep is "latest" or {"last": N} (N at most 500). |
Topics and keys are named through the naming library, never as strings:
{entity, event, params} — e.g. {"entity": "virtufin.service.workmanager/worker", "event":
"lifecycle"}. A name the library cannot resolve is a validation error at its path.
A page opens at most 8 subscriptions (topic sources plus refreshOn topics). While a
source's subscription is down (or not live yet) it is read every 2 s and the subscription
is opened again with backoff (1 s up to 30 s).
The component catalog¶
What a page may use (src/pages/catalog.ts); props are checked against each component's
schema, and no component renders markup taken from a page. The catalog with each
component's props JSON Schema is published at /schemas/page-catalog.v1.json
(Schemas).
| Component | Props | What it shows |
|---|---|---|
Stack |
direction (vertical/horizontal), gap (0–48) |
Lays its children out in a column or a row. |
Heading |
text, level (1–3) |
A heading. |
Text |
text |
A paragraph of plain text. |
WorkerTable |
source, filter (a worker filter expression), tableId |
The workers of a ListWorkers invoke source in the data grid. |
ValueStream |
source, title |
The values of a topic or state source, newest first. |
WorkerBrowser |
workers, lifecycle |
The Workers view. |
ConnectionBrowser |
workers, lifecycle, metrics |
The Connections view. |
FeedBrowser |
workers, lifecycle, metrics |
The Feeds view. |
EventStoreBrowser |
workers, lifecycle, metrics |
The EventStores view. |
StrategyBrowser |
workers |
The Strategy view. |
ScenarioBrowser, TriggerBrowser, StateBrowser, EventBrowser, InstrumentBrowser, OrderBookBrowser, IndicatorBrowser, PortfolioBrowser, PnlBrowser, RiskBrowser, ScriptBrowser |
none | The view of that name. |
The browser components carry their views' actions; their writes go through the write gate as in the views.
Built-in, shared and your pages¶
| Kind | Where | Who changes it |
|---|---|---|
| Built-in | Shipped with the app (src/pages/builtin/): feeds, instruments, orderbook, indicators, portfolio, pnl, risk, scripts, strategy, scenario, workers, connections, triggers, states, eventstores, events, workers_overview. |
Nobody: read only, Copy to change. |
| Shared | On the context: the envelope at cfg.page.<NAME> (the name upper-cased), the names in cfg.page.index (updated by compare-and-swap). Followed live through the state-change topics. Every client of the context sees them (the TUI renders them too). |
Admins: Share, × to unshare (writes). |
| Yours | This browser (localStorage, key virtufin.pages), as text, so a draft that does not validate yet is kept too. |
You. |
When a navigation entry names a page, yours wins over a shared one, which wins over a built-in one of the same name.
Config > Pages lists the three kinds; New page, Copy, Edit JSON (validated as you type, errors with their paths, the last valid version still shown), Share, Generate… and Change with AI… (AI-generated pages). To show a page in the navigation, drag it from the palette in Config > Navigation (Make a page).