Why Mermaid is the Best Way to Document Your Architecture in the AI Era

Creating documentation for your project was always a fundamental skill for me, long before LLMs even existed.
Being able to quickly read how to setup a project or what the project is about it's something that every repository should have.
And in the LLMs era, where you need to also tell a model how your project works, without it having to waste tokens reading through your code and figuring things out on its own, it's even more important.

But what changed is how the documentation is consumed. Is no longer for humans-only to be understood, but it's also massively important for machines.

One of the most important aspect we need to document about a project is often the architecture or any flows of how that piece of software you wrote works.

And what's the easiest way to graphically show that? Diagrams.

In the past a common way to do it was using ASCII, so you might have something like this:

┌─────────────┐        ┌─────────────┐        ┌─────────────┐
│   Browser   │ ──────▶│   Backend   │ ──────▶│  Database   │
└─────────────┘        └─────────────┘        └─────────────┘

Simple to read, fairly universal to show it anywhere, it doesn't need any special plugin or software to be read, it just works.

And often an LLM, when you ask to create a diagram, will use just that, as it's easier for a human to read.

But this doesn't mean that, while is effective to humans, is also effective to AI models.

Enter Mermaid.js

Another way to represent the exact same diagram above, is to use a format called mermaid.
It's a very simple format that is supported by Github, Gitlab, Gitea, etc... and that diagram will look like this:

flowchart LR
    Browser --> Backend --> Database

Again, still fairly easy to read, maybe less fancy than the ASCII, but it will render beautifully iin a browser where that format is supported.
You can also zoom in, it scales up to whatever resolution you want, and many other advantages, and the only real disadvantage is the fact that you need something to render it, which is the mermaid renderer.

Another issue is that when you have complex diagram, if you don't render it with mermaid library, it becomes hard to read for humans. Something like this for example:

flowchart TD
    User["👤 User"] --> Browser["🌐 Browser"]
    Browser --> CDN["CDN\n(Static Assets)"]
    Browser --> LB["Load Balancer"]

    LB --> API1["API Server 1"]
    LB --> API2["API Server 2"]

    API1 & API2 --> Cache["Redis Cache"]
    API1 & API2 --> DB[("PostgreSQL")]
    API1 & API2 --> Queue["Message Queue\n(SQS / RabbitMQ)"]

    Queue --> Worker["Background Worker"]
    Worker --> DB

    API1 & API2 --> Auth["Auth Service\n(OAuth / JWT)"]
    API1 & API2 --> ThirdParty["Third Party APIs\n(Email, Payments)"]

You can still understand what's going on, but for a human is harder to read.

So at this point, if you are a human, you could argue against one or the other.
But that's the key: if you are human.

If you are an LLM, it's a completely different story.

But it's not just about AI

Before we even get to the AI angle, mermaid has some very practical advantages for humans too that are worth mentioning.

It lives in your codebase. Because mermaid diagrams are just text, they live right in your markdown files alongside your code. This means they go through the same version control process as everything else — you can review changes in a PR, revert them, and see exactly who changed what and when. Try doing that with a PNG exported from Lucidchart.

Diffs are meaningful. Following on from the above, when somebody updates a diagram, the diff in your PR will show exactly what changed in the flow, not just "image.png was modified". This makes code reviews a lot more useful and transparent.
No extra tooling required. With traditional diagramming tools like Figma, Draw.io or Lucidchart, you need to open a separate application, make your changes, export an image, and then commit it. With mermaid, you just edit the text directly in your markdown file. Your editor, GitHub, and most modern documentation platforms will handle the rendering for you.

It forces you to think in structure. Writing a diagram in mermaid syntax, rather than dragging boxes around a canvas, naturally encourages you to think about the relationships and flow of your system more carefully. It's a bit like the difference between writing pseudocode and drawing boxes freehand — the structured format tends to produce clearer thinking.

LLMs love mermaid

LLMs love mermaid format as it has a lot of key advantages:

• Models are trained to understand mermaid format quite extensively
• They are more compact and easier to follow the flow
• It's more efficient in terms of tokens.

Essentially reading an ASCII diagram for an LLM is a waste of tokens, and it's harder to follow what the diagram is trying to explain, because of extra noise added by the decorative part of the diagram.
Mermaid explains how a diagram works more efficiently.

And where often LLMs have to digest massive amounts of tokens, having an efficient way to digest that information is fundamental.

Mermaid uses way less tokens

So let's compare the same diagram we showed above, and both format, and see what's the difference in tokens:

Diagram using ASCII

Diagram using mermaid

As you can see above, the difference in tokens is massive: 55 tokens for the ASCII versus 10 of the mermaid, and this is a very simple diagram.

But again, what it also matters, apart from the economy of tokens, is the fact that mermaid will be easier to understand for LLMs with way less chances to hallucinate.

Conclusion

Documentation has always been important, but in the AI era, we need to think about two audiences: humans and machines. While ASCII diagrams are universal and need no special tooling to be read, they are noisy and inefficient for LLMs to process.

Mermaid gives you the best of both worlds. It's still readable by humans, it renders beautifully on platforms like GitHub and GitLab, and most importantly, it communicates the same information to an LLM in a fraction of the tokens, with less risk of misinterpretation.

So next time you're documenting your architecture in a README.md or a CLAUDE.md file, skip the ASCII art and reach for Mermaid instead. Your teammates will appreciate it, and your AI tools will thank you for it too.