/c4-architecture

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)

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, ...)`.

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.

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, "...")`.

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_Boundar