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.

🎯 Stakeholder Focus

• Executives: Value delivery and cost.

• Product Managers: Feature scope and external dependencies.

• Developers: High-level system context and data flow.

🚶 User Journey Integration

Instead of a static diagram, frame Level 1 around a Primary User Journey:

• Identify the Primary User (Person).

• Trace their Happy Path across the systems (e.g., "Customer buys a product").

• Label arrows with Action Verbs reflecting the journey (e.g., "Places order using", "Receives invoice from").

🚫 Anti-Patterns to Guard (Level 1)

• NO TECH NAMES: Forbid "React", "PostgreSQL", "Kafka".

• NO CONTAINERS: Don't draw "Web App" or "Database".

• UNDER 20 ELEMENTS: Keep the diagram high-level and readable.

Mermaid Template (Enhanced C4Context)

C4Context title [System Name] - System Context Diagram

Person(customer, "Customer", "Uses the system to buy products.")

System(my_system, "System Name", "Provides product browsing and order management.")

System_Ext(bank, "Bank API", "Handles payments and refunds.")
System_Ext(logistics, "Logistics Service", "Manages shipping and tracking.")

Rel(customer, my_system, "Browses and places orders", "HTTPS/Web")
Rel(my_system, bank, "Requests payment processing", "REST API")
Rel(my_system, logistics, "Sends shipping info", "Webhooks")

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?

• STRICT: Is it free from all technical/implementation details?