Skip to content

Commit 3fcd206

Browse files
richardosborne14richardosborne14
authored
Merge pull request #4 from The-Low-Code-Foundation/add-codebase-docs
Add codebase docs
2 parents 00497d4 + 2cb1a9f commit 3fcd206

23 files changed

+4679
-55
lines changed

‎codebase/architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
lorem ipsum dolor sit amet

‎codebase/architecture/core-concepts.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# Core Concepts
2+
3+
Understanding these fundamental concepts is essential for working with the OpenNoodl codebase.
4+
5+
## Nodes
6+
7+
**Nodes** are the basic building blocks of Noodl applications. They represent discrete units of functionality that can be connected together to create complex behaviors.
8+
9+
### Node Characteristics
10+
11+
- **Inputs**: Data or signals flowing into the node
12+
- **Outputs**: Data or signals flowing out of the node
13+
- **Parameters**: Configuration settings for the node
14+
- **State**: Internal data maintained by the node
15+
16+
## Connections
17+
18+
**Connections** link outputs from one node to inputs of another, creating a flow of data and control through the application.
19+
20+
### Connection Types
21+
22+
- **Data Connections**: Transfer values between nodes
23+
- **Signal Connections**: Trigger actions and events
24+
- **Property Connections**: Bind UI properties to data
25+
26+
## Signals
27+
28+
**Signals** are events that trigger actions in the node graph. They represent moments in time when something happens.
29+
30+
### Signal Flow
31+
32+
```
33+
User Click → Button Node → Logic Node → UI Update
34+
```
35+
36+
## Components
37+
38+
**Components** are reusable collections of nodes that can be instantiated multiple times with different parameters.
39+
40+
### Component Benefits
41+
42+
- Encapsulation of functionality
43+
- Reusability across projects
44+
- Simplified node graphs
45+
- Better organization
46+
47+
## Data Flow
48+
49+
Data in Noodl follows a **reactive** pattern where changes automatically propagate through connected nodes.
50+
51+
### Evaluation Order
52+
53+
1. Input changes trigger node re-evaluation
54+
2. Node processes inputs and updates outputs
55+
3. Connected nodes receive new values
56+
4. Process continues through the graph
57+
58+
## State Management
59+
60+
### Local State
61+
62+
- Maintained within individual nodes
63+
- Persists during the node's lifecycle
64+
- Not shared between node instances
65+
66+
### Global State
67+
68+
- Shared across the entire application
69+
- Accessible from any node
70+
- Managed through special state nodes
71+
72+
## Runtime Environment
73+
74+
### Execution Context
75+
76+
- JavaScript engine for custom code
77+
- Sandboxed environment for security
78+
- Access to browser APIs and Noodl runtime
79+
80+
### Performance Model
81+
82+
- Lazy evaluation (only compute when needed)
83+
- Efficient diff algorithms
84+
- Optimized rendering pipeline

‎codebase/architecture/data-flow.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Data Flow
2+
3+
This document explains how data flows through the OpenNoodl system, from user interactions to UI updates.
4+
5+
## Overview
6+
7+
Noodl uses a **reactive data flow** model where changes automatically propagate through connected nodes, similar to spreadsheet formulas or reactive programming frameworks.
8+
9+
## Signal Propagation
10+
11+
### Basic Flow
12+
13+
```
14+
Input Change → Node Evaluation → Output Update → Connected Nodes
15+
```
16+
17+
### Example Flow
18+
19+
```
20+
Text Input → String Node → Text Display
21+
↓ ↓ ↓
22+
"hello" toUpperCase "HELLO"
23+
```
24+
25+
## Evaluation System
26+
27+
### Lazy Evaluation
28+
29+
- Nodes only execute when their inputs change
30+
- Outputs are cached until inputs change
31+
- Prevents unnecessary computations
32+
33+
### Dependency Tracking
34+
35+
```javascript
36+
// When NodeA.output connects to NodeB.input
37+
NodeA.addDependent(NodeB);
38+
NodeB.addDependency(NodeA);
39+
40+
// When NodeA.output changes
41+
NodeA.notifyDependents(); // Triggers NodeB.evaluate()
42+
```
43+
44+
### Evaluation Order
45+
46+
1. **Topological Sort**: Determine execution order
47+
2. **Batch Updates**: Group related changes
48+
3. **Execute Nodes**: Run in dependency order
49+
4. **Update UI**: Render changes to screen
50+
51+
## Event System
52+
53+
### Event Types
54+
55+
- **User Events**: Click, hover, input, etc.
56+
- **System Events**: Load, resize, timer, etc.
57+
- **Custom Events**: Application-specific signals
58+
59+
### Event Handling
60+
61+
```
62+
Event Source → Event Node → Signal Output → Action Nodes
63+
```
64+
65+
## Data Transformation Pipeline
66+
67+
### Input Processing
68+
69+
1. **Validation**: Check input types and constraints
70+
2. **Transformation**: Convert data formats if needed
71+
3. **Caching**: Store processed values
72+
73+
### Node Execution
74+
75+
1. **Gather Inputs**: Collect all input values
76+
2. **Execute Logic**: Run node-specific functionality
77+
3. **Generate Outputs**: Produce result values
78+
4. **Emit Signals**: Trigger connected events
79+
80+
### Output Distribution
81+
82+
1. **Update Connections**: Send values to connected inputs
83+
2. **Trigger Dependents**: Notify dependent nodes
84+
3. **Schedule UI Updates**: Queue rendering changes
85+
86+
## State Synchronization
87+
88+
### Local State Flow
89+
90+
```
91+
Node Internal State ← → Node Outputs → Connected Inputs
92+
```
93+
94+
### Global State Flow
95+
96+
```
97+
Global State Store ← → State Nodes ← → Application Nodes
98+
```
99+
100+
### External Data Flow
101+
102+
```
103+
API/Database ← → Data Nodes ← → Application Logic
104+
```
105+
106+
## Performance Optimizations
107+
108+
### Change Detection
109+
110+
- **Reference Equality**: Fast comparison for objects
111+
- **Deep Comparison**: Thorough check when needed
112+
- **Dirty Flagging**: Mark changed nodes for re-evaluation
113+
114+
### Batching
115+
116+
- **Synchronous Updates**: Group immediate changes
117+
- **Asynchronous Updates**: Defer expensive operations
118+
- **Frame Scheduling**: Align with browser rendering
119+
120+
### Memoization
121+
122+
```javascript
123+
class OptimizedNode {
124+
evaluate() {
125+
const inputHash = this.getInputHash();
126+
if (inputHash === this.lastInputHash) {
127+
return this.cachedOutput; // Skip computation
128+
}
129+
130+
this.cachedOutput = this.compute();
131+
this.lastInputHash = inputHash;
132+
return this.cachedOutput;
133+
}
134+
}
135+
```
136+
137+
## Debugging Data Flow
138+
139+
### Flow Visualization
140+
141+
- Visual indicators show active connections
142+
- Animation highlights data propagation
143+
- Debugging panels show current values
144+
145+
### Performance Monitoring
146+
147+
- Execution time tracking
148+
- Update frequency analysis
149+
- Memory usage monitoring
150+
151+
### Common Issues
152+
153+
- **Circular Dependencies**: Detect and prevent infinite loops
154+
- **Performance Bottlenecks**: Identify slow nodes
155+
- **Memory Leaks**: Track unreleased references

