# 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

```json
{
  "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
```javascript
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
```bash
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)