docs: add CLAUDE.md with S88 classification and superproject rule reference

References the flow-layout rule set in the EVOLV superproject
(.claude/rules/node-red-flow-layout.md) so Claude Code sessions working
in this repo know the S88 level, colour, and placement lane for this node.

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

CLAUDE.md

@@ -0,0 +1,23 @@
+# settler — Claude Code context
+
+Secondary clarifier / sludge settling.
+Part of the [EVOLV](https://gitea.wbd-rd.nl/RnD/EVOLV) wastewater-automation platform.
+
+## S88 classification
+
+| Level | Colour | Placement lane |
+|---|---|---|
+| **Unit** | `#50a8d9` | L4 |
+
+## Flow layout rules
+
+When wiring this node into a multi-node demo or production flow, follow the
+placement rule set in the **EVOLV superproject**:
+
+> `.claude/rules/node-red-flow-layout.md` (in the EVOLV repo root)
+
+Key points for this node:
+- Place on lane **L4** (x-position per the lane table in the rule).
+- Stack same-level siblings vertically.
+- Parent/children sit on adjacent lanes (children one lane left, parent one lane right).
+- Wrap in a Node-RED group box coloured `#50a8d9` (Unit).

settler.html

@@ -6,6 +6,8 @@
     color: "#e4a363",
     defaults: {
       name: { value: "" },
+      processOutputFormat: { value: "process" },
+      dbaseOutputFormat: { value: "influxdb" },
 
       enableLog: { value: false },
       logLevel: { value: "error" },
@@ -55,6 +57,24 @@
     <input type="text" id="node-input-name" placeholder="Name">
   </div>
 
+  <h3>Output Formats</h3>
+  <div class="form-row">
+    <label for="node-input-processOutputFormat"><i class="fa fa-random"></i> Process Output</label>
+    <select id="node-input-processOutputFormat" style="width:60%;">
+      <option value="process">process</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-dbaseOutputFormat"><i class="fa fa-database"></i> Database Output</label>
+    <select id="node-input-dbaseOutputFormat" style="width:60%;">
+      <option value="influxdb">influxdb</option>
+      <option value="json">json</option>
+      <option value="csv">csv</option>
+    </select>
+  </div>
+
   <!-- Logger fields injected here -->
   <div id="logger-fields-placeholder"></div>
 

src/nodeClass.js

@@ -1,4 +1,5 @@
 const { Settler } = require('./specificClass.js');
+const { configManager } = require('generalFunctions');
 
 
 class nodeClass {
@@ -60,21 +61,8 @@ class nodeClass {
    * @param {object} uiConfig Config set in UI in node-red
    */
   _loadConfig(uiConfig) {
-    this.config = {
+    const cfgMgr = new configManager();
-      general: {
+    this.config = cfgMgr.buildConfig('settler', uiConfig, this.node.id);
-        name: uiConfig.name || this.name,
-        id: this.node.id,
-        unit: null,
-        logging: {
-          enabled: uiConfig.enableLog,
-          logLevel: uiConfig.logLevel
-        }
-      },
-      functionality: {
-        positionVsParent: uiConfig.positionVsParent || 'atEquipment', // Default to 'atEquipment' if not specified
-        softwareType: "settler" // should be set in config manager
-      }
-    }
   }
 
   /**

src/specificClass.js

@@ -1,4 +1,4 @@
-const { childRegistrationUtils, logger, MeasurementContainer } = require('generalFunctions');
+const { childRegistrationUtils, logger, MeasurementContainer, POSITIONS } = require('generalFunctions');
 const EventEmitter = require('events');
 
 // Compatibility-safe array clone for Node runtimes without global structuredClone.
@@ -38,7 +38,7 @@ class Settler {
 
     let F_sr = 0;
     if (this.returnPump) {
-      F_sr = Math.min(this.returnPump.measurements.type("flow").variant("measured").position("atEquipment").getCurrentValue(), F_s);
+      F_sr = Math.min(this.returnPump.measurements.type("flow").variant("measured").position(POSITIONS.AT_EQUIPMENT).getCurrentValue(), F_s);
     }
     const F_so = F_s - F_sr;
 
@@ -117,13 +117,13 @@ class Settler {
   }
 
   _connectReactor(reactorChild) {
-    if (reactorChild.config.functionality.positionVsParent != "upstream") {
+    if (reactorChild.config.functionality.positionVsParent != POSITIONS.UPSTREAM) {
       this.logger.warn("Reactor children of settlers should be upstream.");
     }
 
     this.upstreamReactor = reactorChild;
 
-    reactorChild.emitter.on("stateChange", (eventData) => {
+    reactorChild.emitter.on("stateChange", (_eventData) => {
       this.logger.debug(`State change of upstream reactor detected.`);
       const raw = this.upstreamReactor.getEffluent;
       const effluent = Array.isArray(raw) ? raw[0] : raw;
@@ -133,7 +133,7 @@ class Settler {
   }
 
   _connectMachine(machineChild) {
-    if (machineChild.config.functionality.positionVsParent == "downstream") {
+    if (machineChild.config.functionality.positionVsParent == POSITIONS.DOWNSTREAM) {
       machineChild.upstreamSource = this;
       this.returnPump = machineChild;
       return;
@@ -141,7 +141,7 @@ class Settler {
     this.logger.warn(`Failed to register machine child.`);
   }
 
-  _updateMeasurement(measurementType, value, position, context) {
+  _updateMeasurement(measurementType, value, _position, _context) {
     switch(measurementType) {
       case "quantity (tss)":
         this.C_TS = value;

test/specificClass.test.js

@@ -0,0 +1,263 @@
+/**
+ * Tests for settler specificClass (domain logic).
+ *
+ * The Settler class is a simple mass-balance separator:
+ *  - Splits influent into effluent (clarified), surplus sludge, and return sludge
+ *  - Concentrates particulate species (indices 7-12) into sludge stream
+ *  - Removes particulates from effluent stream
+ *  - registerChild: connects measurements, upstream reactors, machines
+ */
+
+const { Settler } = require('../src/specificClass');
+
+// --------------- helpers ---------------
+
+const NUM_SPECIES = 13;
+
+function makeConfig(overrides = {}) {
+  return {
+    general: {
+      name: 'TestSettler',
+      id: 'settler-test-1',
+      logging: { enabled: false, logLevel: 'error' },
+    },
+    functionality: {
+      softwareType: 'settler',
+      role: 'separator',
+      positionVsParent: 'downstream',
+    },
+    ...overrides,
+  };
+}
+
+// --------------- tests ---------------
+
+describe('Settler specificClass', () => {
+
+  describe('constructor / initialization', () => {
+    it('should create an instance with default values', () => {
+      const s = new Settler(makeConfig());
+      expect(s).toBeDefined();
+      expect(s.F_in).toBe(0);
+      expect(s.Cs_in).toEqual(new Array(NUM_SPECIES).fill(0));
+      expect(s.C_TS).toBe(2500);
+    });
+
+    it('should have null upstreamReactor and returnPump initially', () => {
+      const s = new Settler(makeConfig());
+      expect(s.upstreamReactor).toBeNull();
+      expect(s.returnPump).toBeNull();
+    });
+
+    it('should initialize an EventEmitter', () => {
+      const s = new Settler(makeConfig());
+      expect(s.emitter).toBeDefined();
+      expect(typeof s.emitter.on).toBe('function');
+    });
+
+    it('should initialize a MeasurementContainer', () => {
+      const s = new Settler(makeConfig());
+      expect(s.measurements).toBeDefined();
+    });
+  });
+
+  describe('getEffluent', () => {
+
+    describe('with zero inflow', () => {
+      it('should return three streams with zero flows', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 0;
+        s.Cs_in = new Array(NUM_SPECIES).fill(0);
+        const result = s.getEffluent;
+        expect(result).toHaveLength(3);
+        expect(result[0].payload.F).toBe(0); // effluent
+        expect(result[1].payload.F).toBe(0); // surplus sludge
+        expect(result[2].payload.F).toBe(0); // return sludge
+      });
+    });
+
+    describe('with normal inflow and particulates', () => {
+      let s;
+      let result;
+
+      beforeAll(() => {
+        s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 5000;
+        // Set concentrations: solubles at indices 0-6, particulates at 7-12
+        const C = new Array(NUM_SPECIES).fill(10);
+        C[12] = 5000; // X_TS
+        s.Cs_in = C;
+        result = s.getEffluent;
+      });
+
+      it('should return 3 output streams', () => {
+        expect(result).toHaveLength(3);
+      });
+
+      it('should have effluent topic "Fluent"', () => {
+        expect(result[0].topic).toBe('Fluent');
+      });
+
+      it('should calculate sludge flow F_s = min(F_in * X_TS_in / C_TS, F_in)', () => {
+        // F_s = min(100 * 5000 / 5000, 100) = min(100, 100) = 100
+        const F_eff = result[0].payload.F;
+        const F_so = result[1].payload.F;
+        const F_sr = result[2].payload.F;
+        // Total out should equal F_in (mass balance)
+        expect(F_eff + F_so + F_sr).toBeCloseTo(100, 5);
+      });
+
+      it('should set effluent particulate indices to zero when F_s > 0', () => {
+        const Cs_eff = result[0].payload.C;
+        for (let i = 7; i <= 12; i++) {
+          expect(Cs_eff[i]).toBe(0);
+        }
+      });
+
+      it('should keep effluent soluble indices unchanged', () => {
+        const Cs_eff = result[0].payload.C;
+        for (let i = 0; i < 7; i++) {
+          expect(Cs_eff[i]).toBe(10);
+        }
+      });
+
+      it('should concentrate particulates in sludge stream', () => {
+        const Cs_s = result[1].payload.C;
+        const F_s = Math.min((s.F_in * s.Cs_in[12]) / s.C_TS, s.F_in);
+        // Cs_s[i] = F_in * Cs_in[i] / F_s for particulate indices
+        for (let i = 7; i <= 12; i++) {
+          const expected = s.F_in * s.Cs_in[i] / F_s;
+          expect(Cs_s[i]).toBeCloseTo(expected, 5);
+        }
+      });
+    });
+
+    describe('with low X_TS and high C_TS (dilute sludge)', () => {
+      it('should produce mostly effluent flow', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 10000; // high target concentration
+        const C = new Array(NUM_SPECIES).fill(10);
+        C[12] = 100; // low X_TS in
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        // F_s = min(100 * 100 / 10000, 100) = min(1, 100) = 1
+        expect(result[0].payload.F).toBeCloseTo(99, 5); // most flow is effluent
+      });
+    });
+
+    describe('mass balance', () => {
+      it('should conserve total flow (F_eff + F_so + F_sr = F_in)', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 200;
+        s.C_TS = 3000;
+        const C = new Array(NUM_SPECIES).fill(5);
+        C[12] = 2000;
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        const totalOut = result[0].payload.F + result[1].payload.F + result[2].payload.F;
+        expect(totalOut).toBeCloseTo(200, 5);
+      });
+
+      it('should not produce negative flows', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 50;
+        s.C_TS = 1000;
+        const C = new Array(NUM_SPECIES).fill(0);
+        C[12] = 500;
+        s.Cs_in = C;
+        const result = s.getEffluent;
+        result.forEach(stream => {
+          expect(stream.payload.F).toBeGreaterThanOrEqual(0);
+        });
+      });
+    });
+
+    describe('no return pump', () => {
+      it('should have F_sr = 0 when there is no return pump', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 5000;
+        s.Cs_in = new Array(NUM_SPECIES).fill(10);
+        s.Cs_in[12] = 3000;
+        const result = s.getEffluent;
+        expect(result[2].payload.F).toBe(0);
+      });
+    });
+
+    describe('edge case: X_TS > C_TS (F_s clamped to F_in)', () => {
+      it('should clamp F_s to F_in when X_TS/C_TS ratio exceeds 1', () => {
+        const s = new Settler(makeConfig());
+        s.F_in = 100;
+        s.C_TS = 1000;
+        s.Cs_in = new Array(NUM_SPECIES).fill(10);
+        s.Cs_in[12] = 5000; // X_TS_in > C_TS => F_s = min(500, 100) = 100
+        const result = s.getEffluent;
+        expect(result[0].payload.F).toBe(0); // all flow goes to sludge
+      });
+    });
+  });
+
+  describe('registerChild()', () => {
+    it('should not throw for null child', () => {
+      const s = new Settler(makeConfig());
+      // null child should trigger the error log but not crash
+      expect(() => s.registerChild(null, 'measurement')).not.toThrow();
+    });
+
+    it('should not throw for unknown software type with valid child', () => {
+      const s = new Settler(makeConfig());
+      const fakeChild = {
+        config: {
+          general: { name: 'fake', id: 'fake-1' },
+          functionality: { positionVsParent: 'upstream' },
+          asset: { type: 'pressure' },
+        },
+        measurements: { emitter: { on: jest.fn() } },
+      };
+      expect(() => s.registerChild(fakeChild, 'unknownType')).not.toThrow();
+    });
+  });
+
+  describe('_connectMachine()', () => {
+    it('should set returnPump for downstream machine', () => {
+      const s = new Settler(makeConfig());
+      const fakeMachine = {
+        config: {
+          general: { name: 'pump', id: 'pump-1' },
+          functionality: { positionVsParent: 'downstream' },
+        },
+      };
+      s._connectMachine(fakeMachine);
+      expect(s.returnPump).toBe(fakeMachine);
+      expect(fakeMachine.upstreamSource).toBe(s);
+    });
+
+    it('should not set returnPump for non-downstream machine', () => {
+      const s = new Settler(makeConfig());
+      const fakeMachine = {
+        config: {
+          general: { name: 'pump', id: 'pump-2' },
+          functionality: { positionVsParent: 'upstream' },
+        },
+      };
+      s._connectMachine(fakeMachine);
+      expect(s.returnPump).toBeNull();
+    });
+  });
+
+  describe('_updateMeasurement()', () => {
+    it('should update C_TS when measurement type is "quantity (tss)"', () => {
+      const s = new Settler(makeConfig());
+      s._updateMeasurement('quantity (tss)', 7000, 'atEquipment', {});
+      expect(s.C_TS).toBe(7000);
+    });
+
+    it('should not change C_TS for unrecognized measurement type', () => {
+      const s = new Settler(makeConfig());
+      s._updateMeasurement('temperature', 25, 'atEquipment', {});
+      expect(s.C_TS).toBe(2500); // unchanged
+    });
+  });
+});