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 elseno-cache); - any other path that is not
/v1/…,/auth/…, a probe or a file name answersindex.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: DENYandnosniff. There are no inline scripts or styles: libraries that inject<style>(toasts, editors) are avoided. The E2E listens forsecuritypolicyviolation.
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">withvector-effect: non-scaling-stroke.viewer/geometry.tsalso converts PDF space ↔ displayed frame (mirror ofcore.geometry); its golden fixtures are generated from the Python reference (scripts/gen_geometry_golden.py, checked bytests/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(notpacket_page). - States — each polygon has
data-verification(verified,partial,block_only,unverified,contradicted),data-role(primary,supporting,contradicting),data-selectedanddata-field; the look of each state is one rule inweb/src/index.css. - Selection —
viewer/useSelection.tsis 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/Knext and previous field,Ggo 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.