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]4. Integrate Diagrams
If the visualization plugin is available:
- Invoke
visualization:diagram-generatoragent - 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.mdIntegration 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