EVOLV/.agents/improvements/EXAMPLE_FLOW_TEMPLATE.md

EVOLV Example Flow Template Standard

Overview

Every EVOLV node MUST have example flows in its examples/ directory. Node-RED automatically discovers these and shows them in Import > Examples > EVOLV.

Naming Convention

examples/
  01 - Basic Manual Control.json          # Tier 1: inject-based, zero deps
  02 - Integration with Parent Node.json  # Tier 2: parent-child wiring
  03 - Dashboard Visualization.json       # Tier 3: FlowFuse dashboard (optional)

The filename (minus .json) becomes the menu label in Node-RED.

Tier 1: Basic (inject-based, zero external dependencies)

Purpose: Demonstrate all key functionality using only core Node-RED nodes.

Required elements:

• 1x comment node (top-left): title + 2-3 line description of what the flow demonstrates
• 1x comment node (near inputs): "HOW TO USE: 1. Deploy flow. 2. Click inject nodes..."
• inject nodes for each control action (labeled clearly)
• The EVOLV node under test with realistic, working configuration
• 3x debug nodes: "Port 0: Process", "Port 1: InfluxDB", "Port 2: Parent"
• Optional: 1x function node to format output readably (keep under 20 lines)

Forbidden: No dashboard nodes. No FlowFuse widgets. No HTTP nodes. No third-party nodes.

Config rules:

• All required config fields filled with realistic values
• Model/curve fields set to existing models in the library
• enableLog: true, logLevel: "info" so users can see what happens
• Unit fields explicitly set (not empty strings)

Layout rules:

• Comment nodes: top-left
• Input section: left side (x: 100-400)
• EVOLV node: center (x: 500-600)
• Debug/output: right side (x: 700-900)
• Y spacing: ~60px between nodes

Tier 2: Integration (parent-child relationships)

Purpose: Show how nodes connect as parent-child via Port 2.

Required elements:

• 1x comment node: what relationship is being demonstrated
• Parent node + child node(s) properly wired
• Port 2 of child → Port 0 input of parent (registration pathway)
• inject nodes to send control commands to parent
• inject nodes to send measurement/state to children
• debug nodes on all ports of both parent and children

Node-specific integration patterns:

• machineGroupControl → 2x rotatingMachine
• pumpingStation → 1x rotatingMachine + 1x measurement (assetType: "flow")
• valveGroupControl → 2x valve
• reactor → settler (downstream cascade)
• measurement → any parent node

Tier 3: Dashboard Visualization (optional)

Purpose: Rich interactive demo with FlowFuse dashboard.

Allowed additional dependencies: FlowFuse dashboard nodes only (@flowfuse/node-red-dashboard).

Required elements:

• 1x comment node: "Requires @flowfuse/node-red-dashboard"
• Auto-initialization: inject node with "Inject once after 1 second" for default mode/state
• Dashboard controls clearly labeled
• Charts with proper axis labels and units
• Keep parser/formatter functions under 40 lines (split if needed)
• No null message outputs (filter before sending to charts)

Comment Node Standard

Every comment node must use this format:

Title: [Node Name] - [Flow Tier]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[2-3 line description]

Prerequisites: [list any requirements]

ID Naming Convention

Use predictable, readable IDs for all nodes (not random hex):

{nodeName}_{tier}_{purpose}

Examples:
- rm_basic_tab           (rotatingMachine, basic flow, tab)
- rm_basic_node          (the actual rotatingMachine node)
- rm_basic_debug_port0   (debug on port 0)
- rm_basic_inject_start  (inject for startup)
- rm_basic_comment_title (title comment)

Validation Checklist

Before committing an example flow:

• Can be imported into clean Node-RED + EVOLV (no other packages needed for Tier 1/2)
• All nodes show correct status after deploy (no red triangles)
• Comment nodes present and descriptive
• All 3 output ports wired to something (debug at minimum)
• IDs follow naming convention (no random hex)
• Node config uses realistic values (not empty strings or defaults)
• File named per convention (01/02/03 prefix)

Gitea Wiki Integration

Each node's wiki gets an "Examples" page that:

1. Lists all available example flows with descriptions
2. Links to the raw .json file in the repo
3. Describes prerequisites and step-by-step usage
4. Shows expected behavior after deploy