RnD/EVOLV

Files

Rene De Ren 253ac93896 docs: standards cleanup — single front-door CONTRACTS.md + archive stale plan artifacts

Establish CONTRACTS.md at the EVOLV root as the canonical map of where every
contract, rule, and standard lives. Surface it from CLAUDE.md so every fresh
agent or colleague lands there first.

Reshape .claude/refactor/ to reflect that the platform refactor is done:
live standards stay at the top level; the plan artifacts (CONTINUE_HERE.md,
TASKS.md) move into Archive/ with WARNING banners.

Drop content that drifted out of date or duplicated the new standards stack:
- docs/DEVELOPER_GUIDE.md (pre-refactor walkthrough; superseded by
  wiki/Architecture, wiki/Getting-Started, .claude/rules/node-architecture,
  .claude/refactor/MODULE_SPLIT + per-node CONTRACT.md + src/commands/).
- .agents/decisions/ (15 DECISION files): load-bearing decisions belong in
  commit messages and PR descriptions; live open items in OPEN_QUESTIONS.md.
- .agents/improvements/TOP10_*.md: moved to Archive/.

Bump generalFunctions to 49c77f2 — adds CONTRACT.md inside the library:
different shape from per-node CONTRACT.md files (library API, not msg.topic),
with stability tags and pointers to .claude/refactor/CONTRACTS.md §N.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-18 15:48:46 +02:00

3.3 KiB

Raw Blame History

EVOLV - Claude Code Project Guide

READ FIRST, BEFORE ANY OTHER WORK:

CONTRACTS.md — front-door map: where every contract, rule, and standard lives, and how to find them.

.claude/rules/repo-mem.md — this repo has an MCP server (repo-mem) exposing a substrate-trained repo_search and a persistent fix-trace store. Use those instead of grep for concept queries, and record completed fixes via repo_record_fix.

What This Is

Node-RED custom nodes package for wastewater treatment plant automation. Developed by Waterschap Brabantse Delta R&D team. Follows ISA-88 (S88) batch control standard.

Architecture

Each node follows a three-layer pattern:

Node-RED wrapper (<name>.js) - registers the node type, sets up HTTP endpoints
Node adapter (src/nodeClass.js) - bridges Node-RED API with domain logic, handles config loading, tick loops, events
Domain logic (src/specificClass.js) - pure business logic, no Node-RED dependencies

Key Shared Library: `nodes/generalFunctions/`

logger - structured logging (use this, NOT console.log)
MeasurementContainer - chainable measurement storage (type/variant/position)
configManager - loads JSON configs from src/configs/
MenuManager - dynamic UI dropdowns
outputUtils - formats messages for InfluxDB and process outputs
childRegistrationUtils - parent-child node relationships
coolprop - thermodynamic property calculations

Conventions

Nodes register under category 'EVOLV' in Node-RED
S88 color scheme: Area=#0f52a5, ProcessCell=#0c99d9, Unit=#50a8d9, Equipment=#86bbdd, ControlModule=#a9daee
Config JSON files in generalFunctions/src/configs/ define defaults, types, enums per node
Tick loop runs at 1000ms intervals for time-based updates
Output ports + 3-tier architecture: see .claude/rules/node-architecture.md
Multi-tab demo flows: see .claude/rules/node-red-flow-layout.md for the tab/link-channel/spacing rule set used by examples/
Output coverage (every output, every state, every layer): see .claude/rules/output-coverage.md — manifest + populated/degraded tests are mandatory for any change that touches Port 0/1/2 keys, function-node fan-outs, telemetry fields, or dashboard widget sources

Sources of truth (the canonical files)

Front-door map: CONTRACTS.md — read first; lists every standard and where it lives
Platform API shapes (BaseDomain, BaseNodeAdapter, commands registry, UnitPolicy, …): .claude/refactor/CONTRACTS.md
Code conventions (file/function size, comments, naming): .claude/refactor/CONVENTIONS.md
Per-node module layout: .claude/refactor/MODULE_SPLIT.md
Per-node API contract: nodes/<n>/CONTRACT.md + nodes/<n>/src/commands/index.js (source of truth for accepted msg.topic values)
Shared library API: nodes/generalFunctions/CONTRACT.md (exported classes + utilities)
Live decisions log: .claude/refactor/OPEN_QUESTIONS.md — append, don't invent

Development Notes

No build step required - pure Node.js
Install: npm install in root
Submodule URLs were rewritten from gitea.centraal.wbd-rd.nl to gitea.wbd-rd.nl for external access
Dependencies: mathjs, generalFunctions (git submodule)

3.3 KiB Raw Blame History