pumpingStation/wiki/diagrams/README.md

# Diagrams

Editable source diagrams for the pumpingStation wiki. The current diagrams are **`.drawio.svg` files with the draw.io source embedded**, so anyone can edit the SVG directly in [draw.io](https://app.diagrams.net/) without touching any Markdown.

## File roles

| File | Role |
|---|---|
| `<name>.drawio` | Optional native draw.io XML source, if a diagram also keeps a standalone source file. |
| `<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. |

An optional standalone `.drawio` file can be committed beside the SVG, but the embedded-source SVG is enough for the wiki to render and for the next editor to pick 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.svg` 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** the edited SVG, plus the `.drawio` file if one exists:
   ```bash
   git add 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` | Shared physical basin cross-section — walls, pipe reference heights, derived safety zones, storage/dead volumes |
| `modes/basin-mode-level-linear` | Level-linear control mode — `startLevel`, demand ramp, threshold-shift behaviour |
| `control-zones` | Legacy 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 → Export as → SVG…` with **Include a copy of my diagram** checked → save as `wiki/diagrams/<name>.drawio.svg`.
4. Reference from the wiki page with `![alt](diagrams/<name>.drawio.svg)`.
5. Add an entry to the table above.
6. Commit the new `.drawio.svg` and updated `.md` together.

## These starters are rough

Some diagrams are still rough — layout is approximate, colors and fonts may be defaults, and alignment may need refinement. They're meant to be improved in draw.io as the model settles.

Open the `.drawio.svg` in draw.io and it will load the editable model. The SVG has the draw.io XML embedded in a `content="…"` attribute on the root `<svg>` element — that's what lets draw.io re-open its own SVG exports.