0ff50a0291
Single doc capturing the 'what's not done' at the end of the 2026-05-11 sprint, in priority order: B5 reactor boundary-conditions merge, Phase 8 PR cycle, a handful of small open-questions follow-ups, plus the wiki cosmetics list. README.md links to it from the top. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
83 lines
3.9 KiB
Markdown
83 lines
3.9 KiB
Markdown
# 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.
|
||
|
||
> **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.
|
||
|
||
## 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`.
|