Skip to main content
skill CX Codex

c4-architecture · coco-research — Claude Code skill: C4 diagrams in Mermaid

c4-architecture generates architecture documentation using C4 model: system context, containers, components and deployment as Mermaid diagrams.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill c4-architecture -a claude-code
Open on GitHub

What c4-architecture does

The skill draws four C4 diagram levels — from system context to deployment — plus dynamic request flows. Each level targets a different audience: context for everyone, containers for technical roles, components for developers only. Most teams need just the first two. The skill analyzes the codebase, picks the right abstraction level, and writes diagrams to markdown.

Inside: a four-step workflow and a table showing when to create each level. Triggers on phrases like "architecture diagram", "C4 diagram", "system context". Component diagrams are drawn only when they genuinely add value, not by default.

What it helps with

  • draw system architecture using C4 model
  • document containers, databases and queues in a project
  • show request flow through services
  • visualize external dependencies and actors
  • generate deployment diagram for DevOps

Example prompts for the agent

  • Draw a C4 Context for this repo
  • Create a Container Diagram showing the frontend, API, PostgreSQL and Kafka
  • Build a dynamic diagram for the checkout process

How to install c4-architecture

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill c4-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/c4-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/c4-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about c4-architecture

How to install c4-architecture in Claude Code?

Run npx skills add coco-research/coco --skill c4-architecture -a claude-code, the skill will be at ~/.claude/skills/c4-architecture/SKILL.md.

What does c4-architecture do?

Generates architecture documentation as C4 diagrams (context, containers, components, deployment) in Mermaid format. Analyzes the codebase and chooses the right abstraction level.

When to draw a Component Diagram?

Only when it adds real value — context and containers are enough for most teams. Draw components when you need to show the internal structure of a specific module to developers.

Source text

SKILL.md · MIT
---
name: c4-architecture
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."
domain: engineering
supports: [claude-code, cursor, codex, generic]
version: 0.1.0
---

# 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")

  Rel(user, app, "Uses")
  Rel(app, browser, "Persists data to", "IndexedDB")
```

### Container Diagram (Level 2)

When the request names apps, services, workers, databases, or queues, draw each name as exactly one element: `Container` for an app, service, or worker; `ContainerDb` for a database or store; `ContainerQueue` for a queue or topic. Put that name in the label. Do not make it a `Container_Boundary` and do not invent inner containers or components. Pass only element aliases to `Rel`, never a boundary alias. Keep the request's direction: `A calls B`, `A writes to B`, `A reads B`, `A pulls from B`, `A drains B`, and `from A to B` are all `Rel(a, b, ...)`.

```mermaid
C4Container
  title Container Diagram - Checkout

  Container(shop, "Basket App", "React", "Places orders")
  Container(api, "Catalog API", "Java", "Accepts orders")
  ContainerDb(db, "Catalog DB", "PostgreSQL", "Product rows")
  ContainerQueue(bus, "Price Queue", "Kafka", "Price events")
  Container(worker, "Index Worker", "Java", "Updates search")

  Rel(shop, api, "Sends orders to", "JSON/HTTPS")
  Rel(api, db, "Writes to", "JDBC")
  Rel(api, bus, "Publishes to")
  Rel(bus, worker, "Delivers events to")
```

The workout diagram below breaks one app into internal containers. For a list of named containers, use the flat form above.

```mermaid
C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")
```

**Named parts are elements, not boundaries.** On `C4Container`, each app, service, worker, portal, console, screen, database, store, and queue the user names is one element. Put that exact name in the label:

- app, service, worker, portal, console, or screen → `Container(alias, "Name", "tech", "description")`
- database or store → `ContainerDb(alias, "Name", "tech", "description")`
- queue or topic → `ContainerQueue(alias, "Name", "tech", "description")`

Do not declare that name as `Container_Boundary` and do not nest `Component`s under it. A boundary cannot be a `Rel` endpoint. Aim the arrow with the sentence: "A calls B" / "A writes to B" → `Rel(a, b, "...")`; "events flow from the queue to the worker" → `Rel(queue, worker, "...")`; "the worker pulls or drains the queue" → `Rel(worker, queue, "...")`.

```mermaid
C4Container
  title Container Diagram - Parcel Desk
  Container(desk, "Desk App", "React", "Creates bookings")
  Container(api, "Booking API", "Go", "Reads and writes bookings")
  ContainerDb(db, "Booking DB", "PostgreSQL", "Booking records")
  ContainerQueue(q, "Job Queue", "SQS", "Booking events")
  Container(worker, "Ticket Worker", "Go", "Issues tickets")
  Rel(desk, api, "Calls", "JSON/HTTPS")
  Rel(api, db, "Reads and writes", "SQL")
  Rel(api, q, "Publishes events to")
  Rel(q, worker, "Delivers events to")
