# Frontend MVP Implementation Plan

## Overview
This plan details the concrete implementation steps for the Captain's Log frontend MVP using Vite + React + TypeScript with comprehensive testing infrastructure.

## Project Structure (Planned Implementation)
```
captains-log/
├── justfile                        # Root task runner with combined commands
├── backend/
│   ├── justfile                    # Backend-specific commands
│   └── ... (existing backend structure)
└── frontend/
    ├── justfile                    # Frontend-specific commands
    ├── package.json                # Node.js project manifest
    ├── vite.config.ts              # Vite configuration
    ├── tsconfig.json               # TypeScript configuration
    ├── postcss.config.js           # PostCSS configuration
    ├── index.html                  # Entry HTML file
    ├── src/
    │   ├── main.tsx                # Application entry point
    │   ├── App.tsx                 # Root component with routing
    │   ├── components/
    │   │   ├── TaskCard.tsx        # Individual task display
    │   │   ├── TaskForm.tsx        # Create/edit task form
    │   │   ├── TaskList.tsx        # Main task list view
    │   │   ├── QuickCapture.tsx    # Rapid task entry
    │   │   └── StatusBadge.tsx     # Task status visualization
    │   ├── hooks/
    │   │   ├── useTask.ts          # Single task operations
    │   │   ├── useTasks.ts         # Multiple task operations
    │   │   └── useApi.ts           # Generic API utilities
    │   ├── services/
    │   │   └── api.ts              # Backend API client
    │   ├── types/
    │   │   └── task.ts             # TypeScript type definitions
    │   └── styles/
    │       └── index.css           # CSS imports and custom styles
    └── tests/
        └── components/             # Component unit tests
```

## Phase 1: Project Foundation (Days 1-2)

