Quick Reference

Diagram Type	Syntax	Best For
C4 Context/Container	PlantUML + C4 stdlib	Architecture overview
Sequence	PlantUML	API flows, interactions
Class	PlantUML	Domain models
State	PlantUML or Mermaid	State machines
Flowchart	Mermaid	Simple flows, decisions
ERD	DBML or PlantUML	Database schemas
Network/Infra	D2	Modern architecture

C4 Diagrams

Context Diagram

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(user, "User", "Description")
System(system, "System", "What it does")
System_Ext(external, "External", "Third party")

Rel(user, system, "Uses")
Rel(system, external, "Calls")
SHOW_LEGEND()
@enduml

Container Diagram

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(system, "System") {
    Container(web, "Web App", "React", "UI")
    Container(api, "API", "Go", "Business logic")
    ContainerDb(db, "Database", "PostgreSQL", "Data store")
}

Rel(user, web, "Uses", "HTTPS")
Rel(web, api, "Calls", "JSON/HTTPS")
Rel(api, db, "Reads/Writes", "SQL")
SHOW_LEGEND()
@enduml

Sequence Diagrams

@startuml
actor User
participant "Web" as W
participant "API" as A
database "DB" as D

User -> W: Submit form
activate W
W -> A: POST /resource
activate A
A -> D: INSERT
D --> A: OK
A --> W: 201 Created
deactivate A
W --> User: Success
deactivate W
@enduml

State Machines

@startuml
[*] --> Draft
Draft --> Pending : submit
Pending --> Approved : approve
Pending --> Rejected : reject
Approved --> Active : activate
Active --> [*] : complete
Rejected --> Draft : revise
@enduml

Flowcharts (Mermaid)

flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Entity Relationships (DBML)

Table users {
  id uuid [pk]
  email varchar [unique, not null]
  created_at timestamp [default: `now()`]
}

Table orders {
  id uuid [pk]
  user_id uuid [ref: > users.id]
  status order_status
}

Enum order_status {
  pending
  completed
  cancelled
}

D2 Architecture

direction: right

user: User { shape: person }
system: {
  web: Web App
  api: API
  db: Database { shape: cylinder }

  web -> api: REST
  api -> db: SQL
}
external: External API { shape: cloud }

user -> system.web
system.api -> external

File Organization

diagrams/
├── architecture/
│   ├── c4-context.puml
│   └── c4-container.puml
├── behavior/
│   ├── sequence-{flow}.puml
│   └── state-{entity}.puml
├── data/
│   └── erd-{domain}.dbml
└── rendered/
    ├── png/
    └── svg/

Workflow

Choose diagram type based on what you're documenting
Write diagram source using appropriate syntax
Render via MCP: uml:render_plantuml or uml:render_mermaid
Save source to diagrams/ directory
Generated images go to diagrams/rendered/

Naming Convention

{type}-{subject}.{ext}

Examples:

c4-context.puml
sequence-user-login.puml
state-order.puml
erd-users.dbml

diagrams-kroki

Diagram Generation with Kroki

MCP Setup