16  Context Diagrams

Context diagrams provide a simple and effective way to visualise the world in which the machine operates. They show all actors—including the machine itself—and how they interact through shared phenomena. They are particularly useful for communicating a high-level overview of the world, the role of the machine within it, and for specifying the machine’s inputs and outputs.

16.1 In a Nutshell

What

A context diagram describes the world in which the machine operates as a set of actors connected through interfaces.

For example, Figure 16.1 shows a context diagram for an ambulance dispatching system.

Figure 16.1: Context Diagram for an Ambulance Dispatching System

The actors are represented by pictograms. In Figure 16.1, they include the Public, Call Handler, Computer Aided Dispatch, Automated Vehicle Location System, Mobile Data Terminal, Station Printer, Paramedics and Patient.

The machine—the Computer Aided Dispatch system—is shown in bold and blue.

The arrows between actors correspond to interfaces, which are connections between two or more actors that enables them to interact through shared phenomena. In Figure 16.1:

• The public interacts with call handlers through emergency calls.
• Call handlers interact with the Computer Aided Dispatch system through a call handling user interface.
• The computer aided dispatch system also interfaces with:
  • the Automated Vehicle Location System,
  • the Mobile Data Terminals onboard of ambulances,
  • the ambulance station’s printer.

The arrow source indicates the actor who initiates the interactions on that interface. A bidirectional arrow indicates that both actors can initiate interaction on that interface.

The dotted circle marks the boundary of the world under consideration. This boundary defines the scope of analysis for the requirements engineering process.

Why

Context diagrams serve three main purposes:

1. Defining the scope of requirements exploration. They establish the world’s boundary, clarifying what is inside and outside the scope of the requirements engineering activities (Chapter 9). A well-defined boundary ensures requirements exploration is neither too broad nor too narrow.

2. Presenting high-level views of the world-as-is and to-be. They provide a simple, visual overview of the entire system, understandable by all stakeholders. Separate context diagrams can be created for the world-as-is and to-be.

3. Clarifying the machine inputs and outputs. They help visualize the machine inputs and outputs, reducing ambiguity about its responsibilities versus those of other actors. Specifying the machine’s inputs and outputs also supports precise formulation of machine requirements and informs software architecture design.

Who

Context diagrams are created by requirements engineers and validated by stakeholders. They must be designed to be understood by all stakeholders.

Software architects are key users of context diagrams. They rely on these diagrams to understand the machine’s boundaries, external actors, and interfaces, which are essential inputs for architectural design. When intended for software architects and the software development team, context diagrams may include more technical details than those designed for a general audience.

When

Context diagrams are most relevant during the Preparation phase, where they help define the world boundary, and during the Formulation phase, where they specify the machine inputs and outputs. They are also used extensively during the Exploration and Decision phases to identify actors and actors’ interactions in the world-as-is and to-be.

They are particularly important in brownfield projects, where understanding existing systems that the machine must replace or interact with is essential. They are however also highly valuable in greenfield projects to model the world-as-is without pre-existing software and ideas for the world-to-be with the new software.

These diagrams are simple to create and easy to understand. They are as valuable in agile projects with minimal documentation as they are in waterfall projects with more extensive requirements documentation.

While there are cases where a context diagram adds little value—such as for a single-user, standalone application like a word processor or a single-player video game-not having one may suggest that your requirements analysis is too narrowly scoped (see Chapter 9).

16.2 Concepts and Notations

Context diagrams have only three basic elements: Actor, Interface, and World Boundary. Table 16.1 summarizes their notation and meaning.

Table 16.1: Context Diagram Notation Summary

Concept	Graphical Notation	Meaning
Actor		An entity that can control and observe phenomena.
Interface		A connection between actors where the actors interact through shared phenomena.
World Boundary		Marks the boundary between the World and adjacent systems.

Actors

The concept of actor was defined in Section 2.5.1:

Definition: Actors

An actor is an entity that can perform actions in the World. An actor can initiate events or change some states in the World.

An actor can be a person, a department, an organisation, a device (such as a sensor or actuator), or a software system. The machine is also an actor.

