187 lines
6.4 KiB
Markdown
187 lines
6.4 KiB
Markdown
# Phase 1 Frontend Development Plan
|
|
|
|
**Source**: `development_plan.md`
|
|
**Scope**: React 18 + TypeScript + Vite frontend for text-based RAG Q&A
|
|
**Estimated Duration**: 2-3 days
|
|
**Status**: ✅ Complete (Phase 1.1, 1.2, 1.3 all done)
|
|
|
|
---
|
|
|
|
## Objective
|
|
|
|
Build a React frontend that:
|
|
1. Pre-allocates Phase 2 grid layout (video area empty/hidden in Phase 1)
|
|
2. Allows text input and displays extracted keywords + bullet-point RAG responses with source metadata
|
|
3. Uses TanStack Query for type-safe API calls to the FastAPI backend
|
|
|
|
---
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] Phase 2 grid layout renders: Top-Left (empty video placeholder), Top-Right (input + keywords), Bottom (response)
|
|
- [x] User can type a question and submit
|
|
- [x] Extracted keywords displayed prominently before final answer
|
|
- [x] Bullet-point answer displayed with source metadata (filename, upload_date)
|
|
- [x] Loading states for each pipeline step (keywords loading, answer loading)
|
|
- [x] Error handling for API failures
|
|
- [x] Responsive within desktop viewport (no mobile required)
|
|
- [x] All API calls use TanStack Query with proper caching/invalidation
|
|
|
|
---
|
|
|
|
## Acceptance Tests
|
|
|
|
**File**: `frontend/src/test/e2e/query_flow.test.tsx` (integration test with mocked API)
|
|
- [x] User types question → sees keywords appear → sees bullet answer with sources
|
|
- [x] Empty state handled gracefully
|
|
- [x] API error shows user-friendly message
|
|
- [x] Ingest flow: upload document → success feedback
|
|
|
|
---
|
|
|
|
## Implementation Tasks
|
|
|
|
### Phase 1.1: Project Setup & Layout ✅
|
|
|
|
**Test files to write first**:
|
|
- `src/test/components/Layout.test.tsx` — Test grid renders correctly
|
|
- `src/test/lib/api.test.ts` — Test API client configuration
|
|
|
|
1. **Project scaffold**
|
|
- Initialize Vite project: `npm create vite@latest frontend -- --template react-ts`
|
|
- Install dependencies: `tailwindcss`, `postcss`, `autoprefixer`, `@tanstack/react-query`, `axios`
|
|
- Configure Tailwind CSS
|
|
- Set up shadcn/ui (copy components or install via CLI)
|
|
|
|
2. **API client**
|
|
- `src/lib/api.ts` — Axios instance with base URL configuration
|
|
- `src/lib/queries.ts` — TanStack Query hooks:
|
|
- `useQueryDocument()` — POST /api/v1/query
|
|
- `useIngestDocument()` — POST /api/v1/ingest
|
|
- Type-safe request/response types matching backend Pydantic schemas
|
|
|
|
3. **Layout structure**
|
|
- `src/App.tsx` — Root component with Phase 2 grid pre-allocation
|
|
- Grid layout using Tailwind CSS:
|
|
```
|
|
Top-Left (50%): VideoPlaceholder (hidden/empty in Phase 1)
|
|
Top-Right (50%): QueryInput + KeywordsDisplay
|
|
Bottom (100%): ResponsePanel
|
|
```
|
|
- Use CSS Grid or Flexbox for clean separation
|
|
|
|
**Commit**: "feat: Phase 1.1 frontend project setup with layout and API client" ✅ (`3923e20`, `d3bf131`)
|
|
|
|
### Phase 1.2: Components & Integration ✅
|
|
|
|
**Test files to write first**:
|
|
- `src/test/components/QueryInput.test.tsx` — Test input and submit
|
|
- `src/test/components/KeywordsDisplay.test.tsx` — Test keyword rendering
|
|
- `src/test/components/ResponsePanel.test.tsx` — Test bullet list and metadata
|
|
|
|
1. **QueryInput component**
|
|
- `src/components/QueryInput.tsx`
|
|
- Textarea for question input
|
|
- Submit button with loading state
|
|
- Calls `useQueryDocument` mutation on submit
|
|
|
|
2. **KeywordsDisplay component**
|
|
- `src/components/KeywordsDisplay.tsx`
|
|
- Shows extracted keywords as tags/chips
|
|
- Loading skeleton while keywords are being extracted
|
|
- Animated entrance when keywords arrive
|
|
|
|
3. **ResponsePanel component**
|
|
- `src/components/ResponsePanel.tsx`
|
|
- Displays bullet-point answer
|
|
- Shows source metadata cards (filename, upload_date)
|
|
- Loading skeleton while answer is being generated
|
|
- Empty state when no query submitted yet
|
|
|
|
4. **IngestPanel component (optional for Phase 1)**
|
|
- `src/components/IngestPanel.tsx`
|
|
- Simple file upload for DOCX and PDF
|
|
- Progress indicator during upload
|
|
- Success/error feedback
|
|
|
|
5. **Error handling**
|
|
- Global error boundary
|
|
- Toast notifications for API errors
|
|
- Retry mechanism for failed queries
|
|
|
|
**Commit**: "feat: Phase 1.2 frontend components with query flow" ✅ (`fa94b7c`, `3d76b89`, `a7d5dc6`, `6b54480`)
|
|
|
|
### Phase 1.3: Polish & Integration Testing ✅
|
|
|
|
**Test files to write first**:
|
|
- `src/test/e2e/query_flow.spec.ts` — End-to-end test with backend
|
|
|
|
1. **Loading states**
|
|
- Skeleton loaders for each panel
|
|
- Step-by-step progress indicator showing pipeline stage:
|
|
"Extracting keywords..." → "Retrieving documents..." → "Filtering relevance..." → "Generating answer..."
|
|
|
|
2. **Styling polish**
|
|
- Consistent spacing and typography
|
|
- Dark/light mode support (optional)
|
|
- Smooth transitions between states
|
|
|
|
3. **Integration with backend**
|
|
- End-to-end test: upload DOCX/PDF → ask question → verify keywords + answer + sources
|
|
- Verify CORS works correctly
|
|
- Test error scenarios
|
|
|
|
4. **Build verification**
|
|
- `npm run build` succeeds
|
|
- Production build serves correctly via `npm run preview`
|
|
|
|
**Commit**: "feat: Phase 1.3 frontend polish, loading states, and integration" ✅ (`864b684`, `f6618fd`, `e927e5f`)
|
|
|
|
---
|
|
|
|
## Completion Summary
|
|
|
|
**Phase 1 Frontend complete.** All 3 sub-phases delivered:
|
|
|
|
| Sub-Phase | Commits | Test Files | Tests |
|
|
|-----------|---------|------------|-------|
|
|
| 1.1 Setup & Layout | `d3bf131`, `3923e20` | 2 | 4 |
|
|
| 1.2 Components | `fa94b7c`, `3d76b89`, `a7d5dc6`, `6b54480` | 6 | 37 |
|
|
| 1.3 Polish & Integration | `864b684`, `f6618fd`, `e927e5f` | 9 | 62 |
|
|
|
|
**Components delivered**: QueryInput, KeywordsDisplay, ResponsePanel (collapsible sources + copy button), IngestPanel, ErrorBoundary, PipelineProgress (ready for streaming)
|
|
|
|
**Build**: TypeScript clean, 62/62 tests pass, production build (219KB JS + 13KB CSS)
|
|
|
|
---
|
|
|
|
## Dependencies
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"react": "^18.2.0",
|
|
"react-dom": "^18.2.0",
|
|
"@tanstack/react-query": "^5.x",
|
|
"axios": "^1.6.x",
|
|
"tailwindcss": "^3.4.x",
|
|
"lucide-react": "^0.x"
|
|
},
|
|
"devDependencies": {
|
|
"@types/react": "^18.2.x",
|
|
"@types/react-dom": "^18.2.x",
|
|
"@vitejs/plugin-react": "^4.2.x",
|
|
"typescript": "^5.3.x",
|
|
"vite": "^5.0.x"
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- Video area in Phase 1 should show a placeholder message: "Video upload coming in Phase 2" or be completely hidden
|
|
- Keywords should be visually distinct from the final answer — consider using badges/tags
|
|
- Source metadata cards should be collapsible to avoid cluttering the response area
|
|
- Consider adding a "copy answer" button for convenience |