241 lines
8.0 KiB
Markdown
241 lines
8.0 KiB
Markdown
# 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)
|