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│
│   (DESKTOP ONLY)  │    │ • Data flow       │    │ • Storybook (web) │
│ • React UI        │    │ • Event system    │    │ • Styling         │
│ • Property panels │    │                   │    │                   │
└───────────────────┘    └───────────────────┘    └───────────────────┘
        │                           │
        │                           ▼
        │               ┌───────────────────┐
        │               │  🌐 VIEWER (MIT)  │
        │               │ noodl-viewer-react│
        │               │                   │
        │               │ • React runtime   │
        │               │ • Visual nodes    │
        │               │ • DOM handling    │
        │               │   (WEB - Runs in  │
        │               │    browser)       │
        │               └───────────────────┘
        │
        ▼
┌───────────────────────────────────────────────────────────────────────┐
│                  ⚡ PLATFORM LAYER (Electron)                          │
├───────────────────┬───────────────────┬───────────────────────────────┤
│  noodl-platform   │ platform-electron │    platform-node              │
│  (abstraction)    │  (desktop impl)   │    (server impl)              │
└───────────────────┴───────────────────┴───────────────────────────────┘

⚡ = Electron Desktop Application (NOT accessible via browser)
🌐 = Web Application (runs in browser)

🖥️ Architecture: Desktop vs Web

Critical Distinction for Development:

Component	Runtime	Access Method	Purpose
Editor ⚡	Electron Desktop	npm run dev → auto-launches window	Development environment
Viewer 🌐	Web Browser	Deployed URL or preview inside editor	User-facing applications
Runtime	Node.js/Browser	Embedded in viewer	Application logic engine
Storybook 🌐	Web Browser	npm run start:storybook → browser	Component library development

Important for Testing:

• When working on the editor, you're always in Electron
• Never try to open http://localhost:8080 in a browser - that's the webpack dev server internal to Electron
• The editor automatically launches as an Electron window when you run npm run dev
• Use Electron DevTools (View → Toggle Developer Tools) for debugging the editor
• Console logs from the editor appear in Electron DevTools, NOT in the terminal

---

📁 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/
│
├── preview/                 # 📱 Preview/Launcher UI
│   └── launcher/
│       ├── Launcher.tsx         → Main launcher container
│       ├── LauncherContext.tsx  → Shared state context
│       │
│       ├── components/      # Launcher-specific components
│       │   ├── LauncherProjectCard/     → Project card display
│       │   ├── FolderTree/              → Folder hierarchy UI
│       │   ├── FolderTreeItem/          → Individual folder item
│       │   ├── TagPill/                 → Tag display badge
│       │   ├── TagSelector/             → Tag assignment UI
│       │   ├── ProjectList/             → List view components
│       │   ├── GitStatusBadge/          → Git status indicator
│       │   └── ViewModeToggle/          → Card/List toggle
│       │
│       ├── hooks/           # Launcher hooks
│       │   ├── useProjectOrganization.ts → Folder/tag management
│       │   ├── useProjectList.ts         → Project list logic
│       │   └── usePersistentTab.ts       → Tab state persistence
│       │
│       └── views/           # Launcher view pages
│           ├── Projects.tsx      → Projects tab view
│           └── Templates.tsx     → Templates tab view
│
└── styles/                  # 🎨 Global styles
    └── custom-properties/
        ├── colors.css       → Design tokens (colors)
        ├── fonts.css        → Typography tokens
        └── spacing.css      → Spacing tokens

🚀 Launcher/Projects Organization System (Phase 3)

The Launcher includes a complete project organization system with folders and tags:

Key Components:

• FolderTree: Hierarchical folder display with expand/collapse
• TagPill: Colored badge for displaying project tags (9 predefined colors)
• TagSelector: Checkbox-based UI for assigning tags to projects
• useProjectOrganization: Hook for folder/tag management (uses LocalStorage for Storybook compatibility)

Data Flow:

ProjectOrganizationService (editor)
    ↓ (via LauncherContext)
useProjectOrganization hook
    ↓
FolderTree / TagPill / TagSelector components

Storage:

• Projects identified by localPath (stable across renames)
• Folders: hierarchical structure with parent/child relationships
• Tags: 9 predefined colors (#EF4444, #F97316, #EAB308, #22C55E, #06B6D4, #3B82F6, #8B5CF6, #EC4899, #6B7280)
• Persisted via ProjectOrganizationService → LocalStorage (Storybook) or electron-store (production)

---

🔍 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!