DeutschLernen/docs/features/lesson-management.md

Feature: Lesson & Content Management

Status: ⏳ Planned
Priority: High
Complexity: High
Estimate: 10-16 hours
Assignee: -
Created: May 31, 2025
Target Completion: -
PR: -
Related Features: Infrastructure Setup, User Authentication, Vocabulary System, Quiz System, Story Integration

---

📌 Overview

Purpose

Implement the core lesson management system that allows users to browse, access, and progress through structured German lessons organized by CEFR levels (A1-C1).

User Story

As a learner, I want to access structured lessons organized by difficulty level so that I can systematically learn German from A1 to C1.

Acceptance Criteria

• Lessons are organized by CEFR levels (A1, A2, B1, B2, C1)
• Lessons within each level must be completed in order
• Each lesson contains vocabulary, grammar, story segment, and exercises
• Users can view lesson details and content
• Progress is tracked per user per lesson
• Lessons unlock sequentially based on quiz completion (80% passing score)

---

📋 Requirements

Functional Requirements

ID	Requirement	Priority
FR-001	Create/Read/Update/Delete lessons (Admin)	High
FR-002	List lessons by level	High
FR-003	Get lesson details with all content	High
FR-004	Track user progress through lessons	High
FR-005	Enforce sequential lesson unlocking	High
FR-006	Lesson contains: vocabulary, grammar, story, reading, listening, speaking, writing, quiz	High
FR-007	Calculate level completion percentage	Medium
FR-008	Admin can reorder lessons	Low

Non-Functional Requirements

• Performance: Lesson listing < 200ms
• Performance: Lesson details < 500ms
• Security: Only authorized admins can create/edit lessons
• Data Integrity: Lesson order must be maintained

---

🏗️ Technical Design

Components Involved

• Backend: LessonsController, LessonService, LevelService
• Database: Levels, Lessons, UserProgress tables
• Models: Level, Lesson, LessonDto, LevelDto
• Frontend: LessonPage, LessonList, LessonCard components

Data Flow

1. User requests lessons for A1 level
2. Backend queries Lessons table filtered by LevelId = A1
3. Backend checks UserProgress to determine which lessons are unlocked
4. Backend returns list of lessons with locked/unlocked status
5. User selects a lesson
6. Backend returns full lesson content (vocabulary, grammar, story, etc.)
7. User completes lesson activities
8. User takes quiz
9. If quiz passed (80%), mark lesson as completed and unlock next lesson

API Endpoints

Endpoint	Method	Description	Auth Required
/api/levels	GET	List all CEFR levels	Yes
/api/levels/{levelId}/lessons	GET	List lessons for a specific level	Yes
/api/lessons/{id}	GET	Get full lesson details with all content	Yes
/api/lessons	POST	Create new lesson (Admin)	Yes
/api/lessons/{id}	PUT	Update lesson (Admin)	Yes
/api/lessons/{id}	DELETE	Delete lesson (Admin)	Yes
/api/lessons/{id}/reorder	POST	Reorder lessons (Admin)	Yes

Database Schema (from application-plan.md)

-- Levels table
CREATE TABLE Levels (
    Id SERIAL PRIMARY KEY,
    Name VARCHAR(10) UNIQUE NOT NULL,  -- e.g., "A1", "A2"
    Description TEXT,
    Order INT UNIQUE NOT NULL
);

-- Lessons table
CREATE TABLE Lessons (
    Id SERIAL PRIMARY KEY,
    LevelId INT REFERENCES Levels(Id) ON DELETE CASCADE,
    Title VARCHAR(100) NOT NULL,
    Order INT NOT NULL,
    Topic VARCHAR(100) NOT NULL,
    UNIQUE(LevelId, Order)
);

-- User Progress table
CREATE TABLE UserProgress (
    Id SERIAL PRIMARY KEY,
    UserId INT REFERENCES Users(Id) ON DELETE CASCADE,
    LessonId INT,
    IsCompleted BOOLEAN DEFAULT FALSE,
    QuizScore INT,
    LastAttemptDate TIMESTAMP DEFAULT NOW(),
    UNIQUE(UserId, LessonId)
);

Lesson Content Structure

Each lesson contains:

1. Vocabulary: 5-10 words with translations, articles, audio
2. Grammar: Concept explanation with examples and audio
3. Story Segment: Part of continuous narrative using lesson vocabulary
4. Reading: Short text with comprehension questions
5. Listening: Audio exercises with questions
6. Speaking: Recording exercises
7. Writing: Open-ended prompts
8. Quiz: 10-15 questions to test understanding

---

🚀 Implementation Plan

Phase 1: Database & Models (2-3 hours)

• Create Level entity and repository
• Create Lesson entity and repository
• Create UserProgress entity and repository
• Set up relationships between entities
• Create migrations for Levels, Lessons, UserProgress
• Seed initial A1 level and lessons

Phase 2: Backend Services (3-5 hours)

• Create LevelService with CRUD operations
• Create LessonService with CRUD operations
• Create ProgressService to track user progress
• Implement sequential unlocking logic
• Create DTOs for Level, Lesson, UserProgress
• Create mapping profiles (AutoMapper or manual)

Phase 3: API Controllers (2-3 hours)

• Create LevelsController
• Create LessonsController
• Add authorization (Admin for write operations)
• Add validation for lesson data
• Implement proper error handling

