# CLAUDE.md - Class Generator 2.0

## 📋 Overview
Educational platform with ultra-modular vanilla JS/HTML/CSS architecture. Strict separation, sealed modules, dependency injection.

## 🏗️ Status

**Core ✅**: Module.js, EventBus.js, ModuleLoader.js, Router.js, Application.js, Dev Server
**DRS ✅**: ContentLoader, IAEngine (OpenAI→DeepSeek), LLMValidator, AI Reports, UnifiedDRS
**Exercises ✅**: VocabularyModule, TextAnalysis, GrammarAnalysis, Translation, OpenResponse
**AI ✅**: Production ready, strict scoring (wrong: 0-20, correct: 70-100), no mock fallbacks

## ⚠️ Critical Rules

### Architecture (NON-NEGOTIABLE)
1. **Single responsibility** per module
2. **EventBus only** for communication (no direct deps)
3. **Object.seal()** prevents modification
4. **WeakMap** for private state
5. **Abstract enforcement** - missing methods = fatal error
6. **Dependency injection** - no globals

### DRS vs Games - NEVER MIX
- **DRS** (`src/DRS/`) = Educational exercises with strict interfaces
- **Games** (`src/games/`) = Entertainment, different architecture
- ❌ NEVER `import FlashcardLearning from '../games/'` in DRS
- ✅ ALWAYS `import VocabularyModule from './exercise-modules/'` in DRS

### Technical Constraints
- Vanilla JS/HTML/CSS only (no frameworks)
- ES6 modules, HTTP protocol (never file://)
- **NO SCROLL** - all UI fits viewport height
- Mobile-first, compact headers, vertical space precious

### Development DO's/DON'Ts
✅ Extend Module base, use EventBus, validate deps, seal objects, simple solutions first
❌ Never access internals, globals, skip validation, hardcode paths, overcomplicate positioning

## 🚀 Quick Start
```bash
start.bat  # or: node server.js
# http://localhost:3000
```

## 📁 Structure
```
src/
├── core/          # Module, EventBus, ModuleLoader, Router, Application
├── DRS/           # Exercise modules, services, interfaces
├── games/         # Independent game modules (NOT DRS)
├── styles/        # base.css, components.css
└── Application.js # Bootstrap
```

## 📚 Documentation

**Core Guides:**
- `docs/architecture.md` - Architecture principles and patterns
- `docs/creating-new-module.md` - How to create new modules (Game, DRS, Progress)
- `docs/interfaces.md` - Interface system (C++ style contracts)
- `docs/progress-system.md` - Progress tracking and prerequisites

## 🔍 Debug
```javascript
// F12 toggles debug panel
window.app.getStatus()
window.app.getCore().eventBus.getEventHistory()
window.app.getCore().router.navigate('/games')
```

## 🗄️ AI Cache
Cache currently disabled for testing. See `IAEngine.js` lines 165-170.
**Why**: 100-char cache key too short. **Fix**: Improve to 200+ chars with language/exerciseType/contentHash.

## 🎯 Success Metrics
- **<100ms** module loading
- **<50ms** event propagation
- **<200ms** startup
- **Zero** memory leaks
- **Zero** direct coupling

## 🚧 Next Phase
1. Component-based UI system
2. Example game module
3. Content system integration
4. Testing framework

---

**High-quality, maintainable educational software that scales.**