wiki: master EVOLV wiki refactor — 7 new pages + corrected Home

Complete redesign of the platform-level wiki. Previous Home.md had a broken Mermaid diagram (showed pumpingStation → valveGroupControl as a parent/child edge, which isn't in any configure() declaration). Audit of all 12 specificClass.js configure() calls drives the new ground-truth hierarchy. New pages: - Home.md (rewritten — accurate mermaid, full node + concept index) - Architecture.md (3-tier code structure, generalFunctions API surface, child-registration sequence) - Topology-Patterns.md (5 verified plant configurations + worked example) - Topic-Conventions.md (set./cmd./evt./data./child. + unit policy + S88 palette + measurement key shape + status badge + HealthStatus) - Telemetry.md (Port 0/1/2 contracts + InfluxDB line-protocol layout + FlowFuse charts + Grafana provisioning) - Getting-Started.md (clone, install, Docker vs local, first example) - Glossary.md (S88, EVOLV runtime, WWTP, pumps, control, project terms) - _Sidebar.md (gitea wiki navigation) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 21:47:57 +02:00
parent 9ab9f6b3e3
commit 2ccc8aea9e
8 changed files with 1226 additions and 48 deletions
--- a/wiki/Home.md
+++ b/wiki/Home.md
@@ -1,8 +1,9 @@
-# EVOLV — Wastewater treatment plant automation
+# EVOLV — Wastewater Treatment Plant Automation

-> **Reflects code as of `afc304b` · regenerated `2026-05-11` via `npm run wiki:home`**
+> **Reflects code as of `9ab9f6b` · regenerated `2026-05-11`**
+> Source of truth: `nodes/<name>/src/specificClass.js` `configure()` declarations. Edges below were verified against `router.onRegister(...)` calls and emitter subscriptions.

-EVOLV is a Node-RED node library for wastewater plant automation, developed by the R&D team at Waterschap Brabantse Delta. Nodes follow the ISA-88 (S88) batch control standard. The library exposes 11 active nodes spanning four S88 levels — from Process Cell down to Control Module — plus one utility node for dashboard integration.
+EVOLV is a Node-RED node library for wastewater plant automation, developed by Waterschap Brabantse Delta's R&D team. Nodes follow ISA-88 (S88). The library exposes **11 active nodes** across four S88 levels plus **1 utility node** for Grafana dashboard provisioning, all built on a shared `generalFunctions` library.

 ## Platform overview

@@ -24,64 +25,85 @@ flowchart TB
        diff[diffuser]:::equip
    end
    subgraph CM["Control Module"]
-        meas[measurement]:::ctrl
+        meas["measurement<br/><i>registers with any process node</i>"]:::ctrl
    end
    subgraph UT["Utility"]
-        dash[dashboardAPI]:::neutral
+        dash["dashboardAPI<br/><i>any node → Grafana dashboard</i>"]:::util
    end
-    ps --> mgc
-    ps --> vgc
-    mgc --> rm
-    vgc --> v
-    reactor --> diff
-    meas -.data.-> rm
-    meas -.data.-> v
-    meas -.data.-> reactor
-    meas -.data.-> settler
+
+    ps -->|owns| mgc
+    ps -.->|direct child, no group| rm
+    mgc -->|load-shares| rm
+    vgc -->|positions| v
+    settler -->|return pump| rm
+
+    reactor ==stateChange==> settler
+    diff -. OTR data .-> reactor
+
    classDef pc fill:#0c99d9,color:#fff
    classDef unit fill:#50a8d9,color:#000
    classDef equip fill:#86bbdd,color:#000
    classDef ctrl fill:#a9daee,color:#000
-    classDef neutral fill:#dddddd,color:#000
+    classDef util fill:#dddddd,color:#000
 ```

-S88 colours: Process Cell `#0c99d9`, Unit `#50a8d9`, Equipment `#86bbdd`, Control Module `#a9daee`. Solid arrow = parent/child relationship. Dashed arrow = data flow (`measurement` feeds many node types). Source of truth: `.claude/rules/node-red-flow-layout.md` §14.
+**Edges in this diagram are ground-truth** — every solid arrow is a `router.onRegister(softwareType, …)` declaration in the parent's `configure()`. Dashed arrows are emitter subscriptions (not child registrations). For full data-flow including `measurement` fan-out to every process node and `valveGroupControl`'s flow-source registrations, see **[Topology-Patterns](Topology-Patterns)**.

 ## Live nodes

-| S88 | Node | One-liner | Wiki |
+| S88 level | Node | One-liner | Per-node wiki |
 |---|---|---|---|
-| Process Cell | **pumpingStation** | Manages a wet-well basin, hands demand to one or more group controllers. | [→](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) |
-| Unit | **machineGroupControl** | Load-sharing across a group of rotatingMachines. | [→](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home) |
-| Unit | **valveGroupControl** | Coordinated valve control across a group of valves. | [→](https://gitea.wbd-rd.nl/RnD/valveGroupControl/wiki/Home) |
-| Unit | **reactor** | Bioreactor — couples diffuser + measurements + ASM kinetics. | [→](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home) |
-| Unit | **settler** | Settler / clarifier modelling. | [→](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home) |
-| Unit | **monster** | Composite-sample sensor surrogate / multi-parameter monitor. | [→](https://gitea.wbd-rd.nl/RnD/monster/wiki/Home) |
-| Equipment | **rotatingMachine** | Single pump / compressor — curves, state machine, prediction. | [→](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) |
-| Equipment | **valve** | Single valve actuator with FSM. | [→](https://gitea.wbd-rd.nl/RnD/valve/wiki/Home) |
-| Equipment | **diffuser** | Aeration diffuser, gas-side modelling. | [→](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) |
-| Control Module | **measurement** | Sensor signal-conditioning, scaling, calibration. | [→](https://gitea.wbd-rd.nl/RnD/measurement/wiki/Home) |
-| Utility | **dashboardAPI** | Bridge between EVOLV nodes and Grafana dashboard upserts. | [→](https://gitea.wbd-rd.nl/RnD/dashboardAPI/wiki/Home) |
+| 🟦 Process Cell | **pumpingStation** | Wet-well basin model; dispatches demand to one or more pump groups. | [Home →](https://gitea.wbd-rd.nl/RnD/pumpingStation/wiki/Home) |
+| 🔷 Unit | **machineGroupControl** | Load-sharing across a group of `rotatingMachine` children. | [Home →](https://gitea.wbd-rd.nl/RnD/machineGroupControl/wiki/Home) |
+| 🔷 Unit | **valveGroupControl** | Coordinated position control across a group of `valve` children; can register pump/PS/MGC nodes as flow sources. | [Home →](https://gitea.wbd-rd.nl/RnD/valveGroupControl/wiki/Home) |
+| 🔷 Unit | **reactor** | Bioreactor — ASM kinetics (CSTR/PFR engines); pairs with diffuser + downstream settler. | [Home →](https://gitea.wbd-rd.nl/RnD/reactor/wiki/Home) |
+| 🔷 Unit | **settler** | Secondary clarifier; subscribes to upstream reactor stateChange, drives a return-pump. | [Home →](https://gitea.wbd-rd.nl/RnD/settler/wiki/Home) |
+| 🔷 Unit | **monster** | Composite-sample sensor surrogate / proportional sampling program. | [Home →](https://gitea.wbd-rd.nl/RnD/monster/wiki/Home) |
+| 🟦 Equipment | **rotatingMachine** | Single pump / compressor — characteristic curves, prediction, FSM. | [Home →](https://gitea.wbd-rd.nl/RnD/rotatingMachine/wiki/Home) |
+| 🟦 Equipment | **valve** | Single valve actuator with FSM (shared with rotatingMachine state model). | [Home →](https://gitea.wbd-rd.nl/RnD/valve/wiki/Home) |
+| 🟦 Equipment | **diffuser** | Aeration diffuser; gas-side modelling, OTR emission to reactor. | [Home →](https://gitea.wbd-rd.nl/RnD/diffuser/wiki/Home) |
+| 🔹 Control Module | **measurement** | Sensor signal-conditioning, scaling, smoothing, outlier detection, analog/digital/MQTT. | [Home →](https://gitea.wbd-rd.nl/RnD/measurement/wiki/Home) |
+| ⚪ Utility | **dashboardAPI** | Receives `child.register` for any process node → provisions Grafana dashboard via HTTP. | [Home →](https://gitea.wbd-rd.nl/RnD/dashboardAPI/wiki/Home) |
+| — | **generalFunctions** | Shared library — `BaseDomain`, `BaseNodeAdapter`, `ChildRouter`, `commandRegistry`, `UnitPolicy`, `MeasurementContainer`, `statusBadge`, `HealthStatus`, `logger`, `configManager`. **Not a Node-RED node.** | [Home →](https://gitea.wbd-rd.nl/RnD/generalFunctions/wiki/Home) |

-Plus the shared library `generalFunctions` — not a Node-RED node itself; provides `BaseDomain`, `BaseNodeAdapter`, `ChildRouter`, `UnitPolicy`, `MeasurementContainer`, command registry, logger, and config manager.
+## Start here

-## Standards & conventions
+| You want to… | Read |
+|---|---|
+| Stand up a local dev environment + run an example flow | [Getting-Started](Getting-Started) |
+| Understand the codebase layout, BaseDomain/adapter pattern, output ports | [Architecture](Architecture) |
+| See typical plant configurations and how nodes wire together | [Topology-Patterns](Topology-Patterns) |
+| Know what topic names to use, units, S88 colours | [Topic-Conventions](Topic-Conventions) |
+| Understand what Port 0 / Port 1 / Port 2 carry, InfluxDB layout | [Telemetry](Telemetry) |
+| Decode S88 / EVOLV jargon | [Glossary](Glossary) |

-| Document | What it covers | Where |
-|---|---|---|
-| Node architecture (3-tier) | entry → nodeClass → specificClass | `.claude/rules/node-architecture.md` |
-| Flow layout (Node-RED tabs) | Tab boundaries, lanes, S88 colours, link channels | `.claude/rules/node-red-flow-layout.md` |
-| Telemetry (Port 0/1/2) | InfluxDB line protocol, cardinality, FlowFuse compatibility | `.claude/rules/telemetry.md` |
-| generalFunctions stability | What's safe to change in the shared lib | `.claude/rules/general-functions.md` |
-| repo-mem MCP usage | When to use `repo_search` / `repo_record_fix` instead of grep | `.claude/rules/repo-mem.md` |
-| Refactor goals + tiers | Why the refactor exists, sequencing | `.claude/refactor/README.md` |
-| Code conventions | Style, file size, comments, naming, imports, tests | `.claude/refactor/CONVENTIONS.md` |
-| Contracts | `BaseNodeAdapter`, `BaseDomain`, commands registry, child router, unit policy, status badge, output ports | `.claude/refactor/CONTRACTS.md` |
-| Module split | Per-node `src/` layout for the 4 core nodes + generic template | `.claude/refactor/MODULE_SPLIT.md` |
-| Wiki per-node template | The 14-section page shape | `.claude/refactor/WIKI_TEMPLATE.md` |
-| Wiki home + archive | This page's template | `.claude/refactor/WIKI_HOME_TEMPLATE.md` |
+## Domain concepts

-## Refactor status
+Evergreen technical references (not affected by refactors):
+
+| Page | Topic |
+|---|---|
+| [ASM models](concepts/asm-models) | Activated Sludge Models — biological process kinetics |
+| [PID control theory](concepts/pid-control-theory) | Loop tuning, anti-windup, controller forms |
+| [Pump affinity laws](concepts/pump-affinity-laws) | Speed/flow/head/power scaling |
+| [Settling models](concepts/settling-models) | Takács / Vesilind / discrete settling |
+| [Signal processing — sensors](concepts/signal-processing-sensors) | Smoothing, outlier rejection |
+| [InfluxDB schema design](concepts/influxdb-schema-design) | Cardinality, tags vs fields |
+| [Wastewater compliance NL](concepts/wastewater-compliance-nl) | Dutch regulatory context |
+| [OT security — IEC 62443](concepts/ot-security-iec62443) | OT cybersecurity baseline |
+
+## Operations findings
+
+Algorithm-level proofs and behavioural notes that are still valid:
+
+| Page | Topic |
+|---|---|
+| [BEP gravitation proof](findings/bep-gravitation-proof) | Best-efficiency-point convergence |
+| [Curve non-convexity](findings/curve-non-convexity) | When pump curves break local optima |
+| [NCog behaviour](findings/ncog-behavior) | NCog control metric notes |
+| [Pump switching stability](findings/pump-switching-stability) | Hysteresis design for multi-pump groups |
+
+## Project status

 | Tier | What | Status |
 |---|---|---|
@@ -90,12 +112,14 @@ Plus the shared library `generalFunctions` — not a Node-RED node itself; provi
 | 3 | Convert measurement, MGC, rotatingMachine | ✅ done |
 | 4 | Convert valve, VGC, reactor, settler, monster, diffuser, dashboardAPI | ✅ done |
 | 5 | Canonical topic names + alias deprecation map | ✅ done |
-| 6 | Promote `development` → `main` | ⏳ pending Docker E2E sign-off + human review |
+| 6 | Promote `development` → `main` | ⏳ pending Docker E2E + human review |
 | 8.5 | Remove deprecated paths in `generalFunctions` | ✅ done |
-| 9 | Wiki cleanup — visual-first template + per-node Home pages | 🟡 in progress (per-node rewrites landing 2026-05-11; parent-repo wiki audit this wave) |
-| 10 | Test-suite refactor across all nodes | ⏳ in progress |
+| 9 | Wiki refactor — visual-first per-node + master pages | ✅ landed 2026-05-11 |
+| 10 | Test-suite refactor across all nodes | 🟡 in progress |
 | — | pumpingStation Docker E2E (P2.14) | ⏳ pending |

+823 platform tests pass · 0 failures · 12 submodules + parent on `development`.
+
 ## Archive

-Pre-refactor pages live under `Archive/`. See [Archive index](Archive).
+Pre-refactor planning pages have been moved to the [Archive](Archive). The current Home and supporting pages are the canonical references.