1---2name: diagramming3description: 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)4license: MIT5---67# Diagramming89## Overview10Architecture 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.1112## Diagram Types1314### Structural Diagrams15| Type | Purpose | Tools |16|------|---------|-------|17| C4 (Context, Container, Component, Code) | Hierarchical system decomposition | Structurizr DSL, Mermaid |18| Class diagrams | Object structure and relationships | UML, Mermaid, PlantUML |19| Component diagrams | Internal structure of containers | UML, C4 Level 3 |20| Entity-Relationship (ERD) | Data model relationships | Mermaid, dbdiagram.io |21| Package / Module diagrams | Code organization | UML, Mermaid |2223### Behavioral Diagrams24| Type | Purpose | Tools |25|------|---------|-------|26| Sequence diagrams | Interaction order between actors | Mermaid, PlantUML |27| Activity / Flowcharts | Process and decision flows | Mermaid, D2, BPMN |28| State diagrams | State machine transitions | Mermaid, PlantUML |29| Functional / Data flow | Data transformation pipelines | DFD, Mermaid |3031### Enterprise Architecture32| Type | Purpose | Tools |33|------|---------|-------|34| TOGAF ADM views | Enterprise architecture phases | Archi, Sparx EA |35| ArchiMate models | Business-application-technology layers | Archi, Sparx EA |3637## Diagrams-as-Code Tools3839| Tool | Language | Rendering | Best For |40|------|----------|-----------|----------|41| **Mermaid** | Markdown-like DSL | SVG (browser, GitHub) | Inline docs, PRs, wikis |42| **D2** | Declarative DSL | SVG, PNG, PDF | Architecture diagrams |43| **PlantUML** | Text DSL | PNG, SVG | UML diagrams |44| **Structurizr DSL** | C4-specific DSL | SVG, PNG | C4 model diagrams |4546## Best Practices47- Use "diagrams as code" tools (Mermaid, D2, PlantUML, Structurizr) so diagrams are version-controlled, diffable, and CI-renderable.48- Start with C4 Level 1 (Context) to establish boundaries, then zoom in to Level 2 (Container) and Level 3 (Component) as needed.49- Use Mermaid for diagrams inside Markdown files — GitHub, GitLab, and most documentation platforms render it natively.50- Use D2 or Structurizr for standalone architecture diagrams that need advanced layout control.51- Keep diagrams close to the code they describe — in the same repo, ideally the same directory.52- Include a legend or title on every diagram so readers understand the notation without prior knowledge.
Tyler-R-Kendrick