Class_generator/CLAUDE.md

# CLAUDE.md - Project Context & Instructions

## 📋 Project Overview

**Class Generator 2.0** - Complete rewrite of educational games platform with ultra-modular architecture.

### 🎯 Current Mission
Building a **bulletproof modular system** with strict separation of concerns using vanilla JavaScript, HTML, and CSS. The architecture enforces inviolable responsibility patterns with sealed modules and dependency injection.

### 🏗️ Architecture Status

**PHASE 1 COMPLETED ✅** - Core foundation built with rigorous architectural patterns:
- ✅ **Module.js** - Abstract base class with WeakMap privates and sealed instances
- ✅ **EventBus.js** - Strict event system with validation and module registration
- ✅ **ModuleLoader.js** - Dependency injection with proper initialization order
- ✅ **Router.js** - Navigation with guards, middleware, and state management
- ✅ **Application.js** - Auto-bootstrap system with lifecycle management
- ✅ **Development Server** - HTTP server with ES6 modules and CORS support

**DRS SYSTEM COMPLETED ✅** - Advanced learning modules with dual AI approach:

**Core Exercise Generation:**
- ✅ **ContentLoader** - Pure AI content generation when no real content available
- ✅ **IAEngine** - Multi-provider AI system (OpenAI → DeepSeek → Disable)
- ✅ **LLMValidator** - Intelligent answer validation with detailed feedback
- ✅ **AI Report System** - Session tracking with exportable reports (text/HTML/JSON)
- ✅ **UnifiedDRS** - Component-based exercise presentation system

**Dual Exercise Modes:**
- 🔄 **Intelligent QCM** - AI generates questions + 1 correct + 5 plausible wrong answers (16.7% random chance)
- 🔄 **Open Analysis Modules** - Free-text responses validated by AI with personalized feedback
  - TextAnalysisModule - Deep comprehension with AI coaching
  - GrammarAnalysisModule - Grammar correction with explanations
  - TranslationModule - Translation validation with improvement tips
  - OpenResponseModule - Free-form questions with intelligent evaluation

**AI Architecture:**
- ✅ **AI-Mandatory System** - No fallback without AI, ensures quality consistency
- ✅ **Smart Preview Orchestrator** - Manages AI report sessions and shared services
- ✅ **Dynamic Content Adaptation** - Real content + AI questions when available, pure AI when not

## 🔥 Critical Requirements

### Architecture Principles (NON-NEGOTIABLE)
1. **Inviolable Responsibility** - Each module has exactly one purpose
2. **Zero Direct Dependencies** - All communication via EventBus only
3. **Sealed Instances** - Modules cannot be modified after creation
4. **Private State** - Internal data completely inaccessible via WeakMap
5. **Contract Enforcement** - Abstract methods must be implemented
6. **Dependency Injection** - No globals, everything injected through constructor

### Technical Constraints
- **Vanilla JS/HTML/CSS only** - No frameworks
- **ES6 Modules** - Import/export syntax required
- **HTTP Protocol** - Never file:// (use development server)
- **Modular CSS** - Component-scoped styling
- **Event-Driven** - No direct module coupling

### UI/UX Design Principles (CRITICAL)
- **NO SCROLL POLICY** - All interfaces MUST fit within viewport height without scrolling
- **Height Management** - Vertical space is precious, horizontal space is abundant
- **Compact Navigation** - Top bars and headers must be minimal height
- **Responsive Layout** - Use available width, preserve viewport height
- **Mobile-First** - Design for smallest screens first, then scale up

## 🚀 Development Workflow

### Starting the System
```bash
# Option 1: Windows batch file
start.bat

# Option 2: Node.js directly
node server.js

# Option 3: NPM scripts
npm start
```

**Access:** http://localhost:3000

### Development Server Features
- ✅ ES6 modules support
- ✅ CORS enabled for online communication
- ✅ Proper MIME types for all file formats
- ✅ Development-friendly caching (assets cached, HTML not cached)
- ✅ Graceful error handling with styled 404 pages

## 📁 Project Structure