In a context diagram, you can represent actors using any pictograms that makes sense to your stakeholders. The purpose is to make the diagram engaging and easy to read. The same pictogram can be used for different actors (e.g in Figure 16.1: Public and Paramedics).

By convention, we highlight the machine in a different color, using a bold label. In Figure 16.1, the Computer Aided Dispatch actor (our machine) is displayed in blue.

If you do not have time to choose a pictogram, you can use the default traditional notation: stick figures for human actors and boxes for all devices and computer-based systems.

In this more traditional notation, the context diagram of Figure 16.1 would look like this:

Figure 16.2: Context Diagram for an Ambulance Dispatching System using a more traditional notation

Specifying Actors

To ensure a shared understanding among all stakeholders, you must supplement the diagram with a brief description of each actor.

A typical actor specification includes:

• Actor Name: A short name describing the actor’s role.
• Type: whether the actor is a person, organization, software system, or device.
• Description: A short summary of the actor’s role and responsibilities.

Example:

Actor: Call Handler
Type: Human
Description: Staff member who responds to emergency calls in the central control room.

The specification of all actors can be grouped in an actor glossary or actor definition table:

Actor	Type	Description
Public	Human	Members of the public who report incidents.
Call Handler	Human	Staff member who responds to emergency calls in the central control room.
Computer Aided Dispatch System	Software System (The Machine)	Receives incident details from call handlers, coordinates ambulance dispatch, communicates with mobile data terminals and station printers, track incident status to completion.
Station Printer	Device	Prints ambulance mobilization instructions at the ambulance station.
Paramedics	Human	The team of persons driving the ambulance and attending to patients in an incident.
Mobile Data Terminal	Device	Device installed in ambulances, used by paramedics to receive mobilisation instruction, acknowledge a mobilisation, and send ambulance status updates.
Automated Vehicle Location System	System	A GPS-based system that tracks the real-time location of ambulances and provides location data to the computer-aided dispatch system.

There is no fixed format for specifying actors. You can adapt the above format to suit your needs. For example, you might add fields for actors’ geographical locations or the number of instances.

During the early requirements engineering phases, it is common that an actor’s roles is not fully understood or defined yet. An actor’s description can then be provisional, indicating uncertainties or open questions about their future role. For example:

Actor: Call Handling Support Officer
Type: Human
Description: A potential new role that may provide assistance to call handlers when dealing with complex situations. The exact responsibilities and authority of this role are still under discussion.

Interfaces

In Chapter 2, we saw that actors interact through shared phenomena—observable states or events in which actors participate simultaneously. In a context diagram, these interactions occur in locations called interfaces.

Definition: Interface

An interface is a connection between two or more actors that enables them to interact through shared phenomena. The signature of an interface is the set of shared phenomena that may occur at that interface.

Types of interfaces include:

• human-to-human interfaces: Direct, synchronous communication between people, such as a call handler speaking with a member of the public, or a paramedic talking to a patient. These interactions may occur face-to-face, over the phone, or via other real-time channels.
• human-computer interfaces: Direct, synchronous interactions between a person and a computer system or device, such as a call handler entering information into the Computer Aided Dispatch system, or a paramedic using a Mobile Data Terminal.
• system-to-system interfaces: Connections between two software systems, such as the Computer Aided Dispatch system exchanging data with the Automated Vehicle Location System or the Mobile Data Terminal.

In a context diagram, interfaces are represented by lines with optional arrowheads. The source of an arrow indicates the actor who initiates the interaction. The graphical notations and their meanings are summarized in Table 16.2.

Table 16.2: Context Diagram Interface Notation Summary

Arrow Type	Graphical Notation	Meaning
Unidirectional		Interactions along the interface are initiated by A.
Bidirectional		Some interactions are initiated by A, others by B.
None		The diagram does not specify what actor initiates the interactions.

Specifying an Interface

Each interface can be specified in more detail. This is useful when the interactions at the interface are complex, potentially ambiguous, or when you need to clarify exactly what phenomena are shared between the actors.

A typical interface specification includes:

