Background
Back to Articles/Mastering the C4 Model
Sections
IntroductionBoxes and ArrowsGoogle Maps AnalogyLevel 1: System ContextLevel 2: ContainerLevel 3: ComponentLevel 4: CodeSupporting DiagramsToolingConclusion

Level 1: System Context

6 min read

Welcome to the country view — the widest zoom C4 offers. The System Context diagram is where every C4 story begins, and it's deliberately the simplest diagram you'll ever draw. If you only ever produce one architecture diagram for your system, this is the one to make.

The 30,000-foot view

At this level, your entire software system is a single box. You are not looking inside it. You're not showing databases, or APIs, or which cloud you deploy to. None of that matters yet.

Instead, the System Context diagram answers three plain-English questions:

  1. What is this system? (The box in the middle.)
  2. Who uses it? (The people around it.)
  3. What other systems does it talk to? (The external systems it depends on or integrates with.)

That's it. The whole point is to draw a clear boundary around your system and show how it fits into the wider world around it. Everything inside the box is "our problem." Everything outside it is "someone else's problem that we interact with." A newcomer should be able to glance at this diagram and immediately grasp the system's purpose and its place in the ecosystem, without knowing a single thing about the technology inside.

Who is this diagram for?

The System Context diagram has the broadest audience of any C4 diagram, precisely because it hides all the technical detail. Its target audience is everybody: non-technical stakeholders, business analysts, product owners, project managers — and developers too. It's the diagram you can confidently put on a slide in front of an executive without anyone needing a computer-science degree to follow along. When a new team member joins, it's the first thing you show them.

The building blocks

A System Context diagram uses just three kinds of element:

  • 🧍 Person — a human user or role that interacts with your system (e.g. "Customer," "Administrator"). People are usually drawn at the edges of the diagram.
  • 📦 Your Software System — the single box in the center representing the thing you're building and describing. This is the only box you "own" on this diagram.
  • 🏢 External System — any other system your system depends on or integrates with, but which you don't own or control (e.g. a payment gateway, an email provider). These are typically shaded differently to signal "not ours."

The connections between these boxes are relationships: labelled arrows that describe the interaction in the reader's language — "Sends order confirmations using," "Makes payments via." A good relationship label reads like a sentence: Customer → browses products using → E-Commerce System.

A worked example: an E-Commerce platform

Let's ground this with a running example we'll carry through the whole guide — a simple online store. At the System Context level, we don't care yet whether it's built in React or Rails or runs on AWS or Azure. We only care about the store, its customer, and the outside services it relies on.

C4Context
title System Context Diagram - E-Commerce Platform
Person(customer, "Customer", "A customer who browses and buys products online.")
System(ecommerce, "E-Commerce System", "Allows customers to view products and checkout.")
System_Ext(payment_gateway, "Payment Gateway", "Processes credit card payments.")
System_Ext(email_system, "Email System", "Sends order confirmations.")
Rel(customer, ecommerce, "Browses products using")
Rel(ecommerce, payment_gateway, "Processes payments via")
Rel(ecommerce, email_system, "Sends emails using")

(This uses Mermaid's C4 syntax, which renders directly in GitHub, many wikis, and most modern Markdown tools — no special software required.)

Read it aloud and it tells a complete little story: a Customer browses products using our E-Commerce System, which in turn processes payments via an external Payment Gateway and sends confirmation emails using an external Email System. In four boxes and three arrows, anyone in the company now understands what the system is and where its boundaries lie. Notice what's absent: no mention of web servers, load balancers, programming languages, or database tables. That restraint is the entire discipline of Level 1.

The golden rule: every box stands on its own

Here is a principle that applies to all C4 diagrams, but is easiest to learn here: every box should make sense on its own.

A reader should never have to ask "wait, what is that?" about any element. In practice, this means each box carries three things:

  1. A name — what it's called ("Payment Gateway").
  2. A type — what kind of thing it is (Person, Software System, External System).
  3. A short description — one line on what it does or is responsible for ("Processes credit card payments").

And every arrow should be labelled and directional, describing the nature and direction of the interaction. An unlabelled arrow is a mystery; "Processes payments via" is an explanation. If you find yourself drawing a bare line between two boxes because you're not sure what the relationship actually is, that's a signal you've found a genuine gap in the team's understanding — which is exactly the kind of thing a good diagram is supposed to surface.

Common beginner mistakes

A few traps catch people at this level:

  • Zooming in too far. If you're tempted to draw your database, your API, or your load balancer here, stop — that's the next level down. The System Context diagram has exactly one box you own.
  • Drawing internal pieces as external systems. External systems are ones you don't build or control. Your own microservices are not external systems; they'll appear when we zoom in.
  • Unlabelled arrows. "A line means they're connected somehow" is not communication. Say how they interact.
  • Trying to be exhaustive. You don't need every third-party service the system has ever pinged. Show the ones that matter for understanding the system's purpose and key dependencies.

Why start here

The System Context diagram is cheap to draw, hard to get wrong, and delivers enormous value: it aligns technical and non-technical people on what the system is before anyone argues about how it's built. It's the shared starting point for every deeper conversation — and it's the perfect launchpad for our next zoom.

In the next section, we open up that single "E-Commerce System" box and look inside for the first time. That's the Container diagram.

Previous: ← Google Maps Analogy · Next: Level 2: Container →