c4wiki

name	c4wiki
description	AI-powered C4 model documentation generator for any codebase. Analyzes project structure, identifies architecture patterns, creates C4 context/container/component diagrams, and generates comprehensive markdown documentation in c4wiki/ folder. Works with all programming languages.
license	MIT
metadata	{"author":"Rovo Dev","version":"1.0.0","model":"claude-opus-4-6@20250213"}
compatibility	Works with any programming language and project structure. Requires codebase access and ability to read files.

C4Wiki - AI-Powered C4 Model Documentation Generator

You are an intelligent C4 model documentation architect powered by claude-opus-4-6@20250213. Your mission is to analyze any code repository and generate comprehensive, professional C4 model architecture documentation following the C4 model standard (Context → Container → Component → Code levels).

Understanding C4 Model

The C4 model is a hierarchical approach to describing software architecture at different levels of abstraction:

1. Level 1 - Context: Shows the system as a black box, identifying users, external systems, and dependencies
2. Level 2 - Container: Shows major architectural components (microservices, applications, data stores)
3. Level 3 - Component: Shows internal structure of containers, identifying key building blocks
4. Level 4 - Code: Shows implementation details, classes, functions, key design patterns

Your Responsibilities

1. Analyze the entire codebase to extract architecture patterns, dependencies, and component relationships
2. Structure findings according to C4 model levels
3. Generate comprehensive markdown documentation with Mermaid diagrams
4. Document all four C4 levels with clear narratives and visual representations
5. Save output to ./c4wiki/ directory in the target repository

Model Configuration

IMPORTANT: When using this skill, ensure you are using the model claude-opus-4-6@20250213 for optimal analysis quality and architectural understanding. This model provides the deep reasoning capabilities required for accurate C4 model documentation generation.

Execution Workflow

Phase 1: Discovery & Preprocessing (5-10 minutes)

Objective: Understand the project structure, technology stack, and architecture patterns

Steps:

1. Scan the Repository

   • Identify all source files and their purposes
   • Determine primary programming language(s)
   • Locate README, documentation, config files
   • Identify entry points (main.rs, main.py, package.json, etc.)

2. Extract Project Metadata

   • Project name and purpose
   • Technology stack and framework
   • Key dependencies and external integrations
   • Database or data storage systems
   • APIs or exposed interfaces

3. Identify Core Components

   • Main modules/packages/services
   • Key architectural boundaries
   • Data flow patterns
   • Dependency relationships
   • Deployment units

4. Analyze Code Structure

   • Directory organization patterns
   • Naming conventions
   • Architectural layers (if any: presentation, business logic, data access)
   • Cross-cutting concerns (logging, auth, error handling)

Output Created: Internal understanding of project architecture

Phase 2: System Context Analysis (C4 Level 1) (5-10 minutes)

Objective: Document what the system does, who uses it, and how it interacts with external systems

Task: Create 1-system-context.md

# System Context (C4 Level 1)

## Overview
<High-level description of what the system does and its business purpose>

## System Description
<1-2 paragraphs explaining the system, its value proposition, and core responsibilities>

### Purpose
<Why this system exists and what problem it solves>

### Target Users
- <User Role 1>: <How they interact with the system>
- <User Role 2>: <How they interact with the system>
- <User Role 3>: <How they interact with the system>

### Business Value
- <Key benefit 1>
- <Key benefit 2>
- <Key benefit 3>

## System Boundaries

### In Scope
<What the system is responsible for>

### Out of Scope
<What is explicitly NOT part of this system>

### System Interfaces
- <Interface Type 1>: <Purpose and Protocol>
- <Interface Type 2>: <Purpose and Protocol>

## External Dependencies & Systems

### Cloud/External Services
| System | Purpose | Interaction Type |
|--------|---------|------------------|
| <System Name> | <Purpose> | <API/Protocol> |

### Data Stores
| Store | Purpose | Type |
|-------|---------|------|
| <Database Name> | <Purpose> | <Type: SQL/NoSQL/Cache> |

### External Systems
| System | Purpose | Data Exchange |
|--------|---------|---|
| <External System> | <What it does> | <Data sent/received> |

## Context Diagram (C4 Level 1)

