woody
/
legco_ai_assistant
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
legco_ai_assistant/.plans/phase1_frontend_plan.md

5.6 KiB
Raw Blame History

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: Draft

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

  • Phase 2 grid layout renders: Top-Left (empty video placeholder), Top-Right (input + keywords), Bottom (response)
  • User can type a question and submit
  • Extracted keywords displayed prominently before final answer
  • Bullet-point answer displayed with source metadata (filename, upload_date)
  • Loading states for each pipeline step (keywords loading, answer loading)
  • Error handling for API failures
  • Responsive within desktop viewport (no mobile required)
  • All API calls use TanStack Query with proper caching/invalidation

Acceptance Tests

File: frontend/src/test/e2e/phase1_query_flow.spec.ts (or manual acceptance checklist)

  • User types question → sees keywords appear → sees bullet answer with sources
  • Empty state handled gracefully
  • API error shows user-friendly message

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"

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
    • 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"

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 → 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"

Dependencies

{
  "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