# C4 diagram templates (Mermaid)

From ArchitectureCompass (https://architecturecompass.com). Free to use and adapt.

The C4 model (https://c4model.com/) describes software at four levels of zoom. These templates cover the three you will use most. They use ordinary Mermaid flowcharts, so they render in GitHub, GitLab, many wikis and most Markdown editors. Replace the example names with your own.

## Level 1: System context

Who uses the system, and which other systems does it talk to?

```mermaid
flowchart TB
    customer["Customer<br/><i>Person</i><br/>Places and tracks orders"]
    staff["Support agent<br/><i>Person</i><br/>Handles customer issues"]
    system["Ordering platform<br/><i>Software system</i><br/>Lets customers order products"]
    payments["Payment provider<br/><i>External system</i>"]
    email["Email service<br/><i>External system</i>"]
    erp["ERP<br/><i>Existing internal system</i>"]

    customer -- "Places orders using" --> system
    staff -- "Looks up orders using" --> system
    system -- "Takes payments through" --> payments
    system -- "Sends confirmations through" --> email
    system -- "Sends fulfilled orders to" --> erp
```

## Level 2: Containers

What are the deployable units (applications, databases, queues) inside the system, and how do they talk?

```mermaid
flowchart TB
    customer["Customer<br/><i>Person</i>"]
    subgraph platform ["Ordering platform"]
        web["Web app<br/><i>Container: React</i>"]
        api["Orders API<br/><i>Container: Java, Spring Boot</i>"]
        worker["Payments worker<br/><i>Container: Java</i>"]
        db[("Orders database<br/><i>Container: PostgreSQL</i>")]
        bus{{"Event broker<br/><i>Container: Kafka</i>"}}
    end
    payments["Payment provider<br/><i>External system</i>"]

    customer -- "Uses, HTTPS" --> web
    web -- "Calls, JSON over HTTPS" --> api
    api -- "Reads and writes, SQL" --> db
    api -- "Publishes OrderPlaced" --> bus
    bus -- "Delivers events to" --> worker
    worker -- "Charges cards, HTTPS" --> payments
```

## Level 3: Components

What are the main building blocks inside one container?

```mermaid
flowchart TB
    subgraph api ["Orders API"]
        controller["Order controller<br/><i>Component: REST endpoints</i>"]
        service["Order service<br/><i>Component: business rules</i>"]
        repo["Order repository<br/><i>Component: data access</i>"]
        outbox["Outbox publisher<br/><i>Component: publishes events</i>"]
    end
    db[("Orders database")]
    bus{{"Event broker"}}

    controller --> service
    service --> repo
    service --> outbox
    repo --> db
    outbox --> db
    outbox --> bus
```

## Tips

- Give every box a name, a type and one line on its responsibility.
- Label every arrow with what flows and how (protocol or technology).
- Keep each diagram to one level of zoom; link to the next level instead of mixing them.
- Add a title and a date, and update diagrams when the architecture changes.