# 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`.