design-practice-repository

Artifact/Template: Context Diagram

also known as: System Context Diagram

A context diagram provides an outside view on a single system, including incoming and outgoing relations with other systems. It does not unveil any system-internal design.

Motivation (Addressed Information Need)

The C4 model page on Wikipedia advises to “show the system in scope and its relationship with users and other systems”.

Usage (Produced and Consumed When)

Drawing a context diagram serves one or more of these purposes:

Document external dependencies and coordination needs (including technical risk management and release scheduling).
Identify application owners and other stakeholders of neighboring systems.
Estimate and initiate integration design and implementation.

Template Structure and Notation(s)

Context diagrams are informal, typically; their layout should follow certain conventions. For instance, the external systems or human users can be ordered in specific ways: consumers at the top of the figure and providers at the bottom. Arrow labels and layout should indicate the types of interface (and integration style).

Example(s)

In an order management scenario in telecommunications, external clients such as Web channels supporting human users and external systems (in client/consumer role) may be the primary actors interfacing with the order management system. Secondary actors include backend systems for billing and customer management, as well as the telephony network:

Context Diagram Example

Tools

Context diagrams are typically created with light tools, although full-fledged modeling software can also be used:

Any drawing tool or whiteboarding capability
C4 tools, one option being Structurizr
UML tools, either graphical or text-based (such as PlantUML)

Hints and Pitfalls to Avoid (Common Pitfalls)

Organize the diagram for readability; for instance, place and order consumers and providers by their type (human user, external system) and/or importance and/or time of activity. Label all arrows, and explain their meaning in a legend (for example, runtime API call or compile-time dependency?).
Do not confuse black box and white box and views. Here, no internals should be shown.
Do not stop at the outside view, but zoom in (with a container diagram).
Do not forget to update this diagram as a design evolves; when a new API is consumed, this has to be shown as an outbound external interface in any context diagrams drawn earlier.
Consider Strategic DDD to carve out contexts.

Origins and Signs of Use

This is not a UML diagram type, but has been present in professional services methods since the late 1990s. Many UML tools have some proprietary support, often basic.

The Unified Architecture Method (UAM) has a task called “Define System Scope & Context”.

The System Integration Method in IBM Global Services included a System Context Diagram artifact since its inception in the late 1990s.

The Architecture Modeling activity produces context diagrams.

Related artifacts are:

Strategic DDD context maps, showing relations between bounded contexts
Use cases and user stories (contributing primary external interfaces)
Architecture Overview Diagram

More Information

Domain-driven design tools such as Context Mapper can be used to draw context diagrams that show one or more systems and their relations.
The Agile Modeling website advocates free-form modeling and a multiple-models approach.
There is a Scenario viewpoint in the 4+1 architectural view model.
The Soft Systems Methodology has a Rich Picture artifact.

Data Provenance

title: "Design Practice Repository (DPR): Context Diagram"
author: Olaf Zimmermann (ZIO)
date: "01, 31, 2023"
copyright: Olaf Zimmermann, 2023 (unless noted otherwise). All rights reserved.
license: Creative Commons Attribution 4.0 International License