Architecture diagrams rot when the source file lives in one tool and the service definition lives somewhere else. Mermaid's advantage is mundane and powerful: the diagram is text, so it can sit beside the Markdown and be reviewed in a pull request.
Short answer: use Mermaid for compact flowcharts, sequence diagrams, and dependency views where the source needs to change with the code. Keep labels short, show the boundaries that matter, and split diagrams when they require a zoom control to understand.
flowchart LR
Browser --> API
API --> Queue
Queue --> Worker
Worker --> Database
| Diagram | Best question it answers |
|---|---|
| Flowchart | What calls what? |
| Sequence diagram | In what order do messages happen? |
| ER diagram | Which data entities relate? |
| State diagram | What transitions are allowed? |
A diagram should make a design decision easier to discuss. If it merely redraws every class and table, it is an expensive screenshot of complexity.
The documentation habit that works
Place a diagram at the decision boundary: the service README, the ADR, or the endpoint doc. Use stable nouns (API, billing worker) rather than deployment-specific hostnames. When an edge changes in code review, change the edge in the diagram in the same pull request.
Mermaid does not make architecture simple. It makes a small, useful view cheap enough to keep current.
Cover photo by Ivan S on Pexels.