RnD/EVOLV
3
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
424ad1e29347d64d1efed17ffdbb929189fb554f
EVOLV/.claude/refactor/WIKI_HOME_TEMPLATE.md
Rene De Ren e03a7a51b7 P9 follow-up: expand wiki template + add Home/Archive template 
WIKI_TEMPLATE.md — extend the canonical per-node page from 9 to 14 sections:
  + Header band (commit hash + regen date)
  + Code map (flowchart TB w/ subgraphs over concern modules)
  + Child registration (mirrors ChildRouter declarations)
  + Data model — getOutput() (abstract schema + optional concrete sample)
  + Debug recipes (symptom → first thing to check)
  + AUTOGEN markers around topic-contract + data-model schema so the
    Phase 9 regen script can rewrite in place.
  + 'Picking a visual' table: Mermaid is default, plots/SVG/screenshots
    allowed where they serve the data.
  + Archive banner snippet.

WIKI_HOME_TEMPLATE.md (new) — Home.md + Archive.md templates:
  - Platform-wide Mermaid graph of 11 active nodes, S88-coloured.
  - Navigation table grouped by S88 level.
  - Standards-pointer table to .claude/rules + .claude/refactor docs.
  - Live refactor-status table for returning visitors.
  - Archive index template with archival-date column.

No wiki pages written yet — next step is one worked example
(pumpingStation) before any change to the Gitea wiki repo.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-11 14:25:34 +02:00

6.3 KiB
Raw Blame History

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 -->
Reference in New Issue View Git Blame Copy Permalink