architecture-diagramming

Architecture Diagramming Skill

Generate clear, GitHub-compatible Mermaid architecture diagrams that visualize system components, layers, boundaries, and data flows.

When to Use

Activate this skill when:

• User asks for an architecture diagram
• User says "show me the system architecture", "diagram the components"
• During project planning to visualize the system design
• When explaining how components interact

When NOT to use: not for issue/task dependencies (use dependency-mapping) or API call sequences and process flows (use mermaid-diagrams sequence diagrams).

CRITICAL: Mermaid Syntax Rules

NEVER use parentheses inside labels

Parentheses in Mermaid labels cause rendering errors on GitHub.

WRONG - Will break:

flowchart TD
    A[Component (main)]
    B[Service (auth)]

CORRECT - Use dashes or commas:

flowchart TD
    A[Component - main]
    B[Service - auth]

ALWAYS ensure matching brackets

Each node shape uses specific brackets that must match:

• [Rectangle] - Standard component
• {Diamond} - Decision point
• ([Stadium]) - Pill shape
• [(Database)] - Cylinder for data stores
• ((Circle)) - Circle node

WRONG:

flowchart TD
    A{Decision]

CORRECT:

flowchart TD
    A{Decision}

For other syntax rules, see the mermaid-diagrams skill.

Diagram Patterns

System Overview

Show major components and their relationships:

flowchart TB
    subgraph Client Layer
        Web[Web App]
        Mobile[Mobile App]
    end

    subgraph API Layer
        Gateway[API Gateway]
        Auth[Auth Service]
    end

    subgraph Data Layer
        DB[(Database)]
        Cache[(Redis Cache)]
    end

    Web --> Gateway
    Mobile --> Gateway
    Gateway --> Auth
    Gateway --> DB
    Auth --> Cache

Layered Architecture

Show horizontal layers with clear boundaries:

flowchart TB
    subgraph Presentation
        UI[User Interface]
        API[REST API]
    end

    subgraph Business
        Services[Business Services]
        Rules[Business Rules]
    end

    subgraph Data
        Repos[Repositories]
        Entities[Domain Entities]
    end

    UI --> Services
    API --> Services
    Services --> Rules
    Services --> Repos
    Repos --> Entities