Skip to content
Software Architecture Guide

Context View Antipatterns

Explanation

Section titled “Explanation”

A context view (see Context View) shows your system from the outside. The system is a black box. Around it sit its communication partners, such as users and other IT systems. The antipatterns below, meaning common mistakes, pull the diagram away from that purpose.

Unlabeled arrows. Many people read an arrow between software systems as a data flow. arc42 therefore advises showing data flows, not dependencies. Each arrow should tell readers what data moves and in which direction. Leaving arrows unnamed fails this goal. The Design Practice Repository says to label all arrows and explain their meaning in a legend.

Arrows that hide direction. A single two-headed arrow does not say what moves in each direction. Use one labeled arrow per direction. See Context View Antipattern: Forgetting Bidirectional Data Flows.

Showing system internals. A context diagram gives an outside view only. Do not mix in a white-box view, which shows the parts inside the system. Internals belong in other views, such as the Component View.

Unclear boundary. arc42 tells authors to demarcate the system explicitly from its environment. Readers must see what is inside and what is outside.

Too much detail. arc42 recommends keeping the context an overview and avoiding too many interface details. It gives a counter-example with too many details. The C4 system context diagram follows the same idea. It covers a single system and focuses on people and software systems, not on technologies, protocols or low-level details.

Mixing business and technical context. The business context shows domain interfaces to partners. The technical context shows the channels and transmission media that link the system to its environment. arc42 advises keeping the two apart and deferring the technical context to the deployment view. See Business and Technical Context.

Diagram without a table. arc42 recommends pairing the context diagram with a table. It also lists a tip to show all external interfaces.

Example

Section titled “Example”

An online shop draws its context. A bad version shows one box labeled “Backend” inside the shop, a two-headed arrow to “External system”, and an arrow labeled “process payment”. A better version shows the shop as one black box. Two arrows connect it to a payment provider: “payment request” goes out, “payment result” comes back. A table lists each partner and interface.

Trade-offs

Section titled “Trade-offs”

Keeping the diagram to an overview means some detail is left out. Put that detail in a companion table or in other views, such as the deployment view. Showing all external interfaces and keeping the diagram simple pull in opposite directions. The table helps balance them.

A corrected context view: black box, named neighbors, one labeled arrow per data flow.

Diagram source 
flowchart LR
  C[Customer] -->|order| S[Online Shop]
  S -->|order confirmation| C
  S -->|payment request| P[Payment Provider]
  P -->|payment result| S

Checks

Section titled “Checks”
  • Every arrow carries a label naming the data that flows, and a legend explains the notation.
  • The diagram shows the system as a black box with no internals.
  • The system boundary is explicit and separates the system from its environment.
  • The diagram stays an overview, without technologies, protocols or low-level detail.
  • Business context and technical context are kept apart, and the diagram is paired with a table.
Section titled “Related”

Sources

Section titled “Sources”