Help us improve
Share bugs, ideas, or general feedback.
From acc
Reference for Mermaid syntax (flowchart, sequence, class, ER, state), C4 model levels, diagram types, and examples for technical diagrams.
npx claudepluginhub dykyi-roman/awesome-claude-code --plugin accHow this skill is triggered โ by the user, by Claude, or both
Slash command
/acc:diagram-knowledgeThe summary Claude sees in its skill listing โ used to decide when to auto-load this skill
Quick reference for technical diagrams, Mermaid syntax, and C4 model.
Provides Mermaid templates for flowcharts, sequence diagrams, class diagrams, ER diagrams, and C4 models for technical documentation.
Guides selection of diagram types (sequence, C4, ER, flowchart, etc.) and tools (Mermaid vs PlantUML) based on purpose like architecture, workflows, data. Use for visualization decisions.
Create C4 context, container, component, and code diagrams. Visualize architecture at different abstraction levels. Use when communicating system structure to diverse audiences.
Share bugs, ideas, or general feedback.
Quick reference for technical diagrams, Mermaid syntax, and C4 model.
| Type | Use Case | When to Use |
|---|---|---|
| C4 Context | System boundaries | External actors, systems |
| C4 Container | Deployable units | Apps, databases, services |
| C4 Component | Internal structure | Classes, modules in container |
| Sequence | Interactions | Request flows, protocols |
| Class | Structure | Domain model, relationships |
| ER | Data | Database schema |
| Flowchart | Process | Algorithms, decisions |
| State | Lifecycle | Entity states, transitions |
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Action 1]
B -->|No| D[Action 2]
C --> E[End]
D --> E
Syntax:
flowchart TD|TB|BT|LR|RL
id[Rectangle]
id(Rounded)
id{Diamond}
id([Stadium])
id[[Subroutine]]
id[(Database)]
id((Circle))
sequenceDiagram
participant C as Client
participant A as API
participant D as Database
C->>A: POST /users
A->>D: INSERT user
D-->>A: user_id
A-->>C: 201 Created
Syntax:
->> Solid arrow (sync)
-->> Dashed arrow (async/response)
-) Open arrow
--) Dashed open arrow
Note right of A: Note text
loop Loop name
actions
end
alt Condition
actions
else Other
actions
end
classDiagram
class Order {
-OrderId id
-OrderStatus status
+confirm() void
+cancel() void
}
class OrderItem {
-ProductId productId
-int quantity
}
Order "1" *-- "*" OrderItem : contains
Relationships:
<|-- Inheritance
*-- Composition
o-- Aggregation
--> Association
-- Link
..> Dependency
..|> Implementation
stateDiagram-v2
[*] --> Pending
Pending --> Confirmed : confirm()
Pending --> Cancelled : cancel()
Confirmed --> Shipped : ship()
Confirmed --> Cancelled : cancel()
Shipped --> Delivered : deliver()
Delivered --> [*]
Cancelled --> [*]
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
ORDER_ITEM }o--|| PRODUCT : references
USER {
uuid id PK
string email UK
string name
}
ORDER {
uuid id PK
uuid user_id FK
string status
}
Cardinality:
||--|{ One to many
}|--|{ Many to many
||--|| One to one
||--o{ One to zero-or-many
Shows system and external actors.
flowchart TB
subgraph boundary[System Boundary]
S[("๐ฅ๏ธ E-Commerce System")]
end
U[("๐ค Customer")]
PS[("๐ณ Payment Service")]
ES[("๐ง Email Service")]
U -->|"Browse, Order"| S
S -->|"Process payment"| PS
S -->|"Send notifications"| ES
Shows deployable units.
flowchart TB
subgraph boundary[E-Commerce System]
WA[("๐ Web App\nReact")]
API[("โ๏ธ API\nPHP/Symfony")]
DB[("๐๏ธ Database\nPostgreSQL")]
CACHE[("๐พ Cache\nRedis")]
MQ[("๐ฌ Queue\nRabbitMQ")]
end
WA -->|"REST/JSON"| API
API -->|"SQL"| DB
API -->|"Cache"| CACHE
API -->|"Publish"| MQ
Shows internal structure.
flowchart TB
subgraph api[API Container]
direction TB
subgraph presentation[Presentation]
AC[Action]
RS[Responder]
end
subgraph application[Application]
UC[UseCase]
SV[Service]
end
subgraph domain[Domain]
EN[Entity]
VO[ValueObject]
RP[Repository Interface]
end
subgraph infra[Infrastructure]
RI[Repository Impl]
AD[Adapter]
end
end
AC --> UC
UC --> EN
UC --> RP
RI -.-> RP
| Principle | Description | Example |
|---|---|---|
| 7ยฑ2 Rule | Max 5-9 elements | Aggregate related items |
| Clear labels | Descriptive names | "User Service" not "S1" |
| Consistent style | Same shapes = same type | Rectangles for services |
| Flow direction | Top-down or left-right | Pick one per diagram |
| Context first | Start high-level | C4 Context โ Container |
โ
Good:
- "Payment Service" (descriptive)
- "PostgreSQL Database" (specific)
- "POST /orders" (action-based)
โ Bad:
- "Service A" (meaningless)
- "DB" (ambiguous)
- "Process" (vague)
# Top-down flow (recommended for hierarchies)
flowchart TD
# Left-right (recommended for timelines)
flowchart LR
# Subgraphs for grouping
subgraph name[Label]
content
end
# Styling
style id fill:#f9f,stroke:#333
classDef className fill:#f9f
class id1,id2 className
| Antipattern | Problem | Fix |
|---|---|---|
| Spaghetti | Too many crossing lines | Reorder, use subgraphs |
| Kitchen sink | Everything in one diagram | Split by level/aspect |
| Mystery meat | Cryptic labels | Use full names |
| Outdated | Doesn't match code | Automate from code |
| No legend | Unknown symbols | Add legend/key |
| Invisible boundaries | Unclear scope | Add subgraphs |
| Tool | Type | Best For | Pros | Cons |
|---|---|---|---|---|
| Mermaid | Text-based | Documentation-as-code | Git-friendly, embeds in MD, live preview | Limited styling, complex layouts hard |
| PlantUML | Text-based | UML diagrams | Full UML support, more diagram types | Requires Java, slower rendering |
| Draw.io | GUI | Quick prototypes, business diagrams | Free, intuitive, many templates | Binary files, merge conflicts |
| Excalidraw | GUI | Sketches, whiteboarding | Hand-drawn style, collaborative | Less precise, limited exports |
| Lucidchart | GUI | Enterprise, presentations | Professional output, integrations | Paid, not text-based |
| Scenario | Recommended Tool |
|---|---|
| Code documentation (README, docs/) | Mermaid |
| Strict UML compliance required | PlantUML |
| Quick whiteboard session | Excalidraw |
| Stakeholder presentations | Draw.io or Lucidchart |
| CI/CD pipeline diagrams | Mermaid (auto-generate) |
| Living documentation (auto-update) | Mermaid + code generation |
| Feature | Mermaid | PlantUML | Draw.io | Excalidraw |
|---|---|---|---|---|
| Version control friendly | โ | โ | โ | โ ๏ธ JSON |
| GitHub/GitLab rendering | โ | โ | โ | โ |
| No install required | โ | โ | โ | โ |
| Offline support | โ ๏ธ | โ | โ | โ |
| C4 model support | โ | โ | Manual | Manual |
| Export to PNG/SVG | โ | โ | โ | โ |
| Real-time collaboration | โ | โ | โ | โ |
What are you documenting?
โ
โโ System overview โ C4 Context
โ
โโ Deployment units โ C4 Container
โ
โโ Internal structure โ C4 Component / Class
โ
โโ Data flow
โ โโ Request/Response โ Sequence
โ โโ Data processing โ Flowchart
โ
โโ Data structure
โ โโ Domain model โ Class
โ โโ Database โ ER
โ
โโ Behavior
โโ State machine โ State
โโ Algorithm โ Flowchart
flowchart TB
subgraph presentation[Presentation Layer]
direction LR
A[Action]
R[Responder]
end
subgraph application[Application Layer]
direction LR
UC[UseCase]
DTO[DTO]
end
subgraph domain[Domain Layer]
direction LR
E[Entity]
VO[Value Object]
DS[Domain Service]
RI[Repository Interface]
end
subgraph infrastructure[Infrastructure Layer]
direction LR
RImpl[Repository]
Adapter[Adapter]
end
presentation --> application
application --> domain
infrastructure -.-> domain
flowchart LR
subgraph commands[Write Side]
CMD[Command] --> CH[CommandHandler]
CH --> AR[Aggregate]
AR --> EV[Event]
end
subgraph queries[Read Side]
Q[Query] --> QH[QueryHandler]
QH --> RM[ReadModel]
end
EV -.-> RM
For detailed information, load these reference files:
references/mermaid-syntax.md โ Complete Mermaid syntax referencereferences/c4-model.md โ C4 model detailed guidereferences/sequence-patterns.md โ Common sequence diagram patternsreferences/diagram-tools.md โ Tools and automation