Mermaid Diagrams
Use Mermaid.js for all diagrams in documentation. ASCII art is deprecated.
Why Mermaid
- •Renders in GitHub, GitLab, Notion, Obsidian
- •Easy to edit (text-based)
- •Consistent styling
- •Supports themes
Syntax Reference
Flowchart (Top-Down)
mermaid
flowchart TD
A[Start] --> B{Decision?}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
Flowchart (Left-Right)
mermaid
flowchart LR
A[Input] --> B[Process] --> C[Output]
Subgraphs (Grouping)
mermaid
flowchart TD
subgraph Frontend
A[React] --> B[Vite]
end
subgraph Backend
C[Express] --> D[Prisma]
end
A --> C
Sequence Diagram
mermaid
sequenceDiagram
participant U as User
participant FE as Frontend
participant BE as Backend
U->>FE: Click button
FE->>BE: POST /api
BE-->>FE: Response
FE-->>U: Show result
State Diagram
mermaid
stateDiagram-v2
[*] --> Idle
Idle --> Loading: fetch()
Loading --> Success: 200
Loading --> Error: 4xx/5xx
Success --> Idle: reset
Error --> Idle: retry
Class Diagram (Architecture)
mermaid
classDiagram
class Service {
+create()
+update()
+delete()
}
class Repository {
+findById()
+save()
}
Service --> Repository
Node Shapes
| Shape | Syntax | Use |
|---|---|---|
| Rectangle | [text] | Default |
| Rounded | (text) | Soft shape |
| Stadium | ([text]) | Start/End |
| Diamond | {text} | Decision |
| Circle | ((text)) | Junction |
| Hexagon | {{text}} | Preparation |
Arrow Types
| Arrow | Syntax | Use |
|---|---|---|
| Solid | --> | Normal flow |
| Dotted | -.-> | Optional/async |
| Thick | ==> | Important |
| With text | `--> | label |
Style Classes
mermaid
flowchart LR
A[Node]:::primary --> B[Node]:::secondary
classDef primary fill:#6366f1,color:#fff
classDef secondary fill:#64748b,color:#fff
When to Use
| Diagram Type | Use Case |
|---|---|
flowchart TD | Process flows, decision trees |
flowchart LR | Pipelines, data flow |
sequenceDiagram | API calls, user interactions |
stateDiagram | State machines, lifecycles |
classDiagram | Architecture, relationships |
Migration from ASCII
Replace ASCII box diagrams:
Before (ASCII):
code
┌─────────┐ ┌─────────┐ │ Agent A │ -> │ Agent B │ └─────────┘ └─────────┘
After (Mermaid):
mermaid
flowchart LR
A[Agent A] --> B[Agent B]
Tips
- •Keep diagrams simple (max 10-15 nodes)
- •Use subgraphs for grouping
- •Add labels on important arrows
- •Use consistent naming across diagrams