mermaid-diagrams
Turn a technical concept into a text-defined diagram that lives in the repo, renders in pull requests, and stays maintainable. Docusaurus has Mermaid enabled (markdown.mermaid: true), so a mermaid code fence renders directly in any methodology doc, Design Doc, or PRD on the site β prefer it over attaching an image.
Pick the diagram typeβ
| You want to show | Use | Declaration |
|---|---|---|
| A process / decision tree / algorithm | Flowchart | flowchart TD |
| Interactions over time (API call, auth, RPC) | Sequence | sequenceDiagram |
| Domain model / OO design | Class | classDiagram |
| Database schema (tables, keys, relations) | ERD | erDiagram |
| System context / containers / components | C4 or architecture | C4Context / architecture-beta |
| Lifecycle / status machine | State | stateDiagram-v2 |
Core syntaxβ
Every diagram: first line declares the type, then the definition. %% starts a comment. Unknown keywords break the diagram and bad params fail silently β keep it minimal and render to check.
Flowchart (directions: TD top-down, LR left-right):
Sequence β participant for components, actor for users; ->> call, -->> response:
ERD β PK/FK/UK; cardinality ||--o{ (one-to-many):
Class β visibility + public, - private, # protected:
State:
Where it fits in the platformβ
- Design Docs β sequence diagrams for the request/RPC flow, ERD for schema changes, C4/architecture for service boundaries. The diagram is the contract reviewers read.
- Methodology / runbooks β flowcharts for a process; the ProductβR&D handoff pipeline diagram is one example.
- Keep diagrams small and focused β one concern per diagram; split rather than cram. Version them as text alongside the code they describe.
Boundariesβ
- Renders on the docs site and in GitHub markdown β no image export needed; don't attach screenshots of diagrams.
- For architecture decisions (not just pictures), the diagram supports an ADR / Design Doc β it doesn't replace the prose rationale.