Yes — you can commit an architecture diagram as text and have it render automatically. GitHub has rendered fenced ```mermaid blocks natively since February 2022, GitLab does too, and VS Code shows them in Markdown preview. That's the whole pitch: the diagram is source, so it sits next to the code, diffs in a pull request, and can't drift into a stale PNG that nobody remembers how to edit.
flowchart LR
Browser --> API
API --> Queue
Queue --> Worker
Worker --> Database
The real payoff shows up in review. When a PR adds a call from the API straight to the database, a reviewer sees the diagram edge is now wrong in the same diff and asks about it. A diagram in a separate design tool never gets that scrutiny.
Pick the diagram type by the question it answers
| You need to show | Use | One-line starter |
|---|---|---|
| What calls what | flowchart LR | A --> B |
| Message order over time | sequenceDiagram | Client->>API: request |
| How data entities relate | erDiagram | USER ||--o{ ORDER : places |
| Allowed state transitions | stateDiagram-v2 | Idle --> Running |
A worked sequence example, with real participants for a login flow:
sequenceDiagram
participant U as User
participant W as Web app
participant A as Auth server
U->>W: click "Log in"
W->>A: redirect with PKCE challenge
A-->>U: login form
U->>A: credentials
A-->>W: authorization code
W->>A: code + verifier
A-->>W: access token
Takeaway: that diagram is nine lines of text. It renders on GitHub, diffs cleanly when the flow changes, and answers "what talks to the auth server, and in what order" faster than three paragraphs of prose ever will.
Mistakes that leave a broken diagram in your README
- Special characters in a label without quotes.
A[Cache (Redis)]fails to parse because of the parentheses. Quote it:A["Cache (Redis)"]. Same for colons, brackets, and slashes. - Deployment hostnames as node names. Label nodes with stable nouns —
Billing worker, notbilling-prod-e7a. The infrastructure churns; the architecture doesn't. - One diagram trying to show everything. If a reader needs a zoom control, split it. GitHub also caps diagram size and will silently show a syntax error on very large graphs. Several focused views beat one wall.
- Forgetting the exact fence. It must be
```mermaid, lowercase.```Mermaidor a plain```renders as a code block, not a diagram — a common "why won't it render" moment. - Not previewing before you push. Mermaid's parser is strict; one bad edge breaks the whole diagram. Preview it in an editor or a live editor first, so review isn't the place you discover the syntax error.
Mermaid won't make a tangled architecture simple. What it does is make a small, honest view cheap enough that keeping it current stops being a chore — and a diagram nobody dreads updating is the only kind that stays true.
Cover photo by Ivan S on Pexels.