```
├── src/
│   ├── core/              # COMPLETED - Core system (sealed)
│   │   ├── Module.js      # Abstract base class
│   │   ├── EventBus.js    # Event communication system
│   │   ├── ModuleLoader.js # Dependency injection
│   │   ├── Router.js      # Navigation system
│   │   └── index.js       # Core exports
│   ├── components/        # TODO - UI components
│   ├── games/            # TODO - Game modules
│   ├── content/          # TODO - Content system
│   ├── styles/           # COMPLETED - Modular CSS
│   │   ├── base.css      # Foundation styles
│   │   └── components.css # Reusable UI components
│   └── Application.js    # COMPLETED - Bootstrap system
├── Legacy/               # Archived old system
├── index.html           # COMPLETED - Entry point
├── server.js            # COMPLETED - Development server
├── start.bat            # COMPLETED - Quick start script
├── package.json         # COMPLETED - Node.js config
└── README.md            # COMPLETED - Documentation
```

## 🎮 Creating New Modules

### Game Module Template
```javascript
import Module from '../core/Module.js';

class GameName extends Module {
    constructor(name, dependencies, config) {
        super(name, ['eventBus']); // Declare dependencies

        // Validate dependencies
        if (!dependencies.eventBus) {
            throw new Error('GameName requires EventBus dependency');
        }

        this._eventBus = dependencies.eventBus;
        this._config = config;

        Object.seal(this); // Prevent modification
    }

    async init() {
        this._validateNotDestroyed();

        // Set up event listeners
        this._eventBus.on('game:start', this._handleStart.bind(this), this.name);

        this._setInitialized();
    }

    async destroy() {
        this._validateNotDestroyed();

        // Cleanup logic here

        this._setDestroyed();
    }

    // Private methods
    _handleStart(event) {
        this._validateInitialized();
        // Game logic here
    }
}

export default GameName;
```

### Registration in Application.js
```javascript
modules: [
    {
        name: 'gameName',
        path: './games/GameName.js',
        dependencies: ['eventBus'],
        config: { difficulty: 'medium' }
    }
]
```

## 🔍 Debugging & Monitoring

### Debug Panel (F12 to toggle)
- System status and uptime
- Loaded modules list
- Event history
- Module registration status

### Console Access
```javascript
window.app.getStatus()                    // Application status
window.app.getCore().eventBus            // EventBus instance
window.app.getCore().moduleLoader        // ModuleLoader instance
window.app.getCore().router              // Router instance
```

### Common Commands
```bash
# Check module status
window.app.getCore().moduleLoader.getStatus()

# View event history
window.app.getCore().eventBus.getEventHistory()

# Navigate programmatically
window.app.getCore().router.navigate('/games')
```

## 🚧 Next Development Phase

### Immediate Tasks (PHASE 2)
1. ❌ **Component-based UI System** - Reusable UI components with scoped CSS
2. ❌ **Example Game Module** - Simple memory game to validate architecture
3. ❌ **Content System Integration** - Port content loading from Legacy
4. ❌ **Testing Framework** - Validate module contracts and event flow

### Known Legacy Issues to Fix
31 bug fixes and improvements from the old system:
- Grammar game functionality issues
- Word Storm duration and difficulty problems
- Memory card display issues
- Adventure game text repetition
- UI alignment and feedback issues
- Performance optimizations needed

## 🔒 Security & Rigidity Enforcement

### Module Protection Layers
1. **Object.seal()** - Prevents property addition/deletion
2. **Object.freeze()** - Prevents prototype modification
3. **WeakMap privates** - Internal state completely hidden
4. **Abstract enforcement** - Missing methods throw errors
5. **Validation at boundaries** - All inputs validated

### Error Messages
The system provides explicit error messages for violations:
- "Module is abstract and cannot be instantiated directly"
- "Module name is required and must be a string"
- "EventBus requires module registration before use"
- "Module must be initialized before use"

## 📝 Development Guidelines

### DO's
- ✅ Always extend Module base class for game modules
- ✅ Use EventBus for all inter-module communication
- ✅ Validate dependencies in constructor
- ✅ Call `_setInitialized()` after successful init
- ✅ Use private methods with underscore prefix
- ✅ Seal objects to prevent modification
- ✅ **Start with simple solutions first** - Test basic functionality before adding complexity
- ✅ **Test code in console first** - Validate logic with quick console tests before file changes

### DON'Ts
- ❌ Never access another module's internals directly
- ❌ Never use global variables for communication
- ❌ Never modify Module base class or core system
- ❌ Never skip dependency validation
- ❌ Never use file:// protocol (always use HTTP server)
- ❌ **NEVER HARDCODE JSON PATHS** - Always use dynamic paths based on selected book/chapter
- ❌ **Never overcomplicate positioning logic** - Use simple CSS transforms (translate(-50%, -50%)) for centering before complex calculations

## 🧠 Problem-Solving Best Practices

