Skip to content

Studio (web app)

The Studio is a static single-page app (web/: Vite, React 19, strict TypeScript, TanStack Router and Query, Tailwind with shadcn/ui on Base UI). It talks only to the API of the same origin and keeps no token in the browser: the session is an HttpOnly cookie (see Web identity).

Run it

What Command
Develop (proxy of /v1 and /auth to the API, same origin) DX_API_URL=http://127.0.0.1:8000 pnpm --filter web dev
Build pnpm --filter web build (output web/dist, manifest in web/dist/.vite/)
Serve it from the API DX_WEB_DIST=web/dist (the API answers index.html for deep links and sets the CSP below)
Unit and component tests pnpm --filter web test (test:coverage for the report)
Fast E2E (mocked API, real build) pnpm --filter web e2e
Real-stack E2E (Keycloak, Postgres, API, fake model) pnpm --filter web e2e:stack (heavy: needs Docker)
Regenerate the API client pnpm --filter web gen:api (from openapi/openapi.json)
Check es/en keys pnpm --filter web i18n:check
Check the bundle budget pnpm --filter web check:bundle (≤ 300 KB gzip of the entry graph)

Over plain http (local development) start the API with DX_COOKIE_SECURE=false; Safari refuses __Host- cookies without TLS.

Served by the API (api/web_static.py)

With DX_WEB_DIST set, create_app() appends a catch-all GET after every API route:

  • a file of the build is served as is (assets/* cached for a year, everything else no-cache);
  • any other path that is not /v1/…, /auth/…, a probe or a file name answers index.html;
  • the HTML carries Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' blob: data:; connect-src 'self'; frame-ancestors 'none', X-Frame-Options: DENY and nosniff. There are no inline scripts or styles: libraries that inject <style> (toasts, editors) are avoided. The E2E listens for securitypolicyviolation.

Plug points for later tickets

Nothing below needs a change in the router.

Screens: registerRoute() (web/src/app/registry.ts)

registerRoute({
  id: "workflows",            // same id as a ComingSoon marker replaces it
  path: "/workflows",
  titleKey: "nav.workflows",  // i18n key (add it to es.json and en.json)
  icon: Workflow,             // lucide-react; without an icon it is not in the sidebar
  permission: "workflow:read",
  component: WorkflowsPage,   // lazy(() => import(...)) in your module
});

The routes are read once, when buildRouter() runs, so register before that: import your module from web/src/app/nav.ts (one line). Each screen not yet built is a ComingSoon marker that names the ticket that replaces it:

Marker Path Replaced by
Workflows /workflows T34 (list and canvas), T36
Review /review T33 (inbox), T32 (review in the viewer)
Agent /agent T43
Knowledge /knowledge T48

The viewer's canonical route is /runs/$runId; T34/T36 add /workflows/:id/runs/:runId rendering the same RunPage component, so the viewer does not change.

Settings: registerSettingsPage() (web/src/features/settings/registry.ts)

registerSettingsPage({
  id: "api-keys",
  titleKey: "settings.apiKeys",
  path: "api-keys",            // /settings/api-keys
  permission: "apikey:manage", // an API permission, or "admin" (Owner or Admin); omit for everyone
  component: ApiKeysPage,
  enterprise: false,           // true shows the discreet «Enterprise» label
});

/settings builds its navigation from the registry and hides what the role cannot open (the page also refuses it by URL). Add one import "./<section>/register"; line to web/src/features/settings/pages.ts — T27, T31, T49, T50 and T51 each add theirs and never depend on each other.

Evidence viewer

/runs/$runId follows the run (GET /v1/runs/{id}?wait=20, first read immediate) and, when it succeeded, loads GET /v1/runs/{id}/result and the page images (/v1/runs/{id}/pages/{n}.png) into the viewer chunk (lazy: it is not in the entry graph).

  • Coordinates — page_display_norm_v1: boxes and polygons are normalized 0–1 over the page as displayed (rotation and CropBox applied, origin top-left), the same frame as the server's PNG. Each page is <img> plus <svg viewBox="0 0 1 1" preserveAspectRatio="none"> with vector-effect: non-scaling-stroke. viewer/geometry.ts also converts PDF space ↔ displayed frame (mirror of core.geometry); its golden fixtures are generated from the Python reference (scripts/gen_geometry_golden.py, checked by tests/api/test_web_geometry_golden.py).
  • Shapes — one polygon per word (document spans), per cell (tables) or per line (when the evidence has no finer boxes). The evidence regions carry page (not packet_page).
  • States — each polygon has data-verification (verified, partial, block_only, unverified, contradicted), data-role (primary, supporting, contradicting), data-selected and data-field; the look of each state is one rule in web/src/index.css.
  • Selection — viewer/useSelection.ts is a store shared by page and panel; a click on a highlight selects every field whose region contains the click. performance.measure("dx-select-to-highlight") times a selection until its polygons are in the DOM (the E2E asserts < 150 ms).
  • Keyboard — J/K next and previous field, G go to the selected field's evidence.
  • Virtualization — @tanstack/react-virtual: the visible page and its neighbours are mounted.

Design tokens

Every colour, radius and size is a CSS variable in web/src/index.css (:root and [data-theme="dark"], the UI v2 values of the design); components use the Tailwind utilities that read them. A change of visual direction is a change of that block. web/src/app/Brand.tsx is the one place of the product name and mark.

i18n

es and en bundles in web/src/i18n/*.json, same keys (pnpm i18n:check fails otherwise). Numbers and dates use Intl.* with the UI locale (4594.62 is 4.594,62 in es and 4,594.62 in en). The locale and the theme are stored in localStorage when available; without it the app runs in a no-persistence mode and says so.