Every time I asked an AI for an architecture diagram, I got the same thing back.
A code block of Mermaid. I'd paste it into a Mermaid editor and one of two things would happen. Either it wouldn't render at all, or it would render into this:
That's a real response. Same prompt I'll use for everything in this post:
Design a URL shortener: API, cache, database, click analytics.
I asked chatgpt/Gemini for it five times (with "Draw it as a Mermaid diagram." on the end, like you would in any chat) and rendered each answer with the actual Mermaid library. Two out of five didn't even parse. Both times the model wrote {shortCode} inside an edge label, and Mermaid reads { as the start of a diamond shape. The three that did render all looked like the one above. Arrows crossing through each other, labels sitting on top of labels ("Redirect Traf" colliding with "Create Traffic"), a yellow box around everything.
It's not the model's fault, really. It was asked to do two jobs at once: figure out the system, and lay it out on a page. It's decent at the first one. It's bad at the second, and Mermaid gives you no way to fix it after. You can't grab a box and move it. You edit text and hope.
So I kept ending up in the same place. Ask the AI for the system, then open Excalidraw and drag boxes around by hand for an hour. Which is the part I wanted the AI to do in the first place.
What I wanted instead
Three things:
- The AI decides what's in the system. It never decides where anything goes. No coordinates, no colors, no fonts from the model.
- A real layout engine places everything, and a real router draws the arrows around the boxes, not through them.
- The result lands on an actual canvas I can edit. Not a PNG, not a code block. Excalidraw, because I already live in it and the hand-drawn style reads like a whiteboard session instead of a corporate slide.
That's OpenDiagram. Here's the same prompt:
Same model (Gemini 3.8 Flash), same sentence. Groups for the core and the analytics path, real icons for Postgres, Redis and Kafka, arrows that go around things. And every one of those shapes is a normal Excalidraw element, so if I don't like where the cache sits, I drag it.
How it works (the short version)
The model never outputs Mermaid, and it never outputs pixels. It outputs a small typed spec, one entry per component, like this:
{
"label": "URL Cache",
"sublabel": "Redis",
"category": "cache"
}
No x, no y, no color, no font. Then deterministic code takes over:
- ELK (the Eclipse Layout Kernel) places the nodes and groups.
- A custom router draws every edge and places every label against the final boxes, so labels don't pile up on top of each other.
- A themed renderer turns it into Excalidraw elements. There's a Sketch theme (the hand-drawn one above) and a Classic theme if you want something cleaner for a doc:
The LLM decides what. harness decides how it looks. That split is the whole trick, and it's why the output looks the same quality every time instead of depending on the model's mood.
More prompts, straight from my eval runs
These are raw outputs from my eval suite. No hand edits.
Cloud architecture
AWS architecture for a serverless image-processing pipeline: S3 upload, Lambda resize, SQS, DynamoDB metadata, CloudFront delivery.
Real AWS icons, grouped by stage.
Sequence diagrams
Sequence diagram of an OAuth2 authorization code login with GitHub for a web app.
Numbered messages, dashed replies, an opt fragment for the back-channel token exchange, and the happy path in green.
ER diagrams
ERD for an e-commerce store: users, products, orders, order items, payments, reviews.
Typed columns, PK/FK markers, crow's foot notation.
Lazy prompts
diagram for a ride-hailing platform like Uber:
That's the overview. It kept it high level on purpose and drew the ride request flow and the payment flow as their own diagrams on the same canvas btw.
A hard prompt
Then I tried to break it. One paragraph, around 30 components, and no hint about how to split it up:
Global multi-tenant AI commerce: NL product search, recommendations, image upload, AI shopping assistant, carts, orders, payments, shipment tracking, notifications, flash sales, inventory reservation, fraud, seller dashboards, real-time analytics, vector search, RAG over the catalog, LLM inference, image processing, Kafka, Redis, PostgreSQL, Elasticsearch, vector DB, object storage, CDN, WebSockets, workers, multi-region. Strong consistency for money, eventual for the rest. API gateway, authn/authz, rate limiting, observability, circuit breakers, retries, idempotency, DR, cross-region failover. Control plane vs data plane, sync vs async, stores, caches, queues, externals, all major flows.
Cramming that into one picture gets you the Mermaid hairball from the top of this post. So the agent didn't try. It planned four diagrams by itself: an overview, then one diagram each for checkout, search and fulfillment.
It put money on the strongly consistent path (Redis lock, PostgreSQL ledger, idempotent payment handler) and left analytics on the async Kafka side, which is the split the prompt asked for. It doesn't draw everything from the prompt: DR, cross-region failover and circuit breakers aren't on any diagram. Every diagram is still readable, though, and all four are editable on one canvas, so you can ask the agent for the missing ones next.
What else is in there
- It's an agent, not a form. You chat with it. "Add a Redis cache between the gateway and the service" updates the diagram.
- Import a GitHub repo and get an architecture diagram of it.
- Bring your own key for OpenAI, Anthropic, Google or OpenRouter if you'd rather use your own billing.
- Guest mode. No account needed to try it.
- Open source (AGPL-3.0), self-hostable. The whole stack is on GitHub.
Free beta: please break it
It's live at opendiagram.ink, free while it's in beta.
I want the weird prompts. Your company's actual system. The 40-service monster. The "draw my repo" button on a messy monorepo. A sequence diagram with nested fragments. If the layout does something ugly, that's exactly what I want to see.
- Try it: https://opendiagram.ink
- Code and issues: https://github.com/Itz-Agasta/OpenDiagram
Screenshot anything broken and drop it in a GitHub issue or the comments here. I read all of it.
FAQ
Is there an AI diagram generator that doesn't output Mermaid?
Yes, that's the point of OpenDiagram. The AI produces a semantic spec and a layout engine renders it as native Excalidraw elements, so you get an editable diagram instead of Mermaid text.
Is there an open-source alternative to Eraser.io or DiagramGPT?
OpenDiagram is open source (AGPL-3.0) and self-hostable. It generates system architecture, cloud, sequence and ER diagrams from plain English, and the output is regular Excalidraw you own.
Can I edit the diagram after the AI draws it?
Yes. Everything is a normal Excalidraw shape. Move it, restyle it, add notes, or ask the agent to change it in chat.
What kinds of diagrams can it make?
System design and cloud architecture (AWS, GCP, Kubernetes icons), sequence diagrams, ER diagrams, and flowcharts.
Do I need an API key?
No. It works out of the box during the beta. If you want your own billing or model, you can plug in an OpenAI, Anthropic, Google or OpenRouter key.
Top comments (0)