How Clearwell works
Clearwell watches a water system and helps a human decide what to do. Every box below is a real part of the running software, and the number in it is live. Nothing here is real: the utility is fictional.
One rule shapes everything: cheap checks first, Claude only when needed, and no equipment moves without a person saying yes.
- Simulator0 readingsA hydraulic model of the water network (WNTR) pretends to be the real plant. It produces pressure, flow, tank level and water-quality readings from about 40 sensors, the way a real control system would.
- Redis Streams0 events seen hereA stream is a shared event log: new events are added to the end and never rewritten. Every part of Clearwell reads from it and writes to it. That gives three things: parts that do not need to know each other, a replay of any past moment, and an audit trail.
- Detectors0 detectionsSeveral independent watchers look at the same readings. Each raises a detection when something looks wrong.
- RulesFixed limits taken from regulations and research, such as pressure under 20 psi. No guessing.
- EWMAA smoothed trend. It notices a reading drifting away from its normal.
- CUSUMAdds up small, steady shifts. Many tiny nudges the same way become a signal.
- CanarySeveral sensors disagreeing with their neighbours at once.
- Consensus0 incidentsData aggregation. Two different kinds of watcher must agree before an incident opens. One noisy sensor cannot raise an alarm alone, which cuts false alarms.
- Escalation ladderEach incident climbs only as far as it needs to, because every rung up costs more.
- Rules onlyClear-cut cases go straight to a standard response. Cost: nothing.
- Haiku triageA small, cheap model asks: is this settled, or does it need a deeper read?
- Sonnet assessmentA stronger model reads the readings and writes the likely cause and next steps.
- Opus for Tier 1The strongest model, only when a public notice within 24 hours may be needed.
- Human approval0 approved of 0 askedEvery recommended action waits for a named person to approve or reject it. No actuator change happens without a recorded approval.
- Actuator0 actions appliedThe step that changes the simulated plant, such as closing valves. It refuses to run without an approval event.
- Audit log0 records hereEach record includes the fingerprint (hash) of the one before it. Edit any past record and every fingerprint after it breaks, so tampering shows.
- Bridge0 messagesTurns approved notices into messages people can read.
- ntfy alertsPush alerts to operators' phones. Sent so far: 0.
- X posts (dry run)Public notices are written but not actually posted. Prepared: 0.
SIMULATION: Riverbend Water Authority is fictional. No real system is monitored or controlled.