# C4 Architecture

Generate architecture documentation using C4 model Mermaid diagrams.

- Repository: https://github.com/coco-research/coco (797 stars)
- Category: Writing
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add coco-research/coco --skill c4-architecture -g -a claude-code -y`
Codex: `npx skills add coco-research/coco --skill c4-architecture -g -a codex -y`
Cursor: `npx skills add coco-research/coco --skill c4-architecture -g -a cursor -y`
Gemini CLI: `npx skills add coco-research/coco --skill c4-architecture -g -a gemini-cli -y`

## Description

Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, or generate context/container/component/deployment diagrams.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# C4 Architecture Documentation

Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".

## Workflow

1. **Understand scope**, Determine which C4 level(s) are needed based on audience
2. **Analyze codebase**, Explore the system to identify components, containers, and relationships
3. **Generate diagrams**, Create Mermaid C4 diagrams at appropriate abstraction levels
4. **Document**, Write diagrams to markdown files with explanatory context

## C4 Diagram Levels

Select the appropriate level based on the documentation need:

| Level | Diagram Type | Audience | Shows | When to Create |
|-------|-------------|----------|-------|----------------|
| 1 | **C4Context** | Everyone | System + external actors | Always (required) |
| 2 | **C4Container** | Technical | Apps, databases, services | Always (required) |
| 3 | **C4Component** | Developers | Internal components | Only if adds value |
| 4 | **C4Deployment** | DevOps | Infrastructure nodes | For production systems |
| - | **C4Dynamic** | Technical | Request flows (numbered) | For complex workflows |

**Key Insight:** "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value.

## Quick Start Examples

### System Context (Level 1)
```mermaid
C4Context
  title System Context - Workout Tracker

  Person(user, "User", "Tracks workouts and exercises")
  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")

The rest: https://github.com/coco-research/coco/blob/HEAD/skills/c4-architecture/SKILL.md