diagramming

name	diagramming
description	Use when creating software architecture diagrams, system visualizations, or technical drawings. Covers text-based and visual diagramming approaches for architecture communication. USE FOR: choosing diagram types, comparing diagramming tools, architecture visualization strategy, diagrams-as-code workflows, embedding diagrams in documentation DO NOT USE FOR: specific diagram syntax (use c4-diagrams, mermaidjs, uml, d2, plantuml, etc.), requirements documents (use documentation sub-skills)
license	MIT
metadata	{"displayName":"Diagramming","author":"Tyler-R-Kendrick"}
compatibility	claude, copilot, cursor
references	[{"title":"C4 Model — Simon Brown","url":"https://c4model.com/"},{"title":"Mermaid.js Official Documentation","url":"https://mermaid.js.org/"}]

Diagramming

Overview

Architecture diagrams communicate system structure, behavior, and relationships visually. Modern "diagrams as code" tools let you version, diff, and automate diagram generation alongside your source code.

Diagram Types

Structural Diagrams

Type	Purpose	Tools
C4 (Context, Container, Component, Code)	Hierarchical system decomposition	Structurizr DSL, Mermaid
Class diagrams	Object structure and relationships	UML, Mermaid, PlantUML
Component diagrams	Internal structure of containers	UML, C4 Level 3
Entity-Relationship (ERD)	Data model relationships	Mermaid, dbdiagram.io
Package / Module diagrams	Code organization	UML, Mermaid

Behavioral Diagrams

Type	Purpose	Tools
Sequence diagrams	Interaction order between actors	Mermaid, PlantUML
Activity / Flowcharts	Process and decision flows	Mermaid, D2, BPMN
State diagrams	State machine transitions	Mermaid, PlantUML
Functional / Data flow	Data transformation pipelines	DFD, Mermaid

Enterprise Architecture

Type	Purpose	Tools
TOGAF ADM views	Enterprise architecture phases	Archi, Sparx EA
ArchiMate models	Business-application-technology layers	Archi, Sparx EA

Diagrams-as-Code Tools

Tool	Language	Rendering	Best For
Mermaid	Markdown-like DSL	SVG (browser, GitHub)	Inline docs, PRs, wikis
D2	Declarative DSL	SVG, PNG, PDF	Architecture diagrams
PlantUML	Text DSL	PNG, SVG	UML diagrams
Structurizr DSL	C4-specific DSL	SVG, PNG	C4 model diagrams

Best Practices

• Use "diagrams as code" tools (Mermaid, D2, PlantUML, Structurizr) so diagrams are version-controlled, diffable, and CI-renderable.
• Start with C4 Level 1 (Context) to establish boundaries, then zoom in to Level 2 (Container) and Level 3 (Component) as needed.
• Use Mermaid for diagrams inside Markdown files — GitHub, GitLab, and most documentation platforms render it natively.
• Use D2 or Structurizr for standalone architecture diagrams that need advanced layout control.
• Keep diagrams close to the code they describe — in the same repo, ideally the same directory.
• Include a legend or title on every diagram so readers understand the notation without prior knowledge.