Web client

Web client

A reference single-page app in web/ demonstrates the v1 API end-to-end (Vite + React + TypeScript). It is a clean MVP, not a product UI.

Audience: developers who want a working front-end reference. What you will accomplish: run the SPA against a local server and know what it demonstrates.

What it shows

  • Streaming chat — POST /api/v1/chat/stream parsed as Server-Sent Events (token → sources → done); Stop aborts the request mid-stream.
  • Controls — per-request mode (strict / open / learning / learning_review) and language (auto / en / ar / pt) selectors.
  • Upload doc — pick a local file (PDF / TXT / MD / DOCX / HTML) and POST /api/v1/ingest/upload (multipart); the file goes straight from the browser, no hosting or URL required.
  • Structured citations — collapsible Sources with label, page, relevance score, and snippet.
  • RTL / Arabic — Arabic messages render dir="rtl" via logical CSS properties.
  • Health badge — polls /health and shows a status dot.
  • Review panel — the header Review toggle (or the #/review route) opens an operator panel over the learning_review queue with Approve/Reject. See the Review workflow.
  • Accessibility — aria-live on the streaming answer, keyboard send (Enter) / Shift+Enter newline, visible focus rings, prefers-reduced-motion.

Run it

The dev server proxies /api and /health to 127.0.0.1:8000, so start the backend separately first.

Terminal
cd web
bun install      # or: npm install
bun run dev      # http://localhost:5173 (proxies /api and /health to :8000)

If it fails: If requests 502/404, the backend isn't running on :8000 — start it with uvicorn main:app --port 8000.

Build it

Terminal
bun run build      # tsc -b && vite build → web/dist/
bun run typecheck

Serve dist/ from any static host; point the API at it via CORS (CORS_ORIGINS) or reverse-proxy /api to the backend.

Verify your result

  • Verify: The SPA loads at http://localhost:5173 with a green health dot.
  • Verify: Streaming answers render token-by-token with collapsible citations.
  • Verify: Uploading a supported file queues an ingest; the Review panel works in learning_review.

Common failure modes

Related next steps

EvaluationAPI summary