RnD/EVOLV
3
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0826d6299759b59d50d6c2a9e0c05b5afe0307b4
EVOLV/.claude/refactor/WIKI_HOME_TEMPLATE.md
znetsixe 025bdb4c7e release: palette redesign + CoreSync scaffolding + dashboardAPI MODULE_NOT_FOUND fix 
PALETTE REDESIGN (2026-05-21)
  Sidebar swatches switched from S88 level (all blue) to domain-hue per node.
  Family hue = function (rotating=orange, valves=teal, biology=green/olive,
  sampling=violet, sensor=amber, aeration=sky-blue, infrastructure=slate);
  within a family, darker = higher S88 / "more controller-ish."
  Editor-group rectangles in flow.json still follow S88 — only the
  registerType colour changed.

  Submodule bumps for palette: rotatingMachine, machineGroupControl,
  pumpingStation, valve, valveGroupControl, reactor, settler, monster,
  measurement, diffuser, dashboardAPI.

  Docs touched:
    - CLAUDE.md: palette swatch vs. editor-group bullets split out.
    - .claude/rules/node-red-flow-layout.md: new §10.0 introduces the two
      color systems, full 12-row palette table, and explicit warning not to
      mix the two hexes.
    - .claude/refactor/MODULE_SPLIT.md: per-node headers annotated with
      both `group #XXX` and `palette #XXX`.
    - .claude/refactor/WIKI_HOME_TEMPLATE.md + WIKI_TEMPLATE.md: clarify
      Mermaid classDefs visualize hierarchy, not palette swatches.
    - .claude/refactor/OPEN_QUESTIONS.md: dated decision entry with
      rationale, file list, and follow-ups.

CORESYNC SUBMODULE (new)
  nodes/coresync added pointing at https://gitea.wbd-rd.nl/RnD/coresync.
  FROST/SensorThings handoff path — first version forwards FROST-ready HTTP
  request messages on the dbase output; a downstream http-request node
  performs the POST and feeds responses back on msg.topic = "frost.response".
  Lazy stream resolver, latest-wins queue (keep first + latest, drop middle),
  knot-emit on slope change, provenance preserved in Observation parameters.

    - .gitmodules: add nodes/coresync entry.
    - package.json: register coresync as a Node-RED node.
    - generalFunctions bump: new frostFormatter + 4 node config schemas
      expose the dbase format option.
    - measurement bump: "frost" option added to dbaseOutputFormat dropdown
      (plus the in-flight data.measurement unit-handling work).
    - machineGroupControl bump: small editor compact-fields tweak alongside
      the palette change.
    - CORESYNC_FROST_INTERVIEW_HANDOFF.md added at root with interview state
      (Q20 open: slope angle vs. relative delta comparison).

DASHBOARDAPI MODULE_NOT_FOUND FIX
  package.json: dashboardapi entry path corrected to
  nodes/dashboardAPI/dashboardAPI.js. Commit e04c4a1 renamed the files to
  camelCase but missed package.json; on case-sensitive filesystems
  (Linux/Docker, where the tarball lands) the require resolved to nothing
  and the node showed MODULE_NOT_FOUND in the Node-RED palette.

MISC CLEANUP
  - examples/README.md + examples/pumpingstation-complete-example/ removal
    (build_flow.py, flow.json, README.md superseded by per-node examples).
  - jest.config.js: in-progress tweak.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 15:09:33 +02:00

142 lines
6.5 KiB
Markdown
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 (used here for **hierarchy visualization only** — distinct from the node-palette swatches in the Node-RED sidebar, which are domain-hue; see `.claude/rules/node-red-flow-layout.md` §10.0): 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