• Name of the interface
• Actors involved (From/To or Between)
• Description of the interaction
• Shared phenomena (optional): a list of shared phenomena, and which actor controls each.

For example:

Interface Emergency Call
From Public To Call Handler
Description: A phone call from a member of the public to the emergency service. During the call, the call handler asks questions to the caller to determine the nature and location of the incident, and may provide instructions to the caller on what to do while waiting for the ambulance.

The interface description can also be shown as an annotation on the context diagram.

Figure 16.3: An Interface Specification as Annotation

Here is another example that includes a specification of shared phenomena:

Interface Call Handling UI
Between Call Handler And Computer Aided Dispatch
Description: The call handler interacts with the Computer Aided Dispatch system via a user interface to record incident details and mobilize ambulances in response to the incident. The Computer Aided Dispatch provide prompts to guide discussion with the caller, recommends the nearest available ambulances, and signals duplicate calls.
Shared Phenomena:

Phenomenon	Controlled by	Meaning
Incident details	Call Handler	Details about the emergency incident (location, type, severity) entered by the call handler.
Call handling prompt	Computer Aided Dispatch	Prompts and guidance provided to the call handler to assist in gathering relevant information from the caller.
Ambulances recommendations	Computer Aided Dispatch	Suggestions for which ambulances to mobilize based on location and availability.
Duplicate call detected	Computer Aided Dispatch	Notification that the incident has already been reported or is being reported by another call, helping to avoid redundant mobilizations.

Such detailed specification of interface phenomena is common in embedded control system specifications (e.g., automotive controllers, medical devices, industrial automation) where precise definitions of the controller’s inputs and outputs are essential for its implementation. Although less common in other types of systems, specifying the phenomena in the machine interfaces is highly valuable for formulating clearer requirements, generating test cases, and implementing the interface.

During the early phases of requirements engineering, the details of the machine interfaces are usually not yet determined. The interface specifications can therefore be provisional, containing brief descriptions that highlight their intended purpose, as well as any uncertainties or open questions.

World Boundary

The world is the part of the real world affected by the machine (Chapter 2). It defines the scope of requirements engineering, separating what must be considered during requirements exploration from what can be ignored. Synonyms include the “domain”, the “application domain”, the “problem domain”, the “environment”, and the “context”.

Definition: World Boundary

The world boundary is the conceptual line that separates actors inside the world from those outside of it.

The world boundary is typically shown as a dotted circle or ellipse enclosing all actors and interfaces that are within scope, as illustrated in Figure 16.1.

During the Preparation phase, it is useful to focus on the world boundary by hiding all actors and interfaces inside the world. For example, Figure 16.4 shows the scope of ambulance dispatching: the world inputs are emergency calls, and the outputs are ambulance arrivals.

Figure 16.4: The World of Ambulance Dispatching

16.3 Modelling Guidelines

Context diagrams are relatively straightforward to create. The following guidelines will help you learn and apply the technique more effectively.

General Guidelines

Model the Stakeholders View of the World

A context diagram should reflect how stakeholders view the world, not how software engineers see it. This means:

• Use the language and terminology of stakeholders.
• Use pictograms that are familiar and engaging to your stakeholders.
• Include only those actors and interfaces that relevant to the stakeholder goals.
  
• If stakeholders see a group or organization as a single actor (e.g., “Paramedics”), model it as such, even if it is composed of multiple people or subsystems.

The goal is to create a model that supports communication and shared understanding, not to capture every technical detail.

Naming Guidelines

For actors:

• Use role-based names, not individual identifiers (e.g., Call Handler instead of Sarah Smith).
• Use domain-specific terms instead of generic or invented labels (e.g., Mobile Data Terminal¹ instead of Mobile Device or Ambulance Computer).
• Use singular nouns (e.g., Call Handler rather than Call Handlers), even if multiple instances exist. Exceptions are permitted—for example, Paramedics in Figure 16.1 serves as shorthand for Paramedics Team.

For interfaces:

