Source:
docs/manual/ui-react.mdThis page is generated by
site/scripts/sync-manual-docs.mjs.
React Web UI
The React web UI replaces the original template-based UI with a modern single-page application built on React, TypeScript, and Tailwind CSS. It provides all operator console features — run management, approvals, cost dashboards, tool browsing, and flow building — in a responsive, component-based interface.
Source: cmd/ui/, cmd/ui/frontend/
Overview
The React Web UI is the primary operator interface for Cruvero. It replaces the earlier htmx-based operator console with a full-featured React 18 application served from a single Go binary. The UI surfaces every capability the Cruvero runtime has built across Phases 1-10, including run management, approvals, replay, causal tracing, tool browsing, memory exploration, cost dashboards, supervisor visualization, and a visual flow builder.
Architecture
The frontend is a React 18 + TypeScript application built with Vite. In production, the Go server (cmd/ui) embeds the built React assets via go:embed and serves them as static files. No Node.js is required at runtime.
| Layer | Technology |
|---|---|
| Framework | React 18, TypeScript strict mode |
| Build | Vite, output to cmd/ui/dist/ |
| Routing | React Router v6 |
| Server state | TanStack React Query |
| Client state | Zustand |
| Styling | Tailwind CSS (dark-mode-first) |
| Charts | ECharts (echarts-for-react) |
| JSON editing | Monaco Editor (@monaco-editor/react) |
| Flow builder | React Flow (@xyflow/react v12) |
| Streaming | EventSource API for SSE |
Development
Prerequisites
- Node.js 20+
- npm 10+
- Go 1.25+
Running in development
Start the Go backend (serves API on :8081):
go run ./cmd/ui --addr :8081
Start the Vite dev server with hot reload (proxies API calls to :8081):
cd cmd/ui/frontend && npm run dev
Open http://localhost:5173 in your browser.
Building for production
Build the React app and embed in the Go binary:
make build-ui
Or separately:
cd cmd/ui/frontend && npm ci && npm run build
go build -o bin/cruvero-ui ./cmd/ui
Pages
| Route | Page | Required Role |
|---|---|---|
/ | Run List | Viewer |
/runs/:workflowId | Run Detail | Viewer |
/runs/:workflowId/replay | Replay Console | Editor |
/approvals | Approval Queue | Editor |
/questions | Question Queue | Editor |
/tools | Tool Browser | Viewer |
/tools/registry | Registry Versions | Viewer |
/tools/mcp | MCP Status | Viewer |
/memory | Memory Explorer | Viewer |
/cost | Cost Dashboard | Viewer |
/cost/models | Model Catalog | Viewer |
/cost/prefs | Model Preferences | Admin |
/flows | Flow List | Viewer |
/flows/builder | Flow Builder | Editor |
/supervisor | Supervisor Runs | Viewer |
/supervisor/:workflowId | Supervisor Detail | Viewer |
/traces/:runId | Trace Explorer | Viewer |
/diff-test | Differential Testing | Editor |
/agent-versions | Agent Versions | Viewer |
/inspect/:workflowId | Live Inspection | Editor |
/settings | Settings | Viewer |
/settings/tenant | Tenant Settings | Admin |
/settings/users | User Management | Admin |
Authentication
The UI uses OIDC authentication with Keycloak as the primary identity provider (Azure AD future-proofed). Tokens are stored in HTTP-only secure cookies. The frontend never handles raw JWTs — it reads user info from /api/auth/me.
Roles
- Viewer: Read-only access to runs, logs, metrics, tools, memory
- Editor: Execute runs, approve/reject, edit state, create/edit flows
- Admin: Manage tools, registry, users, workflows, tenant settings
- Super Admin: Tenant management, system config, role assignment
Configuration
| Variable | Default | Description |
|---|---|---|
CRUVERO_UI_MODE | react | react or htmx |
CRUVERO_UI_STATIC_DIR | cmd/ui/dist | Path to React build output |
CRUVERO_UI_DEV_PROXY | — | Vite dev server URL (dev only) |
CRUVERO_AUTH_PROVIDER | keycloak | Identity provider |
CRUVERO_UI_JWKS_URL | — | OIDC JWKS endpoint |
CRUVERO_UI_ISSUER | — | OIDC issuer URL |
CRUVERO_UI_AUDIENCE | — | OIDC audience/client ID |
CRUVERO_UI_SESSION_TIMEOUT | 8h | Session timeout duration |