```

A container diagram declares each named app, service, worker, database, queue, or external system once: `Container`, `ContainerDb`, `ContainerQueue`, or `Container_Ext`, with that name as the label. `Rel` may use only those aliases, or `Person` for a human. Never pass a `Container_Boundary`, `System_Boundary`, or `Deployment_Node` alias — above, arrows go to `spa`, not `app`. Do not replace a named container with a boundary that holds some other element.

Invalid: `Container_Boundary(api, "Checkout API") { Container(handler, "Handler", "Node", "Handles calls") }` then `Rel(shop, api, "Calls")`.
Valid: `Container(shop, "Storefront", "React", "Takes orders")`, `Container(api, "Checkout API", "Node.js", "Validates orders")`, `ContainerDb(db, "Catalog DB", "PostgreSQL", "Product rows")`, `Rel(shop, api, "Submits orders", "JSON/HTTPS")`, `Rel(api, db, "Reads", "SQL")`.

### Component Diagram (Level 3)
```mermaid
C4Component
  title Component Diagram - Workout Feature

  Container(views, "Views", "Vue Router pages")

  Container_Boundary(workout, "Workout Feature") {
    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
    Component(useTimer, "useTimer", "Composable", "Timer state machine")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
  }

  Rel(views, useWorkout, "Uses")
  Rel(useWorkout, useTimer, "Controls")
  Rel(useWorkout, workoutRepo, "Saves to")
```

### Dynamic Diagram (Request Flow)
```mermaid
C4Dynamic
  title Dynamic Diagram - User Sign In Flow

  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
  Container(spa, "Single-Page App", "React", "Banking UI")

  Container_Boundary(api, "API Application") {
    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
    Component(security, "Security Service", "JWT", "Validates credentials")
  }

  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
  Rel(signIn, security, "2. Validate")
  Rel(security, db, "3. Query user", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")
```

### Deployment Diagram
```mermaid
C4Deployment
  title Deployment Diagram - Production

  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web application")
  }

  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
      Container(api, "API Service", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "Database", "PostgreSQL", "Application data")
    }
  }

  Rel(spa, api, "API calls", "HTTPS")
  Rel(api, db, "Reads/writes", "JDBC")
```

## Element Syntax

### People and Systems
```
Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")       # External person
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # External system
SystemDb(alias, "Label", "Description")         # Database system
SystemQueue(alias, "Label", "Description")      # Queue system
```

### Containers
```
Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")
```

### Components
```
Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")
```

### Boundaries
```
Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Boundary(alias, "Label", "type") { ... }
```

### Relationships
```
Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")                        # Bidirectional
Rel_U(from, to, "Label")                        # Upward
Rel_D(from, to, "Label")                        # Downward
Rel_L(from, to, "Label")                        # Leftward
Rel_R(from, to, "Label")                        # Rightward
```

### Deployment Nodes
```
Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # Shorthand
```

## Styling and Layout

### Layout Configuration
```
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
```
- `$c4ShapeInRow` — Number of shapes per row (default: 4)
- `$c4BoundaryInRow` — Number of boundaries per row (default: 2)

### Element Styling
```
UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")
```

### Relationship Styling
```
UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")
```
Use `$offsetX` and `$offsetY` to fix overlapping relationship labels.

## Best Practices

### Essential Rules

1. **Every element must have**: Name, Type, Technology (where applicable), and Description
2. **Use unidirectional arrows only** — Bidirectional arrows create ambiguity
3. **Label arrows with action verbs** — "Sends email using", "Reads from", not just "uses"
4. **Include technology labels** — "JSON/HTTPS", "JDBC", "gRPC"
5. **Stay under 20 elements per diagram** — Split complex systems into multiple diagrams

### Clarity Guidelines

1. **Start at Level 1** — Context diagrams help frame the system scope
2. **One diagram per file** — Keep diagrams focused on a single abstraction level
3. **Meaningful aliases** — Use descriptive aliases (e.g., `orderService` not `s1`)
4. **Concise descriptions** — Keep descriptions under 50 characters when possible
5. **Always include a title** — "System Context diagram for [System Name]"

### What to Avoid

See [references/common-mistakes.md](references/common-mistakes.md) for detailed anti-patterns:
- Confusing containers (deployable) vs components (non-deployable)
- Modeling shared libraries as containers
- Showing message brokers as single containers instead of individual topics
- Adding undefined abstraction levels like "subcomponents"
- Removing type labels to "simplify" diagrams

## Microservices Guidelines

### Single Team Ownership
Model each microservice as a **container** (or container group):
```mermaid
C4Container
  title Microservices - Single Team

  System_Boundary(platform, "E-commerce Platform") {
    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
  }
