pumpingStation/wiki/diagrams/README.md

# Diagrams

Editable source diagrams for the pumpingStation wiki. Each diagram is a **`.drawio` + `.drawio.svg` pair**, so anyone can edit the source in [draw.io](https://app.diagrams.net/) without touching any Markdown.

## Why two files?

| File | Role |
|---|---|
| `<name>.drawio` | Native draw.io XML. The canonical source. |
| `<name>.drawio.svg` | SVG export of the same diagram (with source embedded). What the wiki actually renders, and what round-trips back into draw.io. |

Checking both in means the wiki renders for everyone, and the next editor picks up from exactly where the last one left off.

## Editing workflow

1. **Clone** the repo (you likely already have it if you're editing):
   ```bash
   git clone https://gitea.wbd-rd.nl/RnD/pumpingStation.git
   cd pumpingStation/wiki/diagrams
   ```
2. **Open** the `.drawio` file in draw.io:
   - Web: [app.diagrams.net](https://app.diagrams.net/) → *Open Existing Diagram*, or drag-and-drop.
   - Desktop: [drawio-desktop](https://github.com/jgraph/drawio-desktop/releases).
3. **Edit** — move shapes, change labels, adjust layout.
4. **Export** to SVG with the source embedded:
   - `File → Export as → SVG…`
   - Check **Include a copy of my diagram** ← this is what lets future edits round-trip through the SVG.
   - Save next to the source as `<name>.drawio.svg` (overwrite).
5. **Commit & push** both files:
   ```bash
   git add wiki/diagrams/<name>.drawio wiki/diagrams/<name>.drawio.svg
   git commit -m "Update <name>: <what changed>"
   git push
   ```

## Referencing a diagram from a wiki page

In any Markdown page under `wiki/`:

```markdown
![Basin model](diagrams/basin-model.drawio.svg)
```

Use a descriptive `alt` text; it's the fallback if the SVG fails and it shows up in exports.

## Naming

- kebab-case, one concept per diagram.
- Current diagrams:

| Diagram | Shows |
|---|---|
| `basin-model` | Physical basin cross-section — walls, pipes at their real heights, control thresholds cutting across, zone labels |
| `control-zones` | Vertical level axis ("thermometer") for `levelbased` mode — STOP / DEAD ZONE / RUN with demand ramp |
| `safety-rules` | Dry-run vs overfill rule asymmetry — which children stop, which keep running |

## Making a brand-new diagram

1. Open draw.io, start blank.
2. Draw it.
3. `File → Save As…` → `wiki/diagrams/<name>.drawio`.
4. `File → Export as → SVG…` with **Include a copy of my diagram** checked → save as `wiki/diagrams/<name>.drawio.svg`.
5. Reference from the wiki page with `![alt](diagrams/<name>.drawio.svg)`.
6. Add an entry to the table above.
7. Commit all three files together (`.drawio`, `.drawio.svg`, updated `.md`).

## These starters are rough

The `.drawio` files and their matching `.drawio.svg` exports committed here are **placeholders** — layout is approximate, colors and fonts are defaults, no fine alignment. They're meant to be a starting point; open them in draw.io and refine.

Both formats are round-trippable: open either the `.drawio` or the `.drawio.svg` in draw.io and it will load the editable model. (The SVG has the drawio XML embedded in a `content="…"` attribute on the root `<svg>` element — that's what lets draw.io re-open its own SVG exports.)