mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-11 23:02:56 +01:00
460 lines
16 KiB
Markdown
460 lines
16 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Build editor
|
|
npm run build:editor
|
|
|
|
# Create distributable package
|
|
npm run build:editor:pack
|
|
|
|
# Build cloud runtime
|
|
npm run build:cloud-runtime
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run all editor tests
|
|
npm run test:editor
|
|
|
|
# Run platform tests
|
|
npm run test:platform
|
|
```
|
|
|
|
### Code Quality
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```typescript
|
|
// 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
|
|
|
|
```bash
|
|
# Clear caches
|
|
rm -rf node_modules/.cache
|
|
rm -rf packages/*/node_modules/.cache
|
|
|
|
# Reinstall dependencies
|
|
rm -rf node_modules
|
|
npm install
|
|
```
|
|
|
|
### TypeScript Errors
|
|
|
|
```bash
|
|
# Check for circular dependencies
|
|
npx madge --circular packages/noodl-editor/src
|
|
```
|
|
|
|
### Electron Issues
|
|
|
|
```bash
|
|
# 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!_
|