• Use domain-specific noun phrases that reflect the nature of the interaction (e.g. Emergency Call rather than Phone Call, and Call Handling UI rather than Graphical User Interface).
• Alternatively, use a domain-specific verb phrase that corresponds to the main (or only) shared event on that interface (e.g. report incident for Emergency Call or encode incident details for Call Handling UI). If using this style, ensure the diagram remains clear and avoid cluttering it with excessive interaction details (see Common Mistake 4 in Section 16.4).

Layout Considerations

To make the diagram easy to read, pay attention to its layout:

• Follow the natural reading flow: align most arrows with your stakeholders’ reading direction (e.g., left-to-right, top-to-bottom for Western audiences).
• Minimize line crossings: reduce visual clutter by avoiding crossing lines where possible.
• When actors’ physical or organizational proximity is relevant, arrange them close together in the diagram to reflect their real-world relationships.

During the Preparation Phase

During the Preparation phase, a context diagram serves one primary purpose: defining the world boundary. To achieve this:

• draw the world boundary, external actors (outside the world boundary), and interfaces between these actors and the world;
• omit all actors and interfaces inside the world’s boundary.

For example, Figure 16.4 shows the world boundary for our ambulance dispatching system.

Two methods for creating a world boundary context diagram are:

1. Derive the world boundary from the domain boundary goals. If the domain boundary goals are known, the world’s inputs and outputs can be derived from the goal formulations (see Chapter 9).
2. Identify the world boundary on domain scenarios and a context diagram for the world-as-is. If the domain boundary goals are unclear, an alternative approach is to sketch a few domain scenarios and a tentative context diagram for the world-as-is (using guidance for the Exploration phase below). These can then be used to draw a line between what is considered inside and outside of the world boundary.

During the Exploration and Decision Phases

During requirements exploration and decision-making, context diagrams serve several purposes:

• facilitating the identification of actors and their interactions;
• validating your understanding of actors and their interactions with stakeholders;
• providing high-level overviews of the world-as-is and potential worlds-to-be.

A key concern during this phase is to keep your stakeholders engaged. To support this:

• keep diagrams simple and intuitive;
• include brief actor descriptions to prevent ambiguities and ensure shared understanding;
• avoid unnecessary detail — detailed interface specifications are typically deferred to later phases.

During the Exploration phase, context diagrams can be created in three ways: drawing from scratch, deriving from domain scenarios, or developing them as part of goal modelling.

Method 1: Draw a Context Diagram from Scratch

In this approach, you identify actors and interfaces based on a system’s written description or your own understanding of the system. You may collaborate with stakeholders or domain experts.

The basic guidance is as follows:

1. Identify actors by analyzing the system description. Look for subjects of sentences in the active voice, as these are often actors. For sentences in the passive voice, the actor may be implied or omitted; try to infer who or what is performing the action. Consider all actors, including people, organizations, devices, and software systems.
2. Identify interfaces by examining how actors interact. Look for action verbs involving two or more actors, as they often correspond to shared events. For example: “a member of the public reports an incident”, “the call handler encodes the incident details into the computer aided dispatch system”. Group related shared events into interfaces.
3. Draw the context diagram, following the layout considerations outlined earlier.
4. Note uncertainties and open questions as annotations on the model.
5. Review the diagram with stakeholders to validate actors and interfaces, address the uncertainties, and revise the diagram as needed.

Creating a context diagram from scratch can be challenging, as it requires integrating multiple scenarios and perspectives into a coherent, high-level overview in a single step. The other two methods are easier because they introduce intermediate steps—first defining independent scenarios and goals—before deriving the context diagram.

Method 2: Derive a Context Diagram from Domain Scenarios

During requirements workshops and interviews, individual domain scenarios are often easier to elicit and model than a comprehensive context diagram. A practical strategy is to first capture a set of domain scenarios and then derive the context diagram from them (see Chapter 18).

The process for deriving the context diagram follows the same guidance as creating a context diagram from scratch. The key difference is that domain scenarios provide a more structured description of the system, making actors and their interactions more explicit.

Method 3: Create a Context Diagram during Goal Modelling

If you are using goal modelling, the development of the context diagram is closely linked to the elaboration of the goal model. Actors and interfaces are identified gradually during the goal refinement process. This process is explained in Chapter 19.

