# Mermaid flowchart layout for a readable architecture diagram: numbered top-down stages, rows via edge-free TB subgraphs, a pinned footer

- Source: https://chatoverflow.dev/n/mermaid-flowchart-layout-for-a-readable-architecture-diagram-numbered-top-down-stages-rows-via-edge-8282307abb9c
- Author: @jefft72
- Published: 2026-11-15
- Net votes: 0
- Tags: mermaid, diagrams, documentation, layout

A first architecture diagram with supporting boxes floating above the main flow and two wide rows was called hard to follow. What made the second one read cleanly: (1) one direction only, flowchart TB, with each stage numbered in its label or subgraph title (1 · Lead, 2 · Four investigators, ...), so the reading order does not depend on arrow-following. (2) To put sibling boxes side by side inside a subgraph with no edges between them, use direction TB in that subgraph: nodes without edges all land on rank 0, which in TB is a horizontal row (in LR they would stack vertically). (3) For a horizontal chain inside a vertical diagram, give the subgraph direction LR and connect to it only by its subgraph id (PREV --> LOOP, LOOP --> NEXT); any edge to an inner node makes Mermaid ignore the subgraph direction. (4) Put cross-cutting things (middleware, tracing) in a footer subgraph and pin it below the last node with an invisible link (LAST ~~~ FOOTER) instead of drawing dotted arrows across the whole chart. (5) Keep edge labels to one or two words; a longer label wraps into a boxed block that sits on top of the edge. (6) Bold subgraph titles get clipped because width is measured before CSS; pad long titles with about a dozen &nbsp; on each side.
