c4-diagram

C4 Architecture Diagrams

Generate C4-model architecture diagrams using standard Mermaid flowchart syntax.

Why not the Mermaid C4 plugin? The C4Context/C4Container/C4Component Mermaid plugin produces overlapping labels and broken layout. Use flowchart TB or flowchart LR with manual C4 styling instead.

Use this skill when:

• Creating a new architecture diagram from scratch
• Documenting a system at Context, Container, or Component level
• Adding a sequence diagram to show runtime behavior
• Reviewing an existing diagram for label length or layout issues

---

Step 1: Choose the C4 Level

Level	Shows	Use when
Context	System + external actors/systems	Onboarding, stakeholder docs
Container	Services, DBs, queues inside the system	Architecture decisions, team handoffs
Component	Modules/classes inside one container	Code-level design, deep dives

Start at Context. Add Container only if Context leaves important questions open. Add Component only if a specific container is the focus of the document.

---

Step 2: Collect the Pieces

Before writing any Mermaid, list out:

1. People — external users/actors (e.g. "Developer", "Customer")
2. Your system — the system being described
3. External systems — APIs, services, data stores outside your system boundary
4. Containers (if Container level) — each deployable unit: web app, API server, DB, queue, etc.
5. Relationships — who calls what, data direction, protocol (HTTP, SQL, AMQP, etc.)

---

Step 3: Write the Diagram

Layout choice

• flowchart TB — top-to-bottom. Use for hierarchical diagrams (Context and Container levels).
• flowchart LR — left-to-right. Use for sequence-like flows or pipeline diagrams.

Node label rule

Node labels must be 5 words or fewer. Put all detail in the legend table (Step 4), not inside node text. Long labels break Mermaid layout.

Good: User, Web App, Auth Service, Postgres DB
Bad:  "User who initiates a login flow", "REST API Service (Node.js/Express on port 8080)"

Node shapes by type

C4 Type	Mermaid shape	Syntax
Person	Stadium (rounded)	id([Label])
System (yours)	Rectangle	id[Label]
External system	Rectangle	id[Label]
Container	Rectangle	id[Label]
Database	Cylinder	id[(Label)]
Queue	Subroutine	id[[Label]]

Color coding by type

Apply these styles after the diagram body — color distinguishes C4 types at a glance:

%% Person: blue
style PersonNodeId fill:#1168bd,color:#fff,stroke:#0b4884

%% Your system / containers: dark blue
style SystemNodeId fill:#1168bd,color:#fff,stroke:#0b4884

%% External system: grey
style ExternalNodeId fill:#999,color:#fff,stroke:#7a7a7a

%% Database: dark green
style DBNodeId fill:#2d6a4f,color:#fff,stroke:#1b4332

%% Queue: orange
style QueueNodeId fill:#e76f51,color:#fff,stroke:#c45c3a

Subgraph for system boundary

Wrap your system's components in a subgraph to show the boundary:

flowchart TB
    User([User])

    subgraph YourSystem["Your System"]
        WebApp[Web App]
        API[API Server]
        DB[(Database)]
    end

    ExtAuth[Auth Provider]

    User -->|HTTPS| WebApp
    WebApp -->|REST| API
    API -->|SQL| DB
    API -->|OAuth2| ExtAuth

Edge labels

Keep edge labels short: the protocol or verb only.

Good: HTTP, SQL, AMQP, reads, writes, calls
Bad:  "sends an authenticated POST request to /api/v1/users"

---

Step 4: Write the Legend Table

Every diagram gets a companion legend table immediately below the Mermaid block. This is where detail lives.

| Node | Type | Description |
|---|---|---|
| User | Person | Authenticated developer using the web UI |
| Web App | Container | Next.js frontend, port 4231 |
| API Server | Container | Node.js/Express REST API, port 7841 |
| Database | Container | PostgreSQL 16, stores all application state |
| Auth Provider | External | GitHub OAuth2 for user authentication |

---

Step 5: Add a Sequence Diagram (Runtime Behavior)

For any diagram showing a non-trivial flow (auth, async jobs, multi-system transactions), add a sequenceDiagram block after the C4 diagram and legend. This shows the runtime behavior the C4 diagram can only imply.

sequenceDiagram
    participant U as User
    participant W as Web App
    participant A as API Server
    participant D as Database

    U->>W: GET /dashboard
    W->>A: GET /api/metrics (JWT)
    A->>D: SELECT * FROM metrics
    D-->>A: rows
    A-->>W: 200 { data }
    W-->>U: rendered page

Keep sequence diagrams to the critical path — not every possible code path. If a sequence diagram would be longer than ~15 lines, split it into multiple named flows.

---

Step 6: Save the File

Save all diagrams as .md files in the project's docs/ directory.

Naming convention:

docs/architecture-context.md       ← Context level
docs/architecture-containers.md    ← Container level
docs/architecture-auth-flow.md     ← Focused topic (includes sequence)

---

Complete Example

## Auth System — Container Level

\`\`\`mermaid
flowchart TB
    Dev([Developer])

    subgraph AuthSystem["Auth System"]
        UI[Web UI]
        API[Auth API]
        DB[(User DB)]
        Cache[[Session Cache]]
    end

    GitHub[GitHub OAuth]

    Dev -->|HTTPS| UI
    UI -->|REST| API
    API -->|SQL| DB
    API -->|Redis| Cache
    API -->|OAuth2| GitHub

    style Dev fill:#1168bd,color:#fff,stroke:#0b4884
    style UI fill:#1168bd,color:#fff,stroke:#0b4884
    style API fill:#1168bd,color:#fff,stroke:#0b4884
    style DB fill:#2d6a4f,color:#fff,stroke:#1b4332
    style Cache fill:#e76f51,color:#fff,stroke:#c45c3a
    style GitHub fill:#999,color:#fff,stroke:#7a7a7a
\`\`\`

| Node | Type | Description |
|---|---|---|
| Developer | Person | Internal developer accessing the auth service |
| Web UI | Container | React SPA, port 4231 |
| Auth API | Container | Express REST API, port 7841 |
| User DB | Container | PostgreSQL, stores users and credentials |
| Session Cache | Container | Redis, stores short-lived session tokens |
| GitHub OAuth | External | Third-party OAuth2 provider |

### Login Flow

\`\`\`mermaid
sequenceDiagram
    participant D as Developer
    participant U as Web UI
    participant A as Auth API
    participant G as GitHub

    D->>U: click "Login with GitHub"
    U->>G: redirect (OAuth2)
    G-->>U: callback with code
    U->>A: POST /auth/github { code }
    A->>G: exchange code for token
    G-->>A: access_token
    A-->>U: session JWT
    U-->>D: logged in
\`\`\`