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

21 KiB
Raw Blame History

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

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

Feature created from application-plan.md