Assessment and migration proposal of the UI to Remix

.agents/planning/00-index.md

@@ -0,0 +1,141 @@
+# UI Framework Migration Planning
+
+## Overview
+
+Planning documents for migrating the Antenna UI from Vite + React Router to a more opinionated framework. Two options are evaluated: **Next.js** and **Remix**.
+
+**Recommendation**: Remix is better aligned with our motivations (reducing boilerplate, prescribed patterns, DRF-like experience).
+
+---
+
+## Document Index
+
+### Context & Motivations
+
+| # | Document | Description |
+|---|----------|-------------|
+| 01 | [Current State](./01-current-state.md) | Analysis of current UI and API architecture |
+| 08 | [**Motivations**](./08-motivations.md) | Why we're considering migration (small team, patterns, maintenance) |
+
+### Next.js Assessment
+
+| # | Document | Description |
+|---|----------|-------------|
+| 02 | [Next.js Benefits](./02-nextjs-benefits.md) | What Next.js offers and can replace |
+| 03 | [Required Changes](./03-required-changes.md) | Everything that needs to change for Next.js |
+| 04 | [Custom/Bespoke](./04-custom-bespoke.md) | What stays custom (Next.js) |
+| 05 | [Migration Steps](./05-migration-steps.md) | Phased implementation plan (Next.js) |
+| 06 | [Questions & Risks](./06-questions-risks.md) | Risks, alternatives, benefits (Next.js) |
+| 07 | [Testing & Evaluation](./07-testing-evaluation.md) | Testing plan (Next.js) |
+
+### Remix Assessment (Recommended)
+
+| # | Document | Description |
+|---|----------|-------------|
+| R1 | [Remix Benefits](./remix/01-remix-benefits.md) | What Remix offers - loaders, actions, forms |
+| R2 | [Required Changes](./remix/02-required-changes.md) | Everything that needs to change for Remix |
+| R3 | [Custom/Bespoke](./remix/03-custom-bespoke.md) | What stays custom (Remix) |
+| R4 | [Migration Steps](./remix/04-migration-steps.md) | Phased implementation plan (Remix) |
+| R5 | [Questions & Risks](./remix/05-questions-risks.md) | Risks, alternatives, benefits (Remix) |
+| R6 | [Testing & Evaluation](./remix/06-testing-evaluation.md) | Testing plan (Remix) |
+
+---
+
+## Quick Comparison
+
+### Current Stack
+- **Build**: Vite 4.5.3
+- **Routing**: React Router v6.8.2
+- **State**: React Query + Context
+- **Styling**: Tailwind CSS + SCSS
+- **Components**: Radix UI + nova-ui-kit
+
+### Option A: Next.js
+- **Build**: Next.js 14 (App Router)
+- **Routing**: File-based (app/)
+- **State**: React Query + Context (keep)
+- **Data loading**: Flexible (server components, client)
+- **Forms**: Manual (Server Actions basic)
+
+### Option B: Remix (Recommended)
+- **Build**: Remix 2.x (Vite-based)
+- **Routing**: File-based (routes/)
+- **State**: Minimal (loaders handle server state)
+- **Data loading**: Prescribed (loaders)
+- **Forms**: First-class (`<Form>`, actions)
+
+---
+
+## Comparison Matrix
+
+| Factor | Current | Next.js | Remix |
+|--------|---------|---------|-------|
+| Boilerplate | High | Medium | **Low** |
+| Prescribed Patterns | None | Some | **Many** |
+| Form Handling | Manual | Basic | **Built-in** |
+| Data Flow Opinions | None | Low | **High** |
+| Files to Remove | - | ~10 | **~43** |
+| DRF-like Feel | No | Somewhat | **Yes** |
+| Learning Curve | - | Medium | Medium |
+| Community Size | - | **Largest** | Medium |
+| Migration Time | - | 6-8 weeks | 6-7 weeks |
+
+---
+
+## Key Metrics
+
+### Next.js Migration
+| Aspect | Value |
+|--------|-------|
+| Estimated Duration | 6-8 weeks |
+| Routes to Migrate | ~25 |
+| Files to Change | ~150 |
+| Custom Code Preserved | ~85% |
+| Boilerplate Reduction | Low |
+
+### Remix Migration
+| Aspect | Value |
+|--------|-------|
+| Estimated Duration | 6-7 weeks |
+| Routes to Migrate | ~25 |
+| Files to Delete | ~43 (hooks → loaders) |
+| Custom Code Preserved | ~85% |
+| Boilerplate Reduction | **High** |
+
+---
+
+## Recommendation
+
+**Go with Remix** because:
+
+1. **Loaders replace ~22 data hooks** - prescribed pattern for data fetching
+2. **Actions replace ~15 mutation hooks** - prescribed pattern for mutations
+3. **URL state is built-in** - no more useFilters, useSort, usePagination
+4. **Forms are first-class** - `<Form>` with automatic pending states
+5. **More opinionated** - closer to "DRF for frontend" philosophy
+6. **Same migration effort** - ~6-7 weeks vs 6-8 weeks for Next.js
+
+### Suggested Approach
+
+1. **POC (1 week)**: Migrate login + projects list + one occurrence page
+2. **Evaluate**: Does it reduce boilerplate? Is the pattern clear?
+3. **Decide**: Continue or reconsider
+4. **Full migration (5-6 weeks)**: If POC successful
+
+---
+
+## Team Context
+
+- **2 developers** + periodic interns + AI agents
+- Need **prescribed patterns** for fast onboarding
+- Want to **reduce custom code** maintenance burden
+- Looking for **DRF-like productivity** on frontend
+
+See [Motivations](./08-motivations.md) for full context.
+
+---
+
+## Created
+- **Date**: 2026-02-04
+- **Branch**: claude/nextjs-migration-planning-nx9Cd
+- **Updated**: 2026-02-04 (added Remix assessment)

