# 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