| 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
- Brief text description of the architecture
- Mermaid diagram(s)
- Component legend/table explaining each element
- 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
