diagram

Generate architecture diagrams using Mermaid or PlantUML C4

Architecture Diagram Generation

Generate visual architecture diagrams using Mermaid or PlantUML C4 syntax.

Command

arckit diagram "<diagram type and subject>"

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:

1. Diagram type:

   • C4 Context (Recommended) - System boundary
   • C4 Container - Technical containers
   • Deployment - Infrastructure topology
   • Sequence - API interactions

2. 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

Input: Requirements (BR, INT)

Example:

C4 Container (Level 2)

Purpose: Show technical containers and technology choices

When to Use:

• After HLD phase
• Technology selection
• Understanding technical architecture

Input: HLD, requirements (NFR), Wardley Map

C4 Component (Level 3)

Purpose: Show internal components within a container

When to Use:

• After DLD phase
• Implementation planning
• Code structure design

Input: DLD, component specifications

Deployment Diagram

Purpose: Show infrastructure topology and cloud resources

When to Use:

• Cloud-first compliance
• Infrastructure planning
• Security zone design

Input: HLD, NFR (performance, security), TCoP

Sequence Diagram

Purpose: Show API interactions and request/response flows

When to Use:

• API design and review
• Integration requirements
• Error handling flows

Input: Requirements (INT), HLD/DLD (API specs)

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 Diagrams
• arckit hld-review - Review HLD with diagram validation
• arckit requirements - Source requirements for diagrams
• arckit wardley - Create Wardley Maps for evolution context

Next Steps

After creating diagrams:

1. Validate syntax at mermaid.live or plantuml.com
2. Review with technical team
3. Include in HLD/DLD documentation
4. Update during design changes
5. Use in architecture reviews