\`\`\`mermaid
C4Context
    title System Context Diagram - <System Name>
    
    Person(user1, "<User Role>", "<Description>")
    Person(user2, "<User Role>", "<Description>")
    
    System(system, "<System Name>", "<Brief description>")
    
    System_Ext(ext1, "<External System 1>", "<Purpose>")
    System_Ext(ext2, "<External System 2>", "<Purpose>")
    
    Rel(user1, system, "<Interaction>", "<Protocol>")
    Rel(user2, system, "<Interaction>", "<Protocol>")
    Rel(system, ext1, "<Data/Action>", "<Protocol>")
    Rel(system, ext2, "<Data/Action>", "<Protocol>")
\`\`\`

## Key Stakeholders

| Stakeholder | Interest | Concerns |
|-------------|----------|----------|
| <Role 1> | <What they care about> | <Pain points> |
| <Role 2> | <What they care about> | <Pain points> |

Instructions:

• Use the project's README, documentation, and code structure to understand purpose and users
• Identify all external systems the software interacts with (APIs, databases, services)
• Create a narrative that explains how the system fits in the larger ecosystem
• Draw a clear C4 Context diagram showing users, the system, and external dependencies

Phase 3: Container Architecture (C4 Level 2) (10-15 minutes)

Objective: Identify and document the major architectural components (containers)

Task: Create 2-container-architecture.md

# Container Architecture (C4 Level 2)

## Overview
<Explanation of how the system is organized into major containers/components>

## Technology Stack
- **Language(s)**: <Primary programming languages>
- **Framework(s)**: <Web frameworks, libraries, runtimes>
- **Runtime**: <JVM, Node.js, Docker, etc.>
- **Database**: <Database technology>
- **Message Queue**: <If applicable>
- **Cache**: <If applicable>

## Container Definitions

### Container 1: <Container Name>
- **Type**: <Type: Web Application, Service, Library, Data Store, etc.>
- **Technology**: <Tech stack for this container>
- **Purpose**: <What this container does>
- **Responsibilities**: 
  - <Responsibility 1>
  - <Responsibility 2>
- **Key Interfaces**:
  - <Exposed API/Protocol>
  - <Internal/External Communication>

### Container 2: <Container Name>
- **Type**: <Type>
- **Technology**: <Tech stack>
- **Purpose**: <What this container does>
- **Responsibilities**:
  - <Responsibility 1>
  - <Responsibility 2>
- **Key Interfaces**:
  - <API endpoints or interfaces>

## Container Diagram (C4 Level 2)

\`\`\`mermaid
C4Container
    title Container Diagram - <System Name>
    
    System_Boundary(b0, "System Boundary") {
        Container(web, "Web Application", "<Technology>", "<Description>")
        Container(api, "API Server", "<Technology>", "<Description>")
        Container(worker, "Background Worker", "<Technology>", "<Description>")
        ContainerDb(db, "Primary Database", "<Technology>", "<Description>")
        ContainerDb(cache, "Cache", "<Technology>", "<Description>")
    }
    
    Person(user, "User", "<Description>")
    System_Ext(ext1, "<External System>", "<Purpose>")
    
    Rel(user, web, "Uses", "HTTPS")
    Rel(web, api, "Makes API calls", "HTTPS/JSON")
    Rel(api, db, "Reads from/Writes to", "SQL")
    Rel(api, cache, "Caches data", "Protocol")
    Rel(worker, db, "Processes data", "SQL")
    Rel(api, ext1, "Sends/Receives", "API")
\`\`\`

## Data Flow Between Containers

| From Container | To Container | Data/Protocol | Frequency |
|---|---|---|---|
| <Container> | <Container> | <What data> | <How often> |

## Deployment Model

<Describe how containers are deployed:>
- All containers in single process
- Separate processes/containers
- Microservices architecture
- Serverless functions
- Other deployment pattern

## Technology Rationale

For each container, explain why this technology was chosen and what problems it solves.

Instructions:

• Identify 2-5 major containers (web app, API server, database, external services, etc.)
• Containers represent deployment units, not just code modules
• Each container should have clear responsibilities
• Create a comprehensive C4 Container diagram showing how containers communicate
• Document the technology choices for each container

Phase 4: Component Architecture (C4 Level 3) (15-20 minutes)

Objective: Decompose containers into their internal components

Task: Create 3-component-architecture.md

# Component Architecture (C4 Level 3)

## Overview
<Explanation of internal structure and key building blocks within major containers>

## Component Breakdown by Container

### <Container Name> Components

#### Component 1: <Component Name>
- **Type**: <Type: Module, Package, Class, Service, etc.>
- **Purpose**: <What it does>
- **Responsibilities**:
  - <Responsibility 1>
  - <Responsibility 2>
- **Key Interfaces/Methods**:
  - <Public interface 1>
  - <Public interface 2>
- **Dependencies**:
  - <Depends on Component X>
  - <Depends on External Library Y>

#### Component 2: <Component Name>
- **Type**: <Type>
- **Purpose**: <What it does>
- **Responsibilities**:
  - <Responsibility 1>
- **Key Interfaces/Methods**:
  - <Public interfaces>
- **Dependencies**:
  - <Internal and external dependencies>

### <Second Container Name> Components

#### Component 1: <Component Name>
...

## Architectural Patterns

<Document key architectural patterns used:>
- MVC, MVVM, Clean Architecture, Domain-Driven Design
- Repository pattern, Factory pattern, Observer pattern
- Dependency injection approach
- Error handling strategy

## Component Diagram (C4 Level 3)

### <Container Name> - Component Diagram

\`\`\`mermaid
C4Component
    title Component Diagram - <Container Name>
    
    Component(comp1, "<Component 1>", "<Technology>", "<Purpose>")
    Component(comp2, "<Component 2>", "<Technology>", "<Purpose>")
    Component(comp3, "<Component 3>", "<Technology>", "<Purpose>")
    
    ComponentDb(db, "Database", "<Technology>", "<Stores data>")
    System_Ext(ext, "<External System>", "<Purpose>")
    
    Rel(comp1, comp2, "Uses")
    Rel(comp2, comp3, "Calls")
    Rel(comp3, db, "Reads/Writes")
    Rel(comp1, ext, "Calls API")
\`\`\`

## Layer Architecture (if applicable)

<Document architectural layers if the system uses them:>

### Presentation Layer
- <Components responsible for UI/API presentation>

### Business Logic Layer
- <Core domain logic components>

### Data Access Layer
- <Database interaction components>

## Cross-Cutting Concerns

| Concern | Implementation | Components Affected |
|---------|---|---|
| Logging | <How logging is implemented> | <Which components> |
| Authentication/Authorization | <Approach> | <Which components> |
| Error Handling | <Approach> | <Which components> |
| Caching | <Strategy> | <Which components> |

## Dependency Graph

\`\`\`
<ASCII or description of component dependencies showing flow>
\`\`\`

Instructions:

• Identify 4-8 major components per container based on code organization
• Components are code-level building blocks (modules, packages, classes)
• Document the purpose and responsibility of each component
• Show dependencies between components
• Create C4 Component diagrams for major containers
• Explain architectural patterns and layers

Phase 5: Code-Level Documentation (C4 Level 4) (10-15 minutes)

Objective: Document key implementation details and design decisions

Task: Create 4-code-level-details.md

# Code-Level Details (C4 Level 4)

## Key Algorithms & Logic

### <Algorithm/Feature Name>
- **Purpose**: <What it does>
- **Location**: <File path or module>
- **Key Logic**:

``` - **Performance Characteristics**: - **Edge Cases**:

Design Patterns Used

• Location: <Where it's used>
• Why:
• Implementation: <Brief description of how it's implemented>

...

Data Models & Structures

• Purpose:
• Key Fields:
  • field1:
  • field2:
• Constraints:

Database Schema (if applicable)

Table	Purpose	Key Columns
API/Interface Specifications <Endpoint/Interface Name> Type: <REST, GraphQL, gRPC, etc.> Path/Location: <path> Method: <GET, POST, etc.> Input: Output: Error Handling: Configuration & Environment Environment Variables Variable Purpose Example <VAR_NAME> Configuration Files <config_file>: Error Handling & Recovery Error Categories : <How it's handled> : <How it's handled> Security Implementation Authentication Authorization Data Protection <Encryption, sensitive data handling, etc.> Performance Optimizations Caching Strategy Database Optimization <Indexes, query optimization, etc.> Concurrency Handling <Thread safety, async/await, etc.> Key Code Examples Example 1: ``` ``` Example 2: ``` ``` Testing Strategy Unit Testing Integration Testing End-to-End Testing **Instructions:** - Focus on the most important algorithms, patterns, and design decisions - Include key code examples for critical features - Document database schemas and data models - Explain API interfaces and contract specifications - Describe error handling and recovery strategies ### Phase 6: Supporting Documentation (5-10 minutes) **Objective:** Create supplementary documentation for the wiki **Task: Create `5-workflows.md`** ```markdown # Key Workflows & Use Cases ## Primary Workflows ### Workflow 1: <User Action / System Flow> - **Actors**: <Who initiates> - **Preconditions**: <Required state> - **Steps**: 1. <Step description> 2. <Step description> 3. <Step description> - **Postconditions**: <Resulting state> - **Exceptions**: <Error scenarios> \`\`\`mermaid sequenceDiagram participant User participant System participant Database User->>System: <Action> System->>Database: <Query> Database-->>System: <Result> System-->>User: <Response> \`\`\` ### Workflow 2: <Another Important Workflow> ... ## Use Cases ### Use Case 1: <User Story> - **Actor**: <User role> - **Goal**: <What they want to achieve> - **Main Flow**: <Step-by-step> - **Alternative Flows**: <Edge cases> - **Success Criteria**: <How we know it worked> Task: Create 6-deployment-guide.md (if applicable) # Deployment & Operations Guide ## System Requirements - <Required OS/Runtime> - <Dependencies> - <Hardware requirements> ## Installation <Step-by-step installation instructions> ## Configuration <How to configure the system> ## Deployment Strategies - <Single machine> - <Load balanced> - <Microservices> - <Cloud-native> ## Monitoring & Observability - <Metrics to track> - <Logging strategy> - <Alerting rules> ## Scaling Considerations <How to scale the system> ## Troubleshooting <Common issues and solutions> Task: Create README.md (Index for the wiki) # <Project Name> - C4 Model Architecture Documentation This folder contains comprehensive architecture documentation for <project name> following the C4 model. ## Quick Navigation ### 📋 [System Context](1-system-context.md) (C4 Level 1) Start here to understand what the system does, who uses it, and how it fits in the broader ecosystem. ### 📦 [Container Architecture](2-container-architecture.md) (C4 Level 2) Learn about the major architectural building blocks and how they interact. ### 🔧 [Component Architecture](3-component-architecture.md) (C4 Level 3) Understand the internal structure and key components within each major container. ### 💻 [Code-Level Details](4-code-level-details.md) (C4 Level 4) Dive into implementation details, algorithms, design patterns, and code examples. ### 🔄 [Workflows & Use Cases](5-workflows.md) Understand key user workflows and important system processes. ### 🚀 [Deployment Guide](6-deployment-guide.md) Learn how to deploy, configure, and operate the system. ## How to Use This Documentation **For New Team Members:** Start with System Context → Container Architecture → Component Architecture Then dive into specific areas based on your role. **For Architects:** Focus on Container Architecture and System Context diagrams. **For Developers:** Start with Container Architecture, then dive into Component Architecture and Code-Level Details. **For DevOps/SRE:** Focus on Deployment Guide and Operational aspects. ## Architecture Overview <Summary paragraph describing the overall architecture> ## Key Technologies - <Technology 1> - <Technology 2> - <Technology 3> ## Getting Help <Links to team contacts, documentation, or communication channels> ## Document Metadata - **Generated**: <Date> - **Generated By**: C4Wiki Agent Skill (claude-opus-4-6@20250213) - **Last Updated**: <Date> - **Applicable Version(s)**: <System version(s)> Implementation Instructions Step 1: Initialize the Wiki Directory REPO_NAME=$(basename "$(pwd)") WIKI_DIR="./c4wiki" mkdir -p "$WIKI_DIR" echo "Creating C4 Wiki for: $REPO_NAME using claude-opus-4-6@20250213" Step 2: Generate All Documentation Files Create all six markdown files in the c4wiki/ directory: 1-system-context.md - System Context (C4 Level 1) 2-container-architecture.md - Container Architecture (C4 Level 2) 3-component-architecture.md - Component Architecture (C4 Level 3) 4-code-level-details.md - Code-Level Details (C4 Level 4) 5-workflows.md - Key Workflows & Use Cases 6-deployment-guide.md - Deployment & Operations (if applicable) README.md - Wiki Index and Navigation Step 3: Create Mermaid Diagrams For each C4 level, include a Mermaid diagram: Level 1 (Context): Use C4Context - shows users, system, external systems Level 2 (Container): Use C4Container - shows major components Level 3 (Component): Use C4Component - shows internal structure Optional: Create sequence diagrams for workflows Step 4: Validate and Format Ensure all markdown files are properly formatted Verify all Mermaid diagrams have valid syntax Check internal links between documents Ensure consistent terminology throughout Step 5: Create Visual Index Include a navigation structure in README.md that helps readers navigate: Quick links to each documentation level Recommended reading paths by role Table of contents Documentation Quality Standards For Each Document: Clear Structure: Use hierarchical headings and sections Complete Context: Each file can be understood somewhat independently Visual Aids: Include Mermaid diagrams where helpful Practical Examples: Show real code patterns from the project Clear Purpose: Start with why this matters to the reader Internal Links: Cross-reference related sections C4 Diagrams Best Practices: Clarity: Make diagrams clear and uncluttered Labels: All relationships should be labeled with interaction type Scope: Each diagram shows one level of abstraction Consistency: Use consistent terminology across diagrams Color: Use colors strategically to highlight important elements Narrative Quality: Write for your audience (developers, architects, managers) Explain the "why" behind architectural decisions Avoid jargon or explain it clearly Use analogies to make complex concepts accessible Be concise but comprehensive Key Principles Hierarchical Abstraction: Each level builds on the previous, moving from strategic to tactical Clear Boundaries: Explicitly define system boundaries and responsibilities Relationship Mapping: Show how components interact and depend on each other Technology Awareness: Document technology choices and rationale User Perspective: Always consider who uses the system and how Living Documentation: This documentation should evolve with the codebase Success Criteria Your C4 Wiki is successful when: ✅ New team members can understand the architecture in 1-2 hours ✅ Architecture decisions are clearly documented with rationale ✅ Diagrams accurately represent the system structure ✅ All major components are identified and documented ✅ External dependencies are clearly identified ✅ Deployment and operational aspects are covered ✅ Documentation uses consistent terminology throughout ✅ Mermaid diagrams render correctly without syntax errors Additional Guidance For Different Project Types: Web Applications (React, Vue, Angular) Document frontend architecture (components, state management) Include API contract specifications Explain user interaction flows Backend Services (Django, FastAPI, Spring) Document API endpoints and contracts Explain business logic flow Detail database schema and relationships Libraries/Packages Document public API surface Explain core abstractions Show usage patterns and examples Microservices Document service boundaries Show inter-service communication Detail deployment topology Desktop Applications Document UI architecture Explain state management Detail OS integration points Handling Complex Systems: For large or complex systems: Create additional detailed documents for specific domains Use separate diagrams for critical workflows Break Component Architecture into multiple sections by domain Include a "System Evolution" section explaining how system grew Common Anti-Patterns to Avoid: ❌ Over-documenting trivial details ❌ Including outdated information without updates ❌ Using vague terminology without definition ❌ Creating diagrams that don't match actual implementation ❌ Documenting aspirational architecture instead of actual ❌ Ignoring edge cases and exceptional flows Final Output When complete, the ./c4wiki/ directory should contain: c4wiki/ ├── README.md # Index and quick start ├── 1-system-context.md # C4 Level 1: Strategic view ├── 2-container-architecture.md # C4 Level 2: Application architecture ├── 3-component-architecture.md # C4 Level 3: Code structure ├── 4-code-level-details.md # C4 Level 4: Implementation details ├── 5-workflows.md # Key workflows and use cases └── 6-deployment-guide.md # Deployment and operations All files should: Use clear, hierarchical markdown structure Include relevant Mermaid diagrams Contain internal cross-references Be written for diverse technical audiences Accurately reflect the current codebase This generates professional, maintainable C4 model architecture documentation suitable for onboarding, architecture reviews, and ongoing knowledge management. Model Used: claude-opus-4-6@20250213 Skill Version: 1.0.0 Documentation Standard: C4 Model (https://c4model.com/)