1d0dd45d9a
All 12 submodules + parent EVOLV are now on the `development` branch
with the platform refactor complete:
generalFunctions 7372d12 Phase 1 platform infra (additive)
BaseNodeAdapter / BaseDomain / UnitPolicy
ChildRouter / LatestWinsGate / HealthStatus
commandRegistry / statusBadge / statusUpdater
stats — 113 unit tests
pumpingStation 52d3889 Phase 2 — concern split + integration
basin/measurement/control/safety/io/commands
specificClass 1039→245 lines, 102 tests
measurement 42a0333 Phase 3 — Channel-based analog + BaseDomain
simulator/calibration/commands extracted
specificClass 716→244 lines, 96 tests
machineGroupControl bb2f3be Phase 4 — concern split + integration
groupOps/totals/combinatorics/optimizer/
efficiency/dispatch/commands
specificClass 1808→336 lines, 77 tests
rotatingMachine e058fe9 Phase 5 — concern split + integration
curves/prediction/drift/pressure/state/
measurement/flow/display/commands
specificClass 1760→400 lines, 196 tests
valve e27135b Phase 6 platform refactor + concern split
valveGroupControl e02cd1a Phase 6 platform refactor + concern split
diffuser 0ec9dd1 Phase 6 platform refactor (port 4→3)
monster 2a6a0bc Phase 6 platform refactor + concern split
settler b8247fc Phase 6 platform refactor (reactor link kept)
reactor 7bf464b Phase 6 platform refactor + kinetics/ split
dashboardAPI 2874608 Phase 6 — commandRegistry only (no BaseDomain;
passive HTTP server — see OPEN_QUESTIONS.md)
493 basic tests pass platform-wide (12/12 nodes green).
All canonical input topics (set.* / cmd.* / data.* / child.* / query.* /
evt.*) live alongside legacy aliases with one-time deprecation warnings.
Topic-rename cycle (P7) elapses across one release before alias removal.
Decisions taken during the refactor are recorded in
.claude/refactor/OPEN_QUESTIONS.md (resolved entries + carryovers for
Phase 8.5 cleanup, Phase 9 wiki, and Phase 10 test rewrite).
Ready for review on a per-submodule basis. Promotion to main is gated
on Docker E2E (per-node trial-ready criteria) — not part of this commit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EVOLV Platform Refactor — Guidelines
This directory holds the durable plan and conventions for the platform-wide refactor of the EVOLV Node-RED nodes. Anyone (human or agent) working on this refactor reads these files first.
Goals
- Eliminate boilerplate — every nodeClass today is ~80% identical.
Move the shared parts into
generalFunctions/. Each node keeps only what is genuinely node-specific. - Split big domain classes —
pumpingStation,machineGroupControl, androtatingMachineeach have ~1000–1800 line monolithicspecificClass.jsfiles mixing 6+ concerns. Split each into focused concern-based modules undersrc/. - Document the contract — every msg.topic the node accepts and every
message it emits is declared in code (a
commands/module) and surfaced in a per-nodeCONTRACT.md. - Standardise naming — consistent topic names across the platform
(
set.<noun>,cmd.<verb>,evt.<noun>). - Keep it readable — small files, small functions, comments that say why and skip what.
Constraint: this is the development branch
All 12 submodules + the parent EVOLV repo are on a development branch.
main is untouched. We can change anything without breaking deployments
that track main.
The refactor lands on development. Promotion to main happens once the
whole platform passes its 3-tier tests + Docker E2E.
Layered approach
The refactor is sequenced as tiers, not a big bang.
| Tier | What | Risk | Reversible? |
|---|---|---|---|
| 1 | Add infra in generalFunctions (additive only — no breaking changes) |
Low | Yes |
| 2 | Pilot one node (pumpingStation) end-to-end on the new infra | Med | Yes |
| 3 | Convert remaining core nodes (measurement, MGC, rotatingMachine) | Med | Yes |
| 4 | Convert remaining nodes (valve, VGC, reactor, settler, monster, diffuser, dashboardAPI) | Low | Yes |
| 5 | Standardise input topic names + deprecation map | Med | Behind feature flag |
| 6 | Promote development → main once Docker E2E green platform-wide |
Low | Yes |
| 7 | Wiki cleanup — visual-first template + Mermaid diagrams per node (post-refactor) | Low | Yes |
Each tier is a sequence of small PRs on development, each with its
existing tests green.
Files in this directory
| File | Purpose |
|---|---|
README.md |
This file. |
CONVENTIONS.md |
Code style, file size, comments, naming, imports, tests. |
CONTRACTS.md |
The exact shapes — BaseNodeAdapter, BaseDomain, commands registry, child router, unit policy, status badge, output ports. |
MODULE_SPLIT.md |
Per-node src/ layout for the 4 core nodes + a generic template. |
TASKS.md |
Phased task list. The TaskCreate task tree mirrors this and is the active tracker. |
OPEN_QUESTIONS.md |
Decisions deferred to later — collected here so we don't lose them. |
Workflow rules for spawned agents
If you are an agent working on a refactor task:
- Read this file,
CONVENTIONS.md,CONTRACTS.md, and the relevant section ofMODULE_SPLIT.mdbefore changing code. - Stay within the scope of one task. Don't expand scope without flagging.
- Run the affected node's tests after every meaningful change. Commands:
cd nodes/<nodeName> && node --test test/basic test/integration test/edge - Don't change
generalFunctionsexports unless your task is in tier 1. - If you discover something unclear, append it to
OPEN_QUESTIONS.mdwith a short note. Do not invent a decision. - Comments: small, function-level, why not what. See
CONVENTIONS.md. - When done, summarise: files changed, tests run, anything deferred to
OPEN_QUESTIONS.md.