Decision guidance for selecting the right diagram type and tool. Provides patterns for common visualization scenarios, tool comparison, and best practices.
Limited to specific tools
Additional assets for this skill
This skill is limited to using the following tools:
This skill helps you choose the right diagram type and tool for your visualization needs. Use this when you need to decide:
START
|
+-- Interactions over time? --> SEQUENCE DIAGRAM
|
+-- Object/class structure? --> CLASS DIAGRAM
|
+-- Database schema? --> ER DIAGRAM
|
+-- State transitions? --> STATE DIAGRAM
|
+-- Process/workflow? --> FLOWCHART or ACTIVITY DIAGRAM
|
+-- System architecture?
| |
| +-- High-level context? --> C4 CONTEXT
| +-- Containers/services? --> C4 CONTAINER or COMPONENT
| +-- Infrastructure? --> DEPLOYMENT DIAGRAM
|
+-- Project timeline? --> GANTT CHART
|
+-- Git branching? --> GIT GRAPH (Mermaid only)
|
+-- Hierarchical ideas? --> MINDMAP (PlantUML only)
|
+-- Data structure? --> JSON DIAGRAM (PlantUML only)
| Need | Recommended Tool | Reason |
|---|---|---|
| GitHub/GitLab rendering | Mermaid | Native support |
| Complex C4 models | PlantUML | Mature, better rendering |
| Simple sequence/class | Mermaid | Simpler syntax |
| MindMaps | PlantUML | Only option |
| JSON visualization | PlantUML | Only option |
| GitGraph | Mermaid | Only option |
| ER diagrams | Mermaid | Better default rendering |
| State diagrams | Mermaid | Cleaner output |
| Maximum customization | PlantUML | More styling options |
| Zero setup | Mermaid | Browser-based |
| Enterprise architecture | PlantUML | Better ArchiMate, C4 |
| Feature | Mermaid | PlantUML |
|---|---|---|
| Setup | None (browser) | Java + GraphViz |
| Markdown integration | Native (GitHub, GitLab) | Requires image embedding |
| Learning curve | Gentle | Steeper |
| Customization | Limited | Extensive |
| C4 support | Experimental | Mature |
| Diagram types | ~10 | 15+ |
| JSON/MindMap | No | Yes |
| GitGraph | Yes | No |
| Rendering quality | Good | Good |
| Version control | Inline in Markdown | Separate .puml files |
sequenceDiagram
actor User
participant FE as Frontend
participant API as API Server
participant DB as Database
User->>FE: Action
FE->>+API: Request
API->>+DB: Query
DB-->>-API: Data
API-->>-FE: Response
FE-->>User: Update UI
sequenceDiagram
actor User
participant App as Application
participant Auth as Auth Service
participant Token as Token Store
User->>App: Login request
App->>Auth: Validate credentials
alt Valid
Auth->>Token: Generate token
Token-->>Auth: JWT
Auth-->>App: Success + JWT
App-->>User: Redirect to dashboard
else Invalid
Auth-->>App: 401 Unauthorized
App-->>User: Show error
end
sequenceDiagram
participant Client
participant API
participant Queue
participant Worker
Client->>API: Submit job
API->>Queue: Enqueue task
API-->>Client: 202 Accepted + job ID
Worker->>Queue: Poll for tasks
Queue-->>Worker: Task data
Worker->>Worker: Process
Client->>API: Check status (polling)
API-->>Client: Status: processing
Worker->>API: Report completion
Client->>API: Check status
API-->>Client: Status: complete + result
classDiagram
class Entity {
<<abstract>>
+UUID id
+DateTime createdAt
+DateTime updatedAt
}
class User {
+String email
+String name
+authenticate()
}
class Order {
+OrderStatus status
+Money total
+submit()
+cancel()
}
class OrderItem {
+int quantity
+Money price
}
Entity <|-- User
Entity <|-- Order
User "1" --> "*" Order : places
Order "1" *-- "*" OrderItem : contains
classDiagram
class IRepository~T~ {
<<interface>>
+findById(id) T
+findAll() List~T~
+save(entity) T
+delete(id) void
}
class UserRepository {
+findByEmail(email) User
}
class InMemoryUserRepository {
-Map~UUID,User~ store
}
class PostgresUserRepository {
-DataSource ds
}
IRepository~T~ <|.. UserRepository
UserRepository <|-- InMemoryUserRepository
UserRepository <|-- PostgresUserRepository
classDiagram
class OrderService {
-OrderRepository orderRepo
-PaymentService paymentService
-InventoryService inventoryService
+createOrder(request) Order
+cancelOrder(orderId) void
}
class PaymentService {
-PaymentGateway gateway
+processPayment(order) PaymentResult
+refund(paymentId) void
}
class InventoryService {
-InventoryRepository inventoryRepo
+reserve(items) Reservation
+release(reservationId) void
}
OrderService --> PaymentService
OrderService --> InventoryService
erDiagram
USER {
uuid id PK
string email UK
string password_hash
string name
timestamp created_at
}
POST {
uuid id PK
uuid author_id FK
string title
text content
enum status
timestamp published_at
}
COMMENT {
uuid id PK
uuid post_id FK
uuid user_id FK
text content
timestamp created_at
}
TAG {
uuid id PK
string name UK
}
POST_TAG {
uuid post_id PK,FK
uuid tag_id PK,FK
}
USER ||--o{ POST : writes
USER ||--o{ COMMENT : writes
POST ||--o{ COMMENT : has
POST ||--o{ POST_TAG : has
TAG ||--o{ POST_TAG : has
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : "ordered in"
PRODUCT }|--|| CATEGORY : "belongs to"
CUSTOMER ||--o{ ADDRESS : has
ORDER ||--|| ADDRESS : "ships to"
ORDER ||--o| PAYMENT : "paid by"
CUSTOMER {
uuid id PK
string email UK
string name
}
ORDER {
uuid id PK
uuid customer_id FK
uuid shipping_address_id FK
enum status
decimal total
}
ORDER_ITEM {
uuid order_id PK,FK
uuid product_id PK,FK
int quantity
decimal unit_price
}
PRODUCT {
uuid id PK
string sku UK
string name
decimal price
int stock
}
stateDiagram-v2
[*] --> Draft
Draft --> Submitted : submit
Submitted --> Confirmed : confirm
Submitted --> Cancelled : cancel
Confirmed --> Processing : process
Processing --> Shipped : ship
Processing --> Cancelled : cancel
Shipped --> Delivered : deliver
Shipped --> Returned : return
Delivered --> [*]
Returned --> Refunded : refund
Refunded --> [*]
Cancelled --> [*]
stateDiagram-v2
[*] --> Anonymous
Anonymous --> Authenticating : login
Authenticating --> Authenticated : success
Authenticating --> Anonymous : failure
Authenticated --> Anonymous : logout
Authenticated --> TokenRefresh : token_expiring
TokenRefresh --> Authenticated : refresh_success
TokenRefresh --> Anonymous : refresh_failure
flowchart TD
Start([Start]) --> Q1{Is it urgent?}
Q1 -->|Yes| Q2{Is it important?}
Q1 -->|No| Q3{Is it important?}
Q2 -->|Yes| Do[Do it now]
Q2 -->|No| Delegate[Delegate it]
Q3 -->|Yes| Schedule[Schedule it]
Q3 -->|No| Eliminate[Eliminate it]
Do --> End([End])
Delegate --> End
Schedule --> End
Eliminate --> End
flowchart TD
Request([Request]) --> Validate{Valid?}
Validate -->|Yes| Process[Process Request]
Validate -->|No| ValidationError[Return 400]
Process --> ExternalCall[Call External API]
ExternalCall --> Success{Success?}
Success -->|Yes| Transform[Transform Response]
Success -->|No| Retry{Retries left?}
Retry -->|Yes| Wait[Wait & Retry]
Wait --> ExternalCall
Retry -->|No| ServiceError[Return 503]
Transform --> Cache[Cache Result]
Cache --> Response([Return 200])
ValidationError --> End([End])
ServiceError --> End
Response --> End
C4Context
title System Context - E-Commerce Platform
Person(customer, "Customer", "Online shopper")
Person(admin, "Admin", "Store administrator")
System(ecommerce, "E-Commerce Platform", "Main shopping platform")
System_Ext(payment, "Payment Gateway", "Stripe")
System_Ext(shipping, "Shipping Provider", "FedEx API")
System_Ext(email, "Email Service", "SendGrid")
Rel(customer, ecommerce, "Browses, purchases")
Rel(admin, ecommerce, "Manages products, orders")
Rel(ecommerce, payment, "Processes payments")
Rel(ecommerce, shipping, "Creates shipments")
Rel(ecommerce, email, "Sends notifications")
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml
title Container Diagram - E-Commerce Platform
Person(customer, "Customer", "Online shopper")
System_Boundary(platform, "E-Commerce Platform") {
Container(web, "Web Application", "React", "Customer-facing storefront")
Container(admin, "Admin Panel", "React", "Back-office management")
Container(api, "API Gateway", "Node.js", "API routing and auth")
Container(catalog, "Catalog Service", "Go", "Product management")
Container(orders, "Order Service", "Go", "Order processing")
Container(cart, "Cart Service", "Go", "Shopping cart")
ContainerDb(db, "Database", "PostgreSQL", "Persistent storage")
Container(cache, "Cache", "Redis", "Session and product cache")
Container(queue, "Message Queue", "RabbitMQ", "Async processing")
}
Rel(customer, web, "Uses", "HTTPS")
Rel(web, api, "API calls", "REST")
Rel(admin, api, "API calls", "REST")
Rel(api, catalog, "Routes to")
Rel(api, orders, "Routes to")
Rel(api, cart, "Routes to")
Rel(catalog, db, "Reads/Writes")
Rel(orders, db, "Reads/Writes")
Rel(cart, cache, "Reads/Writes")
Rel(orders, queue, "Publishes")
@enduml
<<Entity>>, <<Service>>)| Question | If Yes, Use |
|---|---|
| Showing message flow between systems? | Sequence |
| Modeling OOP classes and relationships? | Class |
| Documenting database tables? | ER |
| Showing valid state transitions? | State |
| Depicting a process or algorithm? | Flowchart |
| High-level system overview? | C4 Context |
| Service/container architecture? | C4 Container |
| Timeline or schedule? | Gantt |
| Git branching strategy? | Git Graph |
| Brainstorming hierarchy? | MindMap |
For detailed syntax reference:
visualization:mermaid-syntax skillvisualization:plantuml-syntax skillLast Updated: 2025-12-06