Class_generator/docs/architecture.md

Architecture Guide

🏗️ Core Principles

1. Single Responsibility

Each module has exactly one purpose. No mixing of concerns.

2. Event-Driven Communication

All inter-module communication happens through EventBus. Zero direct dependencies.

// ❌ BAD - Direct access
const gameManager = window.app.modules.gameManager;
gameManager.startGame();

// ✅ GOOD - EventBus
eventBus.emit('game:start', { difficulty: 'medium' });

3. Sealed Modules

Modules cannot be modified after creation using Object.seal().

constructor() {
    super('ModuleName');
    this._privateState = {};
    Object.seal(this); // Prevents adding/removing properties
}

4. WeakMap Private State

Internal data is completely inaccessible from outside.

const privateData = new WeakMap();

class SecureModule {
    constructor() {
        privateData.set(this, {
            apiKey: 'secret',
            internalState: {}
        });
    }

    getPrivateData() {
        return privateData.get(this);
    }
}

5. Dependency Injection

No globals. Everything injected through constructor.

class GameModule extends Module {
    constructor(name, dependencies, config) {
        super(name, ['eventBus', 'renderer']);

        // Dependencies injected, not accessed globally
        this._eventBus = dependencies.eventBus;
        this._renderer = dependencies.renderer;
        this._config = config;
    }
}

🔄 Module Lifecycle

1. REGISTRATION  → Application.js modules array
2. LOADING       → ModuleLoader imports class
3. INSTANTIATION → new Module(name, deps, config)
4. INITIALIZATION → module.init() called
5. READY         → Module emits 'ready' event
6. DESTRUCTION   → module.destroy() on cleanup

📦 System Components

Core Layer (src/core/)

Module.js - Abstract base class

• WeakMap private state
• Lifecycle management (init/destroy)
• State validation
• Abstract enforcement

EventBus.js - Event communication

• Module registration required
• Event history tracking
• Cross-module isolation
• Memory leak prevention

ModuleLoader.js - Dependency injection

• Topological sort for dependencies
• Circular dependency detection
• Proper initialization order
• Dynamic import system

Router.js - Navigation system

• Route guards
• Middleware execution
• State management
• History integration

Application.js - Bootstrap system

• Auto-initialization
• Module registration
• Lifecycle coordination
• Debug panel

DRS Layer (src/DRS/)

Exercise Modules (exercise-modules/)

• VocabularyModule - Flashcard spaced repetition
• TextAnalysisModule - AI text comprehension
• GrammarAnalysisModule - AI grammar correction
• TranslationModule - AI translation validation
• OpenResponseModule - Free-form AI evaluation

Services (services/)

• IAEngine - Multi-provider AI system
• LLMValidator - Answer validation
• ContentLoader - Content generation
• ProgressTracker - Progress management
• PrerequisiteEngine - Prerequisite checking

Interfaces (interfaces/)

• StrictInterface - Base enforcement class
• ProgressItemInterface - Progress tracking contract
• ProgressSystemInterface - Progress system contract
• DRSExerciseInterface - Exercise module contract

Games Layer (src/games/)

Independent game modules for entertainment (NOT part of DRS).

• FlashcardLearning.js - Standalone flashcard game
• Future games...

🚫 Separation Rules

DRS vs Games - NEVER MIX

DRS = Educational exercises with strict interfaces Games = Entertainment with different architecture

// ❌ FORBIDDEN - DRS importing games
import FlashcardLearning from '../games/FlashcardLearning.js';

// ✅ CORRECT - DRS uses its own modules
import VocabularyModule from './exercise-modules/VocabularyModule.js';

🔒 Security Layers

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

📊 Data Flow

User Action
    ↓
UI Component
    ↓
Event Emission (EventBus)
    ↓
Module Event Handler
    ↓
Business Logic
    ↓
State Update
    ↓
Event Emission (state changed)
    ↓
UI Update

🎯 Module Types

1. Core Modules

System-level functionality. Never modify these.

2. Game Modules

Entertainment-focused, extend Module base class.

3. DRS Exercise Modules

Educational exercises, implement DRSExerciseInterface.

4. Service Modules

Support functionality (AI, progress, content).

5. UI Components

Reusable interface elements (future phase).

⚡ Performance Targets

• <100ms module loading time
• <50ms event propagation time
• <200ms application startup time
• Zero memory leaks in module lifecycle

🧪 Testing Strategy

1. Unit Tests - Individual module behavior
2. Integration Tests - Module communication via EventBus
3. Interface Tests - Contract compliance (ImplementationValidator)
4. E2E Tests - Complete user flows

📋 Architecture Checklist

For every new feature:

• Single responsibility maintained
• EventBus for all communication
• No direct module dependencies
• Proper dependency injection
• Object.seal() applied
• Abstract methods implemented
• Lifecycle methods complete
• Memory cleanup in destroy()
• Interface compliance validated
• No global variables used

🔍 Debug Tools

// Application status
window.app.getStatus()

// Module inspection
window.app.getCore().moduleLoader.getStatus()

// Event history
window.app.getCore().eventBus.getEventHistory()

// Navigate programmatically
window.app.getCore().router.navigate('/path')

🚨 Common Violations

1. Direct module access → Use EventBus
2. Global variables → Use dependency injection
3. Mixed responsibilities → Split into separate modules
4. No cleanup → Implement destroy() properly
5. Hardcoded dependencies → Declare in constructor
6. Missing validation → Validate all inputs
7. Modifying core → Extend, don't modify

📖 Further Reading

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