EVOLV/.claude/refactor/WIKI_HOME_TEMPLATE.md

# Platform wiki home — `Home.md` template

The landing page for the EVOLV Gitea wiki. Same visual-first rules as `WIKI_TEMPLATE.md`: diagrams lead, tables annotate, ≤ 60 words per paragraph.

`Home.md` answers three questions for a first-time visitor:

1. **What is this platform?** One paragraph.
2. **What nodes exist and how do they relate?** One platform-wide Mermaid graph + a navigation table.
3. **Where do I find the conventions?** A pointer table to the rule files in `.claude/`.

Plus a live refactor-status table so a returning visitor knows what changed since they last looked.

## Template — copy the block below as the seed for `Home.md`

```
<!-- BEGIN TEMPLATE — Home.md -->

# EVOLV — Wastewater treatment plant automation

> **Reflects code as of `<git short hash>` · regenerated `<YYYY-MM-DD>` via `npm run wiki:home`**

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.

## Platform overview

~~~mermaid
flowchart TB
    subgraph PC["Process Cell"]
        ps[pumpingStation]:::pc
    end
    subgraph UN["Unit"]
        mgc[machineGroupControl]:::unit
        vgc[valveGroupControl]:::unit
        reactor[reactor]:::unit
        settler[settler]:::unit
        monster[monster]:::unit
    end
    subgraph EM["Equipment"]
        rm[rotatingMachine]:::equip
        v[valve]:::equip
        diff[diffuser]:::equip
    end
    subgraph CM["Control Module"]
        meas[measurement]:::ctrl
    end
    subgraph UT["Utility"]
        dash[dashboardAPI]:::neutral
    end
    ps --> mgc
    ps --> vgc
    mgc --> rm
    vgc --> v
    reactor --> diff
    meas -.data.-> rm
    meas -.data.-> v
    meas -.data.-> reactor
    meas -.data.-> settler
    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
~~~

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).

## Live nodes

| S88 | Node | One-liner | Wiki |
|---|---|---|---|
| 🟦 Process Cell | **pumpingStation** | Manages a wet-well basin, hands demand to one or more group controllers. | [→](pumpingStation) |
| 🔷 Unit | **machineGroupControl** | Load-sharing across a group of rotatingMachines. | [→](machineGroupControl) |
| 🔷 Unit | **valveGroupControl** | Coordinated valve control across a group of valves. | [→](valveGroupControl) |
| 🔷 Unit | **reactor** | Bioreactor — couples diffuser + measurements + kinetics. | [→](reactor) |
| 🔷 Unit | **settler** | Settler / clarifier modelling. | [→](settler) |
| 🔷 Unit | **monster** | Composite-sample sensor surrogate. | [→](monster) |
| 🟦 Equipment | **rotatingMachine** | Single pump / compressor — curves, state machine, prediction. | [→](rotatingMachine) |
| 🟦 Equipment | **valve** | Single valve actuator with FSM. | [→](valve) |
| 🟦 Equipment | **diffuser** | Aeration diffuser, gas-side modelling. | [→](diffuser) |
| 🔹 Control Module | **measurement** | Sensor signal-conditioning, scaling, calibration. | [→](measurement) |
| ⚪ Utility | **dashboardAPI** | Bridge between FlowFuse dashboard widgets and EVOLV. | [→](dashboardAPI) |

## Standards & conventions

| 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` |
| Topic naming (`set.` / `cmd.` / `evt.`) | Canonical input + output topics | `.claude/refactor/CONTRACTS.md` §1 |
| Wiki page shape | Per-node page template | `.claude/refactor/WIKI_TEMPLATE.md` |
| Wiki home shape | This page's template | `.claude/refactor/WIKI_HOME_TEMPLATE.md` |
| generalFunctions stability rules | What's safe to change | `.claude/rules/general-functions.md` |

## Refactor status

| Tier | What | Status |
|---|---|---|
| 1 | Add infra in generalFunctions (additive only) | ✅ done |
| 2 | Pilot: pumpingStation | ✅ done |
| 3 | Convert measurement, MGC, rotatingMachine | ✅ done |
| 4 | Convert valve, VGC, reactor, settler, monster, diffuser | ✅ done |
| 4* | dashboardAPI | ⏸️ out of scope (no `generalFunctions` dep) |
| 5 | Canonical topic names + alias deprecation | 🟡 partial |
| 6 | development → main promotion | ⏳ pending Docker E2E |
| 7 | Wiki refactor (this work) | 🟡 in progress |

## Archive

Pre-refactor pages live under `Archive/`. See [Archive index](Archive).

<!-- END TEMPLATE -->
```

## Notes for the maintainer

- `npm run wiki:home` (not yet built) re-renders the platform Mermaid block if any node's `softwareType` registration changes. Until then, the diagram is hand-maintained.
- Refactor-status rows flip as tiers land. Anyone landing a tier updates the table in the same PR.
- The "Live nodes" table is hand-maintained but small — bulk changes happen only when a node is added or retired.
- The Mermaid graph above mirrors what's in `.claude/rules/node-red-flow-layout.md` §10.1 (lane convention). If the rule changes, mirror it here.

## Archive index — `Archive.md` template

A separate page that lists every archived page with its archival date and the era it describes.

```
<!-- BEGIN TEMPLATE — Archive.md -->

# Archive — pre-refactor wiki pages

Pages kept for historical reference. **Do not update them.** Corrections go on the current page; if you find a meaningful inaccuracy in the archived page, leave it and add a note to the *current* page explaining what changed.

| Page | Era | Archived on |
|---|---|---|
| [pumpingStation (pre-refactor)](Archive/pumpingStation-pre-refactor) | Pre-Tier-2 (May 2026) | 2026-05-11 |
| [rotatingMachine (pre-refactor)](Archive/rotatingMachine-pre-refactor) | Pre-Tier-3 (May 2026) | 2026-05-11 |
| ... | ... | ... |

Each archived page carries the standard banner at its top (see `WIKI_TEMPLATE.md` → Archive banner).

<!-- END TEMPLATE -->
```