How to keep complex Mermaid diagrams readable

A forty-node Mermaid service map looks fine in an editor window but becomes a cloud of tiny labels in a Slack preview. Zoom helps inspect a detail; it does not tell a new engineer which path matters. Mermaid lays out relationships from text, so the strongest readability fixes happen in the source: choose one reader question, keep one level of detail, group related nodes and move separate stories into linked views. This guide shows when to split the diagram rather than fighting the layout with longer labels and more arrows.

Direct answer: To make a complex Mermaid diagram readable, write down the one question it answers and remove everything else. Keep a single abstraction level, split independent flows into separate diagrams, group related nodes with subgraph, choose a direction that fits the shape, and shorten labels. Then check it at the size people will actually see, such as a Slack preview or a phone.

Start with the reader's question

"How does checkout fail?" and "Which services are in the commerce domain?" need different diagrams. A diagram titled "System architecture" usually has no question, so everything goes in.

Write the question as the diagram title (title in most diagram types, or a comment at the top of the source). Delete any node that does not help answer it.

Keep one abstraction level

Mixing people, services, classes, cloud resources, and tables in one view is the fastest route to clutter. The C4 model is useful here because each level has a clear scope. A context view shows people and systems, a container view shows apps and data stores, and a sequence diagram shows one interaction.

Split by flow, then link the views

When several journeys cross, such as checkout, refunds, and notifications, make a small overview map plus one focused diagram per journey. Repeating a node across views is fine if each view has a distinct purpose. Two flows that keep crossing each other are a strong signal that they belong in separate diagrams.

Use layout controls Mermaid does give you

This service map groups eight nodes into three boundaries so the main path reads left to right:

flowchart LR
    subgraph Edge
        W[Web app]
        G[API gateway]
    end
    subgraph Core
        C[Checkout]
        F[Fraud]
        O[(Orders)]
    end
    subgraph Async
        Q[[Queue]]
        K[Fulfillment worker]
    end
    W --> G --> C
    C --> F
    C --> O
    C --> Q --> K --> O

Techniques in that example:

• subgraph groups show boundaries and pull related nodes together.
• Direction (LR or TD) should follow the dominant flow. Request paths usually read better left to right. Hierarchies read better top to bottom.
• Short labels and stable IDs: C[Checkout] instead of a sentence. Put detail in the thread or a note.
• Fewer edges: drop edges that are obvious from grouping, or that a focused child view shows better.

The flowchart reference covers subgraph direction, edge lengths, and styling classes.

Summarize repetition

Do not draw every retry, instance, or threshold as a node. Use a labeled edge (-- retry x3 -->), a single node for the policy, or a table next to the diagram. For event-heavy systems such as firmware, a table of signals and thresholds explains more than 40 parallel arrows. See architecture diagrams for embedded systems.

Split a crowded service map by question

Imagine a forty-node diagram containing customer entry points, database internals, deployment replicas and every retry branch. A mobile Slack preview makes all labels tiny. Ask two questions: “Which external systems exchange data with us?” and “Where can an order fail?” The first needs a context view; the second needs a focused sequence or flow diagram. Move each detail to the view that answers its question, and link the views rather than shrinking the text.

Maintain these views in Arialine during the Slack review because a teammate can request the split in the diagram thread and inspect each accepted source revision. Check the resulting PNG at phone width and the HTML viewer at full size. The success criterion is whether another engineer can trace the relevant path without zooming into unrelated branches. Mermaid's subgraph guidance can help group what remains, but grouping cannot rescue a diagram with several competing purposes.

Test at the size people will see

A diagram that is fine on a 27-inch monitor can be illegible in a Slack message or on a phone. Look at it where it will be read. Pan and zoom help. Arialine's interactive HTML file supports both in a browser, and on mobile the PNG preview is the primary view. Zoom does not fix a diagram with no clear structure, though.

Where Arialine fits

Splitting a diagram creates a coordination problem: several views that must stay consistent. Arialine keeps each view as a separate board in Slack with its own source and history. When you want to try a different layout or grouping without disturbing the current one, Branch creates a separate board to experiment on. It counts as a new board on the Free plan. Ask for the restructure in plain language (@arialine group gateway and web app into an Edge subgraph) or paste revised source.

Measure readability in the delivery context

Mermaid's configuration options can change layout, theme and renderer behaviour, but configuration cannot repair an unfocused model. Test the diagram at the width where Slack, documentation and exported reports will actually display it.

Ask a reader to identify the entry point, main path, failure path and boundary in under a minute. Record which labels require zoom and which connections cross unrelated areas. Split by question before shrinking type or adding colour. Keep a linked overview so focused views do not become isolated fragments.

Next step: test the current diagram at mobile width and replace the first unreadable region with a named linked view.

FAQ

Can I position boxes manually in Mermaid?

Not in the usual diagram types. Mermaid uses automatic layout, so you influence it through direction, grouping, ordering, and edge length. If you need pixel-level placement, use a visual diagram tool.

How many nodes is too many?

There is no fixed number. If a reader cannot find the main path in a few seconds, split or simplify the diagram. In practice, trouble often starts at around 20 to 25 nodes.

Should I switch tools for very complex systems?

Sometimes. Modeling tools such as Structurizr generate many consistent views from one model. First check whether the real problem is scope, which a tool change will not fix.