Architecture Documentation When to Use This Skill

Use this skill when you need to:

Generate architecture documentation for a system Create C4 diagrams (Context, Container, Component) Document architecture for different stakeholder viewpoints Produce technical overviews or executive summaries

Keywords: document, c4, container, context, component, viewpoint, architecture description, technical overview, executive summary

Document Types Type Audience Content Context All stakeholders System boundaries, external interactions Container Technical leads Services, databases, major components Component Developers Internal structure of containers Deployment Operations Infrastructure, environments Data Data architects Data flows, storage, schemas Executive Summary Leadership Business value, key decisions Document Generation Workflow 1. Analyze the Codebase

Before generating documentation:

Identify the scope (single service, multiple services, entire system) Find existing documentation to incorporate Locate key architectural files (configs, deployment specs) 2. Select Document Type

Choose based on:

Audience: Who will read this? Purpose: Decision support, onboarding, compliance? Scope: Component, service, or system level? 3. Generate Documentation

Each document type has a standard structure:

Context Document

System Context: [System Name]

Overview

[1-2 paragraph description]

Context Diagram

[C4 Context diagram - via visualization plugin]

External Systems

| System | Description | Integration |

| --- | --- | --- |

| ... | ... | ... |

Users/Actors

| Actor | Description | Interactions |

| --- | --- | --- |

| ... | ... | ... |

Container Document

Container Architecture: [System Name]

Overview

[Architecture summary]

Container Diagram

[C4 Container diagram - via visualization plugin]

Containers

[Container Name]

• Technology: [Stack]
• Purpose: [Description]
• Responsibilities: [List]
• Dependencies: [List]

Component Document

Component Architecture: [Container Name]

Overview

[Component structure summary]

Component Diagram

[C4 Component diagram - via visualization plugin]

Components

[Component Name]

• Type: [Service/Repository/Controller/etc.]
• Responsibilities: [List]

• Interfaces: [Public APIs]

• Integrate Diagrams

If the visualization plugin is available:

Invoke visualization:diagram-generator agent Request appropriate C4 diagram type Embed generated Mermaid/PlantUML code in document

Fallback: If visualization plugin unavailable, create text-based architecture description and note that diagrams can be added with the visualization plugin.

Template Structure

All architecture documents should include:

Header: Title, version, date, authors Overview: 1-2 paragraph summary Diagram: Visual representation Details: Structured information about components Decisions: Link to relevant ADRs References: Links to related documentation Completeness Checklist

Before finalizing documentation, verify:

Scope is clearly defined All major components identified External dependencies documented Key decisions linked to ADRs Diagram matches text description Audience-appropriate language used Version and date included Repository Location

Generated documentation should be placed in:

/architecture/ /viewpoints/ context.md containers.md components/ [container-name].md executive-summary.md

Integration with Other Skills adr-management: Link to relevant ADRs in documentation togaf-guidance: Align with current ADM phase zachman-analysis: Ensure appropriate viewpoint coverage Version History v1.0.0 (2025-12-05): Initial release Document generation workflow for C4 diagrams Six document types (context, container, component, deployment, data, executive summary) Visualization plugin integration Completeness checklist Last Updated

Date: 2025-12-05 Model: claude-opus-4-5-20251101