# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

Interactive English learning platform for children (8-9 years old) built as a modular Single Page Application. The system provides 9 different educational games that work with various content modules through a flexible architecture.

## Key Architecture Patterns

### Core System Flow
1. **AppNavigation** (`js/core/navigation.js`) - Central SPA navigation controller
2. **ContentScanner** (`js/core/content-scanner.js`) - Auto-discovers available content modules
3. **GameLoader** (`js/core/game-loader.js`) - Dynamically loads game and content modules
4. **Content Engine** (`js/core/content-engine.js`) - Processes and adapts content for games

### Module Loading System
- Games and content are loaded dynamically via `GameLoader.loadGame(gameType, contentType)`
- All modules register themselves on global objects: `window.GameModules` and `window.ContentModules`
- Content is discovered automatically by `ContentScanner` scanning `js/content/` directory
- Games follow consistent constructor pattern: `new GameClass({ container, content, onScoreUpdate, onGameEnd })`

### URL-Based Navigation
- Single HTML file (`index.html`) handles all navigation via URL parameters
- Routes: `?page=home|games|levels|play&game=<gameType>&content=<contentType>`
- Browser back/forward supported through `popstate` events
- Navigation history maintained in `AppNavigation.navigationHistory`
- Breadcrumb navigation with clickable path elements
- Keyboard shortcuts (ESC = go back)

## Content Module Format

### Rich Content Schema (New Architecture)

Content modules support rich, multimedia educational content with optional properties. The system adapts games and exercises based on available content features:

```javascript
window.ContentModules.ModuleName = {
    name: "Display Name",
    description: "Description text",
    difficulty: "easy|medium|hard|beginner|intermediate|advanced",
    language: "chinese|english|french|spanish",  // Target learning language
    hskLevel: "HSK1|HSK2|HSK3|HSK4|HSK5|HSK6",  // Chinese proficiency level

    // Rich vocabulary with optional multimedia
    vocabulary: {
        "word_or_character": {
            translation: "English translation",
            pinyin: "pronunciation guide",        // Optional: Chinese pinyin
            type: "noun|verb|adjective|greeting|number",  // Word classification
            pronunciation: "audio/word.mp3",     // Optional: audio file
            difficulty: "HSK1|HSK2|...",         // Optional: individual word difficulty
            strokeOrder: ["stroke1", "stroke2"], // Optional: character writing order
            examples: ["example sentence 1"],    // Optional: usage examples
            grammarNotes: "special usage rules"  // Optional: grammar context
        }
        // OR simple format for basic content:
        // "word": "simple translation"
    },

    // Grammar rules and explanations
    grammar: {
        topic_name: {
            title: "Grammar Rule Title",
            explanation: "Detailed explanation",
            examples: [
                { chinese: "中文例子", english: "English example", pinyin: "zhōng wén lì zi" }
            ],
            exercises: [/* grammar-specific exercises */]
        }
    },

    // Audio content with/without text
    audio: {
        withText: [
            {
                title: "Audio Lesson Title",
                audioFile: "audio/lesson1.mp3",
                transcript: "Full text transcript",
                translation: "English translation",
                timestamps: [{ time: 5.2, text: "specific segment" }]  // Optional
            }
        ],
        withoutText: [
            {
                title: "Listening Challenge",
                audioFile: "audio/challenge1.mp3",
                questions: [
                    { question: "What did they say?", type: "ai_interpreted" }
                ]
            }
        ]
    },

    // Poetry and cultural content
    poems: [
        {
            title: "Poem Title",
            content: "Full poem text",
            translation: "English translation",
            audioFile: "audio/poem1.mp3",      // Optional
            culturalContext: "Historical background"
        }
    ],

    // Fill-in-the-blank exercises
    fillInBlanks: [
        {
            sentence: "I _____ to school every day",
            options: ["go", "goes", "going", "went"],    // Multiple choice options
            correctAnswer: "go",
            explanation: "Present tense with 'I'"
        },
        {
            sentence: "The weather is _____ today",
            type: "open_ended",                          // AI-interpreted answers
            acceptedAnswers: ["nice", "good", "beautiful", "sunny"],
            aiPrompt: "Evaluate if answer describes weather positively"
        }
    ],

    // Sentence correction exercises
    corrections: [
        {
            incorrect: "I are happy today",
            correct: "I am happy today",
            explanation: "Use 'am' with pronoun 'I'",
            type: "grammar_correction"
        }
    ],

    // Reading comprehension with AI evaluation
    comprehension: [
        {
            text: "Long reading passage...",
            questions: [
                {
                    question: "What is the main idea?",
                    type: "ai_interpreted",
                    evaluationPrompt: "Check if answer captures main theme"
                },
                {
                    question: "Multiple choice question?",
                    type: "multiple_choice",
                    options: ["A", "B", "C", "D"],
                    correctAnswer: "B"
                }
            ]
        }
    ],

    // Matching exercises (connect lines between columns)
    matching: [
        {
            title: "Match Words to Meanings",
            leftColumn: ["apple", "book", "car"],
            rightColumn: ["苹果", "书", "车"],
            correctPairs: [
                { left: "apple", right: "苹果" },
                { left: "book", right: "书" },
                { left: "car", right: "车" }
            ]
        }
    ],

    // Standard content (backward compatibility)
    sentences: [{ english: "...", chinese: "...", pinyin: "..." }],
    texts: [{ title: "...", content: "...", translation: "..." }],
    dialogues: [{ conversation: [...] }]
};
```

### Content Adaptivity System

The platform automatically adapts available games and exercises based on content richness:

