Class_generator/docs/progress-system.md

Progress System

🎯 Core Philosophy

FUNDAMENTAL RULE: Every piece of content is a trackable progress item with strict validation and type safety.

🏗️ Pedagogical Flow

1. DISCOVERY → 2. MASTERY → 3. APPLICATION
   (passive)      (active)       (context)

Flow Rules (NON-NEGOTIABLE)

• ❌ NO Flashcards on undiscovered words - Must discover first
• ❌ NO Text exercises on unmastered vocabulary - Must master first
• ✅ Always check prerequisites before ANY exercise
• ✅ Form vocabulary lists on-the-fly from next exercise content

📦 Progress Item Types & Weights

Type	Weight	Prerequisites
vocabulary-discovery	1	None
vocabulary-mastery	1	Must be discovered
phrase	6	Vocabulary mastered
dialog	12	Vocabulary mastered
text	15	Vocabulary mastered
audio	12	Vocabulary mastered
image	6	Vocabulary discovered
grammar	6	Vocabulary discovered

Total for 1 vocabulary word = 2 points (1 discovery + 1 mastery)

📈 Progress Calculation

Chapter Analysis

When loading a chapter:

1. Scans ALL content (vocabulary, phrases, dialogs, texts, etc.)
2. Creates progress items for each piece
3. Calculates total weight (sum of all item weights)
4. Stores item registry for tracking

Example Chapter:

• 171 vocabulary words → 342 points (171×2: discovery + mastery)
• 75 phrases → 450 points (75×6)
• 6 dialogs → 72 points (6×12)
• 3 lessons → 45 points (3×15)
• TOTAL: 909 points

Progress Formula

percentage = (completedWeight / totalWeight) × 100

// Example:
// - Discovered 50 words = 50 points
// - Mastered 20 words = 20 points
// - Completed 3 phrases = 18 points (3×6)
// - Completed 1 dialog = 12 points
// Total completed = 100 points
// Progress = (100 / 909) × 100 = 11%

Breakdown Display

{
  percentage: 11,
  completedWeight: 100,
  totalWeight: 909,
  breakdown: {
    'vocabulary-discovery': { count: 50, weight: 50 },
    'vocabulary-mastery': { count: 20, weight: 20 },
    'phrase': { count: 3, weight: 18 },
    'dialog': { count: 1, weight: 12 }
  }
}

🎯 Smart Vocabulary Prerequisites

OLD Approach (Wrong)

Force all 171 words upfront based on arbitrary percentages.

NEW Approach (Correct)

Analyze next content → extract words → check user status → force only needed words.

Example Flow

// Next exercise: Dialog "Academic Conference"
// Words in dialog: methodology, hypothesis, analysis, paradigm, framework

// User status check:
// - methodology: never seen → Discovery needed
// - hypothesis: discovered, not mastered → Mastery needed
// - analysis: mastered → Skip
// - paradigm: never seen → Discovery needed
// - framework: discovered, not mastered → Mastery needed

// Smart system creates:
// 1. Discovery module: [methodology, paradigm] (2 words)
// 2. Mastery module: [hypothesis, framework] (2 words)
// 3. Then allow dialog exercise

Benefits

• Targeted Learning - Only learn words actually needed
• Context-Driven - Vocabulary tied to real content usage
• Efficient Progress - No time wasted on irrelevant words
• Better Retention - Words learned in context of upcoming usage
• Smart Adaptation - UI accurately reflects what's happening

🔧 Key Components

1. ProgressItemInterface

Abstract base with strict validation for all progress items.

Location: src/DRS/interfaces/ProgressItemInterface.js

Methods:

• validate() - Validate item data
• serialize() - Convert to JSON
• getWeight() - Return item weight
• canComplete(state) - Check prerequisites

2. ProgressTracker

Manages state, marks completion, saves progress.

Location: src/DRS/services/ProgressTracker.js

Key Methods:

• markWordDiscovered(word, metadata)
• markWordMastered(word, metadata)
• markContentCompleted(type, id, metadata)
• getProgress(chapterId)
• saveProgress(bookId, chapterId)
• loadProgress(bookId, chapterId)

3. PrerequisiteEngine

Checks prerequisites and enforces pedagogical flow.

Location: src/DRS/services/PrerequisiteEngine.js

Key Methods:

• canComplete(itemType, itemId, context)
• getUnmetPrerequisites(itemType, itemId)
• enforcePrerequisites(exerciseConfig)

4. ContentDependencyAnalyzer

Analyzes content and extracts vocabulary dependencies.

Location: src/DRS/services/ContentDependencyAnalyzer.js

Key Methods:

• analyzeContentDependencies(nextContent, vocabularyModule)
• extractWordsFromContent(content)
• findMissingWords(wordsInContent, vocabularyWords)

📊 UI Integration

Progress Display

Chapter Progress: 11% (100/909 points)

✅ Vocabulary Discovery: 50/171 words (50pts)
✅ Vocabulary Mastery: 20/171 words (20pts)
✅ Phrases: 3/75 (18pts)
✅ Dialogs: 1/6 (12pts)
⬜ Texts: 0/3 (0/45pts)

Smart Guide Updates

🔍 Analyzing next exercise: Dialog "Academic Conference"
📚 4 words needed (2 discovery, 2 mastery)
🎯 Starting Vocabulary Discovery for: methodology, paradigm

✅ Validation Checklist

Before ANY exercise can run:

• Prerequisites analyzed for next specific content
• Missing words identified
• Discovery forced for never-seen words
• Mastery forced for seen-but-not-mastered words
• Progress item created with correct weight
• Completion properly tracked and saved
• Total progress recalculated

If ANY step fails → Clear error message, app stops gracefully

🚨 Error Prevention

Compile-Time (Startup)

• Interface validation via ImplementationValidator
• Method implementation checks
• Weight configuration validation

Runtime

• Prerequisite enforcement before exercises
• State consistency checks
• Progress calculation validation

Visual Feedback

• Red screen for missing implementations
• Clear prerequisite errors
• Progress breakdown always visible

🔍 Debug Commands

// Get current progress
window.app.getCore().progressTracker.getProgress('chapter-1')

// Check if word discovered
window.app.getCore().progressTracker.isWordDiscovered('methodology')

// Check if word mastered
window.app.getCore().progressTracker.isWordMastered('hypothesis')

// Check prerequisites
window.app.getCore().prerequisiteEngine.canComplete('dialog', 'dialog-3')

// Get unmet prerequisites
window.app.getCore().prerequisiteEngine.getUnmetPrerequisites('text', 'lesson-1')

📋 Adding New Progress Item Types

1. Create new class extending ProgressItemInterface
2. Implement all 4 required methods
3. Add weight to WEIGHTS constant
4. Add to ImplementationValidator
5. Update ProgressTracker tracking methods
6. Update UI components
7. Test with validation

🧪 Testing Progress System

// Test progress calculation
const tracker = window.app.getCore().progressTracker;

// Mark some progress
await tracker.markWordDiscovered('test', {});
await tracker.markWordMastered('test', {});

// Check progress
const progress = tracker.getProgress('chapter-1');
console.log(progress);

// Should show updated percentage and breakdown

📖 Further Reading

• docs/interfaces.md - Interface system details
• docs/creating-new-module.md - Module creation guide
• README.md - Project overview