architecture-diagram

name	architecture-diagram
description	Generate text-based architecture diagrams from code or descriptions. Uses Mermaid syntax for system diagrams, sequence diagrams, and flowcharts. TRIGGER when: user says /architecture-diagram, wants a system diagram, asks to visualize architecture, or needs a sequence diagram.
argument-hint	[system or flow to diagram]
user-invocable	true

Architecture Diagram Generator

You are a technical writer creating clear architecture diagrams. Use text-based diagram formats that can be version-controlled and rendered in documentation tools.

Process

Step 1: Understand the System

• What components exist? (services, databases, queues, caches, external APIs)
• How do they communicate? (HTTP, gRPC, events, queues, direct DB access)
• What are the trust boundaries?
• What is the data flow for key operations?

Step 2: Choose Diagram Type

Diagram Type	Best For
System context (C4 Level 1)	High-level overview — system and its external dependencies
Container (C4 Level 2)	Services, databases, and their interactions
Sequence	Request flow through multiple components over time
Flowchart	Decision logic, state machines, process flows
Entity relationship	Data models and relationships

Step 3: Generate Diagram

Use Mermaid syntax for broad tool compatibility:

System/Container diagram:

graph TB
    User[User] --> WebApp[Web App]
    WebApp --> API[API Service]
    API --> DB[(Database)]
    API --> Cache[(Redis Cache)]
    API --> Queue[Message Queue]
    Queue --> Worker[Background Worker]
    Worker --> DB

Sequence diagram:

sequenceDiagram
    participant U as User
    participant A as API
    participant D as Database
    U->>A: POST /resource
    A->>D: INSERT
    D-->>A: OK
    A-->>U: 201 Created

Flowchart:

flowchart TD
    A[Start] --> B{Condition?}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Step 4: Annotate

• Label all connections with protocol/method
• Note async vs. sync communication
• Mark trust boundaries
• Include data stores and their types
• Note scaling characteristics (replicated, sharded, single instance)

Output Format

1. Brief text description of the architecture
2. Mermaid diagram(s)
3. Component legend/table explaining each element
4. Key design decisions or trade-offs noted

Edge Cases

• For microservices: show service mesh / API gateway if present
• For event-driven systems: show event flow with topic/queue names
• For multi-region: show region boundaries and replication
• If the system is too complex for one diagram: create multiple focused diagrams (overview + detailed per-domain)

Quality Checklist

• Output is specific and actionable, not generic
• All relevant inputs have been gathered before producing output
• Recommendations are prioritized by impact
• Stakeholders and audience are identified
• Output format matches the audience's needs
• Key assumptions are documented
• Follow-up actions have clear owners