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

Clone the repo (you likely already have it if you're editing):

git clone https://gitea.wbd-rd.nl/RnD/pumpingStation.git
cd pumpingStation/wiki/diagrams

Open the .drawio.svg file in draw.io:
- Web: app.diagrams.net → Open Existing Diagram, or drag-and-drop.
- Desktop: drawio-desktop.
Edit — move shapes, change labels, adjust layout.
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).

Commit & push the edited SVG, plus the .drawio file if one exists:

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/:

![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

Open draw.io, start blank.
Draw it.
File → Export as → SVG… with Include a copy of my diagram checked → save as wiki/diagrams/<name>.drawio.svg.
Reference from the wiki page with ![alt](diagrams/<name>.drawio.svg).
Add an entry to the table above.
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.