# System context diagram

A context diagram has one job: show your system as a single box, surrounded by the people who use it and the systems it talks to. No technology, no internals.

It is the diagram to put at the top of any architecture page, because it is the only one everybody can read.

---

## When to draw one

* Opening an architecture document.
* Explaining a system to somebody outside the team.
* Agreeing scope: what is ours and what is not.

---

## What is on the diagram

| **Element**     | **Meaning**                                     |
| --------------- | ----------------------------------------------- |
| Person          | Someone who uses the system                     |
| Software system | Your system, drawn as one box                   |
| External system | Something you depend on but do not own          |
| Relationship    | Labelled with what it does and, optionally, how |

---

## A worked example

A context diagram with two external systems:

![System context diagram](https://help.gocapable.com/images/att1417871416.svg)

The source, which you can paste into a new diagram and edit:

```
@startuml
!include <C4/C4_Context>

title System context: Order platform

Person(customer, "Customer", "Places and tracks orders")
Person(agent, "Support agent", "Handles queries and refunds")

System(orders, "Order platform", "Takes orders, handles payment and fulfilment")

System_Ext(payments, "Payment provider", "Authorises and captures card payments")
System_Ext(warehouse, "Warehouse system", "Picks, packs and ships")
System_Ext(email, "Email service", "Transactional email")

Rel(customer, orders, "Places orders using", "HTTPS")
Rel(agent, orders, "Handles queries using", "HTTPS")
Rel(orders, payments, "Charges cards using", "HTTPS/REST")
Rel(orders, warehouse, "Sends fulfilment requests to", "SFTP")
Rel(orders, email, "Sends receipts using", "SMTP")
@enduml
```

---

## A few things that catch people out

* No technology on a context diagram. If it mentions Kubernetes, it has become a container diagram.
* Everything outside the box is either a person or an external system. There is no third category.
* Keep it to one screen. If it does not fit, your system boundary is drawn too wide.

---

## Related

[Container diagramC4 level 2: the deployable pieces inside your system.](https://help.gocapable.com/diagrams/container-diagram.html)

[Component viewC4 level 3: inside one container, for the parts that are hard.](https://help.gocapable.com/diagrams/component-view.html)

[C4 modelBack to the C4 overview.](https://help.gocapable.com/diagrams/c4-model.html)

---

_Context first. Always._