C4 Level 1: How to Draw a System Context Diagram

In our introduction to C4 we described four levels of diagram. This article covers the first and most widely useful: the System Context diagram. If you only ever draw one C4 diagram, this is the one.

What a context diagram shows

A context diagram is the view from 10,000 feet. It shows your system as a single box in the middle, surrounded by the people who use it and the other systems it depends on or exchanges data with. It deliberately says nothing about internal structure or technology. The question it answers is: what is this system, who uses it, and how does it fit into its environment?

The audience is everyone: developers, architects, product owners, business stakeholders, support teams and new joiners. If a non-technical colleague cannot follow it, it is too detailed.

The building blocks

  • The system in scope. One box, named and described in a sentence. This is the thing you are building or documenting.
  • People. Users, roles or personas who interact with the system, such as “Customer”, “Support Agent” or “Administrator”. Use roles, not individual names.
  • External systems. Other software systems your system relies on or that rely on it: payment providers, identity providers, ERP, CRM, email services, data platforms, partner APIs.
  • Relationships. Arrows between the boxes, each labelled with a short description of the interaction, such as “Sends invoices to” or “Authenticates users with”.

Notice what is missing: no databases, no services, no programming languages, no protocols in the boxes. Those belong in the container diagram at level 2. The focus at this level is people and systems rather than technologies.

A worked example

Imagine an online ordering platform for a retailer. Its context diagram might contain:

  • In the centre: “Order Platform – lets customers browse products and place orders.”
  • People: “Customer” places orders and tracks deliveries; “Customer Service Agent” looks up and amends orders.
  • External systems: “Payment Provider” takes card payments; “Identity Provider” signs users in; “Warehouse System” receives orders to fulfil; “Email Service” sends order confirmations.

Relationships might read: Customer places orders using Order Platform; Order Platform takes payments via Payment Provider; Order Platform sends orders to Warehouse System. That is the whole diagram, and it already tells a new team member most of what they need to know about the landscape.

How to draw one in five steps

  1. Name the system and write a one-sentence description of its purpose.
  2. List the people who use it, by role.
  3. List the external systems it integrates with, including ones that call it and ones it calls.
  4. Draw the relationships and label each one with what happens and, if useful, in which direction data flows.
  5. Add a title and a legend, then review it with someone outside the team.

Common mistakes

  • Too much detail. If you are drawing databases or microservices, you have slipped down to level 2.
  • Technology in the boxes. Keep labels in business and system terms; technology choices come later.
  • Unlabelled arrows. An arrow with no label forces the reader to guess.
  • Forgetting the less obvious actors, such as batch jobs, administrators, monitoring tools or other teams’ systems.
  • Drawing the whole enterprise. Scope the diagram to one system; if you need an estate-wide view, make a separate landscape diagram.

A quick checklist

  • Does the diagram have a title that names the system and the diagram type?
  • Is the system in scope clearly distinguished from everything else?
  • Does every person and external system have a name, a type and a short description?
  • Is every relationship labelled?
  • Is there a legend?
  • Could a new starter explain the system’s purpose after one minute with it?

Where to go next

Once your context diagram is agreed, you are ready to zoom in. The next article in this series covers the Container diagram, where we open up the system box and look at the applications, services and data stores inside it.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top