**Content Analysis:**
- System scans each content module for available features
- Generates compatibility scores for each game type
- Recommends optimal learning activities
- Handles graceful degradation when content is incomplete

**Adaptive Game Selection:**
- **Rich vocabulary** → Enable advanced matching games, pronunciation practice
- **Audio files present** → Enable listening exercises, pronunciation challenges
- **Grammar rules** → Enable correction exercises, structured lessons
- **Fill-in-blanks data** → Enable cloze tests with multiple choice or AI evaluation
- **Minimal content** → Fall back to basic vocabulary games

**Missing Content Handling:**
- Display helpful messages: "Add audio files to enable pronunciation practice"
- Suggest content enrichment opportunities
- Gracefully disable incompatible game modes
- Provide content creation tools for missing elements

**Example Adaptive Behavior:**
```javascript
// Content with only basic vocabulary
{ vocabulary: { "hello": "你好" } }
→ Enable: Basic matching, simple quiz
→ Disable: Audio practice, grammar exercises
→ Suggest: "Add pinyin and audio for pronunciation practice"

// Rich multimedia content
{ vocabulary: { "hello": { translation: "你好", pinyin: "nǐ hǎo", pronunciation: "audio/hello.mp3" } } }
→ Enable: All vocabulary games, audio practice, pronunciation scoring
→ Unlock: Advanced difficulty levels, speed challenges
```

## Game Module Format

Game modules must export to `window.GameModules` with this pattern:
```javascript
class GameName {
    constructor({ container, content, onScoreUpdate, onGameEnd }) {
        this.container = container;
        this.content = content;
        this.onScoreUpdate = onScoreUpdate;
        this.onGameEnd = onGameEnd;
    }
    
    start() { /* Initialize game */ }
    destroy() { /* Cleanup */ }
    restart() { /* Reset game state */ }
}

window.GameModules = window.GameModules || {};
window.GameModules.GameName = GameName;
```

## Configuration System

- Main config: `config/games-config.json` - defines available games and content
- Games can be enabled/disabled via `games.{gameType}.enabled`
- Content modules auto-detected but can be configured in `content` section
- UI settings, scoring rules, and feature flags also in main config

## Development Workflow

### Running the Application
Open `index.html` in a web browser - no build process required. All modules load dynamically.

### Adding New Games
1. Create `js/games/{game-name}.js` with proper module export
2. Add game configuration to `config/games-config.json`
3. Update `AppNavigation.getDefaultConfig()` if needed

### Adding New Content
1. Create `js/content/{content-name}.js` with proper module export
2. Add filename to `ContentScanner.contentFiles` array
3. Content will be auto-discovered on next app load

### Content Creation Tool
- Built-in content creator at `js/tools/content-creator.js`
- Accessible via "Créateur de Contenu" button on home page
- Generates properly formatted content modules

## Key Files by Function

**Navigation & Loading:**
- `js/core/navigation.js` - SPA navigation controller (452 lines)
- `js/core/game-loader.js` - Dynamic module loading (336 lines)
- `js/core/content-scanner.js` - Auto content discovery (376 lines)

**Content Processing:**
- `js/core/content-engine.js` - Content processing engine (484 lines)
- `js/core/content-factory.js` - Exercise generation (553 lines)
- `js/core/content-parsers.js` - Content parsing utilities (484 lines)

**Game Implementations:**
- `js/games/whack-a-mole.js` - Standard version (623 lines)
- `js/games/whack-a-mole-hard.js` - Difficult version (643 lines)
- `js/games/memory-match.js` - Memory pairs game (403 lines)
- `js/games/quiz-game.js` - Quiz system (354 lines)
- `js/games/fill-the-blank.js` - Sentence completion (418 lines)
- `js/games/text-reader.js` - Guided text reading (366 lines)
- `js/games/adventure-reader.js` - RPG-style adventure (949 lines)

## Important Implementation Details

### Scoring System
- Games call `this.onScoreUpdate(score)` to update display
- Final scores saved to localStorage with key pattern: `score_{gameType}_{contentType}`
- Best scores tracked and displayed in game-end modal
- Points per correct answer, malus per error, speed bonus
- Score history and achievement badges

### Content Compatibility
- `ContentScanner` evaluates content compatibility with each game type
- Compatibility scoring helps recommend best content for each game
- Games should handle various content formats gracefully

### Memory Management
- `GameLoader.cleanup()` called before loading new games
- Games should implement `destroy()` method for proper cleanup
- Previous game instances must be cleaned up to prevent memory leaks

### Error Handling
- Content loading errors logged but don't crash the application
- Fallback mechanisms for missing content or games
- User-friendly error messages via `Utils.showToast()`

## Design Guidelines

### Visual Design Principles
- Modern, clean design optimized for children (8-9 years old)
- Large, tactile buttons (minimum 44px for touch interfaces)
- High contrast colors for accessibility
- Smooth, non-aggressive animations
- Emoji icons combined with text labels

### Color Palette
- **Primary**: Blue (#3B82F6) - Trust, learning
- **Secondary**: Green (#10B981) - Success, validation  
- **Accent**: Orange (#F59E0B) - Energy, attention
- **Error**: Red (#EF4444) - Clear error indication
- **Neutral**: Gray (#6B7280) - Text, backgrounds

### Accessibility Features
- Full keyboard navigation support
- Alternative text for all images
- Adjustable font sizes
- High contrast mode compatibility
- Screen reader friendly markup

### Responsive Design
- Mobile/tablet adaptation
- Touch-friendly interface
- Portrait/landscape orientation support
- Fluid layouts that work on various screen sizes