/architecture-diagrams

name: architecture-diagrams
description: >
  Create system architecture diagrams using Mermaid, PlantUML, C4 model,
  flowcharts, and sequence diagrams. Use when documenting architecture, system
  design, data flows, or technical workflows.

Architecture Diagrams

Table of Contents

• [Overview](#overview)
• [When to Use](#when-to-use)
• [Quick Start](#quick-start)
• [Reference Guides](#reference-guides)
• [Best Practices](#best-practices)

Overview

Create clear, maintainable architecture diagrams using code-based diagramming tools like Mermaid and PlantUML for system design, data flows, and technical documentation.

When to Use

• System architecture documentation
• C4 model diagrams
• Data flow diagrams
• Sequence diagrams
• Component relationships
• Deployment diagrams
• Infrastructure architecture
• Microservices architecture
• Database schemas (visual)
• Integration patterns

Quick Start

Minimal working example:

graph TB
    subgraph "Client Layer"
        Web[Web App]
        Mobile[Mobile App]
        CLI[CLI Tool]
    end

    subgraph "API Gateway Layer"
        Gateway[API Gateway<br/>Rate Limiting<br/>Authentication]
    end

    subgraph "Service Layer"
        Auth[Auth Service]
        User[User Service]
        Order[Order Service]
        Payment[Payment Service]
        Notification[Notification Service]
    end

    subgraph "Data Layer"
        UserDB[(User DB<br/>PostgreSQL)]
        OrderDB[(Order DB<br/>PostgreSQL)]
        Cache[(Redis Cache)]
        Queue[Message Queue<br/>RabbitMQ]
    end
// ... (see reference guides for full implementation)

Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents | |---|---| | [System Architecture Diagram](references/system-architecture-diagram.md) | System Architecture Diagram | | [Sequence Diagram](references/sequence-diagram.md) | Sequence Diagram | | [C4 Context Diagram](references/c4-context-diagram.md) | C4 Context Diagram | | [Component Diagram](references/component-diagram.md) | Component Diagram | | [Deployment Diagram](references/deployment-diagram.md) | Deployment Diagram | | [Data Flow Diagram](references/data-flow-diagram.md) | Data Flow Diagram | | [Class Diagram](references/class-diagram.md) | Class Diagram | | [Component Diagram](references/component-diagram-2.md) | Component Diagram | | [Deployment Diagram](references/deployment-diagram-2.md) | Deployment Diagram |

Best Practices

✅ DO

• Use consistent notation and symbols
• Include legends for complex diagrams
• Keep diagrams focused on one aspect
• Use color coding meaningfully
• Include titles and descriptions
• Version control your diagrams
• Use text-based formats (Mermaid, PlantUML)
• Show data flow direction clearly
• Include deployment details
• Document diagram conventions
• Keep diagrams up-to-date with code
• Use subgraphs for logical grouping

❌ DON'T

• Overcrowd diagrams with details
• Use inconsistent styling
• Skip diagram legends
• Create binary image files only
• Forget to document relationships
• Mix abstraction levels in one diagram
• Use proprietary formats