```

### Multi-Team Ownership
Promote microservices to **software systems** when owned by separate teams:
```mermaid
C4Context
  title Microservices - Multi-Team

  Person(customer, "Customer", "Places orders")
  System(orderSystem, "Order System", "Team Alpha")
  System(inventorySystem, "Inventory System", "Team Beta")
  System(paymentSystem, "Payment System", "Team Gamma")

  Rel(customer, orderSystem, "Places orders")
  Rel(orderSystem, inventorySystem, "Checks stock")
  Rel(orderSystem, paymentSystem, "Processes payment")
```

### Event-Driven Architecture
Show individual topics/queues as containers, NOT a single "Kafka" box:
```mermaid
C4Container
  title Event-Driven Architecture

  Container(orderService, "Order Service", "Java", "Creates orders")
  Container(stockService, "Stock Service", "Java", "Manages inventory")
  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")
  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")

  Rel(orderService, orderTopic, "Publishes to")
  Rel(stockService, orderTopic, "Subscribes to")
  Rel(stockService, stockTopic, "Publishes to")
  Rel(orderService, stockTopic, "Subscribes to")
```

## Output Location

Write architecture documentation to `docs/architecture/` with naming convention:
- `c4-context.md` — System context diagram
- `c4-containers.md` — Container diagram
- `c4-components-{feature}.md` — Component diagrams per feature
- `c4-deployment.md` — Deployment diagram
- `c4-dynamic-{flow}.md` — Dynamic diagrams for specific flows

## Audience-Appropriate Detail

| Audience | Recommended Diagrams |
|----------|---------------------|
| Executives | System Context only |
| Product Managers | Context + Container |
| Architects | Context + Container + key Components |
| Developers | All levels as needed |
| DevOps | Container + Deployment |

## References

- [references/c4-syntax.md](references/c4-syntax.md) — Complete Mermaid C4 syntax
- [references/common-mistakes.md](references/common-mistakes.md) — Anti-patterns to avoid
- [references/advanced-patterns.md](references/advanced-patterns.md) — Microservices, event-driven, deployment

© coco-research · MIT · coco-research/coco

Similar skills

All skills for DevOps and infrastructure →

c4-architecture by other authors comes first.

c4-architecture microsoft This skill turns code or system requirements into C4 architecture diagrams. Use it to document an existing project or map out a planned one with Mermaid. CX Codex +1 ★ 1,627repo stars architecture-blueprint-generator official github architecture-blueprint-generator analyzes a codebase and creates an architecture blueprint with components, dependencies, and diagrams. Use it before extending a project or onboarding developers. CX Codex +1 12,196installs architecture-diagrams aj-geddes Generates system architecture diagrams, data flows, and C4 models using code formats like Mermaid and PlantUML. Useful when documenting service design directly inside your coding agent. CX Codex +1 2,000installs c4-context Seth Hobson Builds top-level C4 context documentation, covering a system, its people, and its external dependencies. Use it to produce a context diagram and map key user journeys. CX Codex ★ 42,780repo stars c4-code Seth Hobson c4-code is a Claude Code subagent that documents code at the C4 level. It runs on requests to map individual directories and modules. CX Codex ★ 42,780repo stars c4-codebase-architecture lmammino c4-codebase-architecture — a skill that walks an agent through a repository and writes C4 architecture docs: system context, containers, components. Handy for onboarding or picking up someone else's code. CX Codex +1 ★ 24repo stars mermaid-diagram-specialist davila7 mermaid-diagram-specialist generates Markdown-ready Mermaid diagrams for flowcharts, ERDs, sequence diagrams, and C4 architecture. Useful for technical writers and system architects. CX Codex +1 145installs

From the same set82

The whole set →
redesign-existing-projects redesign-existing-projects — a Claude skill that audits an existing site or app for the usual AI-design tells and fixes them inside the current stack, leaving behaviour alone. CX Codex +1 ★ 328repo stars database-architect Get database architecture recommendations, data models, and migration plans. Use the subagent when shaping a schema, scaling a system, or splitting data across services. CX Codex ★ 328repo stars tailwind-patterns The tailwind-patterns skill guides Tailwind CSS v4 setup, responsive layouts, and design tokens. Use it when starting a v4 project or moving one from v3. CX Codex +1 ★ 328repo stars create-subagent create-subagent helps create isolated subagents with targeted system prompts and YAML configurations for code reviews, debugging, and data tasks. CX Codex +1 ★ 328repo stars create-skill create-skill guides you through authoring agent skills by defining directory layout, SKILL.md frontmatter, and precise description triggers. CX Codex +1 ★ 328repo stars ultra-think ultra-think is a Claude Code skill that examines architecture decisions from four viewpoints, compares approaches, and gives one recommendation. CX Codex +1 ★ 328repo stars generate-tests generate-tests writes tests for a file, module or component, after first detecting the project's framework and conventions. CX Codex +1 ★ 328repo stars m0-handoff m0-handoff saves session state into STATE.md and the local M0 daemon so another session or tool picks up right where you stopped. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open