RnD/EVOLV
3
0
Fork 0
Code Issues 22 Pull Requests Actions Packages Projects Releases Wiki Activity

Add refactor planning docs (.claude/refactor/)

Browse Source 
Platform-wide refactor plan: README, CONVENTIONS, CONTRACTS,
MODULE_SPLIT, TASKS, OPEN_QUESTIONS. Source of truth for the
phased refactor across all 12 submodules.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
znetsixe
2026-05-10 18:22:30 +02:00
parent aec90cc8e7
commit 91e4255ef5
6 changed files with 1302 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
.claude/refactor/README.md Normal file
View File

@@ -0,0 +1,77 @@
# 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`.