Codebase Overview: Neo.mjs - The AI-Native Web Platform

Note for Readers: This guide is primarily written for AI agents working with the Neo.mjs codebase and is part of their required session initialization. However, it also serves as a comprehensive overview for human developers seeking to understand the platform's scale, architecture, and design philosophy. References to "querying" refer to the AI Knowledge Base system available to agents.

Understanding the Scale (State of April 2026)

Neo.mjs is not a library. It's a comprehensive web platform with:

• 54,361 lines of core engine source (426 files)
• 41,772 lines of flagship applications (399 files)
• 14,838 lines of component theming (613 files)
• 23,212 lines of working examples (642 files)
• 20,026 lines of AI infrastructure (144 files)
• 24,442 lines of learning materials (148 files)
• 21,937 lines of automated tests (189 files)
• 7,517 lines of build tooling (67 files)
• 1,294 lines of documentation app (17 files)
• 204,082 lines of Agent Knowledge context (3,924 files)
• 260 lines of Swarm Skills (10 files)
• 66,077 lines of pure JSDoc and inline comments

Total: ~205,000 lines of source code + ~274,000 lines of documentation = ~479,000 lines of knowledge

The documentation lines count. They contain intent, architectural rationale, and usage patterns—knowledge that's as valuable as the code itself for understanding the platform.

Note: These metrics exclude:

• The /dist directory (production builds, which would triple these numbers)
• Markdown files in /learn (~100 files of guides, tutorials, and blog posts)
• Generated documentation outputs

This is not a small library—it's a comprehensive platform with more source code than many established frameworks. It represents a decade of architectural thinking about how web applications should work—and how AI agents should collaborate with them.

The Vision: A New Operating System for the Web

Neo.mjs reimagines web development from first principles. It's not "React, but faster" or "Vue, but different." It's a fundamentally different architecture that treats the browser as a distributed computing environment, not a single-threaded document renderer.

The Core Insight

"The browser's main thread should be treated like a neurosurgeon: only perform precise, scheduled operations with zero distractions."

Everything in Neo.mjs flows from this principle. Every architectural decision—the worker threads, the VDOM protocol, the config system—exists to keep the main thread doing exactly one job: updating the DOM with surgical precision.

The Architecture: Why These Choices?

First, it is critical to understand the primary execution boundary. Neo.mjs operates two completely disjointized environments that only ever communicate via the Neural Link (JSON-RPC WebSocket):

1. The Frontend UI Engine: The browser-based application runtime that renders the DOM.
2. The Agent OS (Node.js): The backend cognitive loop and local AI SDK.

1. The Frontend Engine: True Multithreading via Web Workers

The Problem: Within the browser, single-threaded frameworks fundamentally cannot prevent UI jank. They use schedulers and time-slicing, but they're still fighting the browser's event loop.

The Solution: The Neo.mjs Frontend Engine moves all UI application logic to dedicated web workers:

• App Worker: Your entire application (components, state, logic)
• VDom Worker: Diffing and patching calculations
• Data Worker: Store operations and data transformations
• Canvas Worker: Canvas-based rendering for charts and graphics
• Task Worker: Generic background task processing
• Main Thread: DOM updates only

The Trade-off: Added architectural complexity, but guaranteed smoothness under load.

The Result: Over 40,000 delta updates per second in optimized environments. The UI never freezes, regardless of computational intensity.

2. The VDOM as a Cross-Thread Protocol (Frontend Only)

The Problem: Within the Frontend Engine, web workers communicate via postMessage, which requires serializable data. JSX and function components aren't serializable.

The Solution: The Virtual DOM is the protocol. Components describe themselves as JSON blueprints:

{
    tag: 'div',
    cls: ['neo-container'],
    cn: [/* children */]
}

Note: The VDOM is strictly a capability of the Frontend UI Engine. The Agent OS SDK does not render or process VDOM internally; it merely inspects or injects it remotely via the Neural Link.

The Trade-off: More verbose than JSX, but:

• Serializable by definition
• Language-agnostic (ideal for AI generation)
• Debuggable without source maps
• Zero compilation required

The Result: The VDOM isn't a rendering optimization; it's the IPC (Inter-Process Communication) layer of the frontend platform.

3. Two-Tier Reactivity (Not One-Size-Fits-All)

The Problem: Different use cases need different reactivity models:

• Local component state → Simple, imperative updates (push)
• Application-wide state → Dependency tracking (pull)

The Solution: Neo.mjs provides both:

Push-based (Classic): Reactive configs with lifecycle hooks

static config = {
    myValue_: 'default'  // Trailing underscore = reactive
}

afterSetMyValue(value, oldValue) {
    // React to changes
}

Pull-based (Modern): Effect with automatic dependency tracking

Neo.create(Effect, {
    fn: () => this.sum = this.a + this.b  // Auto-tracks a and b
})

The Trade-off: Two systems to learn, but optimal performance for each use case.

The Result: Fine-grained reactivity where you need it, coarse-grained where you don't.

4. Zero-Build Development Mode

The Problem: Build tools add complexity, slow iteration, and create debugging friction (source maps are never perfect).

The Solution: Neo.mjs apps run as native ES Modules directly in the browser. No transpilation. No bundling. No build step in development.

The Trade-off: Modern browser required (ES6+ support).

The Result:

• Instant reload on file save
• Debug the exact code you wrote
• 100% web standards alignment
• Future-proof architecture

The Major Subsystems: What Exists to Explore

Component System (Two Models)

Class-based Components: Full engine features

• Reactive configs with beforeGet/beforeSet/afterSet hooks
• Mixins for composable behavior
• Full inheritance chain
• Instance lifecycle management

Functional Components: Lightweight alternative

• Stateless by default
• Pure render functions
• Composable via nesting
• Full interop with class-based components

Both models work together seamlessly. Choose based on your needs.

Forms Engine

A complete form management system that goes beyond HTML forms:

• True Nested Forms: Forms can contain other forms (impossible in HTML)
• Detached Validation: Validate forms that aren't mounted in the DOM
• Integrated State Provider: Form state lives in the App Worker
• 20+ Field Types: Text, Number, Date, Time, Picker, ComboBox, Chip, Currency, Phone, Email, URL, Password, Search, Range, Color, Country, FileUpload, Hidden, Switch, Radio, CheckBox
• Multi-step Wizards: Preserve state across navigation

Data Layer

A highly optimized and flexible data layer designed for performance with large datasets.

Neo.data.Model: The blueprint for your data records.

• Defines the schema for records, including field names, types, and default values.
• Supports calculated fields and data validation rules.
• Can be configured to track modifications to fields (trackModifiedFields).

Neo.collection.Base: The foundation for data collections.

• Provides powerful client-side filtering and sorting capabilities.
• Manages items with a key-based map for fast lookups.
• Fires mutation events for observing changes.

Neo.data.Store: A powerful collection manager for records, which extends Neo.collection.Base.

• Can be loaded with raw JavaScript objects for maximum performance.
• Uses a RecordFactory to create lightweight, reactive record instances on-demand when data is accessed. This lazy-instantiation approach is extremely memory-efficient.
• Inherits filtering and sorting from collection.Base and adds support for remote operations (e.g., remote filtering, pagination).
• Supports loading data from remote APIs.

Neo.state.Provider: Hierarchical state

• Application-wide state management
• Lives entirely in App Worker
• Automatic change propagation
• Scoped state for component subtrees

Layout System

Declarative layout management without manual positioning:

• Card: Show one child at a time (tabs, wizards, carousels)
• Fit: Single child fills container completely
• Flexbox: CSS flexbox abstraction with sensible defaults
• HBox/VBox: Horizontal/vertical flexbox shortcuts
• Grid: CSS Grid layout with responsive templates
• Form: Specialized layout for form fields with labels

Layouts compose: nest containers with different layouts to achieve complex UIs.

Multi-Window Support

Desktop-class application architecture:

• Single App Worker manages multiple browser windows
• Shared state across windows in real-time
• Move components between windows (keep JavaScript instances alive)
• Window-specific theming and configuration
• Cross-window drag-and-drop
• Use cases: Trading dashboards, monitoring systems, multi-monitor workflows

Component Library (The "Batteries")

Containers:

• Base, Panel, Viewport, Accordion

Forms (20+ field types):

• Text, Number, Date, Time, Picker, ComboBox, Chip, Color, Country, Currency, Phone, Email, URL, Password, Search, Range, FileUpload, Hidden, Switch, Radio, CheckBox, TextArea

Data Display:

• Grid: Spreadsheet-like data grid with sorting, filtering, cell editing
• Table: Simpler table component for basic data display
• List: Virtualized list with selection models
• Tree: Hierarchical data with expand/collapse
• Gallery: Image gallery with multiple layout modes
• Helix: 3D carousel effect for images/cards

Navigation:

• Tab: Tabbed interfaces with multiple layout modes
• Breadcrumb: Hierarchical navigation
• Menu: Context menus and dropdowns
• Toolbar: Action bars with buttons, separators, spacers

Feedback:

• Toast: Temporary notifications
• Dialog: Modal dialogs with custom content
• Progress: Progress bars and spinners
• Tooltip: Contextual help on hover

Third-Party Wrappers:

• AmCharts: Full-featured charting library
• MapboxGL: Interactive maps
• Monaco Editor: Code editor (powers VS Code)
• CesiumJS: 3D globe and map visualization
• Google Maps: Maps integration
• OpenStreetMap: Open-source maps

The Knowledge Landscape: What's Available to Query

Core Engine (/src - 426 files, ~54k lines)

Foundation:

• Neo.mjs: The entry point. Class factory, setupClass(), global configuration
• core/Base.mjs: Foundation of all classes. Config system, instance lifecycle, destruction
• core/Config.mjs: The reactive config system implementation
• core/Effect.mjs: The pull-based reactivity system

Workers:

• worker/App.mjs: Application worker logic
• worker/VDom.mjs: Virtual DOM worker
• worker/Data.mjs: Data processing worker
• worker/Canvas.mjs: Canvas-based rendering worker
• worker/Task.mjs: Generic background task worker
• worker/Base.mjs: Shared worker foundation

Component Architecture:

• component/Base.mjs: Base class for all UI components
• component/Abstract.mjs: Lower-level component abstraction
• container/Base.mjs: Base class for containers (components with children)

Data & State:

• data/Model.mjs: Record definition and validation
• data/Store.mjs: Collection management
• state/Provider.mjs: Hierarchical state management

Managers (Global Singletons):

• manager/Component.mjs: Component registry and lookup
• manager/Focus.mjs: Application-wide focus management
• manager/DomEvent.mjs: Event delegation and handling

Working Examples (/examples - 485 files, 25k lines)

Focused demonstrations organized by category:

• Component examples: Button, Form, Grid, List, Tab, Tree, etc.
• Feature showcases: Drag-drop, animations, theming, routing
• Integration examples: AmCharts, Google Maps, Monaco, etc.
• Layout demonstrations: All layout types with variations
• Form examples: Field types, validation, nested forms, wizards

Each example is self-contained and demonstrates one concept clearly.

Flagship Applications (/apps - 260 files, 23k lines)

Portal (apps/portal/):

• The neo.mjs.com website source
• Multi-window IDE with live code editing
• Dynamic theming system
• Component browser with live examples
• Source code viewer with syntax highlighting

SharedCovid (apps/sharedcovid/):

• Multi-window data visualization
• Real-time COVID-19 statistics
• Shared state across multiple windows
• AmCharts integration
• Gallery and Helix components

RealWorld (apps/RealWorld/):

• Standard benchmark application (Conduit clone)
• Demonstrates full CRUD operations
• Routing and navigation
• Authentication and state management

Learning Materials (/learn)

Structured Content:

• Benefits: Why Neo.mjs exists, what problems it solves
• Getting Started: First steps, tutorials, quick wins
• Fundamentals: Core concepts, architecture deep-dives
• Guides: Task-oriented how-tos
• Blog: Historical context, design decisions, evolution

The content in /learn is the source material for the AI Knowledge Base. Query it for conceptual understanding.

Agent Knowledge Base (/resources/content/ - 3,923 files, ~178.7k lines)

The entire historical footprint and live contextual state of the Neo.mjs project is synchronized locally for the Agent OS within resources/content/:

Release Notes (resources/content/release-notes/):

• Version-by-version changelog
• Feature additions with rationale
• Bug fixes and their context
• Breaking changes and migration guides

Ticket Archive & Active Issues (resources/content/issue-archive/, resources/content/issues/):

• Full contextual history: problem, discussion, solution, implementation
• Searchable history of architectural decisions via Native Graph ingestion

Pull Requests (resources/content/pulls/):

• Complete PR conversations, diff summaries, and Agent-generated "Fat Ticket" reviews
• Links directly to closing commits for deep execution context

Discussions (resources/content/discussions/):

• The Ideation Sandbox
• Proposed architectural features, "Unknown Unknowns", and early-stage brainstorming

Query these when you need to understand why something works a certain way, track the evolution of an architectural design, or find open tasks.

Agent OS Backend (/ai - 144 files, ~20k lines)

The cognitive architecture underpinning the swarm:

• agent/: The cognitive loop, task schedulers, and agent profiles.
• graph/: The Native Edge Graph topology database (Database.mjs, NodeModel.mjs, EdgeModel.mjs).
• daemons/: Offline memory consolidation pipelines (e.g., DreamService.mjs).
• sdk-manifest.md: Public API mapping for interacting with the KB, Memory, GitHub, and Neural Link services.

Swarm Skills & Workflows (/.agent/skills/ - 11 files, ~268 lines)

Formalized Anthropic Progressive Disclosure Skills natively used by the swarm:

• create-skill: Architectural blueprinting for new operational abilities.
• ideation-sandbox: Safe brainstorming pipelines mapped directly into GitHub Discussions.
• pr-review: Evaluation matrix templates spanning [ARCH_ALIGNMENT] to [EFFORT_PROFILE].
• neural-link: Standard operating procedures for traversing the Object-Permanent VDOM structure.
• unit-test: Synthetically driving Playwright natively.

Neo Theming Engine (/resources/scss/ - 613 files, ~14.8k lines)

Documenting the SCSS frameworks defining Neo's glassmorphism and application layouts, structurally detached from the core JS framework rendering engine.

Automated Validation & Docs Parsing

Documenting auxiliary determinism systems:

• /test/ (189 files, ~21.9k lines): Testing layouts (unit, e2e, component, mcp) leveraging the Neural Link for Whitebox E2E.
• /buildScripts/ (62 files, ~6.8k lines): Build pipelines (Webpack distributions) and context generation layers.
• /docs/app/ (17 files, ~1.2k lines): The specialized JSDoc parsing pipeline generating the Neo UI documentation layer (output directed to .gitignore'd /docs/output/).

The AI-Native Design

Neo.mjs isn't just "AI-friendly"—it was architected for AI collaboration from the ground up.

Primary Separation: The Node.js Agent OS vs. The Frontend Engine

The platform features a dedicated Node.js Agent SDK acting as the cognitive backend (Agent OS). This OS is completely isolated from the browser-based Frontend Engine.

• The Agent OS operates within Node.js, leveraging native Child Processes for parallelization (e.g., daemon spawns) instead of Web Workers.
• The UI Runtime (Frontend Engine) operates entirely in the browser using Web Workers.
• The VDOM (Virtual DOM) applies only to the UI runtime.
• The Neural Link (WebSocket JSON-RPC) serves as the exclusive, stateless bridge between these two disjoint worlds.

This local infrastructure exposes five dedicated Model Context Protocol (MCP) servers:

1. Knowledge Base Server (ai/mcp/server/knowledge-base/)

• Indexes the entire platform: source code, examples, guides, release notes, tickets
• Semantic search via vector embeddings (ChromaDB + Google Gemini)
• Sophisticated scoring algorithm prioritizing relevance
• Pre-calculates class inheritance chains for fast queries
• Transforms over 158k lines of code into queryable knowledge

2. Memory Core Server & DreamService (ai/mcp/server/memory-core/)

• Features a sophisticated Hybrid RAG processing pipeline.
• Backed by an independent SQLite-based Native Graph DB to extract topological conflict data.
• Executes offline cognitive maintenance during the "Dream Cycle" (runSandman.mjs).
• Leverages local SLMs (e.g., gemma4-31b) for Subagents and the Librarian daemon to automatically organize episodic memory.
• Consolidates agent "thought process" for analysis and context retrieval.

3. GitHub Workflow Server (ai/mcp/server/github-workflow/)

• 2-way sync between local filesystem and GitHub issues
• Automated ticket creation with "Fat Ticket" templates
• Status tracking and archival
• Ensures all work is traceable and documented

4. Neural Link Server (ai/mcp/server/neural-link/)

• The vital bridge connecting the detached Node.js Agent OS to the browser-based Frontend Engine.
• Bypasses traditional HTML DOM by feeding structured JSON component blueprints directly to agents.
• Enables deep, runtime component state introspection and dynamic mutation.
• Powers deterministic Whitebox E2E testing frameworks, allowing agents to assert accurate internal memory states.

5. File System Server (ai/mcp/server/file-system/)

• A localized file-system proxy exclusively for internal Neo agents.
• (Note: External clients like Claude Code, Gemini CLI, and Antigravity utilize their own native file system tools.)

Why This Matters for You

You're not operating in a typical codebase. You have:

• Queryable Everything: The knowledge base contains the entire platform indexed and searchable
• Semantic Understanding: Vector embeddings understand meaning, not just keywords
• Historical Memory: Past conversations and decisions are preserved
• Structured Conventions: Consistent patterns make navigation predictable

JSON-First Architecture: The VDOM format is AI-readable and AI-writable. You can generate valid Neo.mjs UI from natural language descriptions.

Comprehensive Documentation: 30,000 lines of JSDoc provide rich context for every class, method, and config.

Inheritance Pre-Calculation: The knowledge base pre-computes class hierarchies. When you query a component, you automatically get its parent chain for full context.

You're not just working with Neo.mjs. You're working inside an ecosystem designed for seamless human-AI collaboration.

Key Concepts: Query Entry Points

When you need to understand Neo.mjs, these are high-value concepts to query. Use these terms with the query_documents tool to find relevant source files and guides.

Agent Intelligence & Workflows

• "DreamService", "Agent OS", "Native Edge Graph", "SQLite topology", "Fat Ticket"
• "Swarm protocols", "pr-review templates"

Validation & Parsers

• "Whitebox E2E", "Playwright fixtures", "JSDoc parsing"

Architecture & Philosophy

• "multithreading", "worker architecture", "App Worker", "VDom Worker"
• "off main thread", "main thread", "delta updates"
• "VDOM protocol", "JSON blueprint", "virtual dom"
• "RPC", "remote method access", "postMessage"

Component System

• "component.Base", "container.Base", "core.Base"
• "reactive config", "config system", "trailing underscore"
• "functional component", "class-based component"
• "lifecycle", "construct", "onConstructed", "destroy"

Reactivity & State

• "afterSet", "beforeSet", "beforeGet"
• "Effect", "state.Provider", "state management"
• "two-tier reactivity", "dependency tracking"

Data Management

• "data.Model", "data.Store", "collection"
• "filter", "sort", "store", "proxy"

Forms

• "form.Container", "form.field", "validation"
• "nested forms", "detached validation"
• "field types", "form state"

Layouts

• "layout", "Card layout", "Fit layout"
• "Flexbox", "HBox", "VBox", "Grid layout"

Advanced Features

• "multi-window", "shared state", "child apps"
• "theming", "dark mode", "CSS variables"
• "drag drop", "sortable", "resizable"

Component Library

• Specific components: "Button", "Grid", "Tab", "Tree", "Form", etc.
• Wrappers: "AmChart", "MapboxGL", "Monaco", "CesiumJS"

What Makes Neo.mjs Different

If you're coming from other frameworks, here are the key mental shifts:

Not React

• No JSX → JSON VDOM blueprints
• No hooks → Reactive configs with lifecycle methods
• No virtual DOM reconciliation on main thread → Dedicated VDom Worker
• No single-threaded event loop → True multithreading

Not Vue

• No template compilation → Direct VDOM construction
• No Options API / Composition API → Class-based with configs
• No Vuex needed → Built-in state.Provider

Not Angular

• No TypeScript requirement → Pure ES Modules
• No required CLI for dev → Zero build mode (optional CLI for scaffolding)
• No Zone.js → Explicit reactivity with configs
• Lighter weight → More focused on UI, less on full-stack

The Neo.mjs Way

• Declarative everything: Components, layouts, data, state—all declarative configs
• Worker-first: Logic lives in workers, main thread only touches DOM
• No magic: Explicit, traceable data flow
• Batteries included: Comprehensive component library and tooling
• Standards-based: ES Modules, Web Workers, modern browser APIs

How to Approach This Codebase

Start with the Foundation

1. Read src/Neo.mjs to understand the class system and setupClass()
2. Read src/core/Base.mjs to understand the config system and lifecycle
3. Read a guide: Query "fundamentals" or "getting started"

Understand the Architecture

1. Query "worker architecture" to understand the threading model
2. Query "VDOM" to understand the rendering protocol
3. Query "reactivity" to understand state management

Explore by Example

1. Query "Button component examples" for simple component usage
2. Query "Grid examples" for complex data display
3. Look at /apps/portal/ for a complete application

When Stuck

1. Query the specific concept (e.g., "afterSet hook")
2. Read both the source file (type='src') and guide (type='guide')
3. Check examples (type='example') for practical usage
4. Review tickets (type='ticket') and Pull Requests (type='pull') for execution history
5. Search Discussions (type='discussion') for the underlying architectural "Why"

Remember

This is a ~479,000-line platform, not a 5k-line library. And that's just the indexed source and conceptual knowledge context—it excludes the /dist production builds (which would triple it) and transient tracking data arrays.

Don't assume. Query. The knowledge base contains the answers. Your job is to ask the right questions.