Skip to main content

​
Architecture Diagrams

The /arckit.diagram command generates architecture diagrams using Mermaid or PlantUML C4 syntax for visual documentation. Diagrams integrate with ArcKit’s governance workflow and provide clear, traceable visual documentation.

​
What are Architecture Diagrams?

Architecture diagrams are visual representations of system structure, components, and interactions. They help:
  • Communicate: Complex architectures to stakeholders
  • Validate: Designs against requirements and principles
  • Document: Technical decisions and rationale
  • Trace: Requirements through design components

​
Diagram Types

​
C4 Context Diagram (Level 1)

Purpose: Show system in context with users and external systems When to Use:
  • Starting a new project (after requirements phase)
  • Stakeholder communication (non-technical audience)
  • Understanding system boundaries
  • No detailed technical design yet
Example:

​
C4 Container Diagram (Level 2)

Purpose: Show technical containers and technology choices When to Use:
  • After HLD phase
  • Reviewing vendor proposals
  • Understanding technical architecture
  • Technology selection decisions
Example: Note: Include evolution stage from Wardley Map in square brackets [Custom 0.42]

​
Deployment Diagram

Purpose: Show infrastructure topology and cloud resources When to Use:
  • Cloud-first compliance (TCoP Point 5)
  • Infrastructure planning
  • Security zone design
  • DevOps / SRE discussions
Example:

​
Sequence Diagram

Purpose: Show API interactions and request/response flows When to Use:
  • API design and review
  • Integration requirements (INT)
  • Understanding interaction patterns
  • Error handling flows
Example:

​
Usage

​
Basic Command

/arckit.diagram context booking system

​
With Diagram Type

/arckit.diagram C4 container payment gateway
/arckit.diagram sequence login flow
/arckit.diagram deployment AWS infrastructure

​
Output Format Selection

The command will ask you to choose:
  1. Diagram type: Context, Container, Deployment, Sequence
  2. Output format: Mermaid (recommended) or PlantUML
Mermaid (Recommended):
  • Renders in GitHub, VS Code, mermaid.live
  • Best for diagrams with 12 or fewer elements
PlantUML:
  • Directional layout hints and richer styling
  • Best for complex diagrams
  • Renders in PlantUML server, VS Code extension

​
Viewing Diagrams

​
Mermaid Diagrams

  • GitHub markdown: Renders automatically
  • Online: Paste code into mermaid.live
  • VS Code: Install Mermaid Preview extension

​
PlantUML Diagrams

  • Online: PlantUML Server
  • VS Code: Install PlantUML extension (jebbs.plantuml)
  • CLI: java -jar plantuml.jar diagram.puml

​
Integration with ArcKit Workflow

​
After Requirements Phase

/arckit.diagram context     # Create context diagram
/arckit.wardley             # Map strategic positioning
/arckit.hld-review          # Create high-level design
/arckit.diagram container   # Create container diagram

​
After HLD Approval

/arckit.diagram deployment  # Show infrastructure
/arckit.dld-review          # Create detailed design
/arckit.diagram component   # Show internal structure

​
Best Practices

​
Element Count Thresholds

Diagram TypeMax ElementsSplit Strategy
C4 Context10Split by domain boundary or system group
C4 Container15Split by deployment unit or bounded context
Deployment15Split by cloud region or availability zone
Sequence8 lifelinesSplit by phase (setup, processing, teardown)

​
Quality Criteria

  • Edge crossings: Fewer than 5 for complex diagrams, 0 for simple
  • Visual hierarchy: System boundary is most prominent
  • Grouping: Related elements are proximate
  • Flow direction: Consistent left-to-right or top-to-bottom
  • Traceability: Each line can be followed from source to target
  • Abstraction level: One C4 level per diagram

​
Strategic Context

For each component, annotate with: From Wardley Map (if available):
  • Evolution stage: [Genesis 0.15], [Custom 0.42], [Product 0.70], [Commodity 0.95]
  • Build/Buy decision: BUILD, BUY, USE, REUSE
From Requirements:
  • NFR targets: “10K TPS”, “99.99% availability”, “Sub-200ms response”
  • Compliance: “PCI-DSS Level 1”, “UK GDPR”, “WCAG 2.2 AA”
From UK Government (if applicable):
  • GOV.UK services: “GOV.UK Notify”, “GOV.UK Pay”, “GOV.UK Design System”
  • TCoP compliance: “Cloud First (AWS)”, “Open Source (PostgreSQL)“

​
Output File Format

Diagrams are saved to: 
projects/{project-number}-{project-name}/diagrams/ARC-{PROJECT_ID}-DIAG-{NNN}-v1.0.md
Example: projects/001-payment-gateway/diagrams/ARC-001-DIAG-001-v1.0.md
  • /arckit.wardley - Strategic positioning with Wardley Maps
  • /arckit.hld-review - High-Level Design validation
  • /arckit.dld-review - Detailed Design validation
  • /arckit.requirements - Define requirements first
  • /arckit.traceability - Map diagrams to requirements

Build docs developers (and LLMs) love

Get started for freeTalk to us