Turning text into diagrams with AI: field notes from documenting a side project

Diagrams are a very convenient way to show a system’s architecture quickly, but in practice it’s much easier to draw them once than to keep them up to date. When a service is moved, a queue is renamed, or the API gateway is replaced by yet another “lambda in a tube,” the picture in the README or the design doc starts slowly lying to you.

This repeats over and over: you open a Canvas editor or a Confluence board again in Notion, drag rectangles and arrows around until everything looks decent again. And a couple of sprints later the story repeats itself.

This article is a field report on how I tried to stop redrawing diagrams by hand and shifted that work to AI tools that turn text into pictures.

---

What’s wrong with manual diagrams in real life

Problem #1: short lifespan

A diagram stored in a README file or in a design doc has a “half‑life” of about two sprints. As soon as changes begin in the architecture or infrastructure—a queue rename, a new database shard, a new revision service—the picture no longer matches reality.

You end up choosing between two bad options:

• continually redrawing — spending time on manual edits in a visual editor;
• let the diagram rot — and then it not only doesn’t help, but actually misinforms newcomers on the team.

Both options are expensive in the long run.

Problem #2: costly changes

A manually edited picture doesn’t live next to the code and the configuration. This means that:

• changes to the architecture are not automatically reflected in the README;
• reviewers in the pull request don’t see the system layout “as it will be after merge”;
• you have to manually synchronize changes between the code and the documentation.

This is exactly why text‑oriented approaches (like Mermaid and similar) are gaining popularity in engineering teams.

---

How text‑to‑diagram tools change the equation

The main idea of text‑to‑diagram tools is to make a textual description the source of truth, and treat the picture as a derived artifact.

If the architecture is described in text:

• regenerating the picture takes seconds;
• the text lives next to the code — in the same repository, in the same README or /docs file;
• you can review the picture as part of a pull request: changes to the system’s structure are visible as text diff instead of a binary image.

In this context, AI tools act like a helper translator: they take a human description of an architecture or process and turn it into either a textual notation (such as Mermaid) or a ready‑made visualization.

---

LLM + Mermaid: an almost‑default engineering setup

Why Mermaid

Mermaid is a text format for describing diagrams that can draw sequence diagrams, flow charts, architectural diagrams, and so on. Its key advantages in the context of a codebase and its docs:

• GitHub supports it natively in Markdown files;
• it’s diff‑able and reviewable in pull requests;
• the text description of diagrams can be versioned and stored in a version control system.

What I did with the LLM‑based approach

For example, I would describe something to the LLM roughly like this in plain text:

Запрос от клиента приходит через API‑шлюз в сервис авторизации,
затем проходит в основной backend‑сервис, который ходит в базу данных Postgres
и отправляет задачи в очередь задач Kafka. Отдельный воркер забирает задачи
из Kafka и пишет результат в лог‑сервис и кэш Redis.

And ask it to generate Mermaid markup. In response, it would produce something like this:

flowchart LR
    Client[\\\\\\\"Клиент (web/mobile)\\\\\\\"]
    Gateway[\\\\\\\"API-шлюз\\\\\\\"]
    Auth[\\\\\\\"Сервис авторизации\\\\\\\"]
    Backend[\\\\\\\"Основной бекенд\\\\\\\"]
    DB[\\\\\\\"Postgres\\\\\\\"]
    Q[\\\\\\\"Очередь задач Kafka\\\\\\\"]
    Worker[\\\\\\\"Воркер\\\\\\\"]
    Log[\\\\\\\"Лог-сервис\\\\\\\"]
    Cache[\\\\\\\"Redis\\\\\\\"]

    Client --> Gateway
    Gateway --> Auth
    Auth --> Backend
    Backend --> DB
    Backend --> Q
    Q --> Worker
    Worker --> Log
    Worker --> Cache

This code can be simply pasted into a README.md file, or, say, docs/architecture.md, and GitHub will render it automatically.

---

What works well with this setup

• Change speed of the diagram:
  change the text in the diagram — you get a new picture the next time you view it.

• Diffs and reviews in pull requests:
  if changes to the architecture require renaming or removing a service, this is visible directly in the diff as text changes.

• Integration with doc‑as‑code:
  diagrams live in the same repository and build system for documentation as the code does.

What limits Mermaid

• Layout is not always predictable:
  Mermaid decides itself where to place blocks; once you have more than ten nodes, the diagram can easily turn into “spaghetti.”

• Not all diagram types are supported equally well:
  for example, for complex UML diagrams or high‑level architectural views, you sometimes have to customize CSS semantics or use other tools.

• You need to know basic syntax:
  even though LLMs help a lot, you sometimes need to tweak the result manually, or at least understand the structure of the markup.

---

Napkin AI: when you need a concept, not an exact diagram

Another tool from this quarter’s experiments is Napkin AI. The idea is very similar to “a query to a designer”: you write a paragraph describing what you want to show on the picture, and it offers several visualization options.

For example, you can describe the same architecture in a single paragraph:

Frontend отправляет запросы через API‑шлюз в backend‑сервис,
который ходит в базу данных и отправляет фоновые задачи в очередь.
Воркер асинхронно обрабатывает задачи и пишет результат в лог‑сервис и кэш.

At the output you get several picture options: for example, as a linear flow, as a comparison of two approaches, or even a timeline of task execution.

What works particularly well in Napkin

• For design documents and concepts
  When you need not so much an exact match of the diagram to the real architecture, but rather an illustration of the idea (for example, comparing two integration options or showing evolution of the architecture over time).

• Several ready‑made visual styles
  You can get the same logic in the form of different visualizations and choose the option that fits better with the document text.

---

What didn’t work and where precision is lacking

From this experiment’s experience, you can identify several typical limitations of text‑to‑diagram tools:

• Complex composition of diagrams
  In real project documentation, you often need not one picture but several related diagrams (for example, overall system architecture plus a detailed call graph between services). Switching between “big picture” and “detail on a specific subsystem” is not always convenient with textual tools.

• Non‑ideal automatic layout
  Both Mermaid and generative models sometimes ca

ot optimally arrange elements on the diagram when there are many nodes or complex relationships.

• Not suitable for all types of diagrams
  For example, for a diagram of container cluster infrastructure (Kubernetes, namespaces, resources, etc.) a textual “paragraph description” may not be enough—specialized tools or DSL‑based approaches are better for this kind of thing.

---

Practical recommendations: how to start using the text → AI → diagrams pipeline in your project documentation

Below are several concrete steps you can try on the next project or side project.

1. Describe the architecture in simple sentences in Russian or English

Start with text “without syntax,” just plain language:

• who depends on whom,
• where requests go,
• what storages and queues are involved.

Something like:

Клиентское приложение (web) отправляет запросы через API‑шлюз в основной сервис,
который ходит в базу данных PostgreSQL и отправляет фоновые задачи в очередь Kafka.
Воркер забирает задачи из очереди и отправляет нотификации через внешний сервис уведомлений.

2. Use an LLM as a translator into a textual diagram notation

For example, ask the model:

> “На основе текста ниже сгенерируй Mermaid‑разметку для диаграммы потока данных:”

and then copy the result into the codebase or documentation.

---

3. Keep diagrams as code in a separate file or inside README

If the diagram is separate:

docs/
  architecture.md
README.md

Inside docs/architecture.md, you can keep several diagrams for different levels of detail:

## 1. Общая архитектура

```mermaid
flowchart LR
    Web[\\\\\\\"Web фронтенд\\\\\\\"] --> Gateway[\\\\\\\"API шлюз\\\\\\\"]
    Gateway --> Backend[\\\\\\\"Основной сервис\\\\\\\"]
    Backend --> DB[\\\\\\\"Postgres\\\\\\\"]
    Backend --> Q[\\\\\\\"Kafka\\\\\\\"]
    Q --> Worker[\\\\\\\"Воркер\\\\\\\"]
    Worker --> Notify[\\\\\\\"Сервис уведомлений\\\\\\\"]

...

---

### 4. Use Napkin‑like tools for conceptual illustration in design documents

If you are writing a design doc or prototyping an approach, it’s reasonable to:

- draw a conceptual illustration in a Napkin‑like tool to get a quick picture illustrating the idea;  
- after the architecture is implemented and agreed upon, produce the canonical diagram using a textual notation like Mermaid and fix it in the repository.

---