invoice-master-poc-v2/frontend/REFACTORING_PLAN.md

Frontend Refactoring Plan

Current Structure Issues

1. Flat component organization - All components in one directory
2. Mock data only - No real API integration
3. No state management - Props drilling everywhere
4. CDN dependencies - Should use npm packages
5. Manual routing - Using useState instead of react-router
6. No TypeScript integration with backend - Types don't match API schemas

Recommended Structure

frontend/
├── public/
│   └── favicon.ico
│
├── src/
│   ├── api/                           # API Layer
│   │   ├── client.ts                  # Axios instance + interceptors
│   │   ├── types.ts                   # API request/response types
│   │   └── endpoints/
│   │       ├── documents.ts           # GET /api/v1/admin/documents
│   │       ├── annotations.ts         # GET/POST /api/v1/admin/documents/{id}/annotations
│   │       ├── training.ts            # GET/POST /api/v1/admin/training/*
│   │       ├── inference.ts           # POST /api/v1/infer
│   │       └── async.ts               # POST /api/v1/async/submit
│   │
│   ├── components/
│   │   ├── common/                    # Reusable components
│   │   │   ├── Badge.tsx
│   │   │   ├── Button.tsx
│   │   │   ├── Input.tsx
│   │   │   ├── Modal.tsx
│   │   │   ├── Table.tsx
│   │   │   ├── ProgressBar.tsx
│   │   │   └── StatusBadge.tsx
│   │   │
│   │   ├── layout/                    # Layout components
│   │   │   ├── TopNav.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   └── PageHeader.tsx
│   │   │
│   │   ├── documents/                 # Document-specific components
│   │   │   ├── DocumentTable.tsx
│   │   │   ├── DocumentFilters.tsx
│   │   │   ├── DocumentRow.tsx
│   │   │   ├── UploadModal.tsx
│   │   │   └── BatchUploadModal.tsx
│   │   │
│   │   ├── annotations/               # Annotation components
│   │   │   ├── AnnotationCanvas.tsx
│   │   │   ├── AnnotationBox.tsx
│   │   │   ├── AnnotationTable.tsx
│   │   │   ├── FieldEditor.tsx
│   │   │   └── VerificationPanel.tsx
│   │   │
│   │   └── training/                  # Training components
│   │       ├── DocumentSelector.tsx
│   │       ├── TrainingConfig.tsx
│   │       ├── TrainingJobList.tsx
│   │       ├── ModelCard.tsx
│   │       └── MetricsChart.tsx
│   │
│   ├── pages/                         # Page-level components
│   │   ├── DocumentsPage.tsx          # Was Dashboard.tsx
│   │   ├── DocumentDetailPage.tsx     # Was DocumentDetail.tsx
│   │   ├── TrainingPage.tsx           # Was Training.tsx
│   │   ├── ModelsPage.tsx             # Was Models.tsx
│   │   └── InferencePage.tsx          # New: Test inference
│   │
│   ├── hooks/                         # Custom React Hooks
│   │   ├── useDocuments.ts            # Document CRUD + listing
│   │   ├── useAnnotations.ts          # Annotation management
│   │   ├── useTraining.ts             # Training jobs
│   │   ├── usePolling.ts              # Auto-refresh for async jobs
│   │   └── useDebounce.ts             # Debounce search inputs
│   │
│   ├── store/                         # State Management (Zustand)
│   │   ├── documentsStore.ts
│   │   ├── annotationsStore.ts
│   │   ├── trainingStore.ts
│   │   └── uiStore.ts
│   │
│   ├── types/                         # TypeScript Types
│   │   ├── index.ts
│   │   ├── document.ts
│   │   ├── annotation.ts
│   │   ├── training.ts
│   │   └── api.ts
│   │
│   ├── utils/                         # Utility Functions
│   │   ├── formatters.ts              # Date, currency, etc.
│   │   ├── validators.ts              # Form validation
│   │   └── constants.ts               # Field definitions, statuses
│   │
│   ├── styles/
│   │   └── index.css                  # Tailwind entry
│   │
│   ├── App.tsx
│   ├── main.tsx
│   └── router.tsx                     # React Router config
│
├── .env.example
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── postcss.config.js
└── index.html

Migration Steps

Phase 1: Setup Infrastructure

• Install dependencies (axios, react-router, zustand, @tanstack/react-query)
• Setup local Tailwind (remove CDN)
• Create API client with interceptors
• Add environment variables (.env.local with VITE_API_URL)

Phase 2: Create API Layer

• Create src/api/client.ts with axios instance
• Create src/api/endpoints/documents.ts matching backend API
• Create src/api/endpoints/annotations.ts
• Create src/api/endpoints/training.ts
• Add types matching backend schemas

Phase 3: Reorganize Components

• Move existing components to new structure
• Split large components (Dashboard > DocumentTable + DocumentFilters + DocumentRow)
• Extract reusable components (Badge, Button already done)
• Create layout components (TopNav, Sidebar)

Phase 4: Add Routing

• Install react-router-dom
• Create router.tsx with routes
• Update App.tsx to use RouterProvider
• Add navigation links

Phase 5: State Management

• Create custom hooks (useDocuments, useAnnotations)
• Use @tanstack/react-query for server state
• Add Zustand stores for UI state
• Replace mock data with API calls

Phase 6: Backend Integration

• Update CORS settings in backend
• Test all API endpoints
• Add error handling
• Add loading states

Dependencies to Add

{
  "dependencies": {
    "react-router-dom": "^6.22.0",
    "axios": "^1.6.7",
    "zustand": "^4.5.0",
    "@tanstack/react-query": "^5.20.0",
    "date-fns": "^3.3.0",
    "clsx": "^2.1.0"
  },
  "devDependencies": {
    "tailwindcss": "^3.4.1",
    "autoprefixer": "^10.4.17",
    "postcss": "^8.4.35"
  }
}

Configuration Files to Create

tailwind.config.js

export default {
  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        warm: {
          bg: '#FAFAF8',
          card: '#FFFFFF',
          hover: '#F1F0ED',
          selected: '#ECEAE6',
          border: '#E6E4E1',
          divider: '#D8D6D2',
          text: {
            primary: '#121212',
            secondary: '#2A2A2A',
            muted: '#6B6B6B',
            disabled: '#9A9A9A',
          },
          state: {
            success: '#3E4A3A',
            error: '#4A3A3A',
            warning: '#4A4A3A',
            info: '#3A3A3A',
          }
        }
      }
    }
  }
}

.env.example

VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000/ws

Type Generation from Backend

Consider generating TypeScript types from Python Pydantic schemas:

• Option 1: Use datamodel-code-generator to convert schemas
• Option 2: Manually maintain types in src/types/api.ts
• Option 3: Use OpenAPI spec + openapi-typescript-codegen

Testing Strategy

• Unit tests: Vitest for components
• Integration tests: React Testing Library
• E2E tests: Playwright (matching backend)

Performance Considerations

• Code splitting by route
• Lazy load heavy components (AnnotationCanvas)
• Optimize re-renders with React.memo
• Use virtual scrolling for large tables
• Image lazy loading for document previews

Accessibility

• Proper ARIA labels
• Keyboard navigation
• Focus management
• Color contrast compliance (already done with Warm Graphite theme)