Key Elements: Identifying Persons, Software Systems, and high-level relationships
The System Context Diagram keeps things intentionally minimal — there are only three core element types you need to identify and draw. Mastering these three building blocks is the key to creating clear, accurate, and useful Level 1 diagrams every time.
1. Persons (Users / Actors / Roles)
Definition: Real human beings (or sometimes organizational roles) who directly interact with your software system.
How to identify them:
- Ask: “Who actually uses this system in their day-to-day work or life?”
- Focus on roles, not individuals: “Customer”, “Store Manager”, “Field Technician”, “Compliance Officer”, “End Customer”, “Partner Merchant”.
- Include both internal and external users if they are true end-users (e.g., “Internal Support Agent” vs. “External Auditor”).
- Exclude people who maintain or build the system (e.g., “Developer”, “DevOps Engineer”, “Architect”) unless they genuinely use it as an end-user.
Best practices:
- Use 3–6 major roles at most — group similar ones if needed (e.g., “Retail Customer” and “Corporate Customer” can often become “Customer”).
- Place them on the left or top of the diagram for natural left-to-right or top-to-bottom reading flow.
- Use person icons (stick figure or silhouette) if your tooling supports it — it helps non-technical readers instantly recognize them.
Examples:
- E-commerce platform: “Shopper”, “Customer Service Agent”, “Warehouse Staff”
- Banking app: “Retail Customer”, “Business Customer”, “Bank Teller”
2. Software Systems (Your System + External Systems)
Definition: Cohesive pieces of software that deliver business value or capability.
Two categories:
- Your Software System (the central box)
- This is the single system you are describing.
- Name it using the real-world product/service name your stakeholders already use: “Mobile Banking App”, “Inventory & Order Management System”, “Patient Portal”, “IoT Device Management Platform”.
- Add a 1-sentence purpose if helpful: “Allows customers to manage accounts and make payments from their phone.”
- Always place this box in the center — everything else orbits around it.
- External Software Systems
- Any other software (owned by your organization or third parties) that your system interacts with.
- Treat internal legacy systems, shared platforms, or SaaS services the same way: if your team doesn’t own and evolve them, they are external.
- Common examples: “Core Banking Mainframe”, “Stripe Payment Gateway”, “Okta / Auth0 SSO”, “Salesforce CRM”, “Google Maps API”, “SendGrid Email Service”, “Internal HR System”, “Partner ERP”.
Best practices:
- Use recognizable, business-friendly names — avoid generic terms like “Database” or “API Gateway” at this level.
- Limit to the most important 3–6 external systems. If there are dozens, group them (e.g., “Various Partner APIs”, “External Reporting Tools”) or defer detail to a System Landscape view later.
- Place external systems on the right or bottom to maintain clean flow.
3. High-Level Relationships
Definition: The directional or bidirectional interactions between elements.
How to identify and draw them:
- Draw arrows showing who initiates communication:
- Person → Software System: “Customer submits order”
- Software System → External System: “Inventory System queries Warehouse Management”
- Bidirectional: “CRM ↔ Customer Portal” (syncs data both ways)
- Label relationships only when the label adds meaningful clarity:
- Good: “Authenticates via”, “Submits payment”, “Views real-time map”, “Sends notification”
- Avoid: overly technical labels like “Calls REST API v2” or “Publishes to Kafka topic” — save that for Container level.
- Use solid lines for synchronous calls, dashed lines if asynchronous or less critical (optional convention).
- Keep it sparse: 4–10 relationships total is typical for a clean diagram.
Common relationship patterns:
- Users initiating most interactions (left-to-right flow)
- Your system pulling data from external systems (e.g., pricing, inventory)
- Your system pushing data or events outward (e.g., order confirmation emails)
- Bi-directional syncs with key partners or master data sources
Quick Checklist When Building the Diagram
- One central Software System box (your system)
- 2–6 Persons (key user roles)
- 2–6 External Software Systems (critical dependencies/integrations)
- Clear, directional arrows with optional short, business-oriented labels
- No technologies, no internal structure, no servers/databases/APIs visible
By focusing exclusively on these three element types and their high-level relationships, the System Context Diagram remains simple, powerful, and universally understandable. This minimalism is exactly what makes it such an effective starting point — and the foundation for everything that comes next in the C4 hierarchy.
In the upcoming hands-on section, you’ll apply this directly: we’ll take a natural language description of a system and systematically identify these exact elements using both manual reasoning and AI assistance to build your first complete System Context Diagram.