lasserh/DeutschLernen
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
DeutschLernen/docs/features/frontend-ui.md
Lasse Rune Hansen 76e8af4987 Add complete solution: documentation, frontend, and project files 
- Add comprehensive documentation in docs/ (architecture, features, roadmap)
- Add german-app-frontend with Vite, TypeScript, ESLint configuration
- Add AGENTS.md and .gitignore

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-05-31 18:20:53 +02:00

605 lines
21 KiB
Markdown
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Feature: Frontend UI & Components
> **Status**: ⏳ Planned
> **Priority**: High
> **Complexity**: High
> **Estimate**: 10-16 hours
> **Assignee**: -
> **Created**: May 31, 2025
> **Target Completion**: -
> **PR**: -
> **Related Features**: Infrastructure Setup, User Authentication, Lesson Management, Vocabulary System, Quiz System, Story Integration, AI Services
---
## 📌 Overview
### Purpose
Implement the React + TypeScript frontend application with all UI components, pages, hooks, and services needed for the German learning web app.
### User Story
As a user, I want a responsive, intuitive, and visually appealing web interface so that I can easily navigate the application, access learning content, and track my progress.
### Acceptance Criteria
- [ ] React application with TypeScript and Vite
- [ ] Responsive design (mobile-first)
- [ ] All pages and components implemented
- [ ] State management configured
- [ ] API client for backend communication
- [ ] Audio playback and recording functionality
- [ ] Authentication flow integrated
---
## 📋 Requirements
### Functional Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| FR-001 | React 19 + TypeScript + Vite setup | High |
| FR-002 | Mobile-first responsive design | High |
| FR-003 | Dashboard page with progress | High |
| FR-004 | Lesson pages with all tabs | High |
| FR-005 | Quiz pages with all question types | High |
| FR-006 | Story pages with audio | High |
| FR-007 | Practice pages for speaking/writing | High |
| FR-008 | Profile page | Medium |
| FR-009 | Login/Registration pages | High |
| FR-010 | Audio player component | High |
| FR-011 | Audio recorder component | High |
| FR-012 | API client service | High |
| FR-013 | Authentication context | High |
| FR-014 | Form handling and validation | Medium |
| FR-015 | Error handling and notifications | Medium |
### Non-Functional Requirements
- Performance: Pages load in < 2 seconds
- Accessibility: WCAG 2.1 AA compliance
- Compatibility: Chrome, Firefox, Safari, Edge (latest 2 versions)
- SEO: Basic SEO metadata
- Offline: Basic offline support (cache API responses)
---
## 🏗️ Technical Design
### Architecture Overview
```
german-app-frontend/
├── public/ # Static files
│ └── audio/ # Audio files (served from backend)
├── src/
│ ├── components/ # Reusable UI components
│ │ ├── Dashboard/ # Progress bar, next lesson button
│ │ ├── Lesson/ # Vocabulary, Grammar, Story, Quiz tabs
│ │ ├── Quiz/ # Question type components
│ │ ├── Story/ # Story segment components
│ │ ├── Shared/ # Reusable UI elements
│ │ └── Layout/ # Header, Footer, Navigation
│ │
│ ├── pages/ # Page components
│ │ ├── DashboardPage.tsx
│ │ ├── LessonPage.tsx
│ │ ├── QuizPage.tsx
│ │ ├── StoryPage.tsx
│ │ ├── PracticePage.tsx
│ │ ├── ProfilePage.tsx
│ │ ├── LoginPage.tsx
│ │ └── RegisterPage.tsx
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useApi.ts # API client hook
│ │ ├── useAuth.ts # Authentication hook
│ │ ├── useAudio.ts # Audio playback hook
│ │ ├── useRecorder.ts # Audio recording hook
│ │ └── useLesson.ts # Lesson data hook
│ │
│ ├── services/ # API and business logic services
│ │ ├── api.ts # Base API client
│ │ ├── authService.ts # Authentication service
│ │ ├── lessonService.ts # Lesson service
│ │ ├── quizService.ts # Quiz service
│ │ ├── speechService.ts # Speech recognition service
│ │ └── ttsService.ts # TTS service
│ │
│ ├── stores/ # State management
│ │ └── authStore.ts # Authentication state
│ │
│ ├── types/ # TypeScript type definitions
│ │ └── index.ts # API types, component props
│ │
│ ├── styles/ # Global styles
│ │ ├── tailwind.css # Tailwind CSS
│ │ └── global.css # Global styles
│ │
│ ├── utils/ # Utility functions
│ │ ├── constants.ts # Application constants
│ │ └── helpers.ts # Helper functions
│ │
│ ├── App.tsx # Main application component
│ └── main.tsx # Application entry point
│
├── package.json
├── vite.config.ts
└── tsconfig.json
```
### Component Hierarchy
```
App
├── AuthContext
│ └── AuthProvider
├── Router
│ ├── PublicRoute
│ │ ├── LoginPage
│ │ ├── RegisterPage
│ │ └── ...
│ └── PrivateRoute
│ ├── DashboardPage
│ ├── LessonPage
│ ├── QuizPage
│ ├── StoryPage
│ ├── PracticePage
│ └── ProfilePage
└── Layout
├── Header
└── Footer
```
### Data Flow
```
1. User navigates to a page
2. Page component uses custom hooks to fetch data
3. Hooks call services which use API client
4. API client makes HTTP requests to backend
5. Backend returns data
6. Hooks transform and provide data to components
7. Components render UI with data
8. User interactions trigger service calls
9. Services update backend via API
10. UI updates to reflect changes
```
---
## 🚀 Implementation Plan
### Phase 1: Project Setup (2-4 hours)
- [ ] Initialize Vite + React + TypeScript project
- [ ] Install dependencies (React Router, Tailwind CSS, Axios, etc.)
- [ ] Configure Vite for development and production
- [ ] Set up TypeScript configuration
- [ ] Configure Tailwind CSS
- [ ] Set up folder structure
- [ ] Configure environment variables
- [ ] Set up base HTML template
### Phase 2: Core Infrastructure (2-3 hours)
- [ ] Create API client with Axios
- [ ] Set up error handling and interceptors
- [ ] Create authentication context
- [ ] Implement protected route wrapper
- [ ] Set up state management (Zustand or Redux)
- [ ] Create type definitions for API responses
- [ ] Configure routing with React Router
### Phase 3: Shared Components (2-3 hours)
- [ ] Create Layout components (Header, Footer)
- [ ] Create Button, Input, Card components
- [ ] Create LoadingSpinner, ErrorMessage components
- [ ] Create AudioPlayer component
- [ ] Create Recorder component
- [ ] Create Modal component
- [ ] Create Notification system
### Phase 4: Authentication Pages (2 hours)
- [ ] Create LoginPage
- [ ] Create RegisterPage
- [ ] Create ProfilePage
- [ ] Implement form validation
- [ ] Integrate with AuthService
- [ ] Handle authentication state
### Phase 5: Dashboard Page (2 hours)
- [ ] Create DashboardPage
- [ ] Create ProgressBar component
- [ ] Create NextLessonButton component
- [ ] Create StoryProgress component
- [ ] Create Gamification components (PointsDisplay, StreakDisplay, BadgeList)
- [ ] Integrate with data hooks
### Phase 6: Lesson Pages (3-4 hours)
- [ ] Create LessonPage with tab navigation
- [ ] Create VocabularyTab component
- [ ] Create GrammarTab component
- [ ] Create StoryTab component
- [ ] Create ReadingTab component
- [ ] Create ListeningExercise component
- [ ] Create SpeakingExercise component
- [ ] Create WritingExercise component
- [ ] Create QuizTab component
- [ ] Integrate AudioPlayer and Recorder
### Phase 7: Quiz Pages (2 hours)
- [ ] Create QuizPage
- [ ] Create McqQuestion component
- [ ] Create FillInBlank component
- [ ] Create ListeningQuestion component
- [ ] Create MatchingQuestion component
- [ ] Create QuizResults component
- [ ] Implement quiz submission
- [ ] Display results with feedback
### Phase 8: Story Pages (2 hours)
- [ ] Create StoryPage
- [ ] Create StorySegment component
- [ ] Create StoryPlayer component
- [ ] Implement word click-to-translate
- [ ] Add story navigation
- [ ] Display story progress
### Phase 9: Practice Pages (2 hours)
- [ ] Create PracticePage
- [ ] Create SpeakingPractice component
- [ ] Create WritingPractice component
- [ ] Integrate speech recognition
- [ ] Integrate writing feedback
- [ ] Display practice history
### Phase 10: Polish & Testing (2 hours)
- [ ] Add loading states
- [ ] Add error boundaries
- [ ] Implement form validation
- [ ] Add responsive design tweaks
- [ ] Test on mobile devices
- [ ] Performance optimization
- [ ] Accessibility audit
### Milestones
| Milestone | Date | Status |
|-----------|------|--------|
| Project Setup | - | ⏳ |
| Core Infrastructure | - | ⏳ |
| Shared Components | - | ⏳ |
| Authentication Pages | - | ⏳ |
| Dashboard Page | - | ⏳ |
| Lesson Pages | - | ⏳ |
| Quiz Pages | - | ⏳ |
| Story Pages | - | ⏳ |
| Practice Pages | - | ⏳ |
| Polish & Testing | - | ⏳ |
---
## ✅ Tasks
### Project Setup
- [ ] Initialize Vite project
- [ ] Install React and React DOM
- [ ] Install TypeScript
- [ ] Install React Router
- [ ] Install Tailwind CSS
- [ ] Install Axios
- [ ] Install Zustand (or Redux Toolkit)
- [ ] Install @testing-library/react
- [ ] Install other dependencies
- [ ] Configure Vite
- [ ] Configure TypeScript
- [ ] Configure Tailwind
- [ ] Set up folder structure
- [ ] Create base files
### Core Infrastructure
- [ ] Create src/services/api.ts
- [ ] Create src/contexts/AuthContext.tsx
- [ ] Create src/components/Layout/PrivateRoute.tsx
- [ ] Create src/components/Layout/PublicRoute.tsx
- [ ] Create src/types/index.ts
- [ ] Set up React Router in main.tsx
- [ ] Configure Axios interceptors
### Shared Components
- [ ] Create src/components/Layout/Header.tsx
- [ ] Create src/components/Layout/Footer.tsx
- [ ] Create src/components/Shared/Button.tsx
- [ ] Create src/components/Shared/Input.tsx
- [ ] Create src/components/Shared/Card.tsx
- [ ] Create src/components/Shared/LoadingSpinner.tsx
- [ ] Create src/components/Shared/ErrorMessage.tsx
- [ ] Create src/components/Shared/AudioPlayer.tsx
- [ ] Create src/components/Shared/Recorder.tsx
- [ ] Create src/components/Shared/Modal.tsx
- [ ] Create src/components/Shared/Notification.tsx
### Authentication
- [ ] Create src/pages/LoginPage.tsx
- [ ] Create src/pages/RegisterPage.tsx
- [ ] Create src/pages/ProfilePage.tsx
- [ ] Create src/hooks/useAuth.ts
- [ ] Create src/services/authService.ts
- [ ] Implement form validation
- [ ] Integrate with AuthContext
### Dashboard
- [ ] Create src/pages/DashboardPage.tsx
- [ ] Create src/components/Dashboard/ProgressBar.tsx
- [ ] Create src/components/Dashboard/NextLessonButton.tsx
- [ ] Create src/components/Dashboard/StoryProgress.tsx
- [ ] Create src/components/Gamification/PointsDisplay.tsx
- [ ] Create src/components/Gamification/StreakDisplay.tsx
- [ ] Create src/components/Gamification/BadgeDisplay.tsx
- [ ] Create src/hooks/useDashboard.ts
### Lesson Components
- [ ] Create src/pages/LessonPage.tsx
- [ ] Create src/components/Lesson/VocabularyTab.tsx
- [ ] Create src/components/Lesson/GrammarTab.tsx
- [ ] Create src/components/Lesson/StoryTab.tsx
- [ ] Create src/components/Lesson/ReadingTab.tsx
- [ ] Create src/components/Lesson/ListeningExercise.tsx
- [ ] Create src/components/Lesson/SpeakingExercise.tsx
- [ ] Create src/components/Lesson/WritingExercise.tsx
- [ ] Create src/components/Lesson/QuizTab.tsx
- [ ] Create src/hooks/useLesson.ts
### Quiz Components
- [ ] Create src/pages/QuizPage.tsx
- [ ] Create src/components/Quiz/McqQuestion.tsx
- [ ] Create src/components/Quiz/FillInBlank.tsx
- [ ] Create src/components/Quiz/ListeningQuestion.tsx
- [ ] Create src/components/Quiz/MatchingQuestion.tsx
- [ ] Create src/components/Quiz/QuizResults.tsx
- [ ] Create src/hooks/useQuiz.ts
- [ ] Create src/services/quizService.ts
### Story Components
- [ ] Create src/pages/StoryPage.tsx
- [ ] Create src/components/Story/StorySegment.tsx
- [ ] Create src/components/Story/StoryPlayer.tsx
- [ ] Create src/hooks/useStory.ts
- [ ] Create src/services/storyService.ts
- [ ] Implement word translation on click
### Practice Components
- [ ] Create src/pages/PracticePage.tsx
- [ ] Create src/components/Practice/SpeakingPractice.tsx
- [ ] Create src/components/Practice/WritingPractice.tsx
- [ ] Create src/hooks/usePractice.ts
- [ ] Create src/services/speechService.ts
- [ ] Create src/services/ttsService.ts
### Polish & Testing
- [ ] Add loading states to all components
- [ ] Add error boundaries
- [ ] Implement form validation
- [ ] Add responsive design
- [ ] Test on mobile devices
- [ ] Optimize bundle size
- [ ] Run accessibility audit
---
## 🔗 Dependencies
### Feature Dependencies
- [Infrastructure Setup](infrastructure-setup.md) - Backend must be ready
- [User Authentication](user-authentication.md) - Auth flow must be implemented
- [Lesson Management](lesson-management.md) - Lesson data must be available
- [Vocabulary System](vocabulary-system.md) - Vocabulary data must be available
- [Quiz System](quiz-system.md) - Quiz data must be available
- [Story Integration](story-integration.md) - Story data must be available
- [AI Services](ai-services.md) - AI services must be available
- [Gamification](gamification.md) - Gamification data must be available
### Technical Dependencies
- Node.js 18+
- npm or yarn
- Vite
- React 19
- TypeScript
- Tailwind CSS
- React Router
- Axios
- Zustand or Redux
### Blockers
- [ ] Backend API endpoints must be implemented
- [ ] AI services must be configured
- [ ] Database must be set up
---
## ✅ Definition of Done
### General Criteria (All Features)
- [ ] All acceptance criteria met and verified
- [ ] All tasks in this document completed
- [ ] Code follows Clean Architecture principles
- [ ] Code reviewed and approved by at least 1 team member
- [ ] All tests passing (unit, integration)
- [ ] Documentation updated (README, AGENTS.md if applicable)
- [ ] Feature works in development environment
- [ ] Feature deployed to staging environment
- [ ] Performance meets defined targets
- [ ] Security review completed
- [ ] No critical bugs or blockers
### Frontend-Specific Criteria
- [ ] React application builds successfully
- [ ] All pages render without errors
- [ ] All components render without errors
- [ ] All hooks work correctly
- [ ] All services work correctly
- [ ] API calls return expected data
- [ ] Authentication flow works end-to-end
- [ ] Audio playback works on all supported browsers
- [ ] Audio recording works on all supported browsers
- [ ] Responsive design works on mobile, tablet, and desktop
- [ ] Form validation works correctly
- [ ] Error handling displays user-friendly messages
- [ ] Loading states are displayed appropriately
- [ ] Accessibility meets WCAG 2.1 AA standards
---
## 🧪 Testing Strategy
### Testing Approach
| Test Type | Coverage | Tools | Responsibility |
|-----------|----------|-------|----------------|
| Unit Tests | 80%+ code coverage | MsTest, Moq | Backend Dev |
| Integration Tests | All service interactions | MsTest, TestContainers | Backend Dev |
| API Tests | All endpoints | MsTest, HttpClient | Backend Dev |
| Frontend Unit Tests | Component logic | Vitest | Frontend Dev |
| Frontend Integration | Service integration | Vitest | Frontend Dev |
| E2E Tests | Critical user journeys | Playwright | QA/Dev |
| Manual Testing | Exploratory, edge cases | BrowserStack | QA |
### Frontend-Specific Tests
#### Component Tests
- [ ] All components render without errors
- [ ] All components render with required props
- [ ] All components render with optional props
- [ ] All components handle user interactions correctly
- [ ] All components display loading states
- [ ] All components display error states
- [ ] All components are accessible (keyboard, screen reader)
- [ ] All components are responsive
#### Page Tests
- [ ] Dashboard page loads and displays data
- [ ] Lesson page loads and displays lesson content
- [ ] Lesson page tabs work correctly
- [ ] Quiz page loads and displays questions
- [ ] Quiz page submission works
- [ ] Story page loads and displays segments
- [ ] Story page audio works
- [ ] Practice page loads and displays exercises
- [ ] Practice page speech recognition works
- [ ] Practice page writing feedback works
- [ ] Login page loads and handles submission
- [ ] Register page loads and handles submission
- [ ] Profile page loads and displays user data
#### Service Tests
- [ ] API client makes correct requests
- [ ] API client handles errors correctly
- [ ] API client includes auth headers
- [ ] Auth service handles login/logout
- [ ] Lesson service returns correct data
- [ ] Quiz service handles submission
- [ ] Speech service handles recording/transcription
- [ ] TTS service handles audio generation
#### Integration Tests
- [ ] Auth context provides user state
- [ ] Protected routes redirect correctly
- [ ] Public routes are accessible
- [ ] AudioPlayer component plays audio
- [ ] Recorder component captures audio
- [ ] Modal component opens/closes
- [ ] Notification system displays messages
#### E2E Tests (Critical Journeys)
- [ ] User registration → login → view dashboard
- [ ] User navigation to lesson → complete activities → take quiz
- [ ] User navigation to story → listen to audio
- [ ] User completes lesson → quiz → progress updated
- [ ] User earns badge → badge displayed on profile
#### Browser Compatibility Tests
- [ ] All functionality works on Chrome (latest 2 versions)
- [ ] All functionality works on Firefox (latest 2 versions)
- [ ] All functionality works on Safari (latest 2 versions)
- [ ] All functionality works on Edge (latest 2 versions)
- [ ] Audio recording works on mobile Chrome
- [ ] Audio recording works on mobile Safari
- [ ] Responsive design works on all screen sizes
---
## 📝 Notes & Decisions
### Decisions Made
| Date | Decision | Rationale |
|------|----------|-----------|
| May 31, 2025 | Vite over Create React App | Faster, more modern, better DX |
| May 31, 2025 | React 19 | Latest stable version |
| May 31, 2025 | TypeScript | Type safety, better developer experience |
| May 31, 2025 | Tailwind CSS | Rapid styling, consistent design |
| May 31, 2025 | Zustand for state | Simpler than Redux, good TypeScript support |
| May 31, 2025 | Axios for HTTP | Better error handling than fetch |
| May 31, 2025 | Mobile-first | Most users will be on mobile |
### Technical Notes
- Use functional components with hooks
- Use TypeScript interfaces for all props
- Use async/await for API calls
- Handle loading and error states gracefully
- Use environment variables for API base URL
- Audio files served from backend /public/audio/
- Consider lazy loading for large components
### Component Library Considerations
For MVP, use custom components. Consider these libraries for future:
- **UI Components**: shadcn/ui, Radix UI, or Material UI
- **Forms**: React Hook Form + Zod
- **Icons**: Lucide React or Heroicons
- **Animations**: Framer Motion
- **Charts**: Recharts or Chart.js
### Audio Handling
- Use HTML5 Audio element for playback
- Use MediaRecorder API for recording
- Handle microphone permission errors
- Support Web Audio API for advanced features
- Consider audio compression for upload
### Performance Optimization
- Code splitting with React.lazy
- Image optimization
- Bundle analysis with rollup-plugin-visualizer
- Service worker for caching (workbox)
- Preload important resources
### Gotchas
- ⚠️ MediaRecorder API may not work on some mobile browsers
- ⚠️ Audio playback may be blocked without user interaction
- ⚠️ Safari has different audio format support
- ⚠️ Mobile keyboards may cover input fields
- ⚠️ Touch targets must be large enough for mobile
- ⚠️ CORS issues with audio files from different domains
---
## 📊 Progress History
| Date | Status Change | Notes |
|------|---------------|-------|
| May 31, 2025 | Created | Initial plan based on application-plan.md |
---
## 📎 Related Files & Links
- Architecture: [Frontend Structure](../architecture/frontend-structure.md)
- Architecture: [Application Plan](../architecture/application-plan.md)
- Feature: [Infrastructure Setup](infrastructure-setup.md)
- Feature: [User Authentication](user-authentication.md)
- Feature: [Lesson Management](lesson-management.md)
- Feature: [Vocabulary System](vocabulary-system.md)
- Feature: [Quiz System](quiz-system.md)
- Feature: [Story Integration](story-integration.md)
- Feature: [AI Services](ai-services.md)
- Feature: [Gamification](gamification.md)
- Reference: [Vite Docs](https://vitejs.dev/)
- Reference: [React Docs](https://react.dev/)
- Reference: [TypeScript Docs](https://www.typescriptlang.org/docs/)
- Reference: [Tailwind CSS Docs](https://tailwindcss.com/docs)
- Reference: [React Router Docs](https://reactrouter.com/)
---
*Feature created from application-plan.md*
Reference in a new issue View git blame Copy permalink