Architectural Deep Dive

Welcome to the internal documentation of LegoDOM.

This isn't a "how to use" guide. This is a "how it works" guide. Understanding the soul of LegoDOM will make you a better contributor.

The Philosophy

"The Platform is the Runtime."

We avoid compilers, transpilers, and VDOMs. We use:

• ES6 Modules for organization
• Proxies for state
• TreeWalkers for scanning
• Regex for parsing
• MutationObservers for efficiency
• Shadow DOM for encapsulation

The Modular Architecture

LegoDOM evolved from a 1500-line IIFE to a clean, modular ES6 codebase organized in src/:

src/
├── index.js              # The Assembler
├── core/                 # Framework core
├── directives/           # Directive implementations (b-if, b-for, etc.)  
├── features/             # Optional features (router, persistence, errors)
└── utils/                # Shared utilities

The Journey

Follow the path of a block from definition to pixels:

1. Module Pattern - From IIFE to ES6 modules
2. Registry - The block storage system
3. Batcher - Render queue & RAF optimization
4. Reactivity - Proxy-based state management
5. Caching - LRU expression cache
6. Init - How LegoDOM wakes up
7. Registry - Native Web Components Integration
8. Snap - The lifecycle & Shadow DOM
9. Diffing - No VDOM? No problem
10. Studs - The three-tier data system
11. Scanner - Template parsing (Regex vs AST)
12. Render - The "Loop of Truth" & Security
13. Directives - Extracted directive system
14. Events - Event handling & modifiers
15. Router - The "Surgical" Update philosophy
16. State - Global state & $db
17. LegoDOM - The public API
18. Directive Lifecycle - Scan, Execute, Destroy

Dive in.