Skip to content
Software Architecture Guide

Refining Complex Context Views

Explanation

Section titled “Explanation”

A context view shows your system as a black box. That means you see the system from outside, with no internal parts. Around the box sit the users and external systems that talk to it. See Context View and arc42 Context and Scope for the basics.

Keep the top level an overview. arc42 advises restricting the context to an overview and avoiding too many details. The C4 system context diagram follows the same idea. It is a zoomed-out, low-detail picture that technical and non-technical readers can both follow. See System Context Diagram.

Group many partners. If many external systems are involved, arc42 says to cluster them by explicit criteria. State the criterion in the diagram, so readers know why systems sit together.

Cover all partners. The business context includes every communication partner, users and IT systems alike. It specifies the domain interfaces to each partner. It should show data flows, not dependencies.

Describe the technical side too. The technical context covers the channels and transmission media that link the system to its environment. Many stakeholders base architectural decisions on these technical interfaces. arc42 calls domain and technical interfaces among the most critical aspects of a system. This is why the detail behind each interface deserves its own space. See Business and Technical Context.

Choose a notation for the detail. arc42 suggests a table with one row per communication partner. For technical channels, it suggests a UML deployment diagram. The table holds interface detail that would clutter the overview diagram.

The result is a short top-level picture, with the detail of each partner or cluster kept outside the overview.

Example

Section titled “Example”

An online shop talks to customers, a payment provider, three shipping companies and two marketing tools. The top-level diagram shows the shop as one box. It groups the shipping companies and the marketing tools into two clusters, labeled “logistics” and “marketing”. A table then lists each partner in one row, with the data it exchanges and the direction of the flow. A separate deployment diagram shows the technical channels to the payment provider.

Trade-offs

Section titled “Trade-offs”

Keeping the overview small means readers must look elsewhere for detail, such as a table or a second diagram. Clustering hides individual partners behind a group label, so the grouping criteria must be explicit. Splitting the context into several pieces also creates more material to keep consistent.

Overview context with external systems clustered by an explicit criterion

Diagram source 
flowchart LR
  Customer[Customers] -->|orders| S[Shop system]
  S -->|payment requests| Pay[Payment provider]
  subgraph Logistics cluster
    Ship1[Shipper A]
    Ship2[Shipper B]
  end
  S -->|shipment data| Ship1
  S -->|shipment data| Ship2

Checks

Section titled “Checks”
  • The top-level context diagram shows the system as a black box and stays an overview without excessive detail.
  • Where many external systems exist, they are clustered by explicitly stated criteria.
  • The business context covers all communication partners, users and IT systems, and shows data flows rather than dependencies.
  • The technical context describes the channels and transmission media to the environment, for example in a deployment diagram.
  • Each communication partner has a row in a context table.
Section titled “Related”

Sources

Section titled “Sources”