plantuml-diagram-guide

PlantUML Diagram Type Guide

Use this guide to choose the right PlantUML diagram type for documentation. When creating or updating .md files, proactively suggest and use the appropriate diagram type.

IMPORTANT: Every diagram MUST include a title directive immediately after the opening tag. This makes diagrams self-documenting. Example: title User Authentication Flow

Color coding: Read references/colors.md for the muted pastel palette, color support by diagram type, and legend guidance.

Behavioral Diagrams (how things work)

Type	When to use	When to suggest	Syntax
Sequence	Interactions between processes/services, API call flows, request-response chains. For ≤ 10 arrows add hide footbox; for longer diagrams keep footbox for navigation	Spec files with pipeline/API descriptions; new inter-process communication	@startuml with ->, -->, ->>
Activity	Algorithms, business logic, decision trees, branching flows, parallel processes	Decision log entries; complex functions with many branches; CI/CD procedures	@startuml with start, :action;, if/then/else, fork
State	State machines, object lifecycles, connection/session/process states	Code with if/else chains that implement a state machine; specs describing behavior with distinct states	@startuml with [*] -->, state
Use Case	Functional requirements, actor-system interactions, feature overview	PRD files; new feature overview; user stories	@startuml with actor, usecase, -->
Timing	Time-based event characteristics, latency profiling, synchronization, timeout/retry logic	Performance documentation; pipeline latency analysis	@startuml with concise/robust, @

Before creating any sequence diagram, read references/sequence.md for ACK suppression rules, arrow conventions, and visual styling defaults.

Structural Diagrams (how things are built)

Type	When to use	When to suggest	Syntax
Component / Package	High-level system architecture, layers, module dependencies	Architecture docs; adding new modules; specs showing system composition	@startuml with package, component, [name]
Class	Class hierarchies, interfaces, data models (dataclasses, Pydantic), entity relationships	Adding new classes/models; refactoring class hierarchy; storage/query models	@startuml with class, interface, inheritance arrows
Object	Snapshot of object instances with actual data at a specific point in time	Debugging documentation; showing concrete state examples; test data illustration	@startuml with object, field values
ER (Entity-Relationship)	Database schemas, table relationships with cardinalities (1:N, M:N)	Database storage design; any database work	@startuml with entity, field definitions, ||--o{
Deployment	Physical deployment topology: processes, threads, file system, cache, network	Architecture deployment docs; Web UI with server + WebSocket	@startuml with node, artifact, database
Network (nwdiag)	Network topology, servers, subnets, ports	Infrastructure documentation; service communication topology	@startuml with nwdiag { network ... }

Data & Structure Visualization

Type	When to use	When to suggest	Syntax
JSON	Visualize data structures, config files, API request/response formats	API contract documentation; config file structure	@startjson
YAML	Same as JSON but for YAML-formatted configs	YAML config documentation	@startyaml

Project Management & Planning

Type	When to use	When to suggest	Syntax
MindMap	Brainstorming, idea hierarchies, feature categorization, project structure overview	Planning new phases; feature overview; backlog/roadmap organization	@startmindmap with *, **, ***
Gantt	Project timelines, phase planning, task dependencies, milestones	Roadmap documentation; sprint/phase planning	@startgantt with [Task] lasts X days
WBS	Work decomposition, task hierarchy, scope visualization	Planning a new phase; breaking Epic into Stories/Tasks	@startwbs with *, **
Wireframe (Salt)	UI mockups, interface layouts, form structures	UI design; UI-related PRDs	@startsalt with { } layout blocks

Quick Selection Guide

• "Who sends what to whom?" → Sequence
• "What are the system parts?" → Component / Package
• "What states can this be in?" → State
• "What's the algorithm/flow?" → Activity
• "What can users do?" → Use Case
• "What do the classes look like?" → Class
• "What's in the database?" → ER Diagram
• "Where does it run?" → Deployment
• "What's the config/data format?" → JSON/YAML
• "How long does each step take?" → Timing
• "What's the plan/scope?" → MindMap, WBS, or Gantt
• "What will the UI look like?" → Wireframe (Salt)
• "What's the network setup?" → Network (nwdiag)
• "What does a concrete instance look like?" → Object