Architecture Diagram Generation
Generate visual architecture diagrams using Mermaid or PlantUML C4 syntax.Command
Description
Creates architecture diagrams from your project context using industry-standard notations. Supports C4 model (Context, Container, Component), deployment diagrams, sequence diagrams, and data flow diagrams.Arguments
- Diagram type and subject: Type and focus area (e.g., ‘C4 context booking system’, ‘sequence login’, ‘deployment AWS’)
When to Use
- After requirements definition
- Before or during HLD/DLD phases
- For stakeholder communication
- Design review documentation
- Implementation planning
Required Context
- Requirements (ARC--REQ-.md) - Recommended
- HLD (vendors//hld-v*.md) - For container/component diagrams
- DLD (vendors//dld-v*.md) - For component diagrams
- Wardley Maps (WARD) - For evolution context
- Architecture Principles (PRIN) - For constraints
Interactive Configuration
The command prompts for:-
Diagram type:
- C4 Context (Recommended) - System boundary
- C4 Container - Technical containers
- Deployment - Infrastructure topology
- Sequence - API interactions
-
Output format:
- Mermaid (Recommended) - Renders in GitHub/VS Code
- PlantUML - Advanced layout control
Diagram Types
C4 Context (Level 1)
Purpose: Show system in context with users and external systems When to Use:- Starting new project
- Stakeholder communication
- Understanding system boundaries
C4 Container (Level 2)
Purpose: Show technical containers and technology choices When to Use:- After HLD phase
- Technology selection
- Understanding technical architecture
C4 Component (Level 3)
Purpose: Show internal components within a container When to Use:- After DLD phase
- Implementation planning
- Code structure design
Deployment Diagram
Purpose: Show infrastructure topology and cloud resources When to Use:- Cloud-first compliance
- Infrastructure planning
- Security zone design
Sequence Diagram
Purpose: Show API interactions and request/response flows When to Use:- API design and review
- Integration requirements
- Error handling flows
Output Formats
Mermaid
- Renders in GitHub markdown
- Renders in VS Code (Mermaid Preview extension)
- Online editor: https://mermaid.live
- Best for diagrams with ≤12 elements
PlantUML C4
- Directional layout hints
- Richer styling options
- Renders via PlantUML server or VS Code extension
- Best for complex diagrams
- Does NOT render in GitHub markdown
Quality Criteria
Diagrams evaluated on:| # | Criterion | Target |
|---|---|---|
| 1 | Edge crossings | < 5 for complex, 0 for simple |
| 2 | Visual hierarchy | Clear system boundary |
| 3 | Grouping | Related elements proximate |
| 4 | Flow direction | Consistent L-R or T-B |
| 5 | Traceability | Each line follows source to target |
| 6 | Abstraction level | One C4 level per diagram |
| 7 | Edge labels | Legible, no overlaps |
| 8 | Node placement | No unnecessarily long edges |
| 9 | Element count | Within threshold for type |
Element Count Thresholds
| Diagram Type | Max Elements | Split Strategy |
|---|---|---|
| C4 Context | 10 | By domain boundary |
| C4 Container | 15 | By deployment unit |
| C4 Component | 12 | By responsibility |
| Deployment | 15 | By cloud region |
| Sequence | 8 lifelines | By phase |
| Data Flow | 12 | By trust boundary |
Output
Creates:projects/{project}/diagrams/ARC-{PROJECT_ID}-DIAG-{NNN}-v1.0.md
Includes:
- Diagram code (Mermaid or PlantUML)
- Component inventory
- Architecture decisions
- Requirements traceability
- Integration points
- Data flow details
- Security architecture
- NFR coverage
Related Commands
arckit dfd- Generate Yourdon-DeMarco Data Flow Diagramsarckit hld-review- Review HLD with diagram validationarckit requirements- Source requirements for diagramsarckit wardley- Create Wardley Maps for evolution context
Next Steps
After creating diagrams:- Validate syntax at mermaid.live or plantuml.com
- Review with technical team
- Include in HLD/DLD documentation
- Update during design changes
- Use in architecture reviews