.agents/planning/01-current-state.md

@@ -0,0 +1,209 @@
+# Current State of UI and API
+
+## Overview
+
+The Antenna UI is a React 18 single-page application (SPA) built with Vite, serving as the frontend for the Automated Monitoring of Insects ML Platform. It interfaces with a Django REST Framework backend via a versioned JSON API.
+
+---
+
+## UI Architecture
+
+### Build System
+- **Bundler**: Vite 4.5.3
+- **Language**: TypeScript 4.4.2 (strict mode)
+- **Output**: Static bundle deployed to `./build`
+- **Dev Server**: Port 3000 with HMR
+- **Proxy**: Dev server proxies `/api` and `/media` to Django backend
+
+### Routing
+- **Library**: React Router v6.8.2
+- **Pattern**: Client-side SPA routing
+- **Structure**: Nested routes with `<Outlet />` for layout composition
+- **Modal Pattern**: Detail dialogs controlled via URL params (e.g., `/occurrences/:id?`)
+
+**Route Hierarchy:**
+```
+/
+├── /auth
+│   ├── /login
+│   ├── /reset-password
+│   └── /reset-password-confirm
+├── /projects (list)
+└── /projects/:projectId
+    ├── /summary
+    ├── /deployments/:id?
+    ├── /sessions/:id?
+    ├── /captures
+    ├── /occurrences/:id?
+    ├── /taxa/:id?
+    ├── /jobs/:id?
+    ├── /collections
+    ├── /exports/:id?
+    ├── /pipelines/:id?
+    ├── /algorithms/:id?
+    ├── /processing-services/:id?
+    ├── /sites, /devices, /general, /team
+    ├── /default-filters, /storage, /processing
+├── /terms-of-service
+└── /code-of-conduct
+```
+
+### State Management
+
+**Server State**: TanStack React Query v4.29.5
+- Automatic caching and background refetching
+- Query invalidation on mutations
+- DevTools for debugging
+
+**Client State**: React Context API
+- `UserContext` - Authentication token and login state
+- `UserInfoContext` - Current user profile
+- `UserPreferencesContext` - UI preferences (localStorage-backed)
+- `BreadcrumbContext` - Navigation breadcrumbs
+- `CookieConsentContext` - GDPR compliance
+
+### Data Fetching
+
+**Pattern**: Custom hooks wrapping React Query
+
+```typescript
+// List queries
+useOccurrences(params?: FetchParams) → { occurrences, total, isLoading }
+useJobs(params?: FetchParams) → { jobs, total, isLoading }
+
+// Detail queries
+useOccurrenceDetails(id) → { occurrence, isLoading }
+useProjectDetails(projectId) → { project, isLoading }
+
+// Mutations
+useCreateJob(onSuccess) → { createJob, isLoading, error }
+useCreateIdentification(onSuccess) → { createIdentification, isLoading }
+```
+
+**HTTP Client**: Axios with auth header injection
+
+**Query Key Pattern**: `[API_ROUTE, params]`
+
+### Component Organization
+
+```
+ui/src/
+├── components/          # Reusable UI components (filtering, forms, gallery)
+├── design-system/       # Custom primitives (34 component directories)
+│   ├── components/      # Button, Dialog, Table, etc.
+│   └── map/             # Geospatial components
+├── pages/               # Route-level components (21 page directories)
+├── data-services/       # API integration
+│   ├── hooks/           # React Query hooks (22 domain directories)
+│   ├── models/          # Client-side model classes
+│   └── constants.ts     # API routes
+└── utils/               # Shared utilities and contexts
+```
+
+### Styling
+- **Primary**: Tailwind CSS v3.4.14
+- **Secondary**: SCSS modules for component-specific styles
+- **Design Tokens**: `nova-ui-kit` library for colors and variables
+- **Breakpoints**: SM (720px), MD (1024px), LG (1440px)
+
+### Key Dependencies
+| Category | Libraries |
+|----------|-----------|
+| UI Components | Radix UI (7 packages), nova-ui-kit, lucide-react |
+| Forms | react-hook-form v7.43.9 |
+| Maps | leaflet + react-leaflet |
+| Charts | plotly.js + react-plotly.js |
+| Utilities | lodash, date-fns, classnames |
+| Monitoring | @sentry/react |
+
+### Authentication
+- **Method**: Token-based (djoser)
+- **Storage**: localStorage
+- **Header**: `Authorization: Token {token}`
+- **Auto-logout**: On 403 responses
+
+---
+
+## API Architecture
+
+### Base Configuration
+- **URL**: `/api/v2/`
+- **Framework**: Django REST Framework
+- **Schema**: OpenAPI via drf-spectacular
+- **Docs**: Swagger UI at `/api/v2/docs/`
+
+### Versioning
+- Namespace versioning (`/api/v2/`)
+- Single version currently deployed
+
+### Authentication Endpoints
+```
+POST /api/v2/auth/token/login/     # Get token (email + password)
+POST /api/v2/auth/token/logout/    # Logout
+GET  /api/v2/users/me/             # Current user
+POST /api/v2/users/reset_password/ # Password reset
+```
+
+### REST Patterns
+Standard CRUD for all resources:
+```
+GET    /api/v2/{resource}/         # List (paginated)
+POST   /api/v2/{resource}/         # Create
+GET    /api/v2/{resource}/{id}/    # Retrieve
+PUT    /api/v2/{resource}/{id}/    # Update
+DELETE /api/v2/{resource}/{id}/    # Delete
+```
+
+### Key Resources
+| Resource | Endpoint | Custom Actions |
+|----------|----------|----------------|
+| Projects | `/projects/` | `charts/` |
+| Deployments | `/deployments/` | `sync/` |
+| Events | `/events/` | `timeline/` |
+| Captures | `/captures/` | `star/`, `unstar/` |
+| Occurrences | `/occurrences/` | `add/`, `remove/`, `suggest/` |
+| Jobs | `/jobs/` | `run/`, `cancel/`, `retry/`, `tasks/`, `result/` |
+| Pipelines | `/ml/pipelines/` | `test_process/` |
+| Processing Services | `/ml/processing_services/` | `status/`, `register_pipelines/` |
+
+### Pagination
+- **Type**: Limit-Offset
+- **Default Page Size**: 10
+- **Response**: `{ count, next, previous, results, user_permissions }`
+
+### Filtering
+- Field filtering: `?field=value`
+- Ordering: `?ordering=field` or `?ordering=-field`
+- Search: `?search=query`
+- Custom threshold filters for numeric comparisons
+
+### Nested Resources
+```
+/api/v2/projects/{project_id}/members/
+```
+
+---
+
+## Current Pain Points
+
+### Development Experience
+1. **No SSR**: Initial page load shows blank screen, then hydrates
+2. **No Static Generation**: All pages require client-side data fetching
+3. **Manual Route Management**: Route constants must match router config
+4. **No Built-in API Routes**: Can't add BFF (Backend for Frontend) endpoints
+5. **Environment Config**: Manual Vite environment variable setup
+
+### Performance
+1. **Client-side Rendering Only**: No server-side rendering for SEO or performance
+2. **Large Bundle**: Single bundle for entire app (no automatic code splitting by route)
+3. **Image Optimization**: Manual image handling, no built-in optimization
+
+### SEO/Accessibility
+1. **Dynamic Titles**: Managed via react-helmet-async instead of native
+2. **No Metadata API**: Must manually manage Open Graph tags
+3. **Crawler Issues**: SPA content not visible to crawlers without JS
+
+### Architecture
+1. **Proxy Dependency**: Development requires Vite proxy to Django
+2. **No Edge/Middleware**: Can't intercept requests at edge
+3. **Manual Caching**: No built-in data caching beyond React Query