mirror of
https://github.com/The-Low-Code-Foundation/OpenNoodl.git
synced 2026-01-12 07:12:54 +01:00
Merged Axel changes. Added dev docs for Cline
This commit is contained in:
Richard Osborne
378
dev-docs/reference/CODEBASE-MAP.md
Normal file
378
dev-docs/reference/CODEBASE-MAP.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# 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
|
||||
|
||||
```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!*
|
||||
Reference in New Issue
Block a user