Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "

C4 Architecture Documentation Generate software architecture documentation using C4 model diagrams in Mermaid syntax. Workflow 1. Understand scope Determine which C4 level(s) are needed based on audience 2. Analyze codebase Explore the system to identify components, containers, and relationships 3. Generate diagrams Create Mermaid C4 diagrams at appropriate abstraction levels 4. Document Write diagrams to markdown files with explanatory context C4 Diagram Levels Select the appropriate level based on the documentation need: Level Diagram Type Audience Shows When to Create 1 C4Context Everyone System + external actors Always (required) 2 C4Container Technical Apps, databases, services Always (required) 3 C4Component Developers Internal components Only if adds value 4 C4Deployment DevOps Infrastructure nodes For production systems C4Dynamic Technical Request flows (numbered) For complex workflows Key Insight: "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value. Quick Start Examples System Context (Level 1) Container Diagram (Level 2) Component Diagram (Level 3) Dynamic Diagram (Request Flow) Deployment Diagram Element Syntax People and Systems Containers Components Boundaries Relationships Deployment Nodes Styling and Layout Layout Configuration $c4ShapeInRow Number of shapes per row (default: 4) $c4BoundaryInRow Number of boundaries per row (default: 2) Element Styling Relationship Styling Use $offsetX and $offsetY to fix overlapping relationship labels. Best Practices Essential Rules 1. Every element must have : Name, Type, Technology (where applicable), and Description 2. Use unidirectional arrows only Bidirectional arrows create ambiguity 3. Label arrows with action verbs "Sends email using", "Reads from", not just "uses" 4. Include technology labels "JSON/HTTPS", "JDBC", "gRPC" 5. Stay under 20 elements per diagram Split complex systems into multiple diagrams Clarity Guidelines 1. Start at Level 1 Context diagrams help frame the system scope 2. One diagram per file Keep diagrams focused on a single abstraction level 3. Meaningful aliases Use descriptive aliases (e.g., orderService not s1 ) 4. Concise descriptions Keep descriptions under 50 characters when possible 5. Always include a title "System Context diagram for [System Name]" What to Avoid See [references/common mistakes.md](references/common mistakes.md) for detailed anti patterns: Confusing containers (deployable) vs components (non deployable) Modeling shared libraries as containers Showing message brokers as single containers instead of individual topics Adding undefined abstraction levels like "subcomponents" Removing type labels to "simplify" diagrams Microservices Guidelines Single Team Ownership Model each microservice as a container (or container group): Multi Team Ownership Promote microservices to software systems when owned by separate teams: Event Driven Architecture Show individual topics/queues as containers, NOT a single "Kafka" box: Output Location Write architecture documentation to docs/architecture/ with naming convention: c4 context.md System context diagram c4 containers.md Container diagram c4 components {feature}.md Component diagrams per feature c4 deployment.md Deployment diagram c4 dynamic {flow}.md Dynamic diagrams for specific flows Audience Appropriate Detail Audience Recommended Diagrams Executives System Context only Product Managers Context + Container Architects Context + Container + key Components Developers All levels as needed DevOps Container + Deployment References [references/c4 syntax.md](references/c4 syntax.md) Complete Mermaid C4 syntax [references/common mistakes.md](references/common mistakes.md) Anti patterns to avoid [references/advanced patterns.md](references/advanced patterns.md) Microservices, event driven, deployment

c4-architecture