architecture-documentation

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:

1. Identify the scope (single service, multiple services, entire system)
2. Find existing documentation to incorporate
3. 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]

4. Integrate Diagrams

If the visualization plugin is available:

1. Invoke visualization:diagram-generator agent
2. Request appropriate C4 diagram type
3. 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:

1. Header: Title, version, date, authors
2. Overview: 1-2 paragraph summary
3. Diagram: Visual representation
4. Details: Structured information about components
5. Decisions: Link to relevant ADRs
6. 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