Diagrams die for a boring reason: they only have one form, and it is the wrong one for at least half of what you need. A drawing is great for a reader and useless in a pull request. A block of diagram code reviews beautifully and communicates nothing to a stakeholder. So teams pick one, and the other need goes unmet until the diagram falls behind and everyone stops trusting it.
The fix is not to choose. It is to keep both forms and move between them freely. Code becomes a diagram when you want to see it; a diagram becomes code when you want to review or store it. AI smooths the trip in both directions, and the round trip is what makes the diagram durable.
Direction one: code to a diagram
You already have text that describes structure, whether it is Mermaid, D2, or an artifact like a Compose file or SQL schema. Bring it in and it becomes real, editable shapes, laid out for you. Now you can do the things text cannot: highlight the risky path, group a bounded context, drop a note where the tricky bit lives.
graph LR
client --> api
api --> cache
api --> db
worker --> queue
Paste that and it is not a rendered picture; it is a set of boxes and arrows you can pick up and move. The code got you the structure for free. Your edits add the meaning.
Direction two: a diagram back to code
Now reverse it. You have shaped a diagram on the canvas and you want it in the repository, next to the code it describes, where it can be reviewed and versioned. Export it back to Mermaid or D2 and commit the text. The next time someone opens a pull request that changes the system, the diagram's code changes in the same review, under the same eyes.
Where AI helps the round trip
Both directions get easier with a model in the loop, but not in the way the hype suggests. AI is not there to replace the code or the drawing. It is there to bridge the messy gaps:
- Loose input to clean code. Describe a flow in a sentence and get a first pass of diagram code you can render and refine.
- Messy diagram to tidy code. Ask for the exported text to be simplified or relabelled so the committed version reads well.
- Drift to a fresh draft. When the system has moved on, regenerate from the current source and reconcile, instead of hand-patching an old picture.
Two forms of one truth. The code keeps it reviewable; the picture keeps it read.
Why this beats picking a side
The single-form diagram forces a bad trade. Diagram-as-code alone gives you reviewability and a picture nobody enjoys reading. A drawing alone gives you a friendly picture that silently drifts from the code. Keeping both, with an easy round trip, gives you the reviewability of text and the clarity of a visual from the same source. Neither one is the second-class citizen.
The habit worth building
Treat the two forms as one artifact with two views. Draft in whichever is faster for the moment, sketch visually or type the structure, then round-trip to get the other form for free. Do that consistently and the eternal problem of the stale diagram mostly goes away, because there is always a cheap path back to correct.
Paste some diagram code and shape it, or draw something and export the code. Once you have felt the round trip, keeping a diagram current stops being a chore you skip.