### UI Positioning Issues
1. **Start Simple**: Use basic CSS positioning (center with transform) first
2. **Test in Console**: Validate positioning logic with `console.log` and direct DOM manipulation
3. **Check Scope**: Ensure variables like `contentLoader` are globally accessible when needed
4. **Cache-bust**: Add `?v=2` to CSS/JS files when browser cache causes issues
5. **Verify Real Dimensions**: Use `getBoundingClientRect()` only when basic centering fails

### Debugging Workflow
1. **Console First**: Test functions directly in browser console before modifying files
2. **Log Everything**: Add extensive logging to understand execution flow
3. **One Change at a Time**: Make incremental changes and test each step
4. **Simple Solutions Win**: Prefer `left: 50%; transform: translateX(-50%)` over complex calculations

## 🎯 Success Metrics

### Architecture Quality
- **Zero direct coupling** between modules
- **100% sealed instances** - no external modification possible
- **Complete test coverage** of module contracts
- **Event-driven communication** only

### Performance Targets
- **<100ms** module loading time
- **<50ms** event propagation time
- **<200ms** application startup time
- **Zero memory leaks** in module lifecycle

## 🔄 Migration Notes

### From Legacy System
The `Legacy/` folder contains the complete old system. Key architectural changes:

**Old Approach:**
- Global variables and direct coupling
- Manual module registration
- CSS modifications in global files
- Mixed responsibilities in single files

**New Approach:**
- Strict modules with dependency injection
- Automatic loading with dependency resolution
- Component-scoped CSS injection
- Single responsibility per module

### Data Migration
- Content modules need adaptation to new Module base class
- Game logic needs EventBus integration
- CSS needs component scoping
- Configuration needs dependency declaration

---

## 📋 COMPREHENSIVE TEST CHECKLIST

### 🏗️ Architecture Tests

#### Core System Tests
- [ ] **Module.js Tests**
  - [ ] Abstract class cannot be instantiated directly
  - [ ] WeakMap private data is truly private
  - [ ] Object.seal() prevents modification
  - [ ] Lifecycle methods work correctly (init, destroy)
  - [ ] Validation methods throw appropriate errors

- [ ] **EventBus.js Tests**
  - [ ] Event registration and deregistration
  - [ ] Module validation before event usage
  - [ ] Event history tracking
  - [ ] Cross-module communication isolation
  - [ ] Memory leak prevention on module destroy

- [ ] **ModuleLoader.js Tests**
  - [ ] Dependency injection order
  - [ ] Circular dependency detection
  - [ ] Module initialization sequence
  - [ ] Error handling for missing dependencies
  - [ ] Module unloading and cleanup

- [ ] **Router.js Tests**
  - [ ] Navigation guards functionality
  - [ ] Middleware execution order
  - [ ] State management
  - [ ] URL parameter handling
  - [ ] History management

- [ ] **Application.js Tests**
  - [ ] Auto-bootstrap system
  - [ ] Lifecycle management
  - [ ] Module registration
  - [ ] Error recovery
  - [ ] Debug panel functionality

### 🎮 DRS System Tests

#### Module Interface Tests
- [ ] **ExerciseModuleInterface Tests**
  - [ ] All required methods implemented
  - [ ] Method signatures correct
  - [ ] Error throwing for abstract methods

#### Individual Module Tests
- [ ] **TextModule Tests**
  - [ ] Text loading and display
  - [ ] Question generation/extraction
  - [ ] AI validation with fallback
  - [ ] Progress tracking
  - [ ] UI interaction (buttons, inputs)
  - [ ] Viewing time tracking
  - [ ] Results calculation

- [ ] **AudioModule Tests**
  - [ ] Audio playback controls
  - [ ] Playback counting
  - [ ] Transcript reveal timing
  - [ ] AI audio analysis
  - [ ] Progress tracking
  - [ ] Penalty system for excessive playbacks

- [ ] **ImageModule Tests**
  - [ ] Image loading and display
  - [ ] Zoom functionality
  - [ ] Observation time tracking
  - [ ] AI vision analysis
  - [ ] Question types (description, details, interpretation)
  - [ ] Progress tracking

- [ ] **GrammarModule Tests**
  - [ ] Rule explanation display
  - [ ] Exercise type variety (fill-blank, correction, etc.)
  - [ ] Hint system
  - [ ] Attempt tracking
  - [ ] AI grammar analysis
  - [ ] Scoring with penalties/bonuses

