The Practical Guide to C4 Context Diagrams

by Guillermo Quiros

A hands-on, example-driven guide to creating effective System Context Diagrams using the C4 Model with real-world case studies across industries.

Introduction: The Most Important Diagram You Are Probably Skipping

Of all the diagrams that software teams produce, the System Context diagram is the most universally useful and the most consistently neglected. Engineering teams jump immediately to Container diagrams, sequence diagrams, or deployment diagrams the diagrams that feel technical, that feel like real architecture work. The Context diagram, with its simple boxes and arrows and its deliberately non-technical language, feels too simple to be worth the time.

This instinct is wrong, and it is expensive.

The Context diagram is not simple because it is shallow. It is simple because it is doing something genuinely hard with great restraint: it is answering the most fundamental question about a software system what is it, who uses it, and what does it depend on in a format that is legible to every stakeholder, at every level of technical sophistication, in under thirty seconds.

Every time a new engineer joins a team and spends two weeks talking to colleagues before they understand what the system actually does, that is a missing Context diagram. Every time a product manager makes a decision based on an incorrect assumption about what the system does or does not integrate with, that is a missing Context diagram. Every time an incident post-mortem reveals that the team did not fully understand the blast radius of a third-party dependency, that is a missing Context diagram.

The Context diagram is the foundation of all other architecture documentation. Without it, every other diagram lacks context literally. With it, every other diagram becomes easier to understand, easier to maintain, and easier to use.

This guide is not a theoretical treatment of Context diagrams. It is a practical, example-driven guide. Each concept is illustrated with real-world examples drawn from recognizable industries and system types. By the end of the guide, you will be able to create a high-quality Context diagram for any system, avoid the most common mistakes, and use Context diagrams effectively as living documentation artifacts.

What a Context Diagram Is and What It Is Not

The Definition

A System Context diagram is a C4 Model Level 1 diagram that shows:

1. The software system being described the primary subject
2. The people who use or interact with the system users and operators
3. The external systems that the system integrates with dependencies and dependents
4. The nature of the relationships between all of these elements

Nothing more. Nothing less.

The deliberate constraint on what a Context diagram shows is not a limitation it is its defining strength. By excluding internal structure, technology choices, and implementation details, the Context diagram achieves something that no other diagram type achieves: it is simultaneously useful to a non-technical stakeholder and useful to a senior architect. Both can read it, learn from it, and contribute to improving it.

The Zoom Metaphor

The C4 Model uses the metaphor of a map with multiple zoom levels. The Context diagram is the highest zoom level equivalent to a view of a country on a map. At this zoom level, you can see the country, its neighbors, and the major connections between them. You cannot see individual streets, buildings, or neighborhoods. That level of detail would be invisible at this scale, and attempting to show it would make the map unreadable.

Just as a country map helps you understand geographic context where a country is, what surrounds it, how it connects to the world a Context diagram helps you understand system context: where a system sits in its environment, who it serves, and what it depends on.

What a Context Diagram Is Not

It is not a network diagram. Network diagrams show infrastructure topology servers, routers, firewalls, load balancers. A Context diagram shows business-level relationships, not physical network connections.

It is not a data flow diagram. Data flow diagrams (DFDs) show how data moves through a system in detail, including internal processes and data stores. A Context diagram shows only the boundary of the system and its external interactions.

It is not a use case diagram. Use case diagrams show the specific functions a system performs for each actor. A Context diagram shows the actors and their high-level relationship to the system, not the detailed use cases.

It is not a system integration map. Integration maps often show all the technical details of system integrations APIs, protocols, data formats, transformation rules. A Context diagram shows that integrations exist and what their business purpose is, without technical implementation details.

Understanding these distinctions helps avoid the most common Context diagram mistakes importing elements or detail levels that belong to other diagram types.

The Four Elements of a Context Diagram

Every Context diagram is composed of exactly four types of elements. Mastering each element knowing what it is, how to label it, and how to draw it is the foundation of drawing effective Context diagrams.

Element 1: The Software System (The Subject)

The software system is the primary subject of the diagram. It is the system being described the system whose architecture you are documenting. Everything else in the diagram exists to provide context for understanding this system.

Visual representation. The subject system is typically shown as a box in the center of the diagram, visually larger or more prominent than the surrounding elements. In the C4 Model's standard notation, software systems are drawn as boxes with a slightly different color or style than external systems, to distinguish the subject from its environment.

Naming. The subject system should be named with its actual name the name by which it is known within the organization and to its users. "E-Commerce Platform," "Payment Processing System," "Customer Data Platform," "Ride-Sharing App." The name should be unambiguous and consistent with how the system is referred to in other documentation.

Description. Every system box should include a brief description one or two sentences that answer the question "what does this system do?" This description is not optional. A system box with only a name tells the reader nothing they might not already know. A system box with a clear description communicates the system's purpose to any reader, regardless of prior knowledge.

Good description: "Manages the full lifecycle of customer orders from placement through payment, fulfillment, and returns."

Poor description: "Order system."

