Markdown C4 model maker

Draw a C4 model in a Mermaid block. Place people and systems, group them in boundaries, and connect them with labelled relationships to show how a system fits together inline in your document.

Mermaid C4 model syntax

A C4 diagram starts with a header, then lists the elements (people and systems), optional boundaries that group them, and the relationships between them. Each element has an alias, a label and an optional description. Here is each piece you can write.

Elements

Start with C4Context, then add a Person or a System. Each takes an alias, a quoted label and an optional quoted description.

You write

C4Context
  Person(customer, "Customer", "A bank customer")
  System(banking, "Internet Banking", "View accounts")
  System_Ext(mail, "E-mail System", "Sendgrid")
  Rel(customer, banking, "Uses")

You get

Boundaries

Wrap elements in a System_Boundary to group them. The elements between the braces belong to the boundary.

You write

C4Context
  Person(customer, "Customer")
  System_Boundary(b1, "Bank") {
    System(web, "Web App")
    SystemDb(db, "Database", "Accounts")
  }
  Rel(customer, web, "Uses", "HTTPS")

You get

Relationships

Connect two elements with Rel. Add a technology as a fourth argument, use BiRel for a two-way link, or force a direction with Rel_U, Rel_D, Rel_L and Rel_R.

You write

C4Context
  System(web, "Web App")
  System(api, "API")
  SystemDb(db, "Database")
  Rel(web, api, "Calls", "JSON/HTTPS")
  BiRel(api, db, "Reads/Writes")

You get

Cheat sheet

Write this	You get
`C4Context`	Start a system context diagram
`title Text`	Name the diagram
`Person(id, "Label", "Descr")`	A person (drop the description to leave it out)
`Person_Ext(id, "Label")`	A person outside the system
`System(id, "Label", "Descr")`	A software system
`System_Ext(id, "Label")`	An external system
`SystemDb(id, "Label")`	A system drawn as a database
`Container(id, "Label")`	A container (app, service)
`ContainerDb(id, "Label")`	A container drawn as a database
`System_Boundary(id, "Label") { … }`	Group the elements inside the braces
`Rel(a, b, "Label")`	An arrow from a to b
`Rel(a, b, "Label", "Tech")`	An arrow labelled with a technology
`BiRel(a, b, "Label")`	A two-way arrow
`Rel_U / Rel_D / Rel_L / Rel_R`	Force the arrow up, down, left or right