# 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