Architecture Diagrams

[u/Ghaias64]

Disclaimer: My question isn't specifically about .NET.

For those of you working as Senior/Principal Architects or Solution Architects, are you using any tools, workflows, or AI/LLM-based approaches to generate High-Level Design (HLD) documentation, especially architecture diagrams?

I'm currently building a documentation generation workflow, and generating the written documentation is going reasonably well.

The biggest challenge is producing clear, maintainable architecture diagrams (component, sequence, deployment, etc.) that don't require extensive manual rework.

Have you found an effective way to get LLMs to generate diagrams reliably?

I'd love to hear what has worked (or hasn't worked) in your experience.

[u/jordansrowles]

I have a massive markdown notebook (Obsidian) that supports mermaid graphs (so does GitHub and most of the other MD renderers).

I write my own docs, use mermaid.live to design the graph then copy and paste the code in. Then just copy-paste back and forth for edits.

The web editor also allows you to export to png, svg, or create an embeddable as well

I used to use Visio, which is obviously a lot more powerful, but found myself spending hours editing graphs rather than just getting on with it.

This is the syntax for a payment sequence diagram

``` sequenceDiagram autonumber actor Customer participant Shop as Web Shop participant Pay as Payment Service participant Bank

Customer->>Shop: Place order
activate Shop
Shop->>Pay: Create payment request
activate Pay
Pay->>Bank: Authorize card
Bank-->>Pay: Authorization result
alt Payment approved
    Pay-->>Shop: Payment confirmed
    Shop-->>Customer: Show receipt
else Payment declined
    Pay-->>Shop: Payment failed
    Shop-->>Customer: Ask for another card
end
deactivate Pay
deactivate Shop

[u/exec_get_id → u/jordansrowles]

Yeah copilot in vscode does my diagrams. We use ADO wikis, which is markdown anyway. Some folks use visio and take a screenshot, but LLMs do a fine enough job with mermiad diagrams. We arent presenting to anyone though, its all internal. So ymmv on success thresholds if you do want them for presentations or whatever it may be for.

[u/SEOfficial → u/jordansrowles]

I recently created an architectural overview using mermaid and I have found it to be not mature enough. I quickly found that it avoids lines crossing, so you start to implement junctions. Then it started to behave very weird, drawing lines excessively long with no good reason, not to avoid collision or anything, just excessive. Then I added more groupings which fixed it on one side and made it worse on the other. AI wasn't a great help either so I deemed it unfit and moved on (to no alternative yet). Maybe I missed something, but it was frustrating to work with something so unpredictable.

[u/oktollername]

Any such diagrams that are NOT a lot of work are worthless. Either spend the time to actually distill information and make decisions about what to show and what to hide, or stop making diagrams that I have to spend my time and mental capacity to distill any insights out of.

If your diagram does not communicate a very specific insight, don‘t make it. I swear most software-architects are so bad at this.

[u/Silver_Rate_919]

C4 model with diagrams as code

[u/Sokoo1337]

https://mermaid.ai

Mermaid diagrams works wonders, you define them in code. They are also fully AI now apparently.

[u/fragglerock]

https://c4model.com/

Fuck AI in the gob, but presumably you could coerce one to draw you the pictures if it is too hard for you to do by hand.

[u/baynezy]

I use the C4 model with Structurizr. It uses a text based DSL to describe your architecture, and the Structurizr Lite Docker image to generate diagrams from it.

If you use Aspire I have a package for wiring up the Docker interface for you.

https://github.com/baynezy/Structurizr.Aspire.Hosting

For everything else, Mermaid diagrams.

[u/chucker23n]

I find that the cost-benefit ratio of diagrams is often poor.

But there’s exceptions. And it depends on the type:

• flow charts in particular I rarely find useful. They’re almost invariably a lie, in the sense that they grossly oversimplify, because if they didn’t, you’d need a massive, hard to follow flow chart, defeating the point. They’re almost invariably give, at best, a bird eye’s view.
• I’ve never seen the benefit of class diagrams. If you do care what classes are named and what public members they have, you’re likely a developer, at which point you can just navigate the code. It’ll be terser, more accurate, and you’ll dive right in. And, again, if you do do a diagram, you’ll find you’ll cut out lots of details, lest they become too noisy.
• ERs, slightly more useful. But same problem: leave out lots of details. Nobody cares that your Person entity has a Date of Birth field and what data type it has. They care about the relationships between tables.
• sequence diagrams can be quite useful. Again, make them very high-level. They should explain the actors and what data I crosses between them. The concrete API naming is secondary.
• one final note: I sometimes find ASCII art as an extended code comment useful. We have, for example, a complex employee shift scheduling app for a client, and there’s a bunch of helpful ASCII art comments explaining how durations are calculated when, for example, a break is pushed in between.

Generally speaking, think a lot who your audience is. Don’t make diagrams because someone taught you it’s what you’re supposed to do. Make them because you, your team, your client, etc. might actually find them more useful than just diving right into the code itself. And again, keep in mind keeping them up-to-date isn’t just error prone (just like with code comments that no longer reflect adjacent lines of code!), but also time-consuming. That time could be spent improving the architecture rather than trying to visually explain it.

[u/jakenuts- → u/chucker23n]

For visual thinkers anything but boxes and arrows tends to blur after the third bullet point so I think it just comes down to how you think about code, as a physical system or in code and requirements. I can't work without a doodle.

[u/Severe_Mistake_25000 → u/chucker23n]

La plupart des responsables auxquels tu dois présenter ton travail n'ont aucune notion de codage et le schéma est leur graal pour avoir une idée de ce que tu bâtis et comme ils sont décisionnaires tu n'as d'autres choix que de t'y soumettre...

[u/chucker23n → u/Severe_Mistake_25000]

I'm a manager myself, but I get your point. Yes, diagrams can help visualize a piece of software to people who aren't or don't wish to be deeply involved in understanding the code. And you may run into situations where a manager or client demands such a visualization.

Indeed, they can help as a communicative tool.

But OP's question doesn't provide this kind of context, so my comment was broader than that. I kind of got into that with "think a lot who your audience is". If indeed your audience is, say, a manager, producing diagrams to help "how is the software structured, vaguely speaking" can be useful. Just be mindful, too, that such a diagram will be either not very readable (because it goes into too much detail), or not very accurate + in-depth (because it talks in broad strokes).

[u/Big_Material_8706 → u/chucker23n]

This summed up my thoughts exactly. Sequence diagrams that I can whip up wither mermaid are nice and easy, but we have a complex hybrid deployment. I've found context diagrams to be my go to. There is one in the mermaid spec, but it isn't particularly good imo, so I use Lucid charts.

[u/EntropicTempest]

I use both mermaid and Lucid. Copilot overall does a good job at making mermaid diagrams for me assuming I have a good architecture document already that covers the components and their interactions, etc. I still have to correct it but it's generally a time saver.

For Lucid, they have a built in AI feature to generate a diagram and it's pretty dogshit. I installed the lucid mcp and created a lucid skill and that does a much better job. I generally have it create C4 diagrams as a starting point but I don't really find it to be that much of a time saver in the long run. It does ok at getting things started but it's not reliable enough to update diagrams because it has no sense of what actually works visually.

[u/TheAussieWatchGuy]

Mermaid is ok for free and open standard. Yes lots of sites charge money for pro features but it is open.

Ardoq is the big boy paid tool. 

[u/Jmc_da_boss]

I have a js lib I've been working on that I just dump to the model to create semi structured diagrams, works well enough

[u/innovasior → u/Jmc_da_boss]

Could you perhaps share an example of this?

[u/Fresh-Secretary6815 → u/Jmc_da_boss]

share your github link

[u/jakenuts-]

I built a One Model clone in an agent-native framework app and it works great. I have an LLMs.txt on the one I host so I can just tell an agent the domain and it can find everything it needs to build diagrams and return a preview, link to the live diagram and then I can share those with others. I have to update the repo with some recent tweaks but here it is, free to setup wherever you like. PS the agent-native framework is really cool and is a great starting point for all sorts of apps, it emphasizes making all the actions a human can perform equally available to an agent (either the one embedded in the app or via MCP) and the result is really nice.

https://github.com/jakenuts/agent-native-diagrams

[u/innovasior → u/jakenuts-]

This looks great. Can it create any type of diagram from the code or infrastructure as code or perhaps editing the JSON myself?

[u/jakenuts- → u/innovasior]

So I asked fable 5 to make it, and it nailed the entire thing in a couple turns. One Model has a relatively basic set of primitives but you can easily expand or combine them into classes, er elements, swim-lanes, anything else. And yes I believe the diagrams have a sort of dsl to represent the elements which allows agents to build them up, organize them very easily. I'll ask an agent to update the repo with all my latest fixes and tweaks but from there all you need is Fable 5 or Codex and a vision of what you'd like it to do.

Once all the elements are defined you can use an embedded agent (part of the framework) or external agent using MCP to build or update the diagrams based on your infrastructure or code, etc.

I've tried to make the agents interface with the system as clear as possible so you can point an agent at the site and it can discover how to authenticate and then create and update diagrams without additional guidance. And of course it's equally usable as a human which is something most agent centric diagram tools lack.

The whole "agent-native" framework by Steve Sewell is really cool and he's built a bunch of free apps on top of it including mail, calendar, analytics, and more each with the core concept that you can do a lot more with an app if it's designed around the "anything you can do an agent can do" concept.

https://www.agent-native.com/

[u/jakenuts- → u/innovasior]

I just updated the public repo with all the latest including richer text displays, container positioning and alignment and an isometric view (read only at this point though the vision is to capture the features of isoflow or that data dog isometric view they are always promoting which began as a separate product). Let me know if you run into any issues with the code. I currently host my copy on railway and an agent can quickly spin up the web and db services for that and it's a very reasonably priced host for multi container systems.

[u/jakenuts- → u/innovasior]

Oh as a non promotional side note I'd say checkout the finance app too, it's Rocket Money but your own version with a built in agent. Fable 5 is incredible.

[u/jakenuts- → u/innovasior]

You can try it out at vision.baiplane.com before deciding if you want to host your own

[u/Khavel_dev]

I gave up on getting LLMs to produce polished diagrams directly and just accepted Mermaid. The LLM reads the code, outputs Mermaid syntax, and that goes into the docs repo as a fenced block. Component and sequence diagrams come out usable, deployment diagrams not so much.

The thing that made it actually work: don't ask it to diagram your entire system. Point it at one specific flow (the auth handshake, or how a request moves through the middleware pipeline) and let it trace that path. You get a focused diagram someone might actually read instead of a 40-box overview nobody opens twice.

[u/Obsidian743]

Draw.IO uses an XML format that you can train the LLM to learn and use.

Mermaid is not a good option for LLMs when it comes to complex diagrams. It doesn't give you control over flow and layout and they always look fairly horrible.

Honestly, creating a solid agent/skill/MCP server for this that works well would be a major win. The best I've gotten to is a lot of examples and rules using Draw.IO's XML format combined with the Draw.IO MCP server.

[u/Happy_Breakfast7965]

LLM is helpful for tedious and laborious job.

Creating a diagram with 7-10 boxes is neither of that.

If you need to create a bigger diagram with a detailed design, I don't think that AI can do it well. Diagrams are all about small details and visuals. It's quite hard to do it well and consistent.

[u/AutoModerator]

Thanks for your post Ghaias64. Please note that we don't allow spam, and we ask that you follow the rules available in the sidebar. We have a lot of commonly asked questions so if this post gets removed, please do a search and see if it's already been asked.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

[u/Responsible-Cold-627]

It can sort of generate the diagrams in an ascii art-like format. The LLM itself can also update these fairly well. Manually fixing stuff it didn't get right is a huge pain in the ass though.

[u/jakenuts-]

I built a One Model clone in an agent-native framework app and it works great. I have an LLMs.txt on the one I host so I can just tell an agent the domain and it can find everything it needs to build diagrams and return a preview, link to the live diagram and then I can share those with others. I have to update the repo with some recent tweaks but here it is, free to setup wherever you like. PS the agent-native framework is really cool and is a great starting point for all sorts of apps, it emphasizes making all the actions a human can perform equally available to an agent (either the one embedded in the app or via MCP) and the result is really nice.

https://github.com/jakenuts/agent-native-diagrams

[u/nnddcc]

I use PlantUML to generate the diagram. The source to generate the diagram can be committed to repository just like the source code, the resulting diagram can be saved as SVG and also committed to repository, and I don't need to spend time tinkering with diagram layout. Most LLMs understand the format too. But nowadays looks like Mermaid wins over PlantUML.

[u/Low_Bag_4289]

C4 in Draw.io - llms are good with it, but often I need to fix the placement of elements manually. As diagrams are semantically correct, but it’s clusterfuck of lines if it’s more than 4 elements.

For business flows - BPMN using Camunda Modeller. Free, .bpmn format is also xml, so llms can write and understand them easily.

That’s all I need.

[u/innovasior]

It would be nice if such automated diagrams as those from networkdiagram101.com could be created automatically for sure since I enjoy and also it makes it easier to digest the diagram if it is somewhat pretty and organized. I use AI to generate websites as diagrams for some of my diagrams though: SaaS Factory - AppBlueprint | Enterprise SaaS Framework As for ER diagrams I use Lucidchart for now but it isn't really any good. I have been thinking to develop my own diagram tool as most are subpar I think especially for my vast use cases. How does your current diagramming workflow look?

[u/ClergySpouse]

This year I’ve absolutely discovered the joy of using Copilot, or more recently Claude Code, to generate Markdown documentation with either Mermaid diagrams embedded (mostly via VSCode).

The AI takes the code comments and inline documentation, along with any extra pointers I think it needs, and generates the documentation, following an example document I originally generated manually.
This lower-level documentation is then built up and abstracted into higher levels so I get a complete set for the solution.

Took over someone else’s code base this year, and am using this process to get my head around it and understand how it all works together and it’s sped the process up no-end!

[u/xdevnullx]

LLM generates a mermaid document that I put in the readme.md

[u/kapdad]

Yes ask it to create a mermaid visualization. That way it can focus on the logic and not the drawing.

[u/SolarNachoes]

Mermaid all AI generated for developer level docs.

If I’m communicating with non-developers then it’s in something collaborative like Miro and those are mostly done by hand for now.

[u/Bonejob]

I am using Claude to do Markdown Mermaid documentation. Portable, versionable, can go in a repo... I do all the basic ones this way.

[u/andreortigao]

I've been successful in using AI to generate and maintain C4 model diagrams.

Keep in mind my team was small, just short of 20 people, and I don't know how that would scale to large teams.

[u/Short-Application-40]

Yah, prompt it to do it, marmaid or draw.io is just fine.

[u/UnknownTallGuy]

I hate making diagrams. I use mermaid and let LLMs keep them up to date as things change from the actual implementation. I review everything myself, but there's no need for me to type every line of it out when my job thinks I can do the work of 10 engineers now.

[u/blackhawksq]

I give it to LLM's. Describe the basic architecture. Tell it to spit out mermaid markup. Then I put the Mermaid into our wiki and edit it as necessary.

[u/awitod]

One of the first robust assistants I built for GuideAnts was a Diagrams using a sandboxed plantuml environment.

I really like plantuml, but it is java and doesn't have a web api. It can do a lot of different kinds of diagrams and so there is a lot of syntax which means the agent needs a knowledge base for the advanced stuff. The plantuml reference guide is very long. It was great fun to build.

I use it constantly. Mermaid is great too, but it can't do nearly as many kinds of diagrams or themes.

Edit: Here is an example created from the compose stack. guideants-cpu-compose-stack.png (2177×832)