‎codebase/architecture/overview.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# System Architecture
2+
3+
OpenNoodl is a visual programming platform consisting of several key components that work together to provide a seamless low-code development experience.
4+
5+
## High-Level Architecture
6+
7+
```
8+
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
9+
│ Visual Editor │ │ Runtime Engine │ │ Cloud Services│
10+
│ │ │ │ │ │
11+
│ • Node Graph │◄──►│ • Node Runtime │◄──►│ • Deploy │
12+
│ • Property │ │ • Data Flow │ │ • Sync │
13+
│ Panels │ │ • Event System │ │ • Collaboration │
14+
│ • Preview │ │ • Asset Mgmt │ │ │
15+
└─────────────────┘ └─────────────────┘ └─────────────────┘
16+
```
17+
18+
## Core Components
19+
20+
### 1. Visual Editor
21+
22+
The main interface where users create applications by connecting nodes visually.
23+
24+
**Key Features:**
25+
26+
- Drag-and-drop node creation
27+
- Visual connection system
28+
- Property editing panels
29+
- Live preview functionality
30+
- Project management
31+
32+
**Technologies:**
33+
34+
- React-based UI
35+
- Canvas rendering for node graph
36+
- WebSocket for real-time updates
37+
38+
### 2. Runtime Engine
39+
40+
The execution environment that runs the node graphs created in the visual editor.
41+
42+
**Key Features:**
43+
44+
- Node execution system
45+
- Data flow management
46+
- Event propagation
47+
- State management
48+
- Asset handling
49+
50+
**Technologies:**
51+
52+
- Node.js runtime
53+
- Custom evaluation engine
54+
- WebSocket communication
55+
56+
### 3. Node System
57+
58+
A plugin-based architecture where functionality is provided through nodes.
59+
60+
**Node Categories:**
61+
62+
- **UI Nodes**: Visual components (buttons, inputs, etc.)
63+
- **Logic Nodes**: Control flow and data processing
64+
- **Data Nodes**: Database and API interactions
65+
- **Utility Nodes**: Helper functions and transformations
66+
67+
### 4. Project Structure
68+
69+
Applications are organized as projects containing:
70+
71+
- Node graphs (visual logic)
72+
- Assets (images, fonts, etc.)
73+
- Styles and themes
74+
- Configuration files
75+
- Custom code modules
76+
77+
## Data Flow Architecture
78+
79+
### Signal System
80+
81+
Nodes communicate through a signal-based system:
82+
83+
1. **Input Signals**: Data flowing into a node
84+
2. **Output Signals**: Data flowing out of a node
85+
3. **Connection**: Links between output and input signals
86+
4. **Evaluation**: Automatic recalculation when inputs change
87+
88+
### Event System
89+
90+
User interactions and system events trigger cascading updates:
91+
92+
```
93+
User Interaction → Event Node → Logic Nodes → UI Updates
94+
```
95+
96+
## Extensibility
97+
98+
### Plugin Architecture
99+
100+
- Custom node development
101+
- Third-party integrations
102+
- Module system for reusable components
103+
- API for external tool integration
104+
105+
### Custom Code Integration
106+
107+
- JavaScript modules
108+
- External library imports
109+
- Custom function definitions
110+
- Advanced data processing
111+
112+
## Performance Considerations
113+
114+
### Optimization Strategies
115+
116+
- Lazy evaluation of node graphs
117+
- Efficient diff algorithms for UI updates
118+
- Asset caching and optimization
119+
- WebSocket connection pooling
120+
121+
### Scalability
122+
123+
- Modular architecture for easy scaling
124+
- Plugin system for feature extension
125+
- Cloud deployment options
126+
- Performance monitoring and profiling
127+
128+
## Security
129+
130+
### Code Execution
131+
132+
- Sandboxed JavaScript execution
133+
- Input validation and sanitization
134+
- Resource usage limits
135+
- Secure asset handling
136+
137+
### Data Protection
138+
139+
- Encrypted data transmission
140+
- Secure authentication
141+
- Privacy-compliant data handling
142+
- Audit trails for sensitive operations

0 commit comments

Comments
 (0)