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

#A worked example

A context diagram with two external systems:

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

Context first. Always.