captains-log/plan/01_CORE_MVP/frontend.md

Frontend MVP Implementation Plan

Overview

This plan details the concrete implementation steps for the Captain's Log frontend MVP using Vite + React + TypeScript + Tailwind CSS 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
    ├── tailwind.config.js          # Tailwind CSS 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           # Tailwind imports and custom styles
    └── tests/
        └── components/             # Component unit tests

Phase 1: Project Foundation (Days 1-2)

Task 1.1: Initialize Frontend Project

• File: frontend/package.json
  • Create new Vite + React + TypeScript project
  • Add dependencies: react, react-dom, react-router-dom, tailwindcss, @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

• Files: frontend/vite.config.ts, frontend/tsconfig.json, frontend/tailwind.config.js
  • Configure Vite with React plugin and proxy to backend
  • Setup TypeScript with strict mode and path aliases
  • Configure Tailwind CSS with custom design tokens
  • Setup Vitest for testing
  • Expected outcome: npm run dev starts frontend development server

Task 1.3: Create Frontend Justfile

• 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

• 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

• 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

• 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

• 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

• 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 Tailwind CSS for custom styling.

Task 3.1: Main App Component and Routing

• 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 Tailwind utilities
  • 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)

{
  "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",
    "tailwindcss": "^3.4.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

# 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)

set working-directory := '.'

dev-backend:
    cargo run

build-backend:
    cargo build

test-unit-backend:
    cargo test

Frontend Justfile (new commands)

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.