### 🤖 AI Integration Tests

#### AI Provider Tests
- [ ] **OpenAI Integration**
  - [ ] API connectivity test
  - [ ] Response format validation
  - [ ] Error handling
  - [ ] Timeout management

- [ ] **DeepSeek Integration**
  - [ ] API connectivity test
  - [ ] Fallback from OpenAI
  - [ ] Response format validation
  - [ ] Error handling

- [ ] **AI Fallback System**
  - [ ] Provider switching logic
  - [ ] Graceful degradation to basic validation
  - [ ] Status tracking and reporting
  - [ ] Recovery mechanisms

#### Response Parsing Tests
- [ ] **Structured Response Parsing**
  - [ ] [answer]yes/no extraction
  - [ ] [explanation] extraction
  - [ ] Error handling for malformed responses
  - [ ] Multiple format support

### 💾 Data Persistence Tests

#### Progress Tracking Tests
- [ ] **Mastery Tracking**
  - [ ] Timestamp recording
  - [ ] Metadata storage
  - [ ] Progress calculation
  - [ ] Persistent storage integration

- [ ] **Data Merge System**
  - [ ] Local vs external data merging
  - [ ] Conflict resolution strategies
  - [ ] Import/export functionality
  - [ ] Data integrity validation

### 🎨 UI/UX Tests

#### Design Principles Tests
- [ ] **No Scroll Policy**
  - [ ] All interfaces fit viewport height
  - [ ] Responsive breakpoint testing
  - [ ] Mobile viewport compliance

- [ ] **Responsive Design**
  - [ ] Mobile-first approach validation
  - [ ] Horizontal space utilization
  - [ ] Vertical space conservation

#### Component Tests
- [ ] **Button Interactions**
  - [ ] Hover effects
  - [ ] Disabled states
  - [ ] Click handlers
  - [ ] Loading states

- [ ] **Form Controls**
  - [ ] Input validation
  - [ ] Error display
  - [ ] Accessibility compliance
  - [ ] Keyboard navigation

### 🌐 Network & Server Tests

#### Development Server Tests
- [ ] **ES6 Modules Support**
  - [ ] Import/export functionality
  - [ ] MIME type handling
  - [ ] CORS configuration

- [ ] **Caching Strategy**
  - [ ] Assets cached correctly
  - [ ] HTML not cached for development
  - [ ] Cache invalidation

- [ ] **Error Handling**
  - [ ] 404 page display
  - [ ] Graceful error recovery
  - [ ] Error message clarity

### 🔄 Integration Tests

#### End-to-End Scenarios
- [ ] **Complete Exercise Flow**
  - [ ] Module loading
  - [ ] Exercise presentation
  - [ ] User interaction
  - [ ] AI validation
  - [ ] Progress saving
  - [ ] Results display

- [ ] **Multi-Module Navigation**
  - [ ] Module switching
  - [ ] State preservation
  - [ ] Memory cleanup

- [ ] **Data Persistence Flow**
  - [ ] Progress tracking across sessions
  - [ ] Data export/import
  - [ ] Sync functionality

### ⚡ Performance Tests

#### Loading Performance
- [ ] **Module Loading Times**
  - [ ] <100ms module loading
  - [ ] <50ms event propagation
  - [ ] <200ms application startup

#### Memory Management
- [ ] **Memory Leaks**
  - [ ] Module cleanup verification
  - [ ] Event listener removal
  - [ ] DOM element cleanup

### 🔒 Security Tests

#### Module Isolation Tests
- [ ] **Private State Protection**
  - [ ] WeakMap data inaccessible
  - [ ] Sealed object modification prevention
  - [ ] Cross-module boundary enforcement

#### Input Validation Tests
- [ ] **Boundary Validation**
  - [ ] All inputs validated
  - [ ] Error messages for violations
  - [ ] Malicious input handling

### 🎯 TESTING PRIORITY

#### **HIGH PRIORITY** (Core System)
1. Module.js lifecycle and sealing tests
2. EventBus communication isolation
3. ModuleLoader dependency injection
4. Basic DRS module functionality

#### **MEDIUM PRIORITY** (Integration)
1. AI provider fallback system
2. Data persistence and merging
3. UI/UX compliance tests
4. End-to-end exercise flows

#### **LOW PRIORITY** (Polish)
1. Performance benchmarks
2. Advanced security tests
3. Edge case scenarios
4. Browser compatibility

---

**This is a high-quality, maintainable system built for educational software that will scale.**