kinhluan C4 Level 1: System Context & User Journeys
Level 1 focuses on the Big Picture. It bridges the gap between Business Value and Technology by mapping User Journeys to System Scope.
"A System Context diagram can be a useful starting point for diagramming and documenting a software system, allowing you to step back and see the big picture." — Simon Brown
🎯 Stakeholder Focus
| Stakeholder | What they need from L1 | Questions they ask |
|---|---|---|
| Executives | Value delivery, cost, risk | "What does this system do? Who uses it?" |
| Product Managers | Feature scope, external dependencies | "What third-party systems do we depend on?" |
| Developers | High-level context, data flow | "Where does user data come from? Where does it go?" |
| Security Auditors | Trust boundaries, data exposure | "What sensitive data leaves our system?" |
🚶 User Journey Integration
Instead of a static diagram, frame Level 1 around a Primary User Journey:
The Journey Mapping Method
Step 1: Identify the Primary Actor
↓
Step 2: Define their Goal (the "Job-to-be-Done")
↓
Step 3: Trace the Happy Path across systems
↓
Step 4: Label interactions with Action Verbs
↓
Step 5: Identify external systems touched
Example: E-Commerce "Buy Product" Journey
[Customer] ──"Searches for"──▶ [Product Catalog System]
│
├──"Adds to cart"──▶ [Shopping Cart System]
│
├──"Checks out via"──▶ [Order System]
│ │
│ ├──"Requests payment from"──▶ [Payment Gateway]
│ │
│ └──"Notifies"──▶ [Notification Service]
│ │
│ └──"Sends email via"──▶ [Email Provider]
│
└──"Tracks order via"──▶ [Logistics System]
Action Verb Rule: Every arrow must answer "What does the actor DO?" not "What is the connection?"
| ❌ Bad | ✅ Good |
|---|---|
| "Uses" | "Browses products via" |
| "Connects to" | "Submits payment to" |
| "Sends data" | "Publishes order event to" |
🏗️ L1 Diagram Structure
┌─────────────────────────────────────────────────────────────┐
│ SYSTEM CONTEXT │
│ │
│ [Person: Actor] │
│ │ │
│ │ "Action verb describing interaction" │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ [Software System: YOUR SYSTEM] │ │
│ │ "One-sentence description of │ │
│ │ what value it provides" │ │
│ └─────────────────────────────────────┘ │
│ │ │
│ │ "Action verb" │
│ ▼ │
│ [System_Ext: External System] │
│ "What it does for your system" │
│ │
└─────────────────────────────────────────────────────────────┘
📝 Mermaid Templates
Template A: Simple B2C System
C4Context
title System Context Diagram for E-Commerce Platform
Person(customer, "Customer", "Registered user who browses and purchases products.")
System(ecommerce, "E-Commerce Platform", "Allows customers to browse products, manage carts, and place orders.")
System_Ext(payment, "Payment Gateway", "Processes credit card and digital wallet payments.")
System_Ext(email, "Email Service", "Sends transactional emails (order confirmations, shipping updates).")
System_Ext(analytics, "Analytics Platform", "Tracks user behavior and generates reports.")
Rel(customer, ecommerce, "Browses products, places orders", "HTTPS/Web")
Rel(ecommerce, payment, "Processes payments", "REST API/HTTPS")
Rel(ecommerce, email, "Sends notifications", "REST API/HTTPS")
Rel(ecommerce, analytics, "Reports events", "HTTPS/JSON")
Template B: B2B Platform with Multiple Actors
C4Context
title System Context Diagram for SaaS HR Platform
Person(hr_manager, "HR Manager", "Manages employee onboarding and offboarding.")
Person(employee, "Employee", "Views payslips, requests time off.")
Person(payroll_admin, "Payroll Admin", "Processes monthly payroll.")
System(hr_platform, "HR Platform", "Manages employee data, payroll, and time tracking.")
System_Ext(bank, "Bank API", "Executes salary transfers.")
System_Ext(tax_authority, "Tax Authority", "Reports payroll taxes.")
System_Ext(identity_provider, "Identity Provider", "Handles SSO authentication.")
Rel(hr_manager, hr_platform, "Manages employees", "HTTPS/Web")
Rel(employee, hr_platform, "Views personal data", "HTTPS/Web")
Rel(payroll_admin, hr_platform, "Runs payroll", "HTTPS/Web")
Rel(hr_platform, bank, "Transfers salaries", "REST API/HTTPS")
Rel(hr_platform, tax_authority, "Reports taxes", "REST API/HTTPS")
Rel(hr_platform, identity_provider, "Authenticates users", "SAML/OAuth")
Template C: Internal System (No External Users)
C4Context
title System Context Diagram for Data Pipeline
Person(data_engineer, "Data Engineer", "Monitors and maintains the pipeline.")
System(pipeline, "ETL Pipeline", "Extracts data from sources, transforms, and loads to warehouse.")
System_Ext(crm, "CRM System", "Source of customer data.")
System_Ext(warehouse, "Data Warehouse", "Destination for processed data.")
System_Ext(monitoring, "Monitoring System", "Alerts on pipeline failures.")
Rel(data_engineer, pipeline, "Monitors and configures", "Internal Tool")
Rel(crm, pipeline, "Pushes data to", "Webhooks/HTTPS")
Rel(pipeline, warehouse, "Loads transformed data to", "SQL/TCP")
Rel(pipeline, monitoring, "Reports health metrics to", "Metrics API")
🎤 Stakeholder Interview Questions
Before drawing L1, ask these questions:
For Business Stakeholders
- "Who are the primary users of this system?" (Persons)
- "What is the one thing they come here to do?" (Primary journey)
- "What other systems does ours need to talk to?" (External systems)
- "What data enters our system? What data leaves?" (Data flow)
- "What would happen if [external system] went down?" (Criticality)
For Technical Stakeholders
- "What authentication/identity system do users come from?" (Identity provider)
- "Where do we send notifications/emails?" (Communication)
- "What third-party APIs do we call?" (External dependencies)
- "Is there a data warehouse or analytics platform?" (Data consumers)
- "Are there regulatory/reporting requirements?" (Compliance systems)
🚫 Anti-Patterns to Guard (Level 1)
| Anti-Pattern | Symptom | Fix |
|---|---|---|
| Tech Leakage | "React", "PostgreSQL", "Kafka" appear in diagram | Remove all technology names. Use "Product Catalog" not "PostgreSQL" |
| Container Confusion | "Web App", "API", "Database" boxes appear | Those are L2. L1 only has the system boundary |
| Diagram Bloat | >15 elements | Split into multiple views: "Customer Journey", "Admin Journey" |
| Passive Arrows | Labels like "uses", "connects to" | Use active verbs: "places order via", "receives invoice from" |
| Missing Descriptions | Boxes with only names | Every element needs a one-sentence description |
| Orphan Systems | External systems with no relationship | Either connect them or remove them |
✅ Level 1 Success Criteria
- Is it clear who the primary user is?
- Does it answer "What value does this system provide?"
- Are all external systems (third-party) identified?
- Are relationships labeled with action verbs?
- Does a non-technical person understand the whole diagram in 30 seconds?
- STRICT: Is it free from all technical/implementation details?
- STRICT: Does it have ≤15 elements?
🔄 From L1 to L2
When you're ready to zoom in, use these signals:
| L1 Signal | L2 Action |
|---|---|
| "Our system does X, Y, and Z" | Split into 3 containers (one per capability) |
| "We have a web app and mobile app" | Two containers: Web App + Mobile App |
| "Data is stored in..." | Database container |
| "Background jobs process..." | Worker/Job processor container |
| "We use [external service] for..." | Keep as System_Ext in L2, add protocol |
Next: Use c4-level2-container to decompose your system into deployable units.