Documentation Overhaul

Docs/flow-editor-and-nodes.md

@@ -0,0 +1,82 @@
+# Flow Editor and Nodes
+[Back to Docs Index](index.md) | [Index (HTML)](index.html)
+
+## Purpose
+Document the Borealis visual flow editor (React Flow) and how nodes are defined, grouped, and rendered.
+
+## Core UI Components
+- `Data/Engine/web-interface/src/Flow_Editor/Flow_Editor.jsx` - canvas, drag/drop, edge editing, context menus.
+- `Data/Engine/web-interface/src/Flow_Editor/Node_Sidebar.jsx` - node catalog and drag source.
+- `Data/Engine/web-interface/src/Flow_Editor/Node_Configuration_Sidebar.jsx` - per-node configuration UI.
+- `Data/Engine/web-interface/src/Flow_Editor/Context_Menu_Sidebar.jsx` - right-click actions.
+
+## Node Registration Pipeline
+- Node modules are auto-loaded in `Data/Engine/web-interface/src/App.jsx` via:
+  `import.meta.glob('./Nodes/**/*.jsx', { eager: true })`.
+- Each module default-exports a descriptor object that includes:
+  - `type` (unique node type string)
+  - `component` (React component)
+  - metadata like `name`, `category`, `description`, `config`, `usage_documentation`
+- `App.jsx` builds:
+  - `nodeTypes` (type -> component)
+  - `categorizedNodes` (category -> list of descriptors)
+
+## Node Categories (Current Folder Layout)
+- `Agent`
+- `Alerting`
+- `Data Analysis & Manipulation`
+- `Data Collection`
+- `Flow Control`
+- `General Purpose`
+- `Image Processing`
+- `Organization`
+- `Reporting`
+- `Templates`
+
+## Scheduling Flow Usage
+- `Data/Engine/web-interface/src/Scheduling/Create_Job.jsx` uses React Flow for job status and dependency visualization.
+
+## API Endpoints
+None. This is a UI-only domain.
+
+## Related Documentation
+- [Assemblies and Quick Jobs](assemblies.md)
+- [Scheduled Jobs](scheduled-jobs.md)
+- [UI and Notifications](ui-and-notifications.md)
+
+## Codex Agent (Detailed)
+### How node modules are structured
+- A node file exports a descriptor object, for example:
+  - `type: "agent"`
+  - `component: BorealisAgentNode`
+  - `config: [{ key, label, type, defaultValue, optionsKey, ... }]`
+- The `component` is the React Flow node UI.
+- The descriptor is used by the sidebar for display and configuration forms.
+
+### Adding a new node (step-by-step)
+1) Create a new file under `Data/Engine/web-interface/src/nodes/<Category>/Node_<Name>.jsx`.
+2) Export a descriptor object as the default export with `type` and `component` fields.
+3) Include `config` entries if you want the configuration sidebar to render fields.
+4) Rebuild the WebUI (or run Vite dev mode) so `import.meta.glob` picks it up.
+5) Validate drag/drop in the Node Sidebar and ensure the node renders correctly.
+
+### Sidebar behavior
+- `Node_Sidebar.jsx` renders `categorizedNodes` and sets `dataTransfer` payloads with `application/reactflow`.
+- `Flow_Editor.jsx` listens for drop events and creates nodes from the descriptor catalog.
+
+### Node configuration sidebar
+- `Node_Configuration_Sidebar.jsx` uses `useReactFlow().setNodes` to update node data.
+- `config` metadata drives form rendering; data is stored in `node.data`.
+
+### Canvas interactions
+- Right-click context menus allow node delete, edge unlink, and property edit.
+- Snap guides are computed in `Flow_Editor.jsx` for alignment.
+
+### Job flow editor
+- `Scheduling/Create_Job.jsx` uses a custom React Flow setup for status and dependency visualization.
+- Keep job flow nodes separate from the general node catalog to avoid accidental crossover.
+
+### Common gotchas
+- Folder path casing is `src/nodes/` in the repo, but `App.jsx` imports `./Nodes/` (Windows is case-insensitive).
+- Ensure each node descriptor has a unique `type` or React Flow will mis-render.
+- If the sidebar does not show the new node, verify the export default object has `type` and `component`.