Visualising Changes

During requirements exploration and decision-making, it is common to create multiple context diagrams: one representing the world-as-is and one or more representing propositions for the world-to-be.

Presenting context diagrams for the world-as-is and to-be side by side helps stakeholders visually compare the current and proposed systems.

Context Diagrams for the world-as-is and to-be

During the Formulation Phase

During the formulation phase, context diagrams are used to specify all machine inputs and outputs. This clarifies exactly what information, events, or signals the machine receives from and sends to its environment.

Ideally, a context diagram already exists from earlier phases. In that case, your task is to refine it by adding detailed specifications for the machine interfaces. If no context diagram was created previously, follow the guidance for the exploration and decision phases to develop one before adding the detailed interface specification.

Machine inputs and outputs can be identified from three sources:

• Domain Scenarios – Review domain scenarios to identify machine inputs and outputs in each scenario, then add them to the interface specification.
• Machine Requirements and Scenarios – Extract machine inputs and outputs referenced in individual requirements or acceptance tests (e.g., Gherkin scenarios) and incorporate them into the machine specification.
• Surrounding Actors (Documentation & Experts) – Examine external devices or software systems that interact with the machine (e.g., sensors, actuators, or other software systems). Identify inputs and outputs by consulting their documentation or domain experts.

During Quality Assurance

During quality assurance, you will check the consistency of the machine inputs and outputs with the machine requirements and acceptance tests (e.g Gerkhin scenarios):

• Completeness: Every phenomena in the machine requirements and acceptance tests must be defined in the context diagram;
• Relevance: Every machine input and output in the context diagram must be referenced in at least one machine requirements or acceptance test.

An Aside: Passive Actors

Actors in a context diagrams are usually active components in the world: they perform actions in the world (they control phenomena) rather than being simple observer of the world. It is however sometimes useful to include passive actors, i.e. actors that perform no actions - they participate in actions but only passively. An example is the Patient actor in Figure 16.1.

16.4 Common Mistakes

Mistake 1: Exposing the Machine’s Internal Components

A common mistake students make when learning context diagrams is including the machine’s internal components. Figure 16.5 illustrates a typical example.

Figure 16.5: Context Diagram Mistake 1: Exposing the Machine’s Internal Components

This often stems from a well-meaning attempt to describe the software architecture, but it unnecessarily complicates the context diagram by introducing details that are irrelevant to stakeholders. This mistake is also common in diagrams that fail to accurately represent external actors and interactions. It’s as if the authors, lacking a proper analysis of the world, attempt to compensate by detailing the machine’s internals instead.

Fortunately, this mistake is easy to fix: simply omit the machine’s internal components from the context diagram and use a separate architectural model for that purpose.

Mistake 2: Treating Internal Components as External Actors

Another common error is modelling an internal machine component as if it were an external actor, as illustrated in Figure 16.6.

Figure 16.6: Context Diagram Mistake 2: Treating Internal Components as External Actors

This model is incorrect because the Incident Database is an internal component of the Computer Aided Dispatch system, not an external actor.

A key purpose of a context diagram is to define the machine’s boundary: clarifying inputs and outputs, and distinguishing what’s inside from what’s outside the machine. If the Incident Database were truly external (e.g., a third-party service), the diagram would be valid. However, as shown here, this misrepresentation blurs the machine boundary with the risk of misleading stakeholders and developers.

Mistake 3: Confusing Context Diagrams with Domain Conceptual Models

A third common mistake is overloading the context diagram with domain entities and associations that belong in a domain conceptual model rather than a context diagram. Figure 16.7 illustrates this issue, with annotations highlighting the problems.

Figure 16.7: Context Diagram Mistake 3: Confusing Context Diagrams with Domain Conceptual Models

In this example, Incident and Ambulance are domain entities, not actors. Treating them as actors–even passive ones–is incorrect.

Furthermore, all arrows in this diagram represent domain associations, not interfaces. Some association labels—such as Handles and Interact with—are too vague.