Phase 4: Business Logic (2-3 hours)

• Implement lesson unlocking logic
• Calculate level completion percentage
• Add next lesson recommendation
• Implement lesson order validation

Phase 5: Integration with Other Features (1-2 hours)

• Integrate with Vocabulary system
• Integrate with Story system
• Integrate with Quiz system
• Update user progress on quiz completion

Milestones

Milestone	Date	Status
Database & Models	-	⏳
Backend Services	-	⏳
API Controllers	-	⏳
Business Logic	-	⏳
Integration	-	⏳

---

✅ Tasks

Backend

• Create Domain/Entities/Level.cs
• Create Domain/Entities/Lesson.cs
• Create Domain/Entities/UserProgress.cs
• Create Domain/Interfaces/ILevelRepository.cs
• Create Domain/Interfaces/ILessonRepository.cs
• Create Infrastructure/Data/Repositories/LevelRepository.cs
• Create Infrastructure/Data/Repositories/LessonRepository.cs
• Create Infrastructure/Data/Repositories/UserProgressRepository.cs
• Create Application/DTOs/LevelDto.cs
• Create Application/DTOs/LessonDto.cs
• Create Application/DTOs/UserProgressDto.cs
• Create Application/Services/LevelService.cs
• Create Application/Services/LessonService.cs
• Create Application/Services/ProgressService.cs
• Create Presentation/Controllers/LevelsController.cs
• Create Presentation/Controllers/LessonsController.cs
• Register services in Program.cs
• Write unit tests for services
• Write integration tests for controllers

Database

• Create migration for Levels table
• Create migration for Lessons table
• Create migration for UserProgress table
• Seed A1 level with initial lessons
• Add indexes for performance

Business Logic

• Implement LessonUnlockService
• Implement LevelCompletionCalculator
• Add validation for lesson order
• Add authorization checks

Integration

• Integrate with Vocabulary feature
• Integrate with Story feature
• Integrate with Quiz feature
• Update progress when quiz is passed

---

🔗 Dependencies

Feature Dependencies

• Infrastructure Setup - Required (backend project and database)
• User Authentication - Required (for user-specific progress tracking)
• Vocabulary System - Required (lesson content)
• Story Integration - Required (lesson content)
• Quiz System - Required (lesson completion)

Technical Dependencies

• Entity Framework Core
• AutoMapper (optional, for DTO mapping)

Blockers

• Infrastructure Setup must be complete
• User Authentication must be complete for progress tracking

---

✅ 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

Lesson Management-Specific Criteria

• All CEFR levels (A1-C1) can be created and managed
• Lessons can be created, read, updated, and deleted
• Lessons are properly ordered within levels
• Sequential lesson unlocking works correctly
• User progress is tracked per lesson
• Level completion percentage is calculated correctly
• Next lesson recommendation works
• Admin can reorder lessons
• All lesson content (vocabulary, grammar, story, etc.) can be associated

---

🧪 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

Lesson Management-Specific Tests

Backend Tests

• Create level → success
• Create level with duplicate name → error
• Get all levels → returns correct list
• Create lesson → success
• Create lesson with duplicate (level, order) → error
• Get lessons by level → returns correct list
• Get lesson by ID → returns correct lesson
• Update lesson → success
• Update lesson order → updates correctly, cascades to other lessons
• Delete lesson → success, updates other lessons' order
• Get user progress for lesson → returns correct status
• Complete lesson → updates progress, unlocks next lesson
• Calculate level completion → returns correct percentage

Business Logic Tests

• Lesson unlocking with completed previous lesson → success
• Lesson unlocking without completed previous lesson → fails
• Level completion with all lessons completed → 100%
• Level completion with some lessons completed → correct %
• Lesson reordering updates all subsequent lessons → correct
• Lesson deletion updates all subsequent lessons → correct

Integration Tests

• Create lesson with vocabulary → both created
• Create lesson with quiz → both created
• Complete lesson → triggers quiz availability
• User progress updates when quiz passed → lesson marked complete

---

📝 Notes & Decisions

Decisions Made

Date	Decision	Rationale
May 31, 2025	Sequential lesson unlocking	Ensures users learn foundation before advanced topics
May 31, 2025	80% passing score	Balance between rigor and user frustration
May 31, 2025	Lessons organized by CEFR levels	Industry standard for language learning
May 31, 2025	Unlimited quiz retakes	Encourages practice without penalty

Technical Notes

• Lesson order is critical - use database UNIQUE constraint on (LevelId, Order)
• UserProgress table tracks both completion status and quiz scores
• Progress calculation: (completed lessons / total lessons in level) * 100
• Lesson unlocking: User can access lesson N only if lesson N-1 is completed

Gotchas

• ⚠️ Lesson reordering must update all subsequent lessons' Order values
• ⚠️ Deleting a lesson requires updating all lessons with higher Order values
• ⚠️ UserProgress.LessonId can be NULL for lessons not yet started
• ⚠️ Need to handle case where user hasn't started any lessons in a level

---

📊 Progress History

Date	Status Change	Notes
May 31, 2025	Created	Initial plan based on application-plan.md

---

📎 Related Files & Links

• Architecture: Backend Structure
• Architecture: Application Plan
• Database Schema: Initial Database Schema
• Feature: Vocabulary System
• Feature: Story Integration
• Feature: Quiz System

---

Feature created from application-plan.md