The System Context diagram is C4 model level 1 -- the single most important architecture diagram your team can create. This guide explains what belongs in a c4 context diagram, walks through a complete context diagram example, and shows how to create one manually or generate it from your code.

C4 System Context Diagram: Complete Guide with Examples

If you only ever draw one architecture diagram, make it a System Context diagram. It's the entry point of the C4 model, the diagram every stakeholder can read without training, and the fastest way to expose disagreements about what your system actually does.

Yet most teams get it wrong. They cram in databases, microservices, and Kubernetes clusters until the "context" diagram becomes an illegible infrastructure map. Or they skip it entirely and jump straight to a container diagram, leaving non-technical stakeholders with nothing they can understand.

This guide is a deep dive on C4 model level 1: what a system context diagram is, exactly what belongs in it (and what doesn't), a complete worked example, the mistakes that ruin most context diagrams, and a step-by-step process for creating one -- by hand or generated from your codebase. If you're new to the C4 model itself, start with our complete guide to the C4 model and come back.

What Is a System Context Diagram?

A System Context diagram is the first and highest-level diagram in the C4 model. It shows one software system as a single box and answers a single question: how does this system fit into its environment?

As the glossary definition puts it, the System Context diagram focuses on the people and external systems that interact with the system being described, deliberately omitting internal structure. Its goal is to establish scope: who uses the system, which systems it depends on, and which systems depend on it.

Three kinds of elements appear on a context diagram, and only three:

Your software system -- one box, in the center. Not its services, not its databases. One box.
People -- the users, roles, or personas who interact with the system. A "Customer", an "Administrator", a "Support Agent".
External software systems -- the systems yours talks to but your team does not own: a payment gateway, an email provider, a legacy ERP, an identity provider.

Connecting them are relationships: labeled arrows that describe who does what. "Places orders using", "Sends payment requests to", "Receives shipping updates from".

That's the entire vocabulary. Boxes for the system, people, and external systems; arrows for relationships. The discipline of the diagram comes from what you leave out.

Who Is the Audience?

The System Context diagram is unique among the four C4 levels because it's designed for everybody -- including people who will never read a line of code:

Non-technical stakeholders. A product manager, a CEO, or a compliance officer can look at a context diagram and understand the system's purpose, its users, and its third-party dependencies in under a minute.
New team members. Before a new engineer learns your folder structure, they should learn your system boundary. The context diagram is onboarding slide number one.
Architects and security reviewers. Every arrow crossing the system boundary is an integration point, a data flow, and a potential attack surface. Security and compliance reviews often start here.
Other teams. When another team asks "does your system call the billing API directly?", the context diagram answers without a meeting.

This is why technology choices don't belong here. The moment you write "PostgreSQL" or "Kafka" on a context diagram, you've narrowed the audience to engineers -- and you have the container diagram for that.

What Belongs in a Context Diagram (and What Does Not)

Include

The system in scope -- exactly one box, clearly named.
Every category of user -- not individual people, but roles or personas. If customers and warehouse staff use the system differently, they're two separate people-boxes.
Every external system dependency -- including the ones you take for granted: the email service, the identity provider, the analytics platform, the monitoring stack if it's architecturally relevant.
Systems that depend on you -- if a partner's system consumes your API, it belongs on the diagram with the arrow pointing at you.
Labeled relationships -- every arrow needs a verb phrase. An unlabeled arrow is a question mark.

Exclude

Containers -- no web apps, no API services, no databases, no message queues. Those are level 2.
Technology choices -- no "React", no "Go", no "PostgreSQL". A context diagram should survive a complete rewrite of your stack without changing.
Internal structure of external systems -- Stripe is one box, not a diagram of Stripe's architecture.
Infrastructure and deployment details -- no regions, no clusters, no load balancers.
Individual features -- the diagram shows relationships, not a feature list.

A simple test: if removing an element wouldn't change who interacts with the system or which external systems it touches, that element doesn't belong at level 1.

A Complete Context Diagram Example: Online Payment Platform

Let's work through a realistic example. Imagine you're documenting PayFlow, an online payment platform that lets merchants accept card payments on their websites.

Step 1: Name the system

One box in the center: PayFlow Payment Platform. Give it a one-line description: "Allows merchants to accept and manage online card payments."

Step 2: Identify the people

Who interacts with PayFlow, and in what role?

Merchant -- a business owner who configures payment pages, views transactions, and triggers refunds.
End Customer -- a shopper who pays for a purchase through a PayFlow checkout.
Support Agent -- internal staff who investigate disputed transactions.

Step 3: Identify the external systems

What does PayFlow depend on, and what depends on PayFlow?

Card Networks / Acquiring Bank -- authorizes and settles card transactions.
Fraud Detection Service -- scores transactions for fraud risk.
Email Service -- sends receipts and notifications.
Identity Provider -- handles merchant single sign-on.
Merchant E-Commerce Site -- the merchant's own website, which embeds the PayFlow checkout and consumes the PayFlow API.
Accounting Platform -- receives settlement reports for merchant bookkeeping.

Step 4: Draw the relationships

The full element and relationship list looks like this:

People:
  [Merchant]          --> [PayFlow] : Configures payments, views transactions, issues refunds
  [End Customer]      --> [PayFlow] : Pays for purchases via hosted checkout
  [Support Agent]     --> [PayFlow] : Investigates and resolves disputes

External systems:
  [Merchant E-Commerce Site] --> [PayFlow] : Initiates payments via API, embeds checkout
  [PayFlow] --> [Card Networks / Acquiring Bank] : Authorizes and settles card transactions
  [PayFlow] --> [Fraud Detection Service] : Requests risk scores for transactions
  [PayFlow] --> [Email Service] : Sends receipts and payment notifications
  [PayFlow] --> [Identity Provider] : Delegates merchant authentication
  [PayFlow] --> [Accounting Platform] : Exports settlement reports

Ten elements total: one system, three people, six external systems. Every arrow has a verb phrase. There is no mention of services, databases, queues, or languages -- and yet anyone reading this diagram understands what PayFlow is, who uses it, and what it depends on.

Notice what this diagram makes immediately visible:

Compliance surface. Card networks and fraud detection on the diagram tell a security reviewer exactly where PCI-relevant data flows.
Vendor risk. Six external dependencies, each a potential point of failure or contract negotiation.
Two-directional boundary. The merchant's e-commerce site calls into PayFlow -- the system isn't just a consumer of other services, it's a dependency for someone else.

That's the kind of conversation a context diagram is built to start.

Common Mistakes in System Context Diagrams

Mistake 1: Too much detail

The most common failure. The diagram starts clean, then someone adds "just the main database", then the API gateway, then the three core microservices, and within a month it's a container diagram wearing a context diagram's name. The fix is ruthless: your system is one box. If you feel the urge to show internals, that's the signal to create a container diagram as a separate, linked view -- not to overload this one.

Mistake 2: Missing external dependencies

Teams reliably forget the dependencies they consider boring: the email provider, the SMS gateway, the identity provider, the CDN, the feature-flag service. But "boring" dependencies cause real outages and real vendor lock-in. Walk through your configuration files and environment variables -- every API key usually corresponds to an external system that belongs on the diagram.

Mistake 3: Mixing abstraction levels

A diagram showing "Customer → Web App → Orders API → PostgreSQL → Stripe" mixes a person, two containers, a database, and an external system in one flat view. Readers can't tell where your system boundary is. Each C4 diagram should live at exactly one zoom level; the whole point of the C4 model hierarchy is that you zoom in between diagrams, never within one.

Mistake 4: Unlabeled or vague relationships

"Uses" is not a relationship label -- everything "uses" everything. Write what actually happens: "Submits orders via", "Receives webhook events from", "Authenticates against". The labels are where most of the diagram's information lives.

Mistake 5: Drawing it once and never updating it

A context diagram from 2023 that still shows the legacy CRM you migrated off last year is actively misleading. Context diagrams change less often than lower-level diagrams, but they do change -- every new vendor integration, every deprecated partner API. Treat the diagram as living documentation, not a kickoff artifact.

How to Create a System Context Diagram: Step by Step

The manual approach

Name and describe the system. One sentence: what does it do, for whom?
List the user roles. Brainstorm every distinct persona that interacts with the system. Merge roles that interact identically; split roles that don't.
List the external systems. Go through integrations, API keys, webhooks, scheduled exports. Include systems that call you, not just systems you call.
Draw the relationships. One arrow per meaningful interaction, each labeled with a verb phrase. Direction follows the initiative: who initiates the interaction?
Review with the team. This is the highest-value step. A 30-minute review reliably surfaces disagreements: "wait, do we still call that service?", "since when do partners hit our API directly?" Those debates are the deliverable.
Publish it where people will find it -- not buried in a wiki page nobody visits.

Any tool works for the drawing itself: a whiteboard, diagrams.net, Structurizr, PlantUML with C4 extensions. The bottleneck was never the drawing -- it's steps 2, 3, and 5, and keeping the result accurate over time.

The automated approach: generating context diagrams with Archyl

This is where Archyl takes a different path from drawing tools. Instead of starting from a blank canvas, you connect your repositories and run AI discovery: Archyl analyzes your code structure, configuration files, and dependency graphs, then proposes a draft C4 model -- systems, external dependencies, containers, components, and the relationships between them. You review each suggestion, accept or adjust it, and the System Context view renders automatically from the model.

Because the diagram is generated from a model rather than drawn by hand, two things follow:

The levels stay connected. The system box on your context diagram is the same entity you drill into for the container view. No copy-paste drift between diagrams.
Staleness becomes measurable. Archyl's drift detection continuously compares your documented architecture against what actually exists in the codebase, so when an integration is removed or a service renamed, you find out from a drift score instead of from a confused new hire.

If you prefer documentation that lives in version control, Archyl also supports an Architecture as Code workflow: define your C4 model in YAML, commit it alongside your code, and let the diagrams render from that definition.

From Context to Containers

The System Context diagram sets the boundary; the next level opens the box. Once your context diagram is stable, the natural next step is the container diagram -- the level 2 view showing the deployable units (web apps, APIs, databases, brokers) inside your system and how they communicate. We cover that in detail in our C4 Container Diagram guide.

The progression matters. Teams that skip the context diagram and start at level 2 tend to produce container diagrams with fuzzy boundaries -- external systems mixed in with internal services, because nobody ever agreed where the system ends.

FAQ

What is the difference between a System Context diagram and a Container diagram?

The context diagram (level 1) shows your system as a single box and focuses on its environment: users and external systems. The container diagram (level 2) zooms inside that box to show deployable units -- web apps, services, databases -- and their technology choices. Context answers "what does this system interact with?"; containers answer "what is this system made of?"

How many elements should a context diagram have?

There's no hard rule, but most healthy context diagrams have one system, two to five user roles, and three to ten external systems. If you're past fifteen or twenty elements, either your system boundary is too broad, or you're documenting an enterprise landscape -- in which case the C4 System Landscape diagram (multiple systems on one view) is the better fit.

Should databases appear on a System Context diagram?

No -- as long as the database belongs to your system, it's an internal detail and appears at the container level. The exception is a database operated by another team or vendor that your system reads from directly; that's effectively an external system and can appear as one.

Is a C4 context diagram the same as a UML or data-flow context diagram?

Conceptually they're cousins -- the idea of a "context diagram" (one system, its environment) predates C4 and exists in structured analysis and UML practice. The C4 version is distinguished by its place in a hierarchy: every element on it can be decomposed into the next level down, giving you a navigable map instead of a standalone picture.

Ready to create your System Context diagram? Try Archyl free and generate a C4 model directly from your repositories. Or keep reading: What is the C4 Model? A Complete Guide | C4 Container Diagram Guide | System Context Diagram in the glossary.

C4 System Context Diagram: Complete Guide with Examples - Archyl Blog