wrps-demo-kit/01-design/README.md

# 01-design — the design authority

Everything downstream is built against these documents and checked back to them.
The PLC code implements them; the register map is derived from them; the HMI
displays what they define.

## The documents

| Document | What it is | Status |
|---|---|---|
| `00-origin/scada-ai-usecase-pump-scheduling.md` | **The seed.** One page of narrative describing the demo idea. Everything else grew from this. | Origin |
| `WRPS-PRO-001_Process_Basis_of_Design.pdf` | The process: flows, volumes, pump curves, the wet well. Fixes the numbers the demo narrative rests on. | Current |
| `WRPS-DRG-001_PID.pdf` | The P&ID — equipment, instruments, tag numbers. | Current |
| `WRPS-INS-001_Instrument_Index_and_Equipment_List.xlsx` | Every instrument and item of plant, with ranges and units. | Current |
| `WRPS-CTL-001_Control_Philosophy.pdf` | How the station is meant to be operated, and why. | Current |
| `WRPS-CTL-002_Functional_Design_Specification.pdf` | The FDS. **Governs** — where any other document disagrees with it, this one wins. | Current |
| `WRPS-CTL-003_OpenPLC_Implementation_Brief.md` | The bridge from design to code: register map, function blocks, control sequence, simulation model, acceptance tests. | Current, **with amendments** — see below |

Read them in that order. The origin file takes two minutes and makes the rest
make sense.

## ⚠️ CTL-003 carries an amendment block

`WRPS-CTL-003` was written before the deployment route was settled, and its §1
and §9 describe a build system (flat `.st` + MatIEC + a runtime web upload) that
**does not exist on OpenPLC Runtime v4**. The document is kept as issued, with a
dated **Amendments** section at the top listing nine corrections.

Its **§2 Modbus address map was verified line by line against the generated
`03-plc/register-map.csv` and is correct in full**, as are §3–§8. Only the build
system is wrong. See `03-plc/README.md` for how the program is really built.

One amendment is not a documentation defect but real outstanding work: **none of
the 20 acceptance tests in §7 and §8.4 have been run.** The control behaviour is
unverified.

---

## 📌 How these documents were made — and how to do it again

This matters more than the documents themselves, because it is the part you can
reuse for the **next** demo.

**There was no real project.** There is no Waterloo Road Pump Station. The
document set was generated with AI from the single page in `00-origin/`,
deliberately following the shape of a real project lifecycle:

```
  an idea                 00-origin/scada-ai-usecase-pump-scheduling.md
     │                    one page of narrative — the demo you want to give
     ▼
  basic design            WRPS-PRO-001  Process Basis of Design
     │                    WRPS-DRG-001  P&ID
     │                    WRPS-INS-001  Instrument Index
     ▼
  detailed design         WRPS-CTL-001  Control Philosophy
     │                    WRPS-CTL-002  Functional Design Specification
     ▼
  implementation brief    WRPS-CTL-003  addresses, function blocks, tests
     │
     ▼
  code                    03-plc/ ── 04-scada/ ── 05-tests/
```

### Why bother with the paperwork for a demo

It would be quicker to write the PLC code straight from the idea. Three reasons
not to:

1. **The demo has to survive questions.** An automation audience asks "why three
   pumps", "what's the firm capacity", "why does it start at 4.0 m". Answers that
   trace to a Basis of Design land; invented answers do not.
2. **The numbers have to agree with each other.** Wet-well volume, pump curves,
   start levels and the time-to-spill figure on the HMI are all the same handful
   of numbers. Writing them down once, up front, is what stops the screen and the
   story contradicting each other on stage.
3. **It is the artefact set a customer recognises.** Showing a P&ID and an FDS
   alongside the running system is itself part of the pitch.

### Doing it for your own demo

1. **Write the one-pager first.** Narrative, not specification: who is watching,
   what question gets asked, what makes them lean forward. `00-origin/` is the
   model — note how much of it is about the *audience*, not the plant.
2. **Generate the basic design from it,** and read it properly. This is where you
   fix the physical numbers. Everything downstream inherits them, and an error
   here is expensive later.
3. **Generate the detailed design from the basic design,** not from the idea.
   Each layer should cite the one above it. That is what keeps the set coherent.
4. **Write the implementation brief last,** and make it explicit — addresses,
   enumerations, acceptance tests. It is the contract the code is written to and
   the thing you check the built system against.
5. **State which document governs.** Here it is the FDS (CTL-002). Without that
   rule, two AI-generated documents will eventually disagree and nobody will know
   which to believe.

### What this project got wrong, so you needn't

- **CTL-003 was written before the deployment route was proven.** It specified a
  build system that turned out not to exist, and that error is now permanent in
  the record. **Prove the deployment path with a trivial program before writing
  the implementation brief.**
- **Acceptance tests were specified and never run.** A test list in a document is
  not verification. Budget the time to actually run them, or do not claim them in
  the definition of done.
- **A superseded document reused a live document number** (an earlier build brief
  was also numbered CTL-002, colliding with the FDS). Number superseded documents
  out of the live series, or give them a suffix.

> **Everything in this folder is AI-generated fiction built on a real process
> engineering pattern.** It is realistic enough to demo and to build against. It
> is not a real site, and no number in it should be quoted to a customer as a
> reference project.