### Task 1.1: Initialize Frontend Project
- [x] **File**: `frontend/package.json`
  - Create new Vite + React + TypeScript project
  - Add dependencies: react, react-dom, react-router-dom, @types/*
  - Add dev dependencies: vitest, @testing-library/react, @testing-library/jest-dom
  - Configure scripts for dev, build, test, lint
  - **Expected outcome**: `npm install` succeeds

### Task 1.2: Setup Build Tools and Configuration
- [x] **Files**: `frontend/vite.config.ts`, `frontend/tsconfig.json`, `frontend/postcss.config.js`
  - Configure Vite with React plugin and proxy to backend
  - Setup TypeScript with strict mode and path aliases
  - Configure CSS styling framework
  - Setup Vitest for testing
  - **Expected outcome**: `npm run dev` starts frontend development server

### Task 1.3: Create Frontend Justfile
- [x] **File**: `frontend/justfile`
  - Commands: `dev-frontend`, `build-frontend`, `test-frontend`, `lint-frontend`, `fmt-frontend`
  - Setup proxy configuration for backend API
  - **Expected outcome**: `just --list` in frontend directory shows all commands

### Task 1.4: Update Root Justfile Structure
- [x] **Files**: `justfile`, `backend/justfile`
  - Move existing backend commands to `backend/justfile`
  - Create new root justfile with combined commands
  - Add concurrent execution for `dev` command (both backend + frontend)
  - Include commands: `dev`, `build`, `test`, `test-unit`, `fmt`, `lint`
  - **Expected outcome**: `just dev` starts both backend and frontend

## Phase 2: Core API Integration (Days 3-4)

### Task 2.1: Define TypeScript Types
- [x] **File**: `frontend/src/types/task.ts`
  - Create Task interface matching backend TaskModel
  - Add TaskStatus enum (Todo, Done, Backlog)
  - Include API response types and error types
  - **Expected outcome**: Type definitions compile without errors

### Task 2.2: Backend API Client
- [x] **File**: `frontend/src/services/api.ts`
  - Implement API client with fetch wrapper
  - Add all task endpoints: GET, POST, PUT, DELETE /api/tasks
  - Include error handling and response parsing
  - Add request/response logging for development
  - **Expected outcome**: API client can communicate with backend

### Task 2.3: Custom React Hooks for API
- [x] **Files**: `frontend/src/hooks/useTask.ts`, `frontend/src/hooks/useTasks.ts`
  - Create useTask hook for single task operations (get, update, delete)
  - Create useTasks hook for task list operations (list, create)
  - Include loading states, error handling, and optimistic updates
  - Add data caching and synchronization
  - **Expected outcome**: Hooks provide clean API for components

### Task 2.4: API Integration Tests
- [x] **File**: `frontend/tests/api.test.ts`
  - Test API client with mock responses
  - Test custom hooks with mock API calls
  - Test error handling scenarios
  - Use vitest and testing library utilities
  - **Expected outcome**: `just test-frontend` passes all API tests

## Phase 3: Core Components (Days 5-6)

**UI Framework**: Use Material-UI (MUI) for consistent design system and components alongside CSS for custom styling.

### Task 3.1: Main App Component and Routing
- [x] **Files**: `frontend/src/App.tsx`, `frontend/src/main.tsx`
  - Setup React Router with basic navigation
  - Create main layout with MUI AppBar/Drawer and task area
  - Implement responsive design with MUI breakpoints and CSS
  - Add MUI loading states (CircularProgress) and error boundaries
  - Configure MUI theme with custom colors
  - **Expected outcome**: Full application loads and navigates properly with Material Design

### Task 3.2: Task List Component
- [ ] **File**: `frontend/src/components/TaskList.tsx`
  - Display tasks using MUI List/Grid components
  - Filter tasks by status using MUI Chip/Select components
  - Sort tasks with MUI Select dropdown
  - Implement virtual scrolling with MUI virtualization
  - **Expected outcome**: TaskList displays tasks efficiently with Material Design

### Task 3.3: Task Card Component
- [ ] **File**: `frontend/src/components/TaskCard.tsx`
  - Display task with title, description, status, dates
  - Implement inline editing for title and description
  - Add status change buttons/dropdown
  - Include delete confirmation
  - Mobile-friendly touch interactions
  - **Expected outcome**: TaskCard displays and edits tasks correctly

### Task 3.4: Task Form Component
- [ ] **File**: `frontend/src/components/TaskForm.tsx`
  - Create/edit form using Formik for form state management
  - Use MUI TextField, Select, and Button components
  - Form validation with Yup schema and error display
  - Handle form submission with API calls through Formik onSubmit
  - Support both MUI Dialog modal and inline modes
  - **Expected outcome**: TaskForm creates and updates tasks with robust form handling

### Task 3.5: Quick Capture Component
- [ ] **File**: `frontend/src/components/QuickCapture.tsx`
  - Minimal input for rapid task creation
  - Auto-focus and keyboard shortcuts
  - Optimistic UI updates
  - Smart defaults for new tasks
  - **Expected outcome**: QuickCapture enables fast task entry

### Task 3.6: Status Badge Component
- [ ] **File**: `frontend/src/components/StatusBadge.tsx`
  - Visual status indicators with colors
  - Consistent styling across components
  - Accessible color schemes
  - **Expected outcome**: StatusBadge provides clear status visualization

### Task 3.7: Component Unit Tests
- [ ] **Files**: `frontend/tests/components/*.test.tsx`
  - Test all components with React Testing Library
  - Test user interactions and state changes
  - Test API integration through mocked hooks
  - Test accessibility basics (aria labels, keyboard navigation)
  - **Expected outcome**: All component tests pass

## Phase 4: Main Application (Days 7-8)

### Task 4.3: State Management and Persistence
- [ ] **File**: `frontend/src/hooks/useApi.ts`
  - Implement localStorage for offline task caching
  - Add synchronization when coming back online
  - Handle conflicting updates gracefully
  - Maintain app state across page refreshes
  - **Expected outcome**: App works offline and syncs when online

### Task 4.4: Mobile Responsiveness
- [ ] **Files**: Update all component styles
  - Optimize layouts for mobile screens (320px+)
  - Add touch gestures for common actions
  - Ensure forms work well on mobile keyboards
  - Test on various screen sizes
  - **Expected outcome**: App is fully usable on mobile devices

## Phase 5: Polish and Testing (Day 9)

### Task 5.1: Error Handling and User Feedback
- [ ] **Files**: Update all components
  - Add comprehensive error messages
  - Implement toast notifications for actions
  - Add loading spinners and skeleton screens
  - Handle network failures gracefully
  - **Expected outcome**: Users get clear feedback for all actions

### Task 5.2: Performance Optimization
- [ ] **Files**: Review and optimize all components
  - Implement React.memo where appropriate
  - Optimize re-renders with useCallback/useMemo
  - Add code splitting for larger bundles
  - Optimize images and assets
  - **Expected outcome**: App loads and responds quickly

### Task 5.3: Comprehensive Testing
- [ ] **Files**: Expand test coverage
  - Achieve >80% frontend code coverage
  - Test integration between components
  - Test error scenarios and edge cases
  - Add performance tests if needed
  - **Expected outcome**: `just test-frontend` passes with high coverage

### Task 5.4: Final Integration Testing
- [ ] **Manual testing of full application**
  - Test complete user workflows
  - Verify backend-frontend integration
  - Test on different browsers and devices
  - Validate all MVP requirements are met
  - **Expected outcome**: Full application works end-to-end

## Dependencies and Key Technologies

### Core Dependencies (package.json)
```json
{
  "dependencies": {
    "react": "^18.3.0",
    "react-dom": "^18.3.0",
    "react-router-dom": "^6.26.0"
  },
  "devDependencies": {
    "@types/react": "^18.3.0",
    "@types/react-dom": "^18.3.0",
    "@vitejs/plugin-react": "^4.3.0",
    "vite": "^5.4.0",
    "typescript": "^5.5.0",
    "vitest": "^2.0.0",
    "@testing-library/react": "^16.0.0",
    "@testing-library/jest-dom": "^6.5.0"
  }
}
```

### Testing Tools
- **Unit Tests**: Vitest with React Testing Library
- **Component Tests**: User interaction testing
- **API Tests**: Mock-based testing of hooks and services
- **Coverage**: Vitest coverage reporting

## Justfile Commands Structure

### Root Justfile Commands
```just
# Combined commands
dev: dev-backend dev-frontend    # Start both servers concurrently
build: build-backend build-frontend
test: test-backend test-frontend
test-unit: test-unit-backend test-unit-frontend
fmt: fmt-backend fmt-frontend
lint: lint-backend lint-frontend

# Individual service commands
dev-backend:
    just backend/dev-backend
    
dev-frontend:
    just frontend/dev-frontend
```

### Backend Justfile (migrated commands)
```just
set working-directory := '.'

dev-backend:
    cargo run

build-backend:
    cargo build

test-unit-backend:
    cargo test
```

### Frontend Justfile (new commands)
```just
set working-directory := '.'

dev-frontend:
    npm run dev

build-frontend:
    npm run build

test-frontend:
    npm test

lint-frontend:
    npm run lint
```

## Success Criteria
- [ ] All CRUD operations work through the UI
- [ ] Mobile-responsive design functions well
- [ ] >80% frontend code coverage achieved
- [ ] Integration with backend API is seamless
- [ ] Quick capture enables rapid task entry
- [ ] Task list filtering and sorting work correctly
- [ ] Offline functionality with sync capabilities
- [ ] Error handling provides clear user feedback
- [ ] Performance is acceptable for MVP usage

## Testing Strategy Summary
1. **Unit Tests**: Component testing with React Testing Library and Vitest
2. **Integration Tests**: API hook testing with mock backend
3. **Manual Testing**: Cross-browser and mobile device validation
4. **Coverage**: Automated coverage reporting with Vitest
5. **Performance**: Basic performance validation during development

This plan provides a comprehensive roadmap for implementing a robust, well-tested frontend MVP that integrates seamlessly with the existing backend API and meets all requirements outlined in the original plan.md.