Borealis-Github-Replica/Docs/flow-editor-and-nodes.md

Flow Editor and Nodes

Back to Docs Index | 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
• Scheduled Jobs
• UI and Notifications

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.