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

Users/Actors

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]

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