1---2name: diagramming3description: |4 Use when creating software architecture diagrams, system visualizations, or technical drawings. Covers text-based and visual diagramming approaches for architecture communication.5 USE FOR: choosing diagram types, comparing diagramming tools, architecture visualization strategy, diagrams-as-code workflows, embedding diagrams in documentation6 DO NOT USE FOR: specific diagram syntax (use c4-diagrams, mermaidjs, uml, d2, plantuml, etc.), requirements documents (use documentation sub-skills)7license: MIT8metadata:9 displayName: "Diagramming"10 author: "Tyler-R-Kendrick"11compatibility: claude, copilot, cursor12references:13 - title: "C4 Model — Simon Brown"14 url: "https://c4model.com/"15 - title: "Mermaid.js Official Documentation"16 url: "https://mermaid.js.org/"17---1819# Diagramming2021## Overview22Architecture 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.2324## Diagram Types2526### Structural Diagrams27| Type | Purpose | Tools |28|------|---------|-------|29| C4 (Context, Container, Component, Code) | Hierarchical system decomposition | Structurizr DSL, Mermaid |30| Class diagrams | Object structure and relationships | UML, Mermaid, PlantUML |31| Component diagrams | Internal structure of containers | UML, C4 Level 3 |32| Entity-Relationship (ERD) | Data model relationships | Mermaid, dbdiagram.io |33| Package / Module diagrams | Code organization | UML, Mermaid |3435### Behavioral Diagrams36| Type | Purpose | Tools |37|------|---------|-------|38| Sequence diagrams | Interaction order between actors | Mermaid, PlantUML |39| Activity / Flowcharts | Process and decision flows | Mermaid, D2, BPMN |40| State diagrams | State machine transitions | Mermaid, PlantUML |41| Functional / Data flow | Data transformation pipelines | DFD, Mermaid |4243### Enterprise Architecture44| Type | Purpose | Tools |45|------|---------|-------|46| TOGAF ADM views | Enterprise architecture phases | Archi, Sparx EA |47| ArchiMate models | Business-application-technology layers | Archi, Sparx EA |4849## Diagrams-as-Code Tools5051| Tool | Language | Rendering | Best For |52|------|----------|-----------|----------|53| **Mermaid** | Markdown-like DSL | SVG (browser, GitHub) | Inline docs, PRs, wikis |54| **D2** | Declarative DSL | SVG, PNG, PDF | Architecture diagrams |55| **PlantUML** | Text DSL | PNG, SVG | UML diagrams |56| **Structurizr DSL** | C4-specific DSL | SVG, PNG | C4 model diagrams |5758## Best Practices59- Use "diagrams as code" tools (Mermaid, D2, PlantUML, Structurizr) so diagrams are version-controlled, diffable, and CI-renderable.60- Start with C4 Level 1 (Context) to establish boundaries, then zoom in to Level 2 (Container) and Level 3 (Component) as needed.61- Use Mermaid for diagrams inside Markdown files — GitHub, GitLab, and most documentation platforms render it natively.62- Use D2 or Structurizr for standalone architecture diagrams that need advanced layout control.63- Keep diagrams close to the code they describe — in the same repo, ideally the same directory.64- Include a legend or title on every diagram so readers understand the notation without prior knowledge.
Tyler-R-Kendrick