web-app Specification
Purpose
The web app (app, app.virtufin.com): the browser binding of operator-clients, its transport and app server, sign-in and deployment, pages rendered with @json-render/vue (page-specs) and the navigation drawn by its representation profile (navigation-specs).
Requirements
Requirement: Web App Binding
The web app (app, Vue 3) SHALL implement operator-clients and value-presentation for the views it offers. This spec says only how: transport, contexts, routes and controls.
Scenario: Same answers as the TUI
- WHEN the app's CI runs
- THEN it SHALL run the shared value-presentation conformance vectors (kinds, filter expressions, Worker Filter, name tree as each lands) and get the same answers as the TUI
Requirement: Transport
The app SHALL call the API over gRPC-Web on its own origin. It SHALL use generated stubs for the API's own services (Gateway, Pubsub, State, Config). It SHALL call a backend whose generated schemas it ships (the WorkManager, from @virtufin/workmanager) with typed protobuf messages through Gateway.Invoke (operator-clients, Backend Access through the Gateway): built and read with protobuf-es, so field names are checked when the app is built and no JSON is on the way. JSON SHALL be only where people type it: a page's invoke request (converted with the generated schema for such a backend, else sent with Gateway.InvokeJson) and the service explorer (Gateway.InvokeJson); gRPC server reflection is a bidirectional stream gRPC-Web cannot carry. Server streams SHALL use the gRPC-Web text mode, so events arrive as they come. Pubsub.Subscribe SHALL run over fetch, which resolves when the response headers arrive: the api sends them once every topic's subscription is registered, and that is when the stream is live (the grpc-web library reports headers only when a stream ends).
Scenario: A WorkManager call
- WHEN the app lists workers
- THEN it SHALL send
Gateway.Invokewith serviceworkmanager, methodListWorkersand the encodedListWorkersRequest, and decode the bytes as aListWorkersResponse
Scenario: A page's WorkManager request
- WHEN a page's
invokesource namesworkmanagerand a method it lacks, or a request that does not fit the method's input - THEN page validation SHALL refuse it, naming the problem
Requirement: Contexts through the App Server
The app's server side (the Vite dev server; a deployed server serves the same paths) SHALL hold the catalog of contexts, the same contexts.toml the TUI reads. It SHALL list the contexts at /contexts with their name, description and protected, and never their endpoint credentials, and SHALL proxy /ctx/<name>/… to that context's API, adding its API key as x-api-key. API keys SHALL NOT reach the browser. The active context SHALL be state kept in the browser (per user and browser), not in the catalog.
Scenario: Pick a context
- WHEN the user picks a context from the context menu
- THEN the app SHALL check that
/ctx/<name>/answers a gateway call, then switch to it and remember it for the next visit
Scenario: Keys stay on the server
- WHEN the browser fetches
/contextsor any app asset - THEN no API key SHALL be in the response
Requirement: Layout and Controls
The app SHALL show a bar with the active context (its name, its health dot, red with a note when protected), the navigation in use drawn by its representation profile (navigation-specs; web-app, Navigation Representation), and one route per node (e.g. /infra/workers). The API service explorer SHALL be under Infra as Services. Notices (<Action> failed: <reason>, undo offers) SHALL be toasts; a stale view SHALL show its stale note above its table.
Scenario: Deep link
- WHEN the user opens
/infra/workersdirectly - THEN the app SHALL open the Workers view for the remembered context
Scenario: The footer
- WHEN any screen of the app is shown, the sign-in screen included
- THEN a footer SHALL show the copyright on the left (
© 2026 Haener Consulting. All rights reserved) and on the rightVersion <version> | Build <build date, UTC> | Commit <short commit>, the build values fixed when the app is built (the image build passes the CI's build date and commit)
Requirement: Data Grid
Every table in the app SHALL be one shared grid component built on TanStack Table v9 with virtual rows, implementing operator-clients Tables:
- the grid SHALL receive only the rows that pass the filter (the filter is the value-presentation expression language, never the grid's own);
- rows SHALL be keyed, so updates keep the selection, the marks and the scroll position;
- cells SHALL be bounded, with the full value in a popover on demand;
- columns SHALL be resizable by dragging the header edge, the widths kept in the browser per table and header;
- clicking a header SHALL sort by it, again reversed;
- one row SHALL be selected (click, arrow keys), rows SHALL be marked with a checkbox or space;
- light and dark themes SHALL come from CSS variables.
Scenario: Live updates under load
- WHEN a list of 5000 rows receives 100 updates per second while sorted and filtered
- THEN every update SHALL be applied, rows SHALL stay sorted and filtered, and the selection, the marks and the scroll position SHALL stay
Requirement: Sign-in
The app server SHALL sign users in with an OIDC provider, by the authorization code flow with PKCE, and SHALL keep the session in an encrypted, HttpOnly, SameSite=Lax cookie that expires. /auth/login SHALL start the flow, /auth/callback finish it, /auth/logout end the session, and /auth/me SHALL return the signed-in user's name and email and whether they are an admin, or 401. The bar SHALL show a login button when no one is signed in, and the user, an admin badge for an admin, and a logout control when someone is.
Scenario: Sign in
- WHEN a signed-out user opens the app and presses the login button
- THEN the app SHALL send them to the provider and, after the provider's callback, back to the page they opened, signed in, the bar showing their name
Scenario: Admin badge
- WHEN the signed-in user is a member of the configured admin group
- THEN the bar SHALL show the admin badge next to their name
Scenario: Session ends
- WHEN the session cookie has expired or the user logged out
- THEN
/auth/meSHALL answer 401 and the app SHALL show the login button
Requirement: Roles and Server-Side Authorization
The app server SHALL decide what a request may do, not only the UI: without a session, /contexts and /ctx/… SHALL answer 401 and the app SHALL show only the login page; a signed-in user SHALL read; an admin (a member of the provider group the server is configured with) SHALL also write. The server SHALL classify each call by its gRPC method: health, Gateway listing and schema calls, Pubsub.Subscribe and ListTopics, State.GetState and QueryState and the Config service SHALL be reads; for Gateway.Invoke and Gateway.InvokeJson the backend method in the request SHALL decide, List* and Get* being reads; every other call SHALL be a write. A non-admin's write SHALL be refused with 403 before it reaches the api. The UI SHALL disable write controls for a non-admin and say why. The server SHALL refuse a /ctx/… request whose Origin is not the app's own. A protected context SHALL still ask before an admin's write (operator-clients, Contexts).
Scenario: A reader's write
- WHEN a signed-in user who is no admin sends
Gateway.InvokeJsonforworkmanagerStopWorker - THEN the server SHALL answer 403 and nothing SHALL reach the api
Scenario: An admin's write
- WHEN an admin stops a worker on the protected context
- THEN the app SHALL ask first, and on yes the server SHALL forward the call
Scenario: Another origin
- WHEN a request to
/ctx/…carries anOriginother than the app's - THEN the server SHALL refuse it with 403
Requirement: Forwarding over HTTP/2
The app server SHALL forward /ctx/<name>/… to the context's api over HTTP/2: h2c to a context without TLS, h2 to one with TLS, streaming both ways and sending the response headers as soon as they arrive. So the same contexts.toml entries the TUI uses SHALL work, the api's gRPC port included.
Scenario: In-cluster api
- WHEN the deployed app's context names the api Service's gRPC port without TLS
- THEN the app SHALL list workers and follow the lifecycle topic through it
Requirement: Deployed Server
One Node server SHALL serve the built app, /contexts, /ctx/… and /auth/…. Its settings SHALL be named and come from the environment: the provider issuer, the client id and secret, the admin group, the public URL, the session key and lifetime, and the catalog file. The dev server SHALL need no sign-in unless the provider settings are present.
Scenario: Missing settings
- WHEN the deployed server starts without a provider issuer or session key
- THEN it SHALL refuse to start and name the missing setting
Requirement: Pages in the Web App
The web app SHALL render every page with @json-render/vue, at a pinned exact version, behind the page envelope (page-specs), with its catalog's prop schemas in zod and published as JSON Schema. It SHALL offer a Pages view: the user's pages, a JSON editor with the validation errors, and copying a built-in page. Its built-in views SHALL move to shipped page specs one at a time, each with unchanged behaviour shown by its existing tests. The prototype JSON-render mode of the service explorer and the json-render-vue package SHALL be removed.
Scenario: Edit a page
- WHEN the user edits a page in the Pages view and the JSON stops validating
- THEN the view SHALL list the errors with their paths and keep showing the last valid version of the page
Scenario: Workers as a page
- WHEN the Workers view is the shipped Workers page spec
- THEN its tests and browser walk SHALL pass unchanged
Requirement: Navigation Representation
The web app's representation profile SHALL be {levels}, a list of level kinds by depth: tabs (a tab bar under the app bar; at the second level, a sub-tab bar below it), sections (headings in the sidebar), links (entries in the sidebar), nested (indented entries under their parent). tabs SHALL only be the first one or two kinds, followed by at least one other kind (for the sidebar and deeper levels). The default SHALL be ["tabs", "links", "nested"]; levels deeper than the list SHALL use its last kind. The profile SHALL be a document {version, levels} with the published schema web-app-navigation-profile.v1.schema.json, kept per browser and edited in the Navigation view.
Scenario: Tabs and sidebar
- WHEN the profile is the default and the user opens the Config tab
- THEN the sidebar SHALL list Config's children, and choosing Pages SHALL open the Pages view
Scenario: Tabs and sub-tabs
- WHEN the profile is
["tabs", "tabs", "nested"]and the user opens the Infra tab - THEN a sub-tab bar SHALL show Infra's children, the sidebar SHALL show the children of the chosen sub-tab (none for a leaf), and deeper levels SHALL be nested
Scenario: The former look
- WHEN the user sets the profile to
["sections", "links"] - THEN the sidebar SHALL show every top-level node as a heading with its children below, and no tab bar
Requirement: Routes and the Navigation View
The web app SHALL build its routes from the structure in use, a route per node from its ids (/<id>/<id>/…); a path the structure no longer has SHALL open Home with a notice. It SHALL offer a Navigation view (View Id navigation): the structure in use and where it comes from, an editor of the user's structure, open at once on the user's structure or else on the one in use (following it until the user changes something), by drag and drop (a tree whose nodes move within and between levels and into groups, labels edited in place, a palette of every built-in view, every known page and a new group to drag in) and as JSON, both on one draft that validates as it changes and lists errors with their paths, Save and Reset for the user's own structure, Share and Unshare for admins (through the write gate), and the representation profile.
Scenario: Edit the structure
- WHEN the user moves Pages under a new top-level node and saves
- THEN the navigation SHALL show it at once, and the old path SHALL open Home with a notice
Scenario: Reset
- WHEN the user resets their structure
- THEN the context's shared structure SHALL be used, or the built-in default if there is none
Scenario: Drag a view into a group
- WHEN the user drags the view Connections from the palette into the Infra group and saves
- THEN the structure SHALL hold a node opening
connectionsunder Infra, with an id unique among its siblings, and the navigation SHALL show it at once
Scenario: The editor opens at once
- WHEN a user without a structure of their own opens Navigation
- THEN the drag-and-drop tree SHALL show the structure in use at once, with nothing to save until the user changes it