317 lines
12 KiB
Markdown
317 lines
12 KiB
Markdown
# 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
|
|
- [x] **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
|
|
- [x] **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
|
|
- [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
|
|
- [ ] **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)
|
|
|
|
### Task 3.1: 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.2: Task Form Component
|
|
- [ ] **File**: `frontend/src/components/TaskForm.tsx`
|
|
- Create/edit form with all task properties
|
|
- Form validation and error display
|
|
- Handle form submission with API calls
|
|
- Support both modal and inline modes
|
|
- **Expected outcome**: TaskForm creates and updates tasks
|
|
|
|
### Task 3.3: 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.4: 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.5: 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.1: Task List Component
|
|
- [ ] **File**: `frontend/src/components/TaskList.tsx`
|
|
- Display tasks in organized list/grid layout
|
|
- Filter tasks by status (Todo, In Progress, Done, Someday)
|
|
- Sort tasks by created date, priority, due date
|
|
- Implement virtual scrolling for performance
|
|
- **Expected outcome**: TaskList displays tasks efficiently
|
|
|
|
### Task 4.2: Main App Component and Routing
|
|
- [ ] **Files**: `frontend/src/App.tsx`, `frontend/src/main.tsx`
|
|
- Setup React Router with basic navigation
|
|
- Create main layout with header and task area
|
|
- Implement responsive design with Tailwind
|
|
- Add loading states and error boundaries
|
|
- **Expected outcome**: Full application loads and navigates properly
|
|
|
|
### 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",
|
|
"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
|
|
```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.
|