EVOLV/.claude/rules/node-architecture.md

---
paths:
  - "nodes/*/*.js"
  - "nodes/*/*.html"
  - "nodes/*/src/**"
---

# Node Architecture Rules

## 3-Tier Structure
Every node follows entry → nodeClass → specificClass:

1. **Entry file** (`nodes/<nodeName>/<nodeName>.js`): Registers with Node-RED via `RED.nodes.registerType`, exposes admin HTTP endpoints.
2. **nodeClass** (`nodes/<nodeName>/src/nodeClass.js`): Handles Node-RED runtime concerns — message routing, output formatting, tick loops, status updates, `RED.*` API calls.
3. **specificClass** (`nodes/<nodeName>/src/specificClass.js`): Pure domain logic — physics, control algorithms, state machines.

## Separation Rules
- **specificClass must never call `RED.*` directly** — all Node-RED interaction goes through nodeClass.
- specificClass is the source of truth for domain behavior.
- nodeClass is the adapter between Node-RED and domain logic.
- Entry file is minimal — registration and admin endpoints only.

## Output Port Convention
- Port 0: Process data (control outputs, state, setpoints)
- Port 1: InfluxDB telemetry payload
- Port 2: Registration/control plumbing (parent-child handshakes)

## File-Naming Convention
The folder name is the canonical node name and every per-node file MUST match it
exactly (case-sensitive). No abbreviations.

| Path | Required name |
|---|---|
| Folder | `nodes/<nodeName>/` |
| Entry file | `nodes/<nodeName>/<nodeName>.js` |
| Editor HTML | `nodes/<nodeName>/<nodeName>.html` |
| nodeClass | `nodes/<nodeName>/src/nodeClass.js` |
| specificClass | `nodes/<nodeName>/src/specificClass.js` |
| Editor JS modules | `nodes/<nodeName>/src/editor/*.js` |

`machineGroupControl/mgc.js`, `valveGroupControl/vgc.js`, and
`dashboardAPI/dashboardapi.js` are legacy drift. New nodes MUST use the full
folder name; legacy nodes get renamed when next touched (rename = update entry
file, HTML file, `package.json#node-red.nodes`, and any test imports in one
commit).

## Editor JS Layout — `src/editor/`
Editor-side JavaScript that exceeds a couple of dozen lines lives in modular
files under `nodes/<nodeName>/src/editor/`, served by the entry file via:

```js
const path = require('path');
RED.httpAdmin.get(`/${nameOfNode}/editor/:file`, (req, res) => {
  const safe = String(req.params.file || '').replace(/[^a-zA-Z0-9._-]/g, '');
  if (!safe.endsWith('.js')) return res.status(400).send('// invalid');
  res.type('application/javascript');
  res.sendFile(path.join(__dirname, 'src', 'editor', safe), (err) => {
    if (err && !res.headersSent) res.status(404).send('// editor module not found');
  });
});
```

The HTML file then loads them as plain `<script src="/<nodeName>/editor/<file>.js">`
tags. Conventional modules:

| File | Purpose |
|---|---|
| `index.js` | Namespace setup (`window.EVOLV.nodes.<nodeName>.editor = …`), shared helpers |
| `oneditprepare.js` | Implementation called from the `.html`'s `oneditprepare` hook |
| `oneditsave.js` | Implementation called from the `.html`'s `oneditsave` hook |
| Feature modules | One per visual concern, e.g. `basin-diagram.js`, `mode-cards.js`, `timing-donut.js`, `hover-couple.js` |

The `.html` shrinks to: register defaults, declare HTML template, delegate
`oneditprepare`/`oneditsave` to the modules. Inline JS in the `.html` is fine
for **trivial** nodes (≤ ~50 lines of editor JS); past that, extract.

Reference implementations: `pumpingStation/src/editor/` and
`machineGroupControl/src/editor/`. `rotatingMachine` is currently inline and
should be migrated when the editor JS next grows.

## Admin Endpoints
- `GET /<nodeName>/menu.js` — Dynamic menu configuration for editor
- `GET /<nodeName>/configData.js` — Runtime configuration for editor
- `GET /<nodeName>/editor/:file` — (when present) editor JS modules from `src/editor/`

## Submodule Awareness
Most `nodes/*` directories are git submodules. Keep edits scoped to the target node's directory.