2026-05-10 18:22:30 +02:00
|
|
|
|
# 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.
|
|
|
|
|
|
|
2026-05-11 20:18:46 +02:00
|
|
|
|
> **Fresh context? Start here:** read **[`CONTINUE_HERE.md`](./CONTINUE_HERE.md)** first.
|
|
|
|
|
|
> It explains the current state (Phases 1–11 done, 823 platform tests green),
|
|
|
|
|
|
> lists the deferred work in priority order, and points at the specific
|
|
|
|
|
|
> `OPEN_QUESTIONS.md` entries that still need action.
|
|
|
|
|
|
|
2026-05-10 18:22:30 +02:00
|
|
|
|
## 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`.
|
