| name | loom-diagramming |
| description | Create technical diagrams using Mermaid syntax for architecture, sequences, ERDs, flowcharts, and state machines. Use for visualizing system design, data flows, C4 models, and process diagrams in documentation. |
| triggers | ["diagram","diagrams","mermaid","plantuml","draw.io","excalidraw","flowchart","sequence diagram","class diagram","architecture diagram","ERD","entity relationship","entity-relationship","C4","C4 model","system context","container diagram","component diagram","state diagram","state machine","visualize","draw","chart","flow","data flow","API flow","system design","architecture visualization","UML"] |
Diagramming
Overview
Create maintainable technical diagrams in Mermaid (renders in GitHub, GitLab, and most doc tools). Diagrams live in version control next to code — they must stay in sync or they mislead. This skill covers type selection, syntax, and the parsing footguns that waste the most time.
Choose the diagram type
| Type | Use when | Not when |
|---|
| Sequence | Interactions over time across participants | Showing static structure |
| Flowchart | Decision logic, process/pipeline steps | Timing between services (use sequence) |
| State | An entity's lifecycle + transitions/guards | Data flow or call order |
| ERD | Data model, tables, cardinality | Runtime behavior |
| Class | OO structure, interfaces, inheritance | Deployment or infra |
| C4 (Context) | System boundary + external actors/systems | Internal code detail |
| C4 (Container) | Deployable units + their tech + data stores | Class-level detail |
Rule of thumb: structure → flowchart/C4/class/ERD; behavior over time → sequence; lifecycle → state. For architecture, prefer C4's layered zoom (Context → Container → Component) over one sprawling diagram.
Gotchas (Mermaid parsing footguns)
These cause silent render failures or garbled output far more often than logic errors.
end is reserved in flowcharts. A lowercase node id end breaks the parser. Use End, END, or quote it: id["end"]. Same care with subgraph/click/class as bare ids.- Quote labels with special characters. Parentheses
(), {}, [], #, :, ;, and quotes inside a label break parsing — wrap the text: A["fetch(url)"], B["step: parse"]. For literal special chars inside a quoted label, use HTML entities: #quot; won't work — use ", &, # (for #).
- Line breaks:
<br/> inside a label, not \n: A["Line one<br/>Line two"].
- Edge labels with special chars must be quoted:
A -->|"retry (max 3)"| B.
- Leading
o/x on an edge become arrowheads. A---oB renders a circle end, A---xB a cross. Add a space (A --- oB is still risky) or rename the node so an edge doesn't touch a bare o/x.
- Subgraph direction: set
direction LR inside the subgraph; note that edges crossing subgraph boundaries can override a subgraph's internal direction.
- Comments are
%% on their own line. Semicolons are optional line terminators.
- C4 diagrams (
C4Context/C4Container) have limited, sometimes experimental layout control and lag other Mermaid features — verify they render in your target tool before committing to them; a plain flowchart with subgraphs is a robust fallback.
- Don't build the giant diagram. Past ~15-20 nodes it's unreadable and un-reviewable. Split by concern or zoom level. One diagram, one idea.
Keep diagrams in sync
Diagrams are code artifacts: update the diagram in the same PR as the code it depicts, review it in the diff, and prefer a diagram that's easy to regenerate over a pixel-perfect one that rots. A wrong diagram is worse than none.
Syntax quick reference
- Direction:
flowchart TB (top-bottom), LR (left-right). Sequence diagrams auto-layout.
- Node shapes:
[Rect] process · (Rounded) start/end · {Diamond} decision · [(DB)] store · ((Circle)) connector.
- Edges:
--> solid · -.-> dotted/optional · ==> emphasis · ->> (sequence) sync message · -->> async/return.
- Sequence keywords:
participant, autonumber, alt/else/end, loop/end, par/and/end, Note over A,B.
Examples
C4 Context (Level 1)
C4Context
title System Context — E-Commerce Platform
Person(customer, "Customer", "Browses and purchases")
System(ecommerce, "E-Commerce Platform", "Core system")
System_Ext(payment, "Payment Gateway", "Processes payments")
Rel(customer, ecommerce, "Uses")
Rel(ecommerce, payment, "Charges", "HTTPS")
C4 Container (Level 2)
C4Container
title Containers — E-Commerce Platform
Person(customer, "Customer")
Container_Boundary(ec, "E-Commerce Platform") {
Container(web, "Web App", "React", "Customer UI")
Container(api, "API Gateway", "Node.js", "REST API")
ContainerDb(db, "Database", "PostgreSQL", "Stores data")
ContainerQueue(queue, "Queue", "RabbitMQ", "Async events")
}
Rel(customer, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads/writes")
Rel(api, queue, "Publishes")
Sequence — request flow with conditionals
sequenceDiagram
autonumber
participant C as Client
participant S as Service
participant D as Database
C->>S: POST /api/users
S->>S: Validate input
alt Validation fails
S-->>C: 400 Bad Request
else Valid
S->>D: INSERT user
alt Constraint violation
D-->>S: Duplicate key
S-->>C: 409 Conflict
else Success
D-->>S: Created
S-->>C: 201 Created
end
end
Sequence — parallel work
sequenceDiagram
participant O as Order Service
participant I as Inventory
participant P as Payment
par Check inventory and authorize payment
O->>I: Check stock
I-->>O: Available
and
O->>P: Authorize
P-->>O: Authorized
end
O->>P: Capture payment
Flowchart — decision logic
flowchart TD
A[User Login] --> B{Valid credentials?}
B -->|No| D[Show error]
D --> A
B -->|Yes| C{2FA enabled?}
C -->|No| G[Create session]
C -->|Yes| E[Send 2FA code]
E --> F{Code valid?}
F -->|Yes| G
F -->|No| H{Attempts < 3?}
H -->|Yes| E
H -->|No| I[Lock account]
G --> J[Dashboard]
ERD
Cardinality: || exactly one · o| zero-or-one · }| one-or-more · }o zero-or-more (left char = min, right char = max, read toward the entity).
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
ORDER_ITEM }|--|| PRODUCT : references
USER {
uuid id PK
string email UK
timestamp created_at
}
ORDER {
uuid id PK
uuid user_id FK
string status
}
State machine
stateDiagram-v2
[*] --> Draft: create
Draft --> Pending: submit
Pending --> Confirmed: payment received
Pending --> Cancelled: payment failed / timeout
Confirmed --> Shipped: fulfill
Shipped --> Delivered: confirmed
Delivered --> [*]
note right of Pending
Auto-cancels after 24h
end note
Class diagram
classDiagram
class Repository~T~ {
<<interface>>
+findById(id) T
+save(entity: T) T
}
class UserRepository {
-db: Database
+findByEmail(email) User
}
Repository~T~ <|.. UserRepository
UserRepository --> User
Verify before done
