In Section 6.1, we introduced the notion of walking through a view by visiting discrete chunks, which we document with view packets. We need a way to help the reader establish his or her bearings each time the scope of documentation changes, such as when we narrow our focus as the result of taking a refinement step or when we shift laterally to a sibling element at the same granularity. A context diagram serves this purpose, establishing the context for the information contained in the rest of the view packet. Unlike the architectural documentation whose scope is limited to an element of interest and its internal architecture, a context diagram is a view of that element and the environment in which it lives and contains information about both. The purpose of a context diagram is to depict the scope of the subsequent documentation and to bound the problem the element is responsible for solving.
A context diagram shows what is in and what is out of the system under construction and the external entities with which it interacts.
6.2.1 Top-Level Context Diagrams
A distinguished context diagram is one for which the "element" being defined is the system. A top-level context diagram (TLCD) establishes the scope for the system whose architecture is being documented, defining the boundaries around the system that show what's in and what's out. A TLCD shows how the system under consideration interacts with the outside world. Entities in that outside world may be humans, other computer systems, or physical objects, such as sensors or controlled devices. A TLCD identifies sources of data to be processed by the system, destinations of data produced by the system, and other systems with which it must interact.
Use TLCDs as the first ingredient of architectural information presented to a reader. These TLCDs should be the reader's first introduction to a system and its architecture description. They can serve as the jumping-off point for delving into deeper architectural detail in any number of directions.
A TLCD is useful because it clarifies what constitutes the system of interest. Sometimes, an organization is asked to develop a system that is part of a larger system, and a TLCD depicts that. Sometimes, the supporting tools and environment, some off-line-processing software in a system, or some other tangential software is considered outside the scope of the system being developed. A TLCD clarifies what is in and what is out.
A system does not have just one TLCD but potentially one TLCD for each view, because the system's context can be described using the different vocabularies of the various views. A context diagram in one of the component-and-connector views shows interactions between the system of concern and its environment. A context diagram in a layered view shows which layers are within the project's scope and which are not. A TLCD for a view is associated with the view packet of that view that shows the entire system, if there is one. (Recall from Section 6.1 that not all views begin at a granularity showing the entire system.)
6.2.2 Content of a Context Diagram
Context diagrams show
A pure context diagram does not disclose any architectural detail about an entity, although in practice, most context diagrams show some internal structure of the entity being put in context. Context diagrams do not show any temporal information, such as order of interactions or data flow. They do not show the conditions under which data is transferred, stimuli fired, messages transmitted, and so on.
6.2.3 Context Diagrams and Other Supporting Documentation
Context diagrams are part of the view packet's supporting documentation. As such, they impart some obligations on the other supporting documentation.
Every view packet should have a context diagram. This requirement is satisfied in most cases by a pointer to a context diagram elsewhere that establishes the context for that packet.
6.2.4 Notations for Context Diagrams
Informally, context diagrams consist of a circle-and-line drawing, with the entity being defined depicted in the center as a circle, the entities external to it with which it interacts depicted as various shapes, and lines depicting interactions connecting the entities as appropriate. Because context diagrams are often used to explain systems to people who know more about the externals of the application than the internals, such diagrams can be quite elaborate and use all sorts of idiomatic symbols for entities in the environment.
UML does not have an explicit mechanism for a context diagram. UML's means for showing system context are use case diagrams. Elements in a use case diagram are actors, use cases, and associations between them. Actors denote external systems and agents, such as the user. The use case icon denotes system functions. The basic symbology is shown in Figure 6.8.
Figure 6.8. Symbology of use case diagrams showing actors, associations, and use cases
One actor may be associated with several use cases. Figure 6.9 shows the UML use case diagram for a hypothetical patient monitoring system. The external entities are the patient, the nurse, and a patient log. Patient and nurse provide input to the system, and the system produces a patient log. Although this diagram provides a good overview of the functionality of the system and the external entities that interact with the system, the diagram can easily get out of control if all the possible functionality is put into this diagram.
Figure 6.9. A few use cases in a UML use case diagram, showing some context of a patient monitoring system
Other context diagrams use UML class diagrams. Figure 6.10 shows the patient monitoring system again, using a class diagram. This style of diagram contains less information, containing no description of the functionality of the system. But for more complex environments, this way of documenting the system context gives a better overview. If this style of context diagram is used, you still would expect more detailed specifications about the expected functionality of the system. Therefore, use case diagrams as shown in Figure 6.9 more naturally occur as part of the behavior description of the whole system.
Figure 6.10. Description of a system context, using a UML class diagram. The class stereotyped as «system» depicts the system whose context is shown; Patient, Nurse, and PatientLog are external entities. Different symbols are used here to distinguish people from technical things.
6.2.5 Example of a Context Diagram
Figure 6.11 shows a context diagram for the ECS system detailed in Appendix A.
Figure 6.11. A context diagram from the ECS Science Data Processing Segment as documented in Appendix A. The thick-lined rectangle in the middle depicts the system; the thin-lined rectangles around it show the external entities: people or other systems. In this context diagram, people and systems are differentiated only by the name of the box, not the shape. Replication is depicted by repeated boxes. The arrows show data flow between the system and the external entities. The external systems need to be explained in the element catalog in this diagram's view packet.
Software Architectures and Documentation
Part I. Software Architecture Viewtypes and Styles
The Module Viewtype
Styles of the Module Viewtype
The Component-and-Connector Viewtype
Styles of the Component-and-Connector Viewtype
The Allocation Viewtype and Styles
Part II. Software Architecture Documentation in Practice
Documenting Software Interfaces
Choosing the Views
Building the Documentation Package
Other Views and Beyond
Rationale, Background, and Design Constraints