C4 Architecture Documentation Workflow
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.
Phase 1: Code-Level Documentation (Bottom-Up Analysis)
1.1 Discover All Subdirectories
- Use codebase search to identify all subdirectories in the repository
- Sort directories by depth (deepest first) for bottom-up processing
- Filter out common non-code directories (node_modules, .git, build, dist, etc.)
- Create list of directories to process
1.2 Process Each Directory (Bottom-Up)
For each directory, starting from the deepest:
Use Task tool with subagent_type="c4-architecture::c4-code"
Prompt: |
Analyze the code in directory: [directory_path]
Create comprehensive C4 Code-level documentation following this structure:
- Overview Section:
- Name: [Descriptive name for this code directory]
- Description: [Short description of what this code does]
- Location: [Link to actual directory path relative to repo root]
- Language: [Primary programming language(s) used]
- Purpose: [What this code accomplishes]
- Code Elements Section:
- Document all functions/methods with complete signatures:
- Function name, parameters (with types), return type
- Description of what each function does
- Location (file path and line numbers)
- Dependencies (what this function depends on)
- Document all classes/modules:
- Class name, description, location
- Methods and their signatures
- Dependencies
- Dependencies Section:
- Internal dependencies (other code in this repo)
- External dependencies (libraries, frameworks, services)
- Relationships Section:
- 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-.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)
- Technical boundaries (shared frameworks, libraries)
- Organizational boundaries (team ownership, if evident)
2.2 Create Component Documentation
For each identified component:
Use Task tool with subagent_type="c4-architecture::c4-component"
Prompt: |
Synthesize the following C4 Code-level documentation files into a logical component:
Code files to analyze:
[List of c4-code-*.md file paths]
Create comprehensive C4 Component-level documentation following this structure:
- Overview Section:
- Name: [Component name - descriptive and meaningful]
- Description: [Short description of component purpose]
- Type: [Application, Service, Library, etc.]
- Technology: [Primary technologies used]
- Purpose Section:
- Detailed description of what this component does
- What problems it solves
- Its role in the system
- Software Features Section:
- List all software features provided by this component
- Each feature with a brief description
- Code Elements Section:
- List all c4-code-*.md files contained in this component
- Link to each file with a brief description
- Interfaces Section:
- Document all component interfaces:
- Interface name
- Protocol (REST, GraphQL, gRPC, Events, etc.)
- Description
- Operations (function signatures, endpoints, etc.)
- Dependencies Section:
- Components used (other components this depends on)
- External systems (databases, APIs, services)
- Component Diagram:
- Mermaid diagram showing this component and its relationships
Save the output as: C4-Documentation/c4-component-[component-name].md
Use a sanitized component name for the filename.
Expected output: c4-component-.md file for each component
Context: All relevant c4-code-*.md files for this component
2.3 Create Master Component Index
Use Task tool with subagent_type="c4-architecture::c4-component"
Prompt: |
Create a master component index that lists all components in the system.
Based on all c4-component-*.md files created, generate:
- System Components Section:
- List all components with:
- Component name
- Short description
- Link to component documentation
- Component Relationships Diagram:
- Mermaid diagram showing all components and their relationships
- Show dependencies between components
- Show external system dependencies
Save the output as: C4-Documentation/c4-component.md
Expected output: Master c4-component.md file
Context: All c4-component-*.md files
Phase 3: Container-Level Synthesis
3.1 Analyze Components and Deployment Definitions
- Review all c4-component-*.md files
- Search for deployment/infrastructure definitions:
- Dockerfiles
- Kubernetes manifests (deployments, services, etc.)
- Docker Compose files
- Terraform/CloudFormation configs
- Cloud service definitions (AWS Lambda, Azure Functions, etc.)
- CI/CD pipeline definitions
3.2 Map Components to Containers
Use Task tool with subagent_type="c4-architecture::c4-container"
Prompt: |
Synthesize components into containers based on deployment definitions.
Component documentation:
[List of all c4-component-*.md file paths]
Deployment definitions found:
[List of deployment config files: Dockerfiles, K8s manifests, etc.]
Create comprehensive C4 Container-level documentation following this structure:
- Containers Section (for each container):
- Name: [Container name]
- Description: [Short description of container purpose and deployment]
- Type: [Web Application, API, Database, Message Queue, etc.]
- Technology: [Primary technologies: Node.js, Python, PostgreSQL, etc.]
- Deployment: [Docker, Kubernetes, Cloud Service, etc.]
- Purpose Section (for each container):
- Detailed description of what this container does
- How it's deployed
- Its role in the system
- Components Section (for each container):
- List all components deployed in this container
- Link to component documentation
- Interfaces Section (for each container):
- Document all container APIs and interfaces:
- API/Interface name
- Protocol (REST, GraphQL, gRPC, Events, etc.)
- Description
- Link to OpenAPI/Swagger/API Spec file
- List of endpoints/operations
- API Specifications:
- 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)
- Description (who they are, what they need)
- Goals (what they want to achieve)
- Key features used
- System Features Section:
- For each high-level feature:
- Feature name
- Description (what this feature does)
- Users (which personas use this feature)
- Link to user journey map
- User Journeys Section:
- For each key feature and persona:
- Journey name: [Feature Name] - [Persona Name] Journey
- Step-by-step journey:
- ...
- Include all system touchpoints
- For programmatic users (external systems, APIs):
- Integration journey with step-by-step process
- External Systems and Dependencies Section:
- For each external system:
- System name
- Type (Database, API, Service, Message Queue, etc.)
- Description (what it provides)
- Integration type (API, Events, File Transfer, etc.)
- Purpose (why the system depends on this)
- System Context Diagram:
- Mermaid C4Context diagram showing:
- The system (as a box in the center)
- All personas (users) around it
- All external systems around it
- Relationships and data flows
- Use C4Context notation for proper C4 diagram
- Related Documentation Section:
- Links to container documentation
- Links to component documentation
Save the output as: C4-Documentation/c4-context.md
Ensure the documentation is:
- Understandable by non-technical stakeholders
- Focuses on system purpose, users, and external relationships
- Includes comprehensive user journey maps
- Identifies all external systems and dependencies
Expected output: c4-context.md with complete system context
Context: All container, component, and system documentation
Configuration Options
target_directory: Root directory to analyze (default: current repository root)
exclude_patterns: Patterns to exclude (default: node_modules, .git, build, dist, etc.)
output_directory: Where to write C4 documentation (default: C4-Documentation/)
include_tests: Whether to analyze test files for context (default: true)
api_format: Format for API specs (default: openapi)
Success Criteria
- ✅ Every subdirectory has a corresponding c4-code-*.md file
- ✅ All code-level documentation includes complete function signatures
- ✅ Components are logically grouped with clear boundaries
- ✅ All components have interface documentation
- ✅ Master component index created with relationship diagram
- ✅ Containers map to actual deployment units
- ✅ All container APIs documented with OpenAPI/Swagger specs
- ✅ Container diagram shows deployment architecture
- ✅ System context includes all personas (human and programmatic)
- ✅ User journeys documented for all key features
- ✅ All external systems and dependencies identified
- ✅ Context diagram shows system, users, and external systems
- ✅ Documentation is organized in C4-Documentation/ directory
Output Structure
C4-Documentation/
├── c4-code-*.md # Code-level docs (one per directory)
├── c4-component-*.md # Component-level docs (one per component)
├── c4-component.md # Master component index
├── c4-container.md # Container-level docs
├── c4-context.md # Context-level docs
└── apis/ # API specifications
├── [container]-api.yaml # OpenAPI specs for each container
└── ...
Coordination Notes
- Bottom-up processing: Process directories from deepest to shallowest
- Incremental synthesis: Each level builds on the previous level's documentation
- Complete coverage: Every directory must have code-level documentation before synthesis
- Link consistency: All documentation files link to each other appropriately
- API documentation: Container APIs must have OpenAPI/Swagger specifications
- Stakeholder-friendly: Context documentation should be understandable by non-technical stakeholders
- Mermaid diagrams: Use proper C4 Mermaid notation for all diagrams
Example Usage
/c4-architecture:c4-architecture
This will:
- Walk through all subdirectories bottom-up
- Create c4-code-*.md for each directory
- Synthesize into components
- Map to containers with API docs
- Create system context with personas and journeys
All documentation written to: C4-Documentation/
1---
2name: c4-architecture-c4-architecture
3description: "Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach."
4risk: critical
5source: community
6date_added: "2026-02-27"
7quality: stub
8metadata:
9 source: https://skillmd.com/skills/kursku/c4-architecture-c4-architecture
10---
11
12# C4 Architecture Documentation Workflow
13
14Generate comprehensive C4 architecture documentation for an existing repository/codebase using a bottom-up analysis approach.
15
16[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.]
17
18## Use this skill when
19
20- Working on c4 architecture documentation workflow tasks or workflows
21- Needing guidance, best practices, or checklists for c4 architecture documentation workflow
22
23## Do not use this skill when
24
25- The task is unrelated to c4 architecture documentation workflow
26- You need a different domain or tool outside this scope
27
28## Instructions
29
30- Clarify goals, constraints, and required inputs.
31- Apply relevant best practices and validate outcomes.
32- Provide actionable steps and verification.
33- If detailed examples are required, open `resources/implementation-playbook.md`.
34
35## Overview
36
37This workflow creates comprehensive C4 architecture documentation following the [official C4 model](https://c4model.com/diagrams) by:
38
391. **Code Level**: Analyzing every subdirectory bottom-up to create code-level documentation
402. **Component Level**: Synthesizing code documentation into logical components within containers
413. **Container Level**: Mapping components to deployment containers with API documentation (shows high-level technology choices)
424. **Context Level**: Creating high-level system context with personas and user journeys (focuses on people and software systems, not technologies)
43
44**Note**: According to the [C4 model](https://c4model.com/diagrams), 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.
45
46All documentation is written to a new `C4-Documentation/` directory in the repository root.
47
48## Phase 1: Code-Level Documentation (Bottom-Up Analysis)
49
50### 1.1 Discover All Subdirectories
51
52- Use codebase search to identify all subdirectories in the repository
53- Sort directories by depth (deepest first) for bottom-up processing
54- Filter out common non-code directories (node_modules, .git, build, dist, etc.)
55- Create list of directories to process
56
57### 1.2 Process Each Directory (Bottom-Up)
58
59For each directory, starting from the deepest:
60
61- Use Task tool with subagent_type="c4-architecture::c4-code"
62- Prompt: |
63 Analyze the code in directory: [directory_path]
64
65 Create comprehensive C4 Code-level documentation following this structure:
66 1. **Overview Section**:
67 - Name: [Descriptive name for this code directory]
68 - Description: [Short description of what this code does]
69 - Location: [Link to actual directory path relative to repo root]
70 - Language: [Primary programming language(s) used]
71 - Purpose: [What this code accomplishes]
72 2. **Code Elements Section**:
73 - Document all functions/methods with complete signatures:
74 - Function name, parameters (with types), return type
75 - Description of what each function does
76 - Location (file path and line numbers)
77 - Dependencies (what this function depends on)
78 - Document all classes/modules:
79 - Class name, description, location
80 - Methods and their signatures
81 - Dependencies
82 3. **Dependencies Section**:
83 - Internal dependencies (other code in this repo)
84 - External dependencies (libraries, frameworks, services)
85 4. **Relationships Section**:
86 - Optional Mermaid diagram if relationships are complex
87
88 Save the output as: C4-Documentation/c4-code-[directory-name].md
89 Use a sanitized directory name (replace / with -, remove special chars) for the filename.
90
91 Ensure the documentation includes:
92 - Complete function signatures with all parameters and types
93 - Links to actual source code locations
94 - All dependencies (internal and external)
95 - Clear, descriptive names and descriptions
96
97- Expected output: c4-code-<directory-name>.md file in C4-Documentation/
98- Context: All files in the directory and its subdirectories
99
100**Repeat for every subdirectory** until all directories have corresponding c4-code-\*.md files.
101
102## Phase 2: Component-Level Synthesis
103
104### 2.1 Analyze All Code-Level Documentation
105
106- Collect all c4-code-\*.md files created in Phase 1
107- Analyze code structure, dependencies, and relationships
108- Identify logical component boundaries based on:
109 - Domain boundaries (related business functionality)
110 - Technical boundaries (shared frameworks, libraries)
111 - Organizational boundaries (team ownership, if evident)
112
113### 2.2 Create Component Documentation
114
115For each identified component:
116
117- Use Task tool with subagent_type="c4-architecture::c4-component"
118- Prompt: |
119 Synthesize the following C4 Code-level documentation files into a logical component:
120
121 Code files to analyze:
122 [List of c4-code-*.md file paths]
123
124 Create comprehensive C4 Component-level documentation following this structure:
125 1. **Overview Section**:
126 - Name: [Component name - descriptive and meaningful]
127 - Description: [Short description of component purpose]
128 - Type: [Application, Service, Library, etc.]
129 - Technology: [Primary technologies used]
130 2. **Purpose Section**:
131 - Detailed description of what this component does
132 - What problems it solves
133 - Its role in the system
134 3. **Software Features Section**:
135 - List all software features provided by this component
136 - Each feature with a brief description
137 4. **Code Elements Section**:
138 - List all c4-code-\*.md files contained in this component
139 - Link to each file with a brief description
140 5. **Interfaces Section**:
141 - Document all component interfaces:
142 - Interface name
143 - Protocol (REST, GraphQL, gRPC, Events, etc.)
144 - Description
145 - Operations (function signatures, endpoints, etc.)
146 6. **Dependencies Section**:
147 - Components used (other components this depends on)
148 - External systems (databases, APIs, services)
149 7. **Component Diagram**:
150 - Mermaid diagram showing this component and its relationships
151
152 Save the output as: C4-Documentation/c4-component-[component-name].md
153 Use a sanitized component name for the filename.
154
155- Expected output: c4-component-<name>.md file for each component
156- Context: All relevant c4-code-\*.md files for this component
157
158### 2.3 Create Master Component Index
159
160- Use Task tool with subagent_type="c4-architecture::c4-component"
161- Prompt: |
162 Create a master component index that lists all components in the system.
163
164 Based on all c4-component-\*.md files created, generate:
165 1. **System Components Section**:
166 - List all components with:
167 - Component name
168 - Short description
169 - Link to component documentation
170 2. **Component Relationships Diagram**:
171 - Mermaid diagram showing all components and their relationships
172 - Show dependencies between components
173 - Show external system dependencies
174
175 Save the output as: C4-Documentation/c4-component.md
176
177- Expected output: Master c4-component.md file
178- Context: All c4-component-\*.md files
179
180## Phase 3: Container-Level Synthesis
181
182### 3.1 Analyze Components and Deployment Definitions
183
184- Review all c4-component-\*.md files
185- Search for deployment/infrastructure definitions:
186 - Dockerfiles
187 - Kubernetes manifests (deployments, services, etc.)
188 - Docker Compose files
189 - Terraform/CloudFormation configs
190 - Cloud service definitions (AWS Lambda, Azure Functions, etc.)
191 - CI/CD pipeline definitions
192
193### 3.2 Map Components to Containers
194
195- Use Task tool with subagent_type="c4-architecture::c4-container"
196- Prompt: |
197 Synthesize components into containers based on deployment definitions.
198
199 Component documentation:
200 [List of all c4-component-*.md file paths]
201
202 Deployment definitions found:
203 [List of deployment config files: Dockerfiles, K8s manifests, etc.]
204
205 Create comprehensive C4 Container-level documentation following this structure:
206 1. **Containers Section** (for each container):
207 - Name: [Container name]
208 - Description: [Short description of container purpose and deployment]
209 - Type: [Web Application, API, Database, Message Queue, etc.]
210 - Technology: [Primary technologies: Node.js, Python, PostgreSQL, etc.]
211 - Deployment: [Docker, Kubernetes, Cloud Service, etc.]
212 2. **Purpose Section** (for each container):
213 - Detailed description of what this container does
214 - How it's deployed
215 - Its role in the system
216 3. **Components Section** (for each container):
217 - List all components deployed in this container
218 - Link to component documentation
219 4. **Interfaces Section** (for each container):
220 - Document all container APIs and interfaces:
221 - API/Interface name
222 - Protocol (REST, GraphQL, gRPC, Events, etc.)
223 - Description
224 - Link to OpenAPI/Swagger/API Spec file
225 - List of endpoints/operations
226 5. **API Specifications**:
227 - For each container API, create an OpenAPI 3.1+ specification
228 - Save as: C4-Documentation/apis/[container-name]-api.yaml
229 - Include:
230 - All endpoints with methods (GET, POST, etc.)
231 - Request/response schemas
232 - Authentication requirements
233 - Error responses
234 6. **Dependencies Section** (for each container):
235 - Containers used (other containers this depends on)
236 - External systems (databases, third-party APIs, etc.)
237 - Communication protocols
238 7. **Infrastructure Section** (for each container):
239 - Link to deployment config (Dockerfile, K8s manifest, etc.)
240 - Scaling strategy
241 - Resource requirements (CPU, memory, storage)
242 8. **Container Diagram**:
243 - Mermaid diagram showing all containers and their relationships
244 - Show communication protocols
245 - Show external system dependencies
246
247 Save the output as: C4-Documentation/c4-container.md
248
249- Expected output: c4-container.md with all containers and API specifications
250- Context: All component documentation and deployment definitions
251
252## Phase 4: Context-Level Documentation
253
254### 4.1 Analyze System Documentation
255
256- Review container and component documentation
257- Search for system documentation:
258 - README files
259 - Architecture documentation
260 - Requirements documents
261 - Design documents
262 - Test files (to understand system behavior)
263 - API documentation
264 - User documentation
265
266### 4.2 Create Context Documentation
267
268- Use Task tool with subagent_type="c4-architecture::c4-context"
269- Prompt: |
270 Create comprehensive C4 Context-level documentation for the system.
271
272 Container documentation: C4-Documentation/c4-container.md
273 Component documentation: C4-Documentation/c4-component.md
274 System documentation: [List of README, architecture docs, requirements, etc.]
275 Test files: [List of test files that show system behavior]
276
277 Create comprehensive C4 Context-level documentation following this structure:
278 1. **System Overview Section**:
279 - Short Description: [One-sentence description of what the system does]
280 - Long Description: [Detailed description of system purpose, capabilities, problems solved]
281 2. **Personas Section**:
282 - For each persona (human users and programmatic "users"):
283 - Persona name
284 - Type (Human User / Programmatic User / External System)
285 - Description (who they are, what they need)
286 - Goals (what they want to achieve)
287 - Key features used
288 3. **System Features Section**:
289 - For each high-level feature:
290 - Feature name
291 - Description (what this feature does)
292 - Users (which personas use this feature)
293 - Link to user journey map
294 4. **User Journeys Section**:
295 - For each key feature and persona:
296 - Journey name: [Feature Name] - [Persona Name] Journey
297 - Step-by-step journey:
298 1. [Step 1]: [Description]
299 2. [Step 2]: [Description]
300 ...
301 - Include all system touchpoints
302 - For programmatic users (external systems, APIs):
303 - Integration journey with step-by-step process
304 5. **External Systems and Dependencies Section**:
305 - For each external system:
306 - System name
307 - Type (Database, API, Service, Message Queue, etc.)
308 - Description (what it provides)
309 - Integration type (API, Events, File Transfer, etc.)
310 - Purpose (why the system depends on this)
311 6. **System Context Diagram**:
312 - Mermaid C4Context diagram showing:
313 - The system (as a box in the center)
314 - All personas (users) around it
315 - All external systems around it
316 - Relationships and data flows
317 - Use C4Context notation for proper C4 diagram
318 7. **Related Documentation Section**:
319 - Links to container documentation
320 - Links to component documentation
321
322 Save the output as: C4-Documentation/c4-context.md
323
324 Ensure the documentation is:
325 - Understandable by non-technical stakeholders
326 - Focuses on system purpose, users, and external relationships
327 - Includes comprehensive user journey maps
328 - Identifies all external systems and dependencies
329
330- Expected output: c4-context.md with complete system context
331- Context: All container, component, and system documentation
332
333## Configuration Options
334
335- `target_directory`: Root directory to analyze (default: current repository root)
336- `exclude_patterns`: Patterns to exclude (default: node_modules, .git, build, dist, etc.)
337- `output_directory`: Where to write C4 documentation (default: C4-Documentation/)
338- `include_tests`: Whether to analyze test files for context (default: true)
339- `api_format`: Format for API specs (default: openapi)
340
341## Success Criteria
342
343- ✅ Every subdirectory has a corresponding c4-code-\*.md file
344- ✅ All code-level documentation includes complete function signatures
345- ✅ Components are logically grouped with clear boundaries
346- ✅ All components have interface documentation
347- ✅ Master component index created with relationship diagram
348- ✅ Containers map to actual deployment units
349- ✅ All container APIs documented with OpenAPI/Swagger specs
350- ✅ Container diagram shows deployment architecture
351- ✅ System context includes all personas (human and programmatic)
352- ✅ User journeys documented for all key features
353- ✅ All external systems and dependencies identified
354- ✅ Context diagram shows system, users, and external systems
355- ✅ Documentation is organized in C4-Documentation/ directory
356
357## Output Structure
358
359```
360C4-Documentation/
361├── c4-code-*.md # Code-level docs (one per directory)
362├── c4-component-*.md # Component-level docs (one per component)
363├── c4-component.md # Master component index
364├── c4-container.md # Container-level docs
365├── c4-context.md # Context-level docs
366└── apis/ # API specifications
367 ├── [container]-api.yaml # OpenAPI specs for each container
368 └── ...
369```
370
371## Coordination Notes
372
373- **Bottom-up processing**: Process directories from deepest to shallowest
374- **Incremental synthesis**: Each level builds on the previous level's documentation
375- **Complete coverage**: Every directory must have code-level documentation before synthesis
376- **Link consistency**: All documentation files link to each other appropriately
377- **API documentation**: Container APIs must have OpenAPI/Swagger specifications
378- **Stakeholder-friendly**: Context documentation should be understandable by non-technical stakeholders
379- **Mermaid diagrams**: Use proper C4 Mermaid notation for all diagrams
380
381## Example Usage
382
383```bash
384/c4-architecture:c4-architecture
385```
386
387This will:
388
3891. Walk through all subdirectories bottom-up
3902. Create c4-code-\*.md for each directory
3913. Synthesize into components
3924. Map to containers with API docs
3935. Create system context with personas and journeys
394
395All documentation written to: C4-Documentation/