Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
[Extended thinking: This workflow implements a complete C4 architecture documentation process following the C4 model (Context, Container, Component, Code). It uses a bottom-up approach, starting from the deepest code directories and working upward, ensuring every code element is documented before synthesizing into higher-level abstractions. The workflow coordinates four specialized C4 agents (Code, Component, Container, Context) to create a complete architectural documentation set that serves both technical and non-technical stakeholders.]
Use this skill when
Working on c4 architecture documentation workflow tasks or workflows
Needing guidance, best practices, or checklists for c4 architecture documentation workflow
Do not use this skill when
The task is unrelated to c4 architecture documentation workflow
You need a different domain or tool outside this scope
Instructions
Clarify goals, constraints, and required inputs.
Apply relevant best practices and validate outcomes.
Provide actionable steps and verification.
If detailed examples are required, open resources/implementation-playbook.md.
Overview
This workflow creates comprehensive C4 architecture documentation following the official C4 model by:
Code Level: Analyzing every subdirectory bottom-up to create code-level documentation
Component Level: Synthesizing code documentation into logical components within containers
Container Level: Mapping components to deployment containers with API documentation (shows high-level technology choices)
Context Level: Creating high-level system context with personas and user journeys (focuses on people and software systems, not technologies)
Note: According to the C4 model, you don't need to use all 4 levels of diagram - the system context and container diagrams are sufficient for most software development teams. This workflow generates all levels for completeness, but teams can choose which levels to use.
All documentation is written to a new C4-Documentation/ directory in the repository root.
Optional Mermaid diagram if relationships are complex
Save the output as: C4-Documentation/c4-code-[directory-name].md
Use a sanitized directory name (replace / with -, remove special chars) for the filename.
Ensure the documentation includes:
Complete function signatures with all parameters and types
Links to actual source code locations
All dependencies (internal and external)
Clear, descriptive names and descriptions
Expected output: c4-code-<directory-name>.md file in C4-Documentation/
Context: All files in the directory and its subdirectories
Repeat for every subdirectory until all directories have corresponding c4-code-*.md files.
Phase 2: Component-Level Synthesis
2.1 Analyze All Code-Level Documentation
Collect all c4-code-*.md files created in Phase 1
Analyze code structure, dependencies, and relationships
Identify logical component boundaries based on:
Domain boundaries (related business functionality)
For each container API, create an OpenAPI 3.1+ specification
Save as: C4-Documentation/apis/[container-name]-api.yaml
Include:
All endpoints with methods (GET, POST, etc.)
Request/response schemas
Authentication requirements
Error responses
Dependencies Section (for each container):
Containers used (other containers this depends on)
External systems (databases, third-party APIs, etc.)
Communication protocols
Infrastructure Section (for each container):
Link to deployment config (Dockerfile, K8s manifest, etc.)
Scaling strategy
Resource requirements (CPU, memory, storage)
Container Diagram:
Mermaid diagram showing all containers and their relationships
Show communication protocols
Show external system dependencies
Save the output as: C4-Documentation/c4-container.md
Expected output: c4-container.md with all containers and API specifications
Context: All component documentation and deployment definitions
Phase 4: Context-Level Documentation
4.1 Analyze System Documentation
Review container and component documentation
Search for system documentation:
README files
Architecture documentation
Requirements documents
Design documents
Test files (to understand system behavior)
API documentation
User documentation
4.2 Create Context Documentation
Use Task tool with subagent_type="c4-architecture::c4-context"
Prompt: |
Create comprehensive C4 Context-level documentation for the system.
Container documentation: C4-Documentation/c4-container.md
Component documentation: C4-Documentation/c4-component.md
System documentation: [List of README, architecture docs, requirements, etc.]
Test files: [List of test files that show system behavior]
Create comprehensive C4 Context-level documentation following this structure:
System Overview Section:
Short Description: [One-sentence description of what the system does]
Long Description: [Detailed description of system purpose, capabilities, problems solved]
Personas Section:
For each persona (human users and programmatic "users"):
Persona name
Type (Human User / Programmatic User / External System)
