Class_generator/CLAUDE.md

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

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

// 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.