C4 Architecture C4 Architecture

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