Architecture Diagramming Standard

Priority: P1 (HIGH)

Pipeline

Never hand-write mxGraph XML. Write a spec; the scripts own every visual decision, so diagrams stay identical across authors, repositories, and sessions.

1. Write spec.json — schema in diagram-spec.md. For an ERD, generate it: python3 scripts/schema_to_spec.py db/schema.sql --title "<System> — ERD" -o spec.json
2. python3 scripts/validate_spec.py spec.json
3. python3 scripts/render_drawio.py spec.json -o docs/architecture/<slug>.drawio --strict (exit 2 = a layout finding; change the spec, per layout-rules.md)
4. For related views, optionally validate view-manifest.md: python3 scripts/validate_manifest.py view-manifest.json
5. Export the image: a draw.io MCP tool if the session has one, else python3 scripts/export_drawio.py docs/architecture/<slug>.drawio -f png -o docs/architecture/<slug>.png, else ship the .drawio and say the image was not exported. See export paths.
6. Inspect the exported image at normal reading size; strict validation cannot prove labels and edges are legible. Fix the spec and re-export before handoff.