Skip to content

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:

  1. Yours: saved in this browser (localStorage, key virtufin.navigation) from Config > Navigation.
  2. The context's shared one: cfg.navigation in the context's state store (domain-devkit virtufin.pages), shared by an admin.
  3. The built-in default (src/navigation/default.json, the same as @virtufin/domain-devkit ships): 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.
  • 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).