System Context Diagrams

The system context diagram is the most viewed and least maintained architecture artifact. It is the diagram shown to executives, handed to new team members, and referenced in proposals. It is also the diagram most likely to be stale because nobody updates it when a new integration is added. The context diagram's power is its simplicity: the system is one box, surrounded by the actors and external systems that interact with it. Everything the reader needs to understand the system's boundaries in a single view.

1. The System Box One box. Your system. Label it with the name and a one-line description of what it does. "Order Management Platform — manages customer orders from placement through fulfillment." The description anchors the reader. Without it, the box is a name that assumes prior knowledge. With it, the diagram is self-contained.
2. Actors and External Systems Surround the box with the people and systems that interact with it. Label each with their role and the relationship direction. "Customer — places orders" pointing into the system. "Payment Gateway — processes payments" with a bidirectional arrow. "Warehouse System — receives pick lists" pointing out. Each relationship is a sentence: who does what with the system.
3. The Completeness Test Show the diagram to someone who has never seen the system. Ask them: "Who uses this system, what external systems does it depend on, and what external systems depend on it?" If they can answer all three questions from the diagram alone, the context diagram is complete. If they cannot, the diagram is missing actors or relationships.