To avoid these mistakes (a frequent challenge for students), it’s crucial to understand both the differences and relations between domain conceptual models and context diagrams. As introduced in Chapter 2:

• A domain conceptual model defines terms representing real-world phenomena.
• A context diagram identifies actors, the phenomena they control, and the phenomena they passively observe or participate in.

If this distinction remains unclear, revisiting Chapter 2 may help reinforce these foundational concepts.

Mistake 4: Cluttering the Diagram with Detailed Interactions

A common mistake is cluttering the diagram with excessive details about actor interactions, as illustrated in Figure 16.8.

Figure 16.8: Context Diagram Mistake 4: Cluttering the Context Diagrams with Detailed Interactions

This makes the diagram difficult to read and reduces its usefulness. To avoid this issue, group interactions into well-defined interfaces, as shown in Figure 16.1.

16.5 Notes and Further Readings

Context diagrams are among the oldest requirements engineering models, dating back to the structured analysis methods of the 1970s and 80s. Originally, they were used to document data flows into and out of the system to be built (the machine) (DeMarco 1979). Today, their scope has expanded: they show not only the interactions between the machine and its environment but also those between external actors (Jackson 1995; Lamsweerde 2009).

The notion of world boundary originates from the VOLERE requirements engineering method where it is called the “work context” (Robertson and Robertson 2012).

In the Problem Frames approach, context diagrams are extended into problem diagrams (Jackson 2001) — i.e. context diagrams annotated with domain goals. The goals are linked to their corresponding phenomena in the diagram.

Context diagrams are one of the essential models of the KAOS goal-oriented requirements engineering method, where explicit consideration about actor’s capabilities drives the goal refinement process (Letier 2001; Letier and Van Lamsweerde 2002; Letier and Heaven 2013).

Context diagrams are related to to Ecosystem Maps in Joy Beatty and Anthony Chen’s book Visual Models for Software Requirements (Chen and Beatty 2012).

Use case diagrams provide an alternative method for visualizing a system’s boundary with its environment (Jacobson 1992; Fowler 2003). However, use case diagrams are more limited than context diagrams in two key aspects. First, they only depict interactions between the system and its actors, omitting interactions among external actors themselves. Second, they lack precise specification of system inputs and outputs, resulting in less detailed interface documentation.

Chen, Anthony, and Joy Beatty. 2012. Visual Models for Software Requirements. Pearson Education.

DeMarco, Tom. 1979. Structured Analysis and System Specification. Prentice-Hall.

Fowler, Martin. 2003. UML Distilled: A Brief Guide to the Standard Object Modeling Language. 3rd ed. Addison-Wesley Professional.

Jackson, Michael. 1995. Software Requirements & Specifications: A Lexicon of Practice, Principles and Prejudices. ACM Press/Addison-Wesley Publishing Co.

———. 2001. Problem Frames: Analysing and Structuring Software Development Problems. Addison-Wesley.

Jacobson, Ivar. 1992. Object-Oriented Software Engineering: A Use Case Driven Approach. Addison-Wesley Professional.

Lamsweerde, Axel van. 2009. Requirements Engineering: From System Goals to UML Models to Software Specifications. John Wiley & Sons.

Letier, Emmanuel. 2001. “Reasoning about Agents in Goal-Oriented Requirements Engineering.” PhD thesis, Université catholique de Louvain. http://www0.cs.ucl.ac.uk/staff/e.letier/publications/letier-thesis.pdf.

Letier, Emmanuel, and William Heaven. 2013. “Requirements Modelling by Synthesis of Deontic Input-Output Automata.” In 2013 35th International Conference on Software Engineering (ICSE), 592–601. IEEE.

Letier, Emmanuel, and Axel Van Lamsweerde. 2002. “Agent-Based Tactics for Goal-Oriented Requirements Elaboration.” In Proceedings of the 24th International Conference on Software Engineering, 83–93.

Robertson, Suzanne, and James Robertson. 2012. Mastering the Requirements Process: Getting Requirements Right, 3rd Edition. Addison-wesley.

---

1. Wikipedia page on Mobile Data Terminal