Creating software systems is a complex task. You don't just put your head down at your keyboard and bash out code. You need to take concepts and ideas out of your (or other people's) head and somehow reason them into a working software product. In my experience one of the most effective ways to do this is to visualise the system.
People will shy away from a dense technical document or be confused by TLAs (three letter acronyms) but they'll often understand a picture. This isn't anything ground breaking, toolkits like UML or Entity Relationship Diagrams have been around for decades. The chore, however, is in creating these diagrams.
It can be a bit of a slog to draw these diagrams out and even more so when you need to iterate on them. Enter AI language models.
Your AI "Rubber Duck" 🦆
We've all heard of rubber duck debugging - explaining your code to an inanimate object to help solve problems. LLMs take this concept to the next level, acting as an intelligent conversation partner during system design.
When designing a new system, you can describe your requirements to an LLM and ask it to:
- Identify potential edge cases
- Verify your assumptions and logic
- Suggest database schemas, relationships, index and keys
- Create class hierarchies
- Design API endpoints
- Map out system architecture
The real power comes from two aspects:
- The interactive nature of these tools: A good LLM will ask clarifying questions, challenge assumptions, and help refine your ideas - much like a seasoned developer would.
- Producing outputs that are easy to understand, use and disseminate to stakeholders. The chat thread with the LLM isn't useful when building out the system, what you really need is diagrams.
Enter Mermaid
While LLMs excel at textual interaction, they can't directly create visual diagrams. However you like to visualise your systems whether that be through UML or Entity Relationship Diagrams or something else this is where Mermaid comes in. Mermaid is a JavaScript-based diagramming tool that turns markdown-like text into diagrams. And something LLMs are pretty good at is generating markdown-like text.
Mermaid can help to create:
- Flowcharts
- Sequence diagrams
- Entity Relationship Diagrams (ERD)
- Class diagrams
- State diagrams
Here's a simple example of Mermaid syntax for a basic flowchart:
graph TD
A[Start] --> B{Is user authenticated?}
B -->|Yes| C[Show Dashboard]
B -->|No| D[Show Login Page]
D --> E[Validate Credentials]
E -->|Success| C
E -->|Failure| DYou can hopefully see how ChatGPT or Claude can generate this Mermaid syntax based on your conversation with them, making it incredibly fast to create professional diagrams.
Tools for rendering Mermaid diagrams
Once you have your Mermaid markdown, you'll need to render it. Here are our favourite tools:
-
Mermaid Live Editor https://mermaid.live
- Real-time preview
- Export to SVG or PNG
- Share diagrams via URLs
-
GitHub
- Native Mermaid support in markdown
- Perfect for documentation
- Version control for your diagrams
-
VS Code + Mermaid Extension
- Preview diagrams while coding
- Export capabilities
- Integrated development experience
The most accessible option is the Mermaid Live Editor (it's a free to use web based tool that doesn't require any installation). Take the codeblock below and paste it into the Mermaid Live Editor and it will render the diagram.
graph TD
A[Client Has Idea] -->|Comes to Add Jam| B{What's Needed?}
B -->|Mobile App| C[React Native Magic]
B -->|Web App| D[React Wizardry]
B -->|Backend| E[Ruby on Rails Powers]
C --> F[Cross-Platform Joy]
D --> G[Lightning Fast UIs]
E --> H[Robust APIs]
F & G & H -->|Combine Powers| I[Happy Users]
I -->|Success!| J[Another Add Jam Masterpiece]
style A fill:#f9f,stroke:#333,stroke-width:2px
style J fill:#9ff,stroke:#333,stroke-width:2px
style C fill:#ffb366,stroke:#333,stroke-width:2px
style D fill:#ff8080,stroke:#333,stroke-width:2px
style E fill:#ff6666,stroke:#333,stroke-width:2pxI encourage you to paste the codeblock into the Mermaid Live Editor and play around with it yourself... but if you're too lazy here's a preview of our beautiful diagram:
NB the style declarations at the bottom of the diagram? That's how we added those nice colors to make the flowchart more visually appealing. Feel free to try change the colors in the live editor!
Actually, there is another way to share this diagram... you can view the diagram here on Mermaid Live Editor or it's really simple to export as a PNG or SVG. It really is a powerful and low effort way to share your system designs.
Why is Mermaid from ChatGPT or Claude good for system design?
AI is all the rage right now and many businesses are jumping on the bandwagon and shoehorning AI into their processes. That isn't a good thing, you need to find ways to implement AI into your processes that are actually a value add. I feel this approach of using LLMs to generate Mermaid diagrams is a value add, here's my thinking:
1. Rapid iteration of system diagrams
Instead of wrestling with drag-and-drop interfaces or expensive diagramming tools, you can quickly describe changes and generate updated diagrams in seconds. The speed of iteration is a huge benefit.
2. Open standards and free to use
Mermaid provides a consistent format that's:
- Version control friendly
- Easy to maintain
- Simple to share
- Platform independent
- Open source and free to use
You don't need to fumble with licences for team members and collaborators.
3. Documentation as code
Your diagrams can live alongside your code in plain text, making them:
- Easy to version
- Simple to update
- Accessible to all team members
We've added Mermaid diagrams directly into our repos for several projects now and it's a great way to keep the diagrams up to date with the code.
4. Knowledge extraction
LLMs can help explain complex systems and suggest improvements based on best practices and common patterns.
Limitations and best practices
While powerful, as with any task involving popular LLMs in 2025, there are some limitations to keep in mind:
-
Minimise complexity For large systems, break down your diagrams into smaller, focused components. LLMs work better with specific, bounded contexts. If your diagram is growing too big and complex the quality of output will decrease quite quickly. It's best to break systems down into smaller components if feasible.
-
Verification required Always review and verify the
generated diagramsoutput from the LLM. This is a golden rule for any use of AI in a business process. LLMs can (and will) make mistakes or misunderstand requirements. Leverage the capabilities of the LLM but check the output, ultimately you are responsible for the quality of the output. -
Interactive refinement Don't accept the first suggestion. Iterate with the LLM to refine and improve the design. Challenge its assumptions and provide corrections when needed. LLMs are not perfect and in fact they're often in a hurry to just agrees with you even if you're wrong.
-
Complement, don't replace Use LLMs as a tool in your toolkit, not a replacement for careful system design and review processes. Take the outputs to team members and project stakeholders. Get them to review and provide feedback.
Conclusion
At Add Jam, we've found that combining LLMs such as ChatGPT and Claude with Mermaid diagrams significantly speeds up our system design process while maintaining high quality documentation. However, we always ensure human oversight and validation of the output.
Our actual approach to using the LLMs is via Raycast on MacOS. We've written about our approach to using Raycast to speed up our development workflow, we still highly recommend Raycast as a tool for MacOS users.
Looking to embrace the power of AI in your software development process? Take it from us using ChatGPT and Claude to generate Mermaid diagrams is a great way to get started.
Add Jam are a Scotland based team that specialises in creating well-documented, maintainable software solutions on web and mobile. Get in touch to learn how we can help streamline your development workflow with modern tools and best practices.
