Skip to content

04. Frontend Deep Dive

Stack and entrypoints

Item Value
Framework React 19 + TypeScript
Bundler Vite 7
Styling Tailwind CSS v4 + shadcn/ui
Server state TanStack Query
Client state Zustand (useRecentStore, persisted)
HTTP Axios (src/api/client.ts)
Routing React Router 7 (createBrowserRouter)

Entry: frontend/src/main.tsx (QueryClient + Toaster) → App.tsx.

Routes

Path Page Purpose
/ Dashboard Recent activity overview
/documents DocumentsList Upload + list
/documents/:id DocumentDetail OCR / extraction viewers
/jobs JobsList Job list
/jobs/:id JobDetail Stages and chunks
/factsheets FactsheetsList List / delete
/factsheets/:id FactsheetDetail Result + provenance
/factsheet/generate (generate flow) Kick off UC1

API client layer

Module Role
api/client.ts Axios instance; base URL from VITE_API_BASE_URL or /api/v1
api/documents.ts Upload, list, status, artifacts, delete
api/jobs.ts List, detail, chunks, stage triggers
api/factsheet.ts Generate, poll status, CRUD

Confirmed: No auth interceptors on the Axios client despite docs mentioning them.

State and UX patterns

  • TanStack Query for lists/details and polling intervals on in-flight jobs/factsheets
  • Zustand persist for recent documents/jobs/factsheets on the dashboard
  • Sonner toasts for success/error
  • Domain components under components/documents, components/jobs, components/factsheet
  • ProvenanceTooltip.tsx surfaces field-level source snippets and confidence

Proxy caveat

vite.config.ts proxies /api to http://localhost:8888, while Makefile/BACKEND_PORT default is 8000. Local setup must align proxy target, VITE_API_BASE_URL, or both.

Type safety and build

  • strict TypeScript project references (tsconfig.app.json)
  • ESLint flat config
  • pnpm lockfile committed
  • No frontend unit/e2e test suite found in this checkout

Frontend interview Q&A

Q: How does the UI track long OCR jobs?
A: Poll document/job endpoints with React Query; job detail exposes stage and chunk status from the backend state machine.

Q: How is factsheet trust shown?
A: Results include provenance metadata; ProvenanceTooltip shows doc id, confidence, and snippet so operators can verify LLM-filled fields.