# Project Architecture Rules (Non-Obvious Only)

## Language Documentation

For comprehensive language specifications, syntax, and features, refer to the **edu.wiki** documentation:
- **Basic Syntax**: `edu.wiki/Basic-Syntax.md` - Core language syntax, types, functions, classes
- **Feature Specification**: `edu.wiki/Feature-Specification.md` - Detailed feature requirements and implementation specs
- **EBNF Grammar**: `edu.wiki/EBNF-Grammar.md` - Formal language grammar definition
- **Project Goals**: `edu.wiki/Goals.md` - High-level language design goals and philosophy

## Critical Design Principle

**NO HARDCODED IMPLEMENTATIONS**: Parser and interpreter must not contain hardcoded function definitions, imports, or language features unless they are core edu language constructs. All user-defined functions, imports, and modules must be processed dynamically through the AST and module system.

## Architecture Constraints

- Direct AST interpretation bypasses traditional compile-transpile cycle for 110x speed improvement
- Three-phase execution: Phase 1 (imports) → Phase 2 (declarations) → Phase 3 (statements)
- Module system uses shared function body references to enable safe import/export without AST corruption
- Environment hierarchy: globals → module environments → function execution environments
- Function memory model: `importedFunction` pointer preserves original while wrapper handles module context
- Token classification system: Declaration vs Keyword types determine parser routing logic
- Const enforcement: separate `constFlags` map in Environment rather than Value-level immutability
- Module registry pattern: `gModuleRegistry.executeFunction()` prevents interpreter recursion cycles
- Test auto-discovery: SCons scans `__tests__/` directories eliminating manual test registration
- Platform abstraction: SCons handles MSVC/GCC compiler differences while maintaining C++17 standard