The C4 context diagram is the big picture of your software system. It shows who uses it, what external systems it depends on, and how they all connect. Level 1 of the C4 model — the diagram every stakeholder should see first.
A C4 context diagram is Level 1 of the C4 model, created by Simon Brown. It answers the most fundamental question about your software: “What does this system do, and who interacts with it?” The diagram shows your system as a single box in the center, surrounded by the people who use it and the external systems it depends on.
Context diagrams are intentionally simple. They hide all internal complexity — no databases, no microservices, no message queues. That detail belongs in container diagrams (Level 2) and component diagrams (Level 3). The context diagram is for everyone: business stakeholders, product managers, new team members, and engineers alike.
In Mermaid syntax, a context diagram uses the C4Context diagram type with four building blocks: Person for users, System for your software, System_Ext for external dependencies, and Rel for relationships between elements.
Every context diagram uses these four building blocks. Each element type has a specific meaning in C4 notation.
A user, role, or persona that interacts with your system. Rendered as a human figure.
Person(customer, "Customer", "Places orders and tracks delivery")The software system being described. This is the focal point of the diagram — everything else revolves around it.
System(platform, "E-Commerce Platform", "Handles catalog, orders, payments")An external system your software depends on but does not own. Payment gateways, email services, third-party APIs.
System_Ext(stripe, "Stripe", "Payment processing")A relationship showing how two elements interact. Include the protocol or mechanism when relevant.
Rel(customer, platform, "Browses products", "HTTPS")A SaaS platform context diagram showing customers, admins, and external integrations.
C4Context
title System Context — SaaS Analytics Platform
Person(analyst, "Data Analyst", "Runs queries and builds dashboards")
Person(admin, "Platform Admin", "Manages users, billing, and configuration")
System(platform, "Analytics Platform", "Ingests data, runs queries, serves dashboards")
System_Ext(dataWarehouse, "Snowflake", "Cloud data warehouse")
System_Ext(auth, "Auth0", "Identity and access management")
System_Ext(email, "SendGrid", "Transactional email delivery")
System_Ext(billing, "Stripe", "Subscription billing")
Rel(analyst, platform, "Builds dashboards, runs queries", "HTTPS")
Rel(admin, platform, "Manages users and billing", "HTTPS")
Rel(platform, dataWarehouse, "Queries data from", "SQL/HTTPS")
Rel(platform, auth, "Authenticates users via", "OIDC")
Rel(platform, email, "Sends notifications through", "API")
Rel(platform, billing, "Processes subscriptions via", "API")Paste this into Cybewave Studio to render it instantly.
The same diagram expressed in PlantUML with C4-PlantUML macros.
@startuml
!include <C4/C4_Context>
title System Context — SaaS Analytics Platform
Person(analyst, "Data Analyst", "Runs queries and builds dashboards")
Person(admin, "Platform Admin", "Manages users and billing")
System(platform, "Analytics Platform", "Ingests data, runs queries, serves dashboards")
System_Ext(warehouse, "Snowflake", "Cloud data warehouse")
System_Ext(auth, "Auth0", "Identity and access management")
System_Ext(email, "SendGrid", "Transactional email delivery")
System_Ext(billing, "Stripe", "Subscription billing")
Rel(analyst, platform, "Builds dashboards", "HTTPS")
Rel(admin, platform, "Manages config", "HTTPS")
Rel(platform, warehouse, "Queries data", "SQL")
Rel(platform, auth, "Authenticates via", "OIDC")
Rel(platform, email, "Sends email", "API")
Rel(platform, billing, "Processes billing", "API")
@endumlList every person or role that interacts with your system. Customers, admins, operators, API consumers — anyone who sends or receives data.
Your system is a single box. Everything you build and deploy is inside it. Do not show internal services — that belongs in the container diagram.
Identify every external system your software talks to: payment gateways, email services, identity providers, third-party APIs, data warehouses.
Connect elements with labeled arrows showing what flows between them. Include the protocol (HTTPS, gRPC, API) when it adds clarity.
Context diagrams are the starting point for every architecture discussion.
Give new hires the 30-second overview of your entire system: who uses it, what it depends on, and where it fits in the bigger picture. Context diagrams answer "what does this company actually build?" faster than any wiki page.
When presenting to executives, investors, or non-technical stakeholders, the context diagram removes implementation noise. It shows the system in terms they understand — users, business functions, and third-party integrations.
Every ADR should start with the current context diagram showing what the system looks like today, followed by the proposed change. Reviewers immediately understand the scope of the decision without reading pages of prose.
Context diagrams identify your trust boundaries and external attack surfaces. Every Person and System_Ext represents an entry point that needs authentication, authorization, and input validation.
When evaluating third-party services, update the context diagram to show the proposed integration. Teams can quickly assess how a new dependency affects system boundaries and data flow.
Auditors need to understand what data flows where. A context diagram shows which external systems handle PII, payment data, or regulated information — the foundation for SOC 2 and GDPR documentation.
| Aspect | Context (L1) | Container (L2) | Component (L3) |
|---|---|---|---|
| Scope | Entire system + surroundings | Inside one system | Inside one container |
| Audience | Everyone | Architects, senior devs | Developers on that service |
| Shows | Users, system, external deps | Apps, DBs, queues, caches | Modules, classes, interfaces |
| Hides | All internal detail | Internal module structure | Implementation code |
| Question it answers | "What does the system do?" | "How is the system built?" | "How is this service structured?" |
| Update frequency | Quarterly | Monthly | Per sprint/feature |
The most common architecture documentation mistake is starting too deep. Teams jump straight to class diagrams or deployment topologies without first establishing what the system does and who it serves. The C4 context diagram forces you to answer the foundational question first: what is this system, who uses it, and what does it depend on?
Context diagrams also expose hidden dependencies. When you map every external system your software interacts with, you often discover integrations that aren't documented anywhere — a legacy SFTP feed, a webhook to a partner system, an OAuth provider nobody remembers configuring. These undocumented dependencies are exactly where outages originate.
For growing teams, the context diagram becomes the shared mental model. When everyone aligns on the system boundary — what's inside vs. outside — architectural conversations become more productive. Debates about where to put new functionality resolve faster because the boundary is explicit, not assumed. And when the boundary needs to change, the context diagram makes the trade-offs visible.
A C4 context diagram is Level 1 of the C4 model. It shows your system as a single box surrounded by the people who use it and the external systems it depends on. It is designed to be understandable by everyone — from business stakeholders to developers.
A well-scoped context diagram typically has 1-3 person types, 1 system (yours), and 3-8 external systems. If you have more than 15 elements, your system boundary may be too wide — consider splitting into multiple systems.
No. The context diagram treats your system as a single box — a black box. Internal services, databases, and microservices belong in the container diagram (Level 2). The context diagram only shows the external view.
System represents the software you are building and own. System_Ext represents an external system that your software depends on but you do not control — payment gateways, email services, third-party APIs, partner systems.
Yes. In Cybewave Studio, describe your system, users, and external dependencies in plain English. The AI generates a properly structured C4 context diagram in Mermaid or PlantUML syntax. You can then refine it with follow-up prompts.
Free to start. 50 AI credits/month. No credit card required.
Get started for free →