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