EVOLV/.claude/refactor/README.md

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

1. Eliminate boilerplate — every nodeClass today is ~80% identical. Move the shared parts into generalFunctions/. Each node keeps only what is genuinely node-specific.
2. Split big domain classes — pumpingStation, machineGroupControl, and rotatingMachine each have ~1000–1800 line monolithic specificClass.js files mixing 6+ concerns. Split each into focused concern-based modules under src/.
3. 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-node CONTRACT.md.
4. Standardise naming — consistent topic names across the platform (set.<noun>, cmd.<verb>, evt.<noun>).
5. 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:

1. Read this file, CONVENTIONS.md, CONTRACTS.md, and the relevant section of MODULE_SPLIT.md before changing code.
2. Stay within the scope of one task. Don't expand scope without flagging.
3. Run the affected node's tests after every meaningful change. Commands:

   cd nodes/<nodeName> && node --test test/basic test/integration test/edge
   

4. Don't change generalFunctions exports unless your task is in tier 1.
5. If you discover something unclear, append it to OPEN_QUESTIONS.md with a short note. Do not invent a decision.
6. Comments: small, function-level, why not what. See CONVENTIONS.md.
7. When done, summarise: files changed, tests run, anything deferred to OPEN_QUESTIONS.md.