OpenNoodl/dev-docs/reference/CODEBASE-MAP.md

OpenNoodl Codebase Quick Navigation

🗺️ Package Map

┌─────────────────────────────────────────────────────────────────────────┐
│                           MONOREPO ROOT                                  │
├─────────────────────────────────────────────────────────────────────────┤
│  package.json          → Workspace config, global scripts               │
│  lerna.json            → Monorepo management                            │
│  scripts/              → Build and CI scripts                           │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
        ┌───────────────────────────┼───────────────────────────┐
        ▼                           ▼                           ▼
┌───────────────────┐    ┌───────────────────┐    ┌───────────────────┐
│   EDITOR (GPL)    │    │   RUNTIME (MIT)   │    │   UI LIBRARY      │
│   noodl-editor    │    │   noodl-runtime   │    │   noodl-core-ui   │
│                   │    │                   │    │                   │
│ • Electron app    │    │ • Node engine     │    │ • React components│
│ • React UI        │    │ • Data flow       │    │ • Storybook       │
│ • Property panels │    │ • Event system    │    │ • Styling         │
└───────────────────┘    └───────────────────┘    └───────────────────┘
        │                           │
        │                           ▼
        │               ┌───────────────────┐
        │               │  VIEWER (MIT)     │
        │               │ noodl-viewer-react│
        │               │                   │
        │               │ • React runtime   │
        │               │ • Visual nodes    │
        │               │ • DOM handling    │
        │               └───────────────────┘
        │
        ▼
┌───────────────────────────────────────────────────────────────────────┐
│                        PLATFORM LAYER                                  │
├───────────────────┬───────────────────┬───────────────────────────────┤
│  noodl-platform   │ platform-electron │    platform-node              │
│  (abstraction)    │  (desktop impl)   │    (server impl)              │
└───────────────────┴───────────────────┴───────────────────────────────┘

---

📁 Key Directories

noodl-editor (Main Application)

packages/noodl-editor/src/
├── editor/src/
│   ├── models/              # 🎯 Business logic & data
│   │   ├── projectmodel.ts      → Project state
│   │   ├── nodegraphmodel.ts    → Graph structure
│   │   ├── componentmodel.ts    → Components
│   │   ├── nodelibrary/         → Node type registry
│   │   ├── AiAssistant/         → AI features
│   │   └── sidebar/             → Sidebar state
│   │
│   ├── views/               # 🖥️ UI components
│   │   ├── nodegrapheditor.ts   → Canvas/graph editor
│   │   ├── panels/              → Property panels
│   │   ├── NodePicker/          → Node creation UI
│   │   ├── documents/           → Document views
│   │   └── popups/              → Modal dialogs
│   │
│   ├── utils/               # 🔧 Utilities
│   │   ├── CodeEditor/          → Monaco integration
│   │   ├── filesystem.ts        → File operations
│   │   └── projectimporter.js   → Import/export
│   │
│   ├── store/               # 💾 Persistent state
│   │   └── AiAssistantStore.ts  → AI settings
│   │
│   └── pages/               # 📄 Page components
│       └── EditorPage/          → Main editor page
│
├── main/                    # ⚡ Electron main process
│   └── main.js                  → App entry point
│
└── shared/                  # 🔗 Shared utilities
    └── utils/
        └── EventDispatcher.ts   → Pub/sub system

noodl-runtime (Execution Engine)

packages/noodl-runtime/
├── src/
│   ├── nodes/               # 📦 Node implementations
│   │   └── std-library/
│   │       ├── data/            → Data nodes (REST, DB, etc.)
│   │       ├── logic/           → Logic nodes
│   │       └── events/          → Event nodes
│   │
│   ├── node.js              # Base node class
│   ├── nodedefinition.js    # Node definition API
│   ├── noderegister.js      # Node registry
│   ├── nodescope.js         # Component scope
│   └── nodecontext.js       # Runtime context
│
└── noodl-runtime.js         # Main runtime entry

noodl-viewer-react (React Runtime)

packages/noodl-viewer-react/src/
├── nodes/                   # 🎨 Visual nodes
│   ├── basic/                   → Group, Text, Image
│   ├── controls/                → Button, Input, Checkbox
│   ├── navigation/              → PageRouter, Page
│   └── std-library/             → Standard library nodes
│
└── react-component-node.js  # React node wrapper

noodl-core-ui (Component Library)

packages/noodl-core-ui/src/
├── components/
│   ├── common/              # 🧩 Basic components
│   │   ├── Icon/
│   │   └── ActivityIndicator/
│   │
│   ├── inputs/              # 📝 Form controls
│   │   ├── TextInput/
│   │   ├── PrimaryButton/
│   │   └── Checkbox/
│   │
│   ├── layout/              # 📐 Layout components
│   │   ├── Box/
│   │   ├── Container/
│   │   └── Tabs/
│   │
│   ├── popups/              # 💬 Dialogs & menus
│   │   ├── MenuDialog/
│   │   └── PopupToolbar/
│   │
│   └── ai/                  # 🤖 AI UI components
│       ├── AiChatBox/
│       └── AiChatMessage/
│
└── styles/                  # 🎨 Global styles

---

🔍 Finding Things

Search Patterns

# Find a file by name
find packages/ -name "*NodeGraph*" -type f

# Find where a function is defined
grep -rn "function processNode" packages/

# Find where something is imported/used
grep -r "import.*from.*nodegraphmodel" packages/

# Find all usages of a component
grep -r "<NodeEditor" packages/ --include="*.tsx"

# Find TODO/FIXME comments
grep -rn "TODO\|FIXME" packages/noodl-editor/src

Common Search Targets

Looking for...	Search pattern
Node definitions	packages/noodl-runtime/src/nodes/
React visual nodes	packages/noodl-viewer-react/src/nodes/
UI components	packages/noodl-core-ui/src/components/
Models/state	packages/noodl-editor/src/editor/src/models/
Property panels	packages/noodl-editor/src/editor/src/views/panels/
Tests	packages/noodl-editor/tests/

---

🚀 Quick Commands

Development

# Start everything
npm run dev

# Start just the editor (faster)
npm run start:editor

# Start Storybook (UI components)
npm run start:storybook

# Start viewer dev server
npm run start:viewer

Building

# Build editor
npm run build:editor

# Create distributable package
npm run build:editor:pack

# Build cloud runtime
npm run build:cloud-runtime

Testing

# Run all editor tests
npm run test:editor

# Run platform tests
npm run test:platform

Code Quality

# Type check
npx tsc --noEmit

# Lint
npx eslint packages/noodl-editor/src

# Format
npx prettier --write "packages/**/*.{ts,tsx}"

---

🔗 Key Files Reference

Configuration

File	Purpose
package.json	Root workspace config
lerna.json	Monorepo settings
tsconfig.json	TypeScript config
.eslintrc.js	Linting rules
.prettierrc	Code formatting

Entry Points

File	Purpose
noodl-editor/src/main/main.js	Electron main process
noodl-editor/src/editor/src/index.js	Renderer entry
noodl-runtime/noodl-runtime.js	Runtime engine
noodl-viewer-react/index.js	React runtime

Core Models

File	Purpose
projectmodel.ts	Project state management
nodegraphmodel.ts	Graph data structure
componentmodel.ts	Component definitions
nodelibrary.ts	Node type registry

Important Views

File	Purpose
nodegrapheditor.ts	Main canvas editor
EditorPage.tsx	Main page layout
NodePicker.tsx	Node creation panel
PropertyEditor/	Property panels

---

🏷️ Type System

Key Types (global.d.ts)

// TSFixme - Type escape hatch (TO BE REMOVED)
type TSFixme = any;

// Node colors
type NodeColor = 'data' | 'visual' | 'logic' | 'component' | 'javascript';

// CSS modules
declare module '*.scss' {
  const styles: { readonly [key: string]: string };
  export default styles;
}

Common Interfaces

// Node graph structures (nodegraphmodel.ts)
interface NodeGraphNode {
  id: string;
  type: string;
  x: number;
  y: number;
  parameters: Record<string, any>;
}

interface Connection {
  fromId: string;
  fromPort: string;
  toId: string;
  toPort: string;
}

// Component structure (componentmodel.ts)
interface ComponentModel {
  name: string;
  graph: NodeGraphModel;
  metadata: Record<string, any>;
}

---

📝 Path Aliases

// Configured in tsconfig.json
@noodl-models/       → packages/noodl-editor/src/editor/src/models/
@noodl-utils/        → packages/noodl-editor/src/editor/src/utils/
@noodl-contexts/     → packages/noodl-editor/src/editor/src/contexts/
@noodl-hooks/        → packages/noodl-editor/src/editor/src/hooks/
@noodl-constants/    → packages/noodl-editor/src/editor/src/constants/
@noodl-core-ui/      → packages/noodl-core-ui/src/
@noodl/platform      → packages/noodl-platform/src/

---

🚨 Common Issues

Build Problems

# Clear caches
rm -rf node_modules/.cache
rm -rf packages/*/node_modules/.cache

# Reinstall dependencies
rm -rf node_modules
npm install

TypeScript Errors

# Check for circular dependencies
npx madge --circular packages/noodl-editor/src

Electron Issues

# Clear app data (macOS)
rm -rf ~/Library/Application\ Support/OpenNoodl/

# Rebuild native modules
npm run rebuild

---

Quick reference card for OpenNoodl development. Print or pin to your IDE!