Scope. The subject system's box represents the entire system all of its components, services, and infrastructure. Internal structure is not shown. The box is a black box from the outside.

Element 2: People (Users and Operators)

People represent the human beings who interact with the system. In the C4 Model, people are shown as person-shaped icons (or boxes with a person icon) outside the system boundary.

What counts as a person. Any human being who directly interacts with the system who sends inputs to it or receives outputs from it is a person in the Context diagram. This includes:

• End users of the system's primary interface (web application, mobile app)
• Internal operators who use administrative interfaces
• Developers who use the system's APIs
• Analysts who query the system's data exports
• Auditors who review the system's logs or reports

Roles, not individuals. People are represented at the role level, not the individual level. "Customer" represents all customers, not a specific person. "Back-office Agent" represents all back-office agents. "System Administrator" represents all administrators.

Role names should describe the person's relationship to the system, not their organizational title. "Customer" is better than "External User." "Warehouse Operator" is better than "Level 3 Staff Member." The name should tell the reader who this person is in the context of the system being described.

Description. Each person element should include a brief description of who this person is and how they interact with the system. "A registered customer who places and tracks orders through the web and mobile application." This description adds clarity, especially for readers unfamiliar with the organization or domain.

Primary vs. secondary actors. Not all users have the same relationship to the system. Primary users are those whose goals the system primarily exists to serve they are the reason the system was built. Secondary users are those who interact with the system in support of the primary users or for operational purposes.

In a banking application, the primary user is the bank customer who manages their account. Secondary users include customer service agents who access the system on behalf of customers, and compliance officers who review transaction records. Both appear in the Context diagram, but they serve different roles.

Element 3: External Systems

External systems are software systems that the subject system interacts with, but that are outside the subject system's scope. They are systems that another team, another organization, or an external provider owns and operates.

What counts as an external system. An external system is any software system that:

• The subject system makes API calls to or receives API calls from
• The subject system sends data to or receives data from
• The subject system publishes events to or subscribes to events from
• Is managed and operated by a different team or organization than the subject system

Examples of external systems include: payment processors (Stripe, PayPal), identity providers (Auth0, Okta, Google Sign-In), email delivery services (SendGrid, Mailgun), SMS providers (Twilio), CRM systems (Salesforce), ERP systems (SAP), analytics platforms (Segment, Mixpanel), monitoring platforms (PagerDuty, Datadog), shipping carriers' APIs (FedEx, UPS), mapping services (Google Maps, Mapbox), and other internal systems owned by different teams.

The key test. If a system failure in the external system would require your team to respond (even if only to display an error message to users), it is an external dependency worth showing in the Context diagram.

Naming and description. External systems should be labeled with their actual name ("Stripe," "Salesforce," "SendGrid") if they are well-known third-party systems, or with a descriptive name if they are internal systems ("Inventory Management System," "Customer Data Platform"). Each should include a brief description of the role it plays in the context of the subject system.

Level of detail. External systems are black boxes in the Context diagram. Their internal structure, technology, and implementation are not shown or described. Only the name, a brief description, and the nature of the relationship to the subject system are relevant.

What to exclude. Not every external system that the subject system technically interacts with needs to appear in the Context diagram. Infrastructure services monitoring agents, log shippers, secret managers are typically operational concerns rather than business-level integrations and can be omitted from the Context diagram (they belong in the Deployment diagram). The test is: "Does this external system relationship need to be visible to understand what the system does and how it fits in its environment?" If yes, include it. If no, exclude it.

Element 4: Relationships (Arrows)

Relationships are the arrows that connect people to the system, the system to external systems, and (occasionally) external systems to people. They are the most information-dense element of the Context diagram when labeled correctly and the most wasteful element when left unlabeled.

Every arrow must be labeled. An unlabeled arrow in a Context diagram communicates nothing beyond "these things are connected somehow." A labeled arrow communicates the nature of the connection what flows, in what direction, and for what purpose. The difference in understanding between a labeled and unlabeled arrow is enormous.

Arrow label anatomy. An effective arrow label answers three questions:

• What flows? Orders, payment requests, customer data, authentication tokens, shipping status updates
• In what direction? The arrow's direction shows the primary direction of initiation; the label can clarify bidirectional flows
• For what purpose? Places orders, requests payment authorization, receives shipping updates

"Sends payment authorization requests and receives authorization results" is an excellent arrow label. "Uses" is not.

Directionality. Arrows should point in the direction of the primary flow of interaction, not necessarily in the direction of data flow. If Service A calls Service B's API to request data, the arrow points from A to B (because A initiates the interaction), even though the data flows from B to A (in the response).

For relationships where the initiating party changes depending on the operation, use bidirectional arrows with a label that describes both directions.

Building a Context Diagram: Step by Step

Creating a Context diagram is a disciplined process. Following these steps consistently produces diagrams that are accurate, complete, and useful.

Step 1: Name and Describe the Subject System

Before drawing anything, write down the name and a two-sentence description of the system being described. This description is not optional it is the foundation of the entire diagram.

Ask yourself: "If I had to explain this system to a new colleague in two sentences, what would I say?" The answer to that question is the system description. Write it down before drawing anything else.

If you cannot write a clear two-sentence description of the system, that is important information it means the system's scope or purpose is not yet clear enough to be documented. That clarity problem needs to be resolved before the diagram can be drawn.

Step 2: Identify the People

List all the human beings who interact directly with the system. For each person, record:

• Their role name (the name that describes their relationship to the system)
• A one-sentence description of who they are and how they interact
• Whether they are a primary actor (the system exists primarily to serve them) or a secondary actor (they interact with the system in support of the primary actors or for operational purposes)

At this stage, cast a wide net. Include everyone you can think of. You can prune the list later. Missing a significant actor is a worse mistake than including one that turns out to be minor.

Step 3: Identify the External Systems

List all the software systems that the subject system interacts with. For each external system, record:

• Its name
• A one-sentence description of what it does and why the subject system interacts with it
• The direction of the primary interaction (the subject system calls it, it calls the subject system, or both)
• The nature of the interaction (what data or requests flow between them)

Again, cast a wide net initially. Consider: payment systems, identity systems, email and SMS systems, analytics systems, other internal systems, third-party data providers, ERP and CRM systems, monitoring and alerting systems.

Then apply the pruning test: "Does this relationship need to be visible in the Context diagram for a reader to understand what the system does and how it fits in its environment?" Remove any systems that fail this test.

Step 4: Draft the Relationships

For each connection between the subject system and a person or external system, write the relationship label before placing the arrow on the diagram. A relationship label should describe the interaction in plain language.

The discipline of writing labels before drawing arrows prevents the common mistake of drawing unlabeled arrows with the intention of labeling them later an intention that rarely materializes.

Step 5: Draw the Diagram

With the elements and relationships documented, draw the diagram. Apply these layout principles:

Center the subject system. The subject system is the primary focus of the diagram. Place it in the center.

People on the left and top. By convention, people (users) are typically placed to the left or above the subject system.

External systems on the right and bottom. External systems (dependencies) are typically placed to the right or below the subject system.

Avoid crossing arrows. Crossing arrows create visual confusion. Adjust the placement of elements to minimize crossings.

Group related elements. If multiple external systems serve a similar purpose (multiple analytics providers, multiple payment processors), consider grouping them visually to reduce clutter.

Step 6: Review and Validate

A Context diagram that has not been reviewed by its intended audience has not been validated. After drawing the diagram, review it with:

Non-technical stakeholders (product managers, business analysts). Ask them to explain the diagram back to you. If they struggle or misunderstand any element, the diagram needs improvement.

Team members who know the system well. Ask them: "Is anything missing? Is anything wrong? Is there anything here that would surprise you?" Engineers who work with the system daily will catch missing external systems and incorrect relationship descriptions.

New team members or people unfamiliar with the system. Ask them: "After reading this diagram, what questions do you still have?" Their questions reveal gaps in the diagram.

Real-World Example 1: E-Commerce Platform

System Description

The system is an e-commerce platform for a mid-sized online retailer. It allows customers to browse products, place orders, make payments, and track their shipments. It is used by customers directly and by internal teams for order management and customer support.

People

Customer A registered or guest user who browses the product catalog, places orders, makes payments, and tracks shipment status through the web and mobile application.

Customer Service Agent An internal team member who accesses the platform's administrative interface to view order details, process refunds, update order status, and assist customers with issues.

Warehouse Operator An internal team member who receives pick-and-pack instructions through the platform's warehouse interface and updates fulfillment status.

Finance Manager An internal team member who accesses financial reports, reconciliation dashboards, and payout summaries.

External Systems

Stripe Payment processor. The platform submits payment authorization requests and captures payments for customer orders. Stripe sends webhook notifications for payment events (authorization, capture, refund, dispute).

Auth0 Identity provider. The platform delegates authentication to Auth0 for customer registration, login, and session management, including social login (Google, Facebook).

SendGrid Email delivery service. The platform sends transactional emails (order confirmation, shipping notification, password reset) through SendGrid.

Twilio SMS delivery service. The platform sends order status SMS notifications to customers who opt in.

FedEx API Shipping carrier integration. The platform submits shipment creation requests to FedEx and receives tracking updates for active shipments.

Google Analytics Web analytics platform. The platform sends anonymized user behavior events (page views, add-to-cart, purchase completions) to Google Analytics for marketing analysis.

Inventory Management System (internal, owned by the warehouse team) The platform queries real-time inventory availability and sends inventory reservation requests when orders are placed.

ERP System (SAP, owned by the finance team) The platform sends completed order financial data to the ERP system for accounting, revenue recognition, and financial reporting.

What the Diagram Reveals

Even before the diagram is drawn, this element list reveals something important: the e-commerce platform has eight external dependencies. This is significant information for:

• Risk assessment. Eight external systems means eight potential failure points. Which ones are critical path (the order cannot be completed without them) and which are non-critical (the order can complete but some functionality is degraded)?
• Team communication. Four of these external systems are third-party services; two are internal systems owned by different teams. The relationships with the internal teams (Inventory, ERP) require ongoing coordination that the relationship with third-party services does not.
• Onboarding. A new engineer joining the e-commerce team can immediately understand the system's environment from this diagram, without reading documentation or talking to multiple colleagues.

Context Diagram Description

Real-World Example 2: Banking Mobile Application

System Description

The system is a mobile banking application for a retail bank. It allows bank customers to view account balances, transfer funds between accounts, pay bills, and manage their cards. It integrates with the bank's core banking platform and several regulated third-party services.

People

Bank Customer A retail banking customer who uses the iOS and Android applications to view balances, initiate transfers, pay bills, and manage their debit and credit cards.

Customer Support Representative A bank employee who accesses a support view of customer accounts to assist with inquiries, flag suspicious activity, and initiate certain account operations on behalf of customers.

Compliance Officer A bank employee who reviews transaction records, generates regulatory reports, and monitors for suspicious activity patterns.

External Systems

Core Banking System (internal, owned by the bank's IT infrastructure team) The authoritative source of account balances, transaction history, and account ownership data. The mobile application reads account data from and submits transaction instructions to the core banking system.

Payment Network (SWIFT/SEPA) The interbank payment network used to process external fund transfers. The mobile application's transfer instructions are routed through the core banking system to the payment network, but the payment network appears as an external dependency because its processing status is visible to the mobile application.

Identity Verification Service (Onfido) A third-party KYC (Know Your Customer) service used during new account onboarding to verify customer identity through document scanning and biometric comparison.

Push Notification Service (APNs / FCM) Apple Push Notification service and Firebase Cloud Messaging, used to deliver transaction alerts, security notifications, and promotional messages to customers' devices.

Open Banking API (PSD2) The bank's regulated Open Banking API, which allows authorized third-party financial applications to access customer account data and initiate payments with customer consent.

Fraud Detection System (internal, owned by the risk team) Real-time fraud scoring service. The mobile application submits transaction requests to the fraud detection system for scoring before submitting them to the core banking system.

Card Management System (internal, owned by the cards team) Manages debit and credit card operations temporary blocks, PIN changes, card replacement requests, spending limit adjustments.

What the Diagram Reveals

This diagram is particularly instructive for a regulated financial services context:

Regulated dependencies. The Open Banking API and Payment Network integrations exist because of regulatory requirements (PSD2 in Europe, equivalent regulations elsewhere). A new engineer or a product manager can immediately see that the system has regulatory integrations and understand that changes to those integrations require compliance review.

Trust boundary visibility. The diagram makes visible the trust boundaries in the system. The core banking system, fraud detection system, and card management system are all internal they are within the bank's trust perimeter. Onfido, APNs/FCM, and the payment network are external they cross the trust perimeter. This has security implications that are immediately visible from the diagram.

Operational dependency chain. The diagram reveals that processing a simple fund transfer involves at least four systems: the mobile application, the fraud detection system, the core banking system, and the payment network. An incident in any of these systems affects transfer processing. This dependency chain is essential knowledge for the incident response team.

Labeling Precision in Financial Systems

Financial systems require particular precision in relationship labels because the relationships often carry regulatory significance. Compare:

Imprecise label: "Sends transaction data"

Precise label: "Submits transfer instructions with customer authorization tokens; receives real-time transaction status and confirmation numbers"

The precise label communicates that the interaction is initiated by the mobile application (not the core banking system), that it includes authorization tokens (a security-relevant detail), and that the response includes a confirmation number (a compliance-relevant detail). This level of precision is appropriate for financial system Context diagrams and is worth the additional label length.

Real-World Example 3: SaaS Project Management Tool

System Description

The system is a cloud-based project management SaaS application (similar to Asana, Jira, or Linear). It allows teams to create and track tasks, manage projects, collaborate on work, and report on progress. It is used by software development teams, marketing teams, and operations teams at client organizations.

People

Team Member An end user at a client organization who creates tasks, updates task status, comments on work, and views project progress through the web application and mobile app.

Project Manager A user with elevated permissions who creates projects, assigns work, manages team members' access, and generates progress reports.

Organization Administrator A client organization's designated administrator who manages subscription settings, user provisioning, SSO configuration, and billing information.

SaaS Platform Administrator (internal) An internal team member at the SaaS company who manages tenant configuration, monitors system health, handles escalated support cases, and manages feature flags.

External Systems

Stripe Subscription billing. The platform manages subscription creation, plan changes, payment collection, and invoice generation through Stripe. Stripe sends webhook events for billing lifecycle events (payment success, payment failure, subscription cancellation).

Auth0 Identity and access management. Handles authentication for all users, including support for client organizations' SSO configurations (SAML, OIDC) so enterprise customers can integrate with their own identity providers (Okta, Azure AD, Google Workspace).

GitHub (integration) Development workflow integration. Team Members can link tasks to GitHub pull requests and commits. The platform receives webhook events from GitHub when PR status changes, automatically updating linked task status.

Slack (integration) Collaboration integration. The platform sends task update notifications and @mention alerts to Slack channels configured by client teams. Users can create tasks directly from Slack messages.

SendGrid Transactional email. The platform sends email notifications (task assignments, @mentions, deadline reminders, weekly digests) through SendGrid.

Amazon S3 File storage. The platform stores file attachments, exported reports, and project data backups in S3.

Datadog Monitoring and alerting. The platform sends application metrics, logs, and traces to Datadog for performance monitoring and incident alerting.

Intercom Customer support and in-app messaging. The platform integrates with Intercom to provide in-app help, support chat, and onboarding guidance to users.

Segment Customer data platform. The platform sends user behavior events (feature usage, page views, onboarding milestones) to Segment for product analytics and marketing automation.

What the Diagram Reveals

Integration as a product feature. For a SaaS product, integrations (GitHub, Slack) are product features they are part of the value proposition, not just infrastructure. The Context diagram makes this explicit by showing these integrations at the same level as the core system interactions.

The multi-tenant complexity. The Organization Administrator person element signals that this is a multi-tenant system where individual client organizations have their own configuration and governance. This is an important architectural signal multi-tenancy is a significant design concern that the Context diagram makes visible without requiring technical detail.

The distinction between customer-facing and operational external systems. The diagram includes both customer-facing integrations (GitHub, Slack, Stripe, Auth0) and operational integrations (Datadog, Intercom, Segment). For product and engineering planning conversations, the distinction between these two categories is important. Some teams prefer to separate them showing customer-facing integrations in the primary Context diagram and operational integrations in a separate operational Context diagram.

Real-World Example 4: Healthcare Patient Portal

System Description

The system is a patient-facing healthcare portal for a hospital network. It allows patients to view their medical records, schedule appointments, communicate with their care team, request prescription refills, and access test results.

People

Patient A registered patient of the hospital network who accesses their health records, schedules appointments, and communicates with their care team through the web and mobile portal.

Clinician (Doctor / Nurse Practitioner) A healthcare provider who accesses a clinical view of patient messages, reviews prescription refill requests, and updates appointment notes through the portal's clinical interface.

Patient Coordinator A hospital administrative staff member who manages appointment scheduling, handles patient registration, and coordinates referrals.

IT Administrator An internal hospital IT team member who manages user provisioning, system configuration, and integration settings.

External Systems

Electronic Health Record System (Epic EHR) The hospital network's primary clinical data system. The patient portal reads patient records, lab results, appointment data, and care team information from Epic. Write-back operations (appointment bookings, prescription refill requests, message responses) are submitted to Epic for processing.

Appointment Scheduling System The hospital's appointment scheduling infrastructure (integrated with Epic). The portal queries real-time appointment availability and submits booking requests.

Pharmacy Management System The hospital's pharmacy system. The portal submits prescription refill requests and receives fulfillment status updates.

HL7 FHIR API The standardized healthcare data API that the portal uses to exchange patient data with authorized third-party health applications (Apple Health, Google Health, third-party care management apps) with patient consent.

Identity Provider (Azure Active Directory) The hospital network's enterprise identity system. Clinicians and staff authenticate through the hospital's Azure AD; patients use a separate authentication flow managed by the portal.

SendGrid Email delivery. The portal sends appointment reminders, test result availability notifications, and secure message alerts.

Twilio SMS delivery. The portal sends appointment reminders and prescription pickup notifications via SMS.

Secure Messaging Gateway A HIPAA-compliant messaging service that handles the delivery of secure messages between patients and their care team, ensuring message content is encrypted and access-controlled in compliance with HIPAA.

MyChart (Epic) Epic's patient-facing interface. The portal integrates with MyChart for certain clinical workflows where Epic's native patient interface is the system of record.

What the Diagram Reveals

Regulatory context made visible. The healthcare domain is heavily regulated (HIPAA in the US). The Context diagram surfaces the regulatory implications through its elements: the Secure Messaging Gateway (labeled as HIPAA-compliant) signals that message security is not just a technical preference but a compliance requirement. The HL7 FHIR API signals that interoperability with external health applications is a regulatory requirement (the 21st Century Cures Act in the US mandates FHIR-based patient data access). A reader who understands the healthcare regulatory environment immediately understands the compliance context from the diagram.

Integration complexity in healthcare. Epic EHR is both the primary data source and the system of record for clinical operations. The portal is, in many ways, a presentation layer over Epic rather than an independent system. The Context diagram makes this dependency relationship explicit the portal cannot function without Epic, and changes to Epic's integration APIs have significant implications for the portal team.

The dual identity provider pattern. Clinicians and patients authenticate through different identity systems (Azure AD for clinicians, the portal's own authentication for patients). This pattern appears in the Context diagram through the presence of Azure Active Directory as an external system, combined with the implication that patient authentication is handled internally. This is an important security architecture signal.

Real-World Example 5: Ride-Sharing Platform

System Description

The system is a ride-sharing platform (similar to Uber or Lyft). It connects passengers who need rides with drivers who provide them, handles real-time matching, routing, and payment processing, and manages the operational aspects of the platform including driver onboarding and support.

People

Passenger A registered user who requests rides, tracks driver location in real time, makes payments, and rates their experience through the iOS and Android mobile application.

Driver An independent contractor who accepts ride requests, navigates to pickup and drop-off locations, and manages their earnings and account through the driver mobile application.

Operations Manager An internal team member who monitors platform health, manages surge pricing zones, handles escalated support cases, and configures platform settings.

Support Agent An internal team member who handles passenger and driver support requests, resolves payment disputes, and manages account issues.

External Systems

Stripe Connect Payment processing with driver payout management. The platform processes passenger payments and manages driver payouts through Stripe Connect, which supports marketplace-style payment flows where funds are collected from passengers and distributed to drivers.

Google Maps Platform Mapping, routing, and geocoding. The platform uses Google Maps for real-time map display, route calculation, ETA estimation, and address geocoding.

Twilio SMS and voice communication. The platform sends ride confirmation SMS, allows passengers and drivers to communicate through anonymized phone numbers, and handles driver verification calls.

Firebase (Google) Real-time data synchronization. The platform uses Firebase's real-time database for live driver location updates, ride status changes, and push notifications to both passenger and driver applications.

Background Check Provider (Checkr) Driver background screening. During driver onboarding, the platform submits background check requests to Checkr and receives screening results that determine driver eligibility.

Vehicle Insurance Verification (Snapsheet) Insurance document verification. The platform submits driver insurance document images for automated verification during onboarding and at renewal.

Auth0 Identity and access management. The platform handles authentication for passengers, drivers, and internal users, with support for social login for passengers.

SendGrid Email delivery for account management and marketing communications.

Segment Customer data platform for product analytics and marketing automation.

Driver Background Check Regulatory API Jurisdiction-specific APIs for regulatory compliance (e.g., TLC API for New York City taxi commission compliance, state DMV APIs for license verification in regulated markets).

What the Diagram Reveals

Two distinct user populations. The passenger and driver are both users of the platform but have entirely different experiences, workflows, and requirements. The Context diagram makes this explicit there are two primary actors with different interfaces (passenger app vs. driver app). This has significant implications for product, design, and engineering organization.

The marketplace payment complexity. Stripe Connect rather than standard Stripe signals that the payment model is a marketplace model (funds flow from passengers through the platform to drivers), not a simple merchant model. This is an important business model signal that is visible in the Context diagram through the technology label.

Regulatory integration depth. The Driver Background Check Regulatory API signals that the platform operates in a regulated environment with jurisdiction-specific compliance requirements. This is significant for product planning regulatory integrations are often market-specific and add significant complexity to international expansion.

Real-time data architecture signal. The presence of Firebase as an external system signals that the platform has real-time data requirements (live driver location, live ride status). This is not a typical integration it is a fundamental architectural choice. The Context diagram surfaces this choice without requiring technical implementation detail.

Common Mistakes and How to Avoid Them

Mistake 1: Including Internal Components as External Systems

The most common mistake in Context diagrams is showing internal components services, databases, queues that are part of the subject system as if they were external systems.

Example of the mistake: An e-commerce platform's Context diagram shows "Order Service," "Payment Service," and "Product Catalog Service" as separate boxes connected to the main system box. These are internal services, not external systems.

Why it happens: Engineers naturally think about the internal architecture of their system. Drawing the Context diagram after having already thought deeply about the Container diagram causes internal components to "leak" into the Context diagram.

How to avoid it: The test for whether something is an external system: "Does a different team own and operate this?" If no, it is internal and does not belong in the Context diagram. The subject system box should be a complete black box everything inside it is invisible at this level.

Mistake 2: Unlabeled or Vaguely Labeled Arrows

Arrows without labels or with vague labels ("uses," "connects to," "sends data") are the second most common mistake. They are visually present but informationally empty.

Example of the mistake: An arrow from the subject system to Stripe labeled "uses."

Why it happens: Labeling arrows requires thinking carefully about each relationship what exactly flows, in what direction, and for what purpose. This thinking takes time, and when teams are under time pressure, labels get deferred and never added.

How to avoid it: Adopt a rule: no arrow leaves the diagram without a label. The label does not need to be long even "Submits payment authorization requests; receives authorization results" is sufficient. Write the labels as you draw the arrows, not after.

Mistake 3: Missing Significant External Systems

Context diagrams that show only a subset of a system's external dependencies create a false picture of the system's environment. A reader who relies on an incomplete Context diagram will make decisions based on incorrect assumptions about the system's dependencies.

Example of the mistake: An e-commerce platform's Context diagram shows Stripe but omits the Inventory Management System and the ERP System, because those integrations are less visible to the front-end team who drew the diagram.

Why it happens: Teams draw Context diagrams based on their own knowledge of the system, which is necessarily partial. Front-end engineers know about the APIs the application calls from the browser but may not know about back-end integrations. Infrastructure engineers know about operational integrations that product engineers may not.

How to avoid it: Create the Context diagram collaboratively. When identifying external systems, involve engineers with different areas of responsibility front-end, back-end, infrastructure, data. Ask explicitly: "Are there any integrations I might not know about?"

Mistake 4: Describing the System by Its Technology Rather Than Its Purpose

System and component descriptions that focus on technology ("A Node.js REST API that uses PostgreSQL") communicate nothing about what the system does or why it exists.

Example of the mistake: Subject system description: "A microservices-based platform built with React, Node.js, and PostgreSQL, deployed on AWS."

Why it happens: Engineers naturally describe systems in terms of the technology they know and are responsible for.

How to avoid it: The Context diagram is a business-level document. Descriptions should answer "what does this do for its users?" not "what is it built with?" Technology details belong in Container diagrams and Deployment diagrams, not Context diagrams.

Mistake 5: Drawing for Engineers Rather Than for the Primary Audience

A Context diagram that uses technical jargon, assumes deep domain knowledge, or requires specialist expertise to interpret has missed its primary purpose to communicate clearly to all stakeholders, including non-technical ones.

Example of the mistake: An arrow labeled "Publishes OrderCreated Kafka events to the downstream fulfillment consumer group."

Why it happens: The person drawing the diagram is an engineer who thinks in technical terms.

How to avoid it: Before labeling an arrow, ask: "Could my product manager or my CEO understand this label?" If not, rewrite it. "Notifies the fulfillment system when an order is placed" communicates the same business intent without technical implementation detail. The Container diagram is the right place for Kafka and consumer groups.

Mistake 6: The Oversized Context Diagram

A Context diagram with more than eight to ten elements becomes visually complex and cognitively demanding. When diagrams have fifteen external systems, twelve user roles, and twenty arrows, they communicate less clearly than a diagram with five external systems, three user roles, and eight arrows.

Why it happens: Once teams start identifying external systems, every system has many. The instinct is to include them all for completeness.

How to avoid it: Apply the significance test: "Is this relationship important enough that a reader of this diagram needs to know about it to understand the system's context?" Operational monitoring systems, secret managers, log shippers, and similar infrastructure systems often fail this test. They belong in the Deployment diagram, not the Context diagram.

For systems with genuinely many significant external integrations, consider creating multiple focused Context diagrams one showing the customer-facing integrations, one showing the internal system integrations, one showing the operational integrations.

Context Diagrams as Living Documentation

A Context diagram that was accurate six months ago but does not reflect the system's current integrations is worse than no diagram it misleads its readers and destroys trust in architecture documentation. Keeping Context diagrams current requires both process and tooling.

Triggering Context Diagram Updates

The following events should trigger a review and potential update of the Context diagram:

Adding a new external integration. When the system begins to communicate with a new external system a new payment provider, a new analytics platform, a new internal service the Context diagram must be updated to reflect the new relationship.

Removing or replacing an external integration. When an integration is discontinued (migrating from Mailchimp to SendGrid, replacing an internal legacy system with a new platform), the old external system must be removed and the new one added.

Adding a new user role. When a new category of user begins interacting with the system a new internal team gets access to an administrative interface, a new partner organization gets API access the Context diagram should reflect the new actor.

Significant changes to an existing relationship. If the nature of an existing integration changes significantly a previously read-only integration becomes bidirectional, a real-time integration replaces a batch integration the relationship label should be updated.

Onboarding new team members. Each time a new engineer joins the team and uses the Context diagram as an onboarding resource, they should be asked: "Does this diagram accurately reflect the system as you understand it?" New team members who have recently asked questions and gotten answers often have insights about gaps or inaccuracies that existing team members have overlooked.

Tooling for Context Diagram Maintenance

Structurizr The tool created by Simon Brown (the author of the C4 Model). Structurizr allows Context diagrams (and all other C4 diagrams) to be defined as code in a workspace definition file. The diagram is generated from the code, meaning it is version-controllable, reviewable in pull requests, and maintainable alongside the system's code.

In Structurizr's DSL (Domain Specific Language), a Context diagram for the e-commerce example would be defined as:

workspace {
    model {
        customer = person "Customer" "A registered user who places and tracks orders."
        agent = person "Customer Service Agent" "Handles order issues and refunds."

        ecommerce = softwareSystem "E-Commerce Platform" "Manages product catalog, orders, payments, and fulfillment."

        stripe = softwareSystem "Stripe" "Payment processing and refund management."
        auth0 = softwareSystem "Auth0" "Customer identity and authentication."
        sendgrid = softwareSystem "SendGrid" "Transactional email delivery."
        inventory = softwareSystem "Inventory Management System" "Real-time stock availability and reservation."

        customer -> ecommerce "Places orders and tracks shipments via web and mobile app"
        agent -> ecommerce "Manages orders and processes refunds via admin interface"
        ecommerce -> stripe "Submits payment requests; receives payment events"
        ecommerce -> auth0 "Delegates authentication; manages user sessions"
        ecommerce -> sendgrid "Sends transactional emails"
        ecommerce -> inventory "Queries stock availability; reserves inventory"
    }

    views {
        systemContext ecommerce "SystemContext" {
            include *
            autoLayout
        }
    }
}

This definition can be committed to the same repository as the application code, reviewed in pull requests, and automatically rendered into a diagram by Structurizr's rendering engine.

draw.io / diagrams.net A free, widely used diagramming tool that supports C4 diagram shapes and can export diagrams in an XML format that is version-controllable. Less powerful than Structurizr for maintaining consistency across diagram levels, but accessible and widely understood.

Mermaid A text-based diagramming tool that supports basic C4 Context diagrams through its C4Context diagram type. Mermaid diagrams are plain text and can be embedded directly in Markdown documentation, rendered automatically by GitHub, GitLab, and most documentation platforms.

Context Diagrams for Different Audiences

The same system can have multiple Context diagrams each optimized for a different audience. This is not duplication; it is recognition that different audiences need different information from the same system context.

The Technical Context Diagram

Aimed at engineers and architects. Includes all significant external systems, precise relationship labels that name communication protocols where relevant, and distinction between synchronous and asynchronous relationships. May include technology annotations on external systems.

The Executive Context Diagram

Aimed at senior leadership and non-technical stakeholders. Focuses on business relationships rather than technical integrations. Groups minor external systems into categories (e.g., "Marketing Tools" rather than Segment, Mixpanel, and Amplitude individually). Uses business language throughout no technical terms, no protocol names, no API references.

The Security Context Diagram

Aimed at security and compliance teams. Annotates all external system relationships with trust levels and data sensitivity. Marks which relationships cross network trust boundaries. Identifies which external systems handle sensitive data categories (PII, financial data, health data). Groups external systems by trust zone.

The Incident Response Context Diagram

Aimed at on-call engineers and SREs. Focuses on critical path dependencies the external systems whose failure would cause the subject system to fail or degrade. Annotates each relationship with the impact of that dependency's failure. Includes on-call contacts for each external system. Serves as a quick reference during incidents.

Frequently Asked Questions

How long should a Context diagram take to create?

For a well-understood system, the element identification and relationship documentation process takes one to two hours. Drawing the diagram takes an additional 30 to 60 minutes. Review and validation with stakeholders takes another hour.

Total: three to four hours for a first version of the diagram. Subsequent updates, once the initial diagram exists, typically take 15 to 30 minutes.

Should the Context diagram show the database?

No. A database is an internal component of the subject system it is behind the system boundary. It belongs in the Container diagram, not the Context diagram. The only databases that belong in a Context diagram are databases owned and operated by external systems (e.g., a cloud database service that is managed by a different team).

What if two teams own different parts of the same logical system?

This is a service boundary question. If two teams own different parts of what is presented as a single system in the Context diagram, that may signal that the system boundary is incorrectly drawn or that the system is on a path toward decomposition into multiple systems.

Draw the Context diagram to reflect the current reality. If Team A and Team B both own what users experience as "the platform," draw it as one system. Note the multi-team ownership in the system description. This is valuable information for architectural planning.

How do you handle external systems that are also internal systems from another team's perspective?

An external system in your Context diagram may be the subject system in another team's Context diagram. This is expected and correct. From your system's perspective, it is external it is owned and operated by a different team. From the other team's perspective, it is their system.

The key is consistency: your description of their system in your Context diagram should match how they describe their own system in their Context diagram. This is another argument for diagram-as-code tooling and shared architecture repositories where a system's description is defined once and referenced by all diagrams that include it.

Conclusion

The System Context diagram is the most underrated artifact in software architecture documentation. It is the diagram that every stakeholder technical and non-technical, new and experienced can read and learn from. It is the foundation on which all other architecture documentation rests. And it is the diagram that, when maintained as a living artifact, provides the most durable value over the life of a system.

The examples in this guide e-commerce, banking, SaaS, healthcare, and ride-sharing illustrate the breadth of contexts in which Context diagrams are valuable and the range of insights they surface. In each case, the process of creating the diagram was itself valuable: it forced clarity about system boundaries, surfaced hidden dependencies, and revealed integration complexity that was previously implicit.

The practical lessons from these examples:

Draw the diagram before you think you need it. The moment a system has more than three external integrations and more than one type of user, a Context diagram adds value. Do not wait until the system is "complex enough" it is already complex enough.

Label every arrow. The relationship labels are where most of the diagram's informational value lives. An unlabeled diagram is a missed opportunity.

Validate with your intended audience. A diagram that has not been read and reviewed by the people it is meant to serve has not done its job. Show it to a product manager, a new engineer, and a senior stakeholder. Their responses will tell you what needs to be improved.

Maintain it as the system evolves. A Context diagram that is three months out of date is worse than none. Every new integration, every removed dependency, every new user role should trigger an update. The cost of maintenance is low; the cost of an inaccurate diagram is high.

The System Context diagram is not a formality. It is the shared understanding of what your system is captured, validated, and maintained as a living document. For any system that matters, that shared understanding is worth every minute it takes to create and maintain.