Skip to content

cheriftj/c4-model-skill / skills/c4-model

c4-model

Verified

FileKindSize
SKILL.mdskill md14.1 KB
examples/01-context.example.mdmarkdown4.7 KB
examples/02-container.example.mdmarkdown7.2 KB
level-template.mdmarkdown2.5 KB
mermaid-c4-syntax.mdmarkdown10.5 KB
mode-design.mdmarkdown4.5 KB
mode-document-code.mdmarkdown4.3 KB
mode-document-prose.mdmarkdown2.5 KB
mode-review.mdmarkdown3.5 KB
mode-update.mdmarkdown2.9 KB
review-checklist.mdmarkdown3.6 KB
supporting-diagrams.mdmarkdown4.1 KB

mermaid-c4-syntax.md

View on GitHub
# Mermaid C4 — syntax reference

Syntax reference for C4 in Mermaid. Normative content sourced from the official Mermaid documentation ([`mermaid.js.org/syntax/c4.html`](https://mermaid.js.org/syntax/c4.html)); editorial advice is clearly labeled.

> **Status**: the official Mermaid docs state that the C4 syntax is **experimental** — *"The syntax and properties can change in future releases."* Always verify it renders correctly in the target viewer (GitHub, Mermaid Live Editor, Confluence, Notion…) before publishing.
>
> **PlantUML compatibility**: Mermaid notes that its C4 syntax is compatible with the C4-PlantUML library. Diagrams written in one are close to those written in the other.

## The 5 C4 diagram types in Mermaid

| Keyword | C4 level | Usage |
|---|---|---|
| `C4Context` | 1 | System + actors + external systems |
| `C4Container` | 2 | Containers (apps + stores) of the system |
| `C4Component` | 3 | Components of a container |
| `C4Dynamic` | — | Numbered flow between elements (supporting diagram) |
| `C4Deployment` | — | Deployment topology (nodes + deployed containers) |

For level 4 (Code), Mermaid has no `C4Code` type. Use `classDiagram` (classical UML) — consistent with official C4 practice.

## Elements — full signatures

Parameters prefixed with `?` are optional. The `$link` parameter is always optional.

### Persons

```text
Person(alias, label, ?descr, ?sprite, ?tags, $link)
Person_Ext(alias, label, ?descr, ?sprite, ?tags, $link)
```

### Systems (Context level)

```text
System(alias, label, ?descr, ?sprite, ?tags, $link)
System_Ext(alias, label, ?descr, ?sprite, ?tags, $link)
SystemDb(alias, label, ?descr, ?sprite, ?tags, $link)
SystemDb_Ext(alias, label, ?descr, ?sprite, ?tags, $link)
SystemQueue(alias, label, ?descr, ?sprite, ?tags, $link)
SystemQueue_Ext(alias, label, ?descr, ?sprite, ?tags, $link)
```

### Containers (Container level)

```text
Container(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
Container_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ContainerDb(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ContainerDb_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ContainerQueue(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ContainerQueue_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
```

### Components (Component level)

```text
Component(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
Component_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ComponentDb(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ComponentDb_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ComponentQueue(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
ComponentQueue_Ext(alias, label, ?techn, ?descr, ?sprite, ?tags, $link)
```

### Deployment (Deployment level)

```text
Deployment_Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link)
Node(alias, label, ?type, ?descr, ?sprite, ?tags, $link)           # shortcut
Node_L(alias, label, ?type, ?descr, ?sprite, ?tags, $link)          # left-aligned
Node_R(alias, label, ?type, ?descr, ?sprite, ?tags, $link)          # right-aligned
```

## Boundaries — grouping elements

```text
Boundary(alias, label, ?type, ?tags, $link)
Enterprise_Boundary(alias, label, ?tags, $link)
System_Boundary(alias, label, ?tags, $link)
Container_Boundary(alias, label, ?tags, $link)
```

**Editorial advice** — pick the boundary by level:
- `Enterprise_Boundary` → Context level, wrapping an organization's systems
- `System_Boundary` → Container level, wrapping the containers of a system
- `Container_Boundary` → Component level, wrapping the components of a container

Boundaries can be nested. Syntax: `{` `}` after the label.

## Relationships — full syntax

### Relationship types

| Type | Syntax | Usage |
|---|---|---|
| `Rel` | `Rel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)` | Directed relationship |
| `BiRel` | `BiRel(from, to, label, ?techn, ?descr, ?sprite, ?tags, $link)` | Bidirectional relationship |
| `RelIndex` | `RelIndex(index, from, to, label, ?tags, $link)` | For `C4Dynamic` — the index is ignored; order comes from position in the code |

**Editorial advice** — avoid `BiRel`: split it into two distinct `Rel` calls to make each intent explicit.

### Directional variants

Short and long forms are equivalent:

```text
Rel_U / Rel_Up         # upward
Rel_D / Rel_Down       # downward
Rel_L / Rel_Left       # leftward
Rel_R / Rel_Right      # rightward
Rel_Back               # reversed arrow
```

Directional variants help guide layout — see the "Layout" section below.

## Styling and customization

### `UpdateElementStyle`

Updates an element's appearance without creating a legend entry.

```text
UpdateElementStyle(alias, ?bgColor, ?fontColor, ?borderColor, ?shadowing, ?shape, ?sprite, ?techn, ?legendText, ?legendSprite)
```

### `UpdateRelStyle`

Updates a relationship's appearance and the position of its label.

```text
UpdateRelStyle(from, to, ?textColor, ?lineColor, ?offsetX, ?offsetY)
```

`offsetX` and `offsetY` shift the label from its default position (in pixels).

### `UpdateLayoutConfig`

Adjusts layout dimensions.

```text
UpdateLayoutConfig(?c4ShapeInRow, ?c4BoundaryInRow)
```

Default values: `c4ShapeInRow=4`, `c4BoundaryInRow=2`.

## Parameter passing — positional vs named

Two equivalent syntaxes for optional parameters. Prefix with `$` for named.

**Positional**:

```text
UpdateRelStyle(customerA, bankA, "red", "blue", "-40", "60")
```

**Named** (free order, allows skipping intermediate params):

```text
UpdateRelStyle(customerA, bankA, $offsetX="-40", $offsetY="60", $lineColor="blue", $textColor="red")
UpdateRelStyle(customerA, bankA, $offsetY="60")
```

Named form is more readable when passing only a few options.

## Layout — controlling rendering

Per the Mermaid docs: *"The layout does not use a fully automated layout algorithm. The position of shapes is adjusted by changing the order in which statements are written."*

In practice:
- **Statement order** = primary layout lever
- **Direction suffixes** (`Rel_U`, `Rel_D`, `Rel_L`, `Rel_R`) = secondary lever
- **`UpdateLayoutConfig`** = control over shapes-per-row

If the rendering is unreadable, reorder elements before piling on styles.

## Features not supported (as of this reference's compilation)

Per the official Mermaid docs, the following features are **not yet supported**:

- `sprite`
- `tags` and `AddElementTag` / `AddRelTag`
- `link` parameter (`$link`)
- `Legend`
- Layout statements (`Lay_U`, `Lay_D`, `Lay_L`, `Lay_R` and variants)
- Custom shape functions (`RoundedBoxShape()`, `EightSidedShape()`)
- Line-style functions (`DashedLine()`, `DottedLine()`, `BoldLine()`)

These features exist in C4-PlantUML but not (yet) in Mermaid. Check the official docs before depending on any of them.

## Full examples

The examples below are illustrative, consistent with the syntax documented by Mermaid.

### Context — with `Enterprise_Boundary`

```mermaid
C4Context
    title System Landscape for a Bank

    Person(customer, "Banking Customer")

    Enterprise_Boundary(bank, "Big Bank plc") {
        System(banking_system, "Internet Banking System", "Online banking.")
        System(atm, "ATM", "Withdraw cash.")
        System(call_center, "Call Center System", "Phone support.")
        System_Ext(mainframe, "Mainframe Banking System", "Core banking.")
    }

    System_Ext(mail, "E-mail System")

    Rel(customer, banking_system, "Uses")
    Rel(customer, atm, "Withdraws cash using")
    Rel(customer, call_center, "Calls")
    Rel(banking_system, mainframe, "Uses")
    Rel(atm, mainframe, "Uses")
    Rel(call_center, mainframe, "Uses")
    Rel(banking_system, mail, "Sends e-mail using")
```

### Dynamic — numbered sequence

Inside a `C4Dynamic`, `Rel` calls are **automatically numbered** in declaration order.

```mermaid
C4Dynamic
    title Dynamic diagram - Authentication flow

    ContainerDb(db, "Database", "Oracle")
    Container(spa, "Single-Page App", "JavaScript, Angular")
    Container_Boundary(api, "API Application") {
        Component(sign_in, "Sign In Controller", "Spring MVC")
        Component(security, "Security Component", "Spring Bean")
    }

    Rel(spa, sign_in, "Submits credentials to", "JSON/HTTPS")
    Rel(sign_in, security, "Validates credentials using")
    Rel(security, db, "select * from users where username = ?", "JDBC")
    Rel_Back(security, db, "Returns user data to")
    Rel_Back(sign_in, security, "Returns true if credentials are valid")
```

### Deployment — nested nodes

```mermaid
C4Deployment
    title Deployment diagram for Internet Banking System - Live

    Deployment_Node(customer_pc, "Customer's computer", "Microsoft Windows or macOS") {
        Deployment_Node(browser, "Web Browser", "Chrome, Firefox, Safari, or Edge") {
            Container(spa, "Single-Page App", "JavaScript, Angular")
        }
    }

    Deployment_Node(customer_phone, "Customer's mobile device", "Apple iOS or Android") {
        Container(mobile, "Mobile App", "Xamarin")
    }

    Deployment_Node(dc, "Big Bank plc", "Big Bank plc data center") {
        Deployment_Node(api_server, "bigbank-api***", "Ubuntu 22.04 LTS") {
            Deployment_Node(jvm, "Apache Tomcat", "Apache Tomcat 10.x") {
                Container(api, "API Application", "Java, Docker")
            }
        }

        Deployment_Node(db_server, "bigbank-db01", "Ubuntu 22.04 LTS") {
            ContainerDb(db_primary, "Database", "Oracle 19c")
        }

        Deployment_Node(db_backup, "bigbank-db02", "Ubuntu 22.04 LTS") {
            ContainerDb(db_secondary, "Database", "Oracle 19c")
        }
    }

    Rel(spa, api, "Makes API calls to", "JSON/HTTPS")
    Rel(mobile, api, "Makes API calls to", "JSON/HTTPS")
    Rel(api, db_primary, "Reads from and writes to", "JDBC")
    Rel(db_primary, db_secondary, "Replicates data to")
```

## Common pitfalls (editorial advice)

- **Long overflowing labels** — prefer a short description (1-2 lines) in the diagram, expand in the accompanying Markdown.
- **Deeply nested boundaries** (3+ levels) — often renders poorly. Better split into multiple diagrams.
- **Special characters in labels** — escape quotes if needed, avoid backticks.
- **Relying on an unsupported feature** (see list above) — check the official docs before.

## Links

- Official Mermaid docs: [`mermaid.js.org/syntax/c4.html`](https://mermaid.js.org/syntax/c4.html)
- Simon Brown's C4 model site: [`c4model.com`](https://c4model.com)
- C4-PlantUML (compatible syntax): [`github.com/plantuml-stdlib/C4-PlantUML`](https://github.com/plantuml-stdlib/C4-PlantUML)
- ← Back to SKILL: [`SKILL.md`](SKILL.md)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall