I spend more time than I want to admit redrawing architecture diagrams every time a service moves. This quarter I tried to stop doing that by hand and let AI generate the visuals from plain text instead. Here are the field notes, what worked, what did not, and where each tool fits.
The problem with hand-drawn diagrams
A diagram in a README has a half-life of about two sprints. The moment you rename a queue or split a service, the picture lies. So you either keep redrawing it in some canvas tool, or you let it rot. Both options are bad.
Text-to-diagram tools change the economics. If the source of truth is text, regenerating the picture costs seconds, and the text lives next to your code where it belongs.
What I actually tested
Mermaid plus an LLM. Still my default for anything that ships in a repo. I describe the flow to an LLM, ask for Mermaid syntax, paste it into the markdown. GitHub renders it natively. The win is that the diagram is diffable and reviewable in a pull request. The limit is layout: Mermaid decides where boxes go, and for anything past ten nodes it gets messy.
Napkin AI. This one surprised me. You paste a paragraph of prose and it proposes several visual treatments: a flow, a comparison, a timeline. For a design doc where I want a conceptual picture rather than an exact schema, it is faster than anything else I tried. It is not the tool for precise data, but for explaining an idea to a non-technical stakeholder it is excellent.
Slide tools that generate whole decks. When I had to present the rework to the wider team, I did not want to build forty slides. A few AI presentation tools take an outline and return a full deck with structure and visuals, which you then trim. I went down a rabbit hole comparing them and ended up writing it all up. If you want the long version, I put a full comparison of seven of these tools here: the AI presentation tools I tested. It is in Dutch, but the tool-by-tool breakdown and the pricing table travel fine through a translator.
A workflow that stuck
After a month, this is what I kept doing:
- Keep the canonical architecture in Mermaid, inside the repo, reviewed in PRs.
- Use Napkin for conceptual visuals in design docs and RFCs.
- Generate the first draft of any presentation from an outline, then cut half the text by hand.
The common thread is that AI produces the first version and I own the edit. The moment I let a tool publish unedited output, quality dropped and it showed.
The research angle
One unexpected side effect: once the diagrams were cheap to produce, I started writing more design docs, which meant more reading of prior art. For digging through papers and prior implementations I leaned on AI research tools that cite their sources rather than a general chatbot that makes things up. That is a separate write-up, but the short version is that source-grounded tools beat raw LLMs for anything you will have to defend later.
Takeaways
- If a diagram is the source of truth, keep it as text in the repo.
- Use prose-to-visual tools for ideas, not for precise schemas.
- Always edit AI output before it ships. The first draft is a starting point, not a deliverable.
What are you using to keep diagrams from rotting? I am still looking for a better answer on the large-graph layout problem.
