Add codebase docs

codebase/architecture.md

@@ -0,0 +1 @@
+lorem ipsum dolor sit amet

codebase/architecture/core-concepts.md

@@ -0,0 +1,84 @@
+# Core Concepts
+
+Understanding these fundamental concepts is essential for working with the OpenNoodl codebase.
+
+## Nodes
+
+**Nodes** are the basic building blocks of Noodl applications. They represent discrete units of functionality that can be connected together to create complex behaviors.
+
+### Node Characteristics
+
+- **Inputs**: Data or signals flowing into the node
+- **Outputs**: Data or signals flowing out of the node
+- **Parameters**: Configuration settings for the node
+- **State**: Internal data maintained by the node
+
+## Connections
+
+**Connections** link outputs from one node to inputs of another, creating a flow of data and control through the application.
+
+### Connection Types
+
+- **Data Connections**: Transfer values between nodes
+- **Signal Connections**: Trigger actions and events
+- **Property Connections**: Bind UI properties to data
+
+## Signals
+
+**Signals** are events that trigger actions in the node graph. They represent moments in time when something happens.
+
+### Signal Flow
+
+```
+User Click → Button Node → Logic Node → UI Update
+```
+
+## Components
+
+**Components** are reusable collections of nodes that can be instantiated multiple times with different parameters.
+
+### Component Benefits
+
+- Encapsulation of functionality
+- Reusability across projects
+- Simplified node graphs
+- Better organization
+
+## Data Flow
+
+Data in Noodl follows a **reactive** pattern where changes automatically propagate through connected nodes.
+
+### Evaluation Order
+
+1. Input changes trigger node re-evaluation
+2. Node processes inputs and updates outputs
+3. Connected nodes receive new values
+4. Process continues through the graph
+
+## State Management
+
+### Local State
+
+- Maintained within individual nodes
+- Persists during the node's lifecycle
+- Not shared between node instances
+
+### Global State
+
+- Shared across the entire application
+- Accessible from any node
+- Managed through special state nodes
+
+## Runtime Environment
+
+### Execution Context
+
+- JavaScript engine for custom code
+- Sandboxed environment for security
+- Access to browser APIs and Noodl runtime
+
+### Performance Model
+
+- Lazy evaluation (only compute when needed)
+- Efficient diff algorithms
+- Optimized rendering pipeline

codebase/architecture/data-flow.md

@@ -0,0 +1,155 @@
+# Data Flow
+
+This document explains how data flows through the OpenNoodl system, from user interactions to UI updates.
+
+## Overview
+
+Noodl uses a **reactive data flow** model where changes automatically propagate through connected nodes, similar to spreadsheet formulas or reactive programming frameworks.
+
+## Signal Propagation
+
+### Basic Flow
+
+```
+Input Change → Node Evaluation → Output Update → Connected Nodes
+```
+
+### Example Flow
+
+```
+Text Input → String Node → Text Display
+    ↓            ↓           ↓
+ "hello"    toUpperCase   "HELLO"
+```
+
+## Evaluation System
+
+### Lazy Evaluation
+
+- Nodes only execute when their inputs change
+- Outputs are cached until inputs change
+- Prevents unnecessary computations
+
+### Dependency Tracking
+
+```javascript
+// When NodeA.output connects to NodeB.input
+NodeA.addDependent(NodeB);
+NodeB.addDependency(NodeA);
+
+// When NodeA.output changes
+NodeA.notifyDependents(); // Triggers NodeB.evaluate()
+```
+
+### Evaluation Order
+
+1. **Topological Sort**: Determine execution order
+2. **Batch Updates**: Group related changes
+3. **Execute Nodes**: Run in dependency order
+4. **Update UI**: Render changes to screen
+
+## Event System
+
+### Event Types
+
+- **User Events**: Click, hover, input, etc.
+- **System Events**: Load, resize, timer, etc.
+- **Custom Events**: Application-specific signals
+
+### Event Handling
+
+```
+Event Source → Event Node → Signal Output → Action Nodes
+```
+
+## Data Transformation Pipeline
+
+### Input Processing
+
+1. **Validation**: Check input types and constraints
+2. **Transformation**: Convert data formats if needed
+3. **Caching**: Store processed values
+
+### Node Execution
+
+1. **Gather Inputs**: Collect all input values
+2. **Execute Logic**: Run node-specific functionality
+3. **Generate Outputs**: Produce result values
+4. **Emit Signals**: Trigger connected events
+
+### Output Distribution
+
+1. **Update Connections**: Send values to connected inputs
+2. **Trigger Dependents**: Notify dependent nodes
+3. **Schedule UI Updates**: Queue rendering changes
+
+## State Synchronization
+
+### Local State Flow
+
+```
+Node Internal State ← → Node Outputs → Connected Inputs
+```
+
+### Global State Flow
+
+```
+Global State Store ← → State Nodes ← → Application Nodes
+```
+
+### External Data Flow
+
+```
+API/Database ← → Data Nodes ← → Application Logic
+```
+
+## Performance Optimizations
+
+### Change Detection
+
+- **Reference Equality**: Fast comparison for objects
+- **Deep Comparison**: Thorough check when needed
+- **Dirty Flagging**: Mark changed nodes for re-evaluation
+
+### Batching
+
+- **Synchronous Updates**: Group immediate changes
+- **Asynchronous Updates**: Defer expensive operations
+- **Frame Scheduling**: Align with browser rendering
+
+### Memoization
+
+```javascript
+class OptimizedNode {
+  evaluate() {
+    const inputHash = this.getInputHash();
+    if (inputHash === this.lastInputHash) {
+      return this.cachedOutput; // Skip computation
+    }
+
+    this.cachedOutput = this.compute();
+    this.lastInputHash = inputHash;
+    return this.cachedOutput;
+  }
+}
+```
+
+## Debugging Data Flow
+
+### Flow Visualization
+
+- Visual indicators show active connections
+- Animation highlights data propagation
+- Debugging panels show current values
+
+### Performance Monitoring
+
+- Execution time tracking
+- Update frequency analysis
+- Memory usage monitoring
+
+### Common Issues
+
+- **Circular Dependencies**: Detect and prevent infinite loops
+- **Performance Bottlenecks**: Identify slow nodes
+- **Memory Leaks**: Track unreleased references

codebase/architecture/overview.md

@@ -0,0 +1,142 @@
+# System Architecture
+
+OpenNoodl is a visual programming platform consisting of several key components that work together to provide a seamless low-code development experience.
+
+## High-Level Architecture
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Visual Editor │    │  Runtime Engine │    │   Cloud Services│
+│                 │    │                 │    │                 │
+│ • Node Graph    │◄──►│ • Node Runtime  │◄──►│ • Deploy        │
+│ • Property      │    │ • Data Flow     │    │ • Sync          │
+│   Panels        │    │ • Event System  │    │ • Collaboration │
+│ • Preview       │    │ • Asset Mgmt    │    │                 │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+```
+
+## Core Components
+
+### 1. Visual Editor
+
+The main interface where users create applications by connecting nodes visually.
+
+**Key Features:**
+
+- Drag-and-drop node creation
+- Visual connection system
+- Property editing panels
+- Live preview functionality
+- Project management
+
+**Technologies:**
+
+- React-based UI
+- Canvas rendering for node graph
+- WebSocket for real-time updates
+
+### 2. Runtime Engine
+
+The execution environment that runs the node graphs created in the visual editor.
+
+**Key Features:**
+
+- Node execution system
+- Data flow management
+- Event propagation
+- State management
+- Asset handling
+
+**Technologies:**
+
+- Node.js runtime
+- Custom evaluation engine
+- WebSocket communication
+
+### 3. Node System
+
+A plugin-based architecture where functionality is provided through nodes.
+
+**Node Categories:**
+
+- **UI Nodes**: Visual components (buttons, inputs, etc.)
+- **Logic Nodes**: Control flow and data processing
+- **Data Nodes**: Database and API interactions
+- **Utility Nodes**: Helper functions and transformations
+
+### 4. Project Structure
+
+Applications are organized as projects containing:
+
+- Node graphs (visual logic)
+- Assets (images, fonts, etc.)
+- Styles and themes
+- Configuration files
+- Custom code modules
+
+## Data Flow Architecture
+
+### Signal System
+
+Nodes communicate through a signal-based system:
+
+1. **Input Signals**: Data flowing into a node
+2. **Output Signals**: Data flowing out of a node
+3. **Connection**: Links between output and input signals
+4. **Evaluation**: Automatic recalculation when inputs change
+
+### Event System
+
+User interactions and system events trigger cascading updates:
+
+```
+User Interaction → Event Node → Logic Nodes → UI Updates
+```
+
+## Extensibility
+
+### Plugin Architecture
+
+- Custom node development
+- Third-party integrations
+- Module system for reusable components
+- API for external tool integration
+
+### Custom Code Integration
+
+- JavaScript modules
+- External library imports
+- Custom function definitions
+- Advanced data processing
+
+## Performance Considerations
+
+### Optimization Strategies
+
+- Lazy evaluation of node graphs
+- Efficient diff algorithms for UI updates
+- Asset caching and optimization
+- WebSocket connection pooling
+
+### Scalability
+
+- Modular architecture for easy scaling
+- Plugin system for feature extension
+- Cloud deployment options
+- Performance monitoring and profiling
+
+## Security
+
+### Code Execution
+
+- Sandboxed JavaScript execution
+- Input validation and sanitization
+- Resource usage limits
+- Secure asset handling
+
+### Data Protection
+
+- Encrypted data transmission
+- Secure authentication
+- Privacy-compliant data handling
+- Audit trails for sensitive operations