Diagram as code solves the file-format problem, not the maintenance problem. A text diagram can still become stale, misleading, or impossible to review. The workflow needs to define why the diagram exists, who owns it, and which engineering changes require an update.
Give each diagram one decision to support
Write a short purpose statement near the source. “Shows trust boundaries for the public API” is testable. “System architecture” is too broad and invites every component into one canvas.
Choose a diagram type that matches the question. Use a flowchart for decisions, a sequence diagram for interaction order, an ER diagram for data relationships, and a Gantt chart for a lightweight schedule. Do not force every view into the same notation just to reduce file count.
Store source next to the relevant documentation
If a diagram explains an API, keep it near the API documentation rather than in a remote design folder. Relative proximity makes ownership and review more likely. Name the source predictably and export a rendered artifact only when the publishing platform cannot render Mermaid directly.
When committing both source and exported SVG, identify which file is authoritative. Generated output should not be hand-edited.
Define update triggers
A useful pull request checklist names concrete triggers:
- A service is added, removed, or changes ownership.
- A trust boundary or data destination changes.
- An API call becomes asynchronous or gains a failure branch.
- A database relationship changes optionality or cardinality.
- A documented delivery milestone changes.
These triggers are better than asking every pull request author to “update docs if needed.”
Review meaning before appearance
Reviewers should first verify that nodes, relationships, order, and labels match the implementation. Layout and color come later. A polished diagram with the wrong cardinality is harmful because readers tend to trust visual structure.
Keep changes small enough to review in a text diff. Stable node IDs and one statement per line reduce unrelated churn. If a formatting change rewrites the full file, separate it from the semantic change.
Validate the publishing runtime
Mermaid versions and security policies differ across GitHub, documentation generators, and embedded editors. Test new syntax in the final renderer or state the required version. Avoid interactive links or raw HTML when the diagram must work under a strict security policy.
Use the Mermaid editor for local iteration and export, but treat the checked-in source and its project review process as the durable workflow.