7f72171572
Initialize git, add Apache-2.0 LICENSE, .gitattributes (LF line endings), AGENTS.md (entry points, stack, discovery order, baseline checks), RUNBOOK.md (dev boot, prod deploy with overlay, ingestion, failures, rollback, scaling notes), .env.prod.example with rotated credential placeholders, and dev-only warnings on .env.example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
141 lines
6.3 KiB
Markdown
141 lines
6.3 KiB
Markdown
# LegacyHUB · Frontend
|
||
|
||
React + TypeScript + Vite frontend for **LegacyHUB**, the legacy-document
|
||
indexing and AI search module of the **TeamHUB Suite**.
|
||
|
||
This package ships:
|
||
|
||
- the application shell (collapsible sidebar, top toolbar, breadcrumb nav,
|
||
global ⌘K command palette, light/dark theme, notification center,
|
||
user/profile menu);
|
||
- nine pages: Dashboard, Documents, Ingestion Jobs, Search, Document Viewer,
|
||
Tables & Figures, Quality Control, System Health, Settings;
|
||
- a hybrid AI search workspace with semantic / lexical / hybrid modes, live
|
||
suggestions, expandable filters, highlighted matches, reranker score
|
||
visualization and side-by-side chunk preview;
|
||
- typed service layer (`src/services/*`) with Axios + TanStack Query and a
|
||
mock data backend you can toggle off when the backend is reachable.
|
||
|
||
## Stack
|
||
|
||
| Concern | Library |
|
||
|----------------|-----------------------------------------|
|
||
| Bundler | Vite 5 |
|
||
| Language | TypeScript 5.6 |
|
||
| UI | React 18 |
|
||
| Styling | TailwindCSS 3 + custom design tokens |
|
||
| Components | shadcn/ui primitives (Radix + cva) |
|
||
| Animation | Framer Motion |
|
||
| Charts | Recharts |
|
||
| Server state | TanStack Query |
|
||
| Client state | Zustand |
|
||
| Routing | React Router v6 |
|
||
| HTTP | Axios |
|
||
| Icons | lucide-react |
|
||
| Toasts | sonner |
|
||
| Virtualization | @tanstack/react-virtual |
|
||
|
||
## Quick start
|
||
|
||
```bash
|
||
cd frontend
|
||
cp .env.example .env # VITE_USE_MOCK=true for offline UI development
|
||
npm install
|
||
npm run dev # http://localhost:5173
|
||
```
|
||
|
||
When the FastAPI backend is running, set `VITE_USE_MOCK=false` (or simply
|
||
`VITE_API_BASE_URL=/api/v1` and let the Vite dev proxy at port 8000 handle
|
||
routing). All API calls are isolated through `src/services/*.ts`.
|
||
|
||
## Architecture
|
||
|
||
```
|
||
frontend/src/
|
||
app/ RouterProvider, QueryClient, TooltipProvider, theme bootstrap
|
||
pages/ One file per route — composed of widgets + primitives
|
||
layouts/ AppShell, Sidebar (collapsible), Topbar, Breadcrumbs, ⌘K palette
|
||
widgets/ Domain-specific composite components (KpiCard, Charts, Result cards,
|
||
PdfPreviewPane, ChunkPreview, ServiceHealthCard, Timeline)
|
||
components/
|
||
ui/ shadcn-style primitives — Button, Card, Tabs, Dialog, Select,
|
||
Tooltip, Popover, ScrollArea, Command, Skeleton, Progress, …
|
||
common/ Domain primitives — Logo, StatusChip, ConfidenceMeter,
|
||
QualityFlag, BlockTypeIcon, Highlight, EmptyState, PageHeader,
|
||
ThemeToggle
|
||
services/ Typed API layer (Axios) + TanStack hooks (one file per resource)
|
||
mock/ Deterministic mock data + simulated latency
|
||
hooks/ Wrappers around services exposing TanStack Query hooks
|
||
stores/ Zustand stores: uiStore (theme, sidebar, palette), searchStore
|
||
styles/ Tailwind layer + design tokens (HSL CSS variables)
|
||
lib/ cn(), formatBytes/Number/Percent/Duration, relativeTime, etc.
|
||
```
|
||
|
||
### Design system
|
||
|
||
- **Palette** — white / light-gray surfaces with a single restrained green
|
||
accent (`--primary: 158 64% 32%`) matching QMS Hub.
|
||
- **Surfaces** — three tiers: sunken (page background), default card, raised
|
||
(popovers / dialogs). Glass surfaces via `backdrop-blur` for the topbar.
|
||
- **Corners** — `--radius: 14px` produces soft, premium edges across every
|
||
component.
|
||
- **Shadows** — `shadow-soft` and `shadow-elevated` only. No harsh drop
|
||
shadows.
|
||
- **Typography** — Inter variable, optical sizes, tabular numbers for data
|
||
cells, JetBrains Mono for IDs / paths / hashes.
|
||
- **Motion** — Framer Motion `layoutId` for the active sidebar pill,
|
||
`fade-in-up` for KPI cards, animated tabs and result expansion.
|
||
- **States** — skeleton shimmer instead of spinners wherever possible.
|
||
|
||
### Key flows
|
||
|
||
- **Hybrid search (`/search`)** — Debounced query → TanStack hook hits the
|
||
backend (or mock). Results are virtualized, scored, optionally reranked.
|
||
Picking a result hydrates a side-by-side ChunkPreview with the highlighted
|
||
excerpt, a page thumbnail, citation metadata, and quality flags.
|
||
- **Documents (`/documents`)** — Virtualized table (TanStack Virtual)
|
||
supports thousands of rows. Filters: status, OCR threshold, "needs review",
|
||
free-text search. Clicking a row opens the viewer.
|
||
- **Document Viewer (`/viewer/:id`)** — Split layout. Left pane: PDF page
|
||
thumbnails + synchronized large page preview with highlighted OCR blocks.
|
||
Right pane: extracted chunks / tables / figures / metadata, kept in lock-step
|
||
with the active page. Below: full pipeline timeline.
|
||
- **Ingestion (`/ingestion`)** — Submit a folder path with `recursive` /
|
||
`force` toggles → optimistic queue, run history table with live progress
|
||
bars.
|
||
- **Quality control (`/quality`)** — Three review queues (low confidence,
|
||
handwriting, failed extraction) with reviewer actions and an audit log.
|
||
|
||
### Mock vs real backend
|
||
|
||
`src/services/apiClient.ts` exports a constant `USE_MOCK`. When `true`, every
|
||
service module short-circuits to `src/services/mock/mockData.ts` which
|
||
generates deterministic, seeded data: 280 documents, dashboards, ingestion
|
||
runs, search results, health and queue snapshots, and per-document detail
|
||
(pages, chunks, tables, figures, timeline events).
|
||
|
||
This lets the frontend be developed and demoed without the Python services
|
||
running.
|
||
|
||
### Accessibility
|
||
|
||
- All interactive elements use `ring-focus` (visible 2px primary ring).
|
||
- Sidebar nav exposes tooltips when collapsed.
|
||
- Keyboard: `Ctrl/Cmd + K` opens the global command palette.
|
||
|
||
### Responsive layout
|
||
|
||
- ≥ 1280 px (xl, ultrawide) — three-column dashboards, side-by-side search.
|
||
- 1024–1280 px (laptop) — two-column dashboards, stacked search.
|
||
- < 1024 px — single column; sidebar collapses to icons only.
|
||
|
||
## Scripts
|
||
|
||
```bash
|
||
npm run dev # Vite dev server with /api proxy → :8000
|
||
npm run build # type-check + production bundle
|
||
npm run preview # preview build
|
||
npm run lint
|
||
npm run format
|
||
```
|