UML was intended to be a visual language for capturing software designs and patterns. We use version 2.0 of UML, which made quite a few changes from the original version (1.0).
Physically, UML is a set of specifications from the OMG. There are four individual specifications, all available on the OMG web-site at http://www.omg.org
E This 3-dimensional object is represented through three separate 2-dimensional projections or Views of the object.
Figure 1 - 3-D projection
A single 2-D view does not adequately depict the full object, but all of the views taken together, give a good understanding of the 3-D object. Similarly, the individual views in a set of architecture diagrams must be understood in the context of each other to tell the full story.
ven though UML was born to capture design concepts, we are using it to capture architecture concepts because it is extremely flexible, designed to be extensible and has an extensive vocabulary for expressing behavior, relationship and flow.
It is useful to think of a system as a 3-dimensional entity and an architecture diagram as a 2-dimensional “view” of that 3-dimensional entity. Therefore to get a full picture of the entity in question, one requires multiple views of it. UML provides for multiple views so that the full model1 can be represented.
UML provides for multiple different diagram styles in two groupings:
Structural Diagrams – To represent how things relate
Behavior Diagrams – To represent how things act
Figure 2 - UML Diagram Model
In our usage (i.e. the style guide for representing functional architecture), we will only be using three2 of the available UML diagramming styles: Component diagrams, Sequence Diagrams, and Package Diagrams (these are noted by thick outlines in Figure 1)
1.4Scope and Purpose
The purpose of the architectural diagrams provided in these guidelines is to provide a complete functional architectural overview of the system from a logical perspective. What that means is that we are trying to understand the modules and how they interact in order to provide the features and functions of the system, but not how these modules are arrayed onto computer systems across networks in order to accomplish that task. This latter problem domain is delegated to a set of physical diagramming guidelines which are defined specifically for that purpose and covered in a separate set of guidelines. These diagrams are also not intended to be a detailed design, but as with any well defined architecture, should be both a high enough level to get the full perspective and detailed enough to bind the design and place it in context.
In effect, if you were to compare the processes of architecture and design to the output of your favorite mapping software or web site, the architecture would be like the overview map allowing you to place the detailed maps into context with the whole and with each other.
It is really up to individual organizations as to whether they annotate the diagrams with textual documentation to explain them or not. Many will choose to do so, many will choose not to. As long as the diagrams are kept accurate, the bulk of the information can be conveyed in a meaningful way. If by virtue of writing hundreds of pages of documentation to accompany the diagrams, an organization makes the architecture too costly to maintain, then the purpose is defeated. Non-updated diagrams, that fall out-of-line with reality are like a “dead language”; beautiful as they are, have no real value.
On the other hand, if the diagrams do not “speak” for themselves, without accompanying text, then likewise, the communication problem is not solved. It is important that the communication mechanism be tuned to match the use and style of the organization using it.
One mechanism that has worked in the past is to write very little accompanying text, but to have the architect present the architecture to his/her peers much the way a Masters student would present a thesis for peer review. Everybody learns and knowledge is transferred. But once again style must fit culture.
While the diagramming style is not meant to imply a specific architecture process, or specific architecture tools, we present the diagrams from widest scope top narrowest scope. This may be accomplished following a hierarchical decomposition process or not. We are not trying to prescribe the process followed to achieve the architecture, only to recommend a style for communicating it.
We start with a black-box view of the entire system being described.
A black-box view shows the interfaces a module requires, the interfaces it provides and any other detail required to describe the guaranteed behavior of the module. It does not specify anything about the internal implementation of the module(Pilone & Pitman, 2005, p. 60).
The first view, by virtue of being a black-box view of the entire system, we call the perspective view, because as the name implies it provides perspective into the environment in which the system operates. This view defines all the other systems both inside the company and outside that the system being described interacts with and the interfaces (and contracts) defining that interaction3.
Given a black box view for one or more modules, we can then use a white-box view to look inside.
A white-box view shows the details of how a module realizes the interfaces it provides (Pilone & Pitman, 2005, p. 63).
A white box view of a module shows how the module realizes its interfaces by presenting the contain modules (sub-modules) as black-boxes, with their interconnections. For an example, see: Figure 6 - System View 1, on page:13. These sub-modules may be further decomposed in white-box views in subsequent diagrams. This decomposition process can continue as far as it needs to go. Eventually the white-box decomposition must be illustrated as a UML class diagram. This is when the architecture process has `clearly transitioned into the design process and is therefore no longer the subject of this guideline.
The architecture diagrams and communication proceed from the outer level, progressively opening up the black boxes and looking inside only to find more black boxes, until eventually, we have gone far enough. It’s the architecture equivalent of the Russian Matryoshka Doll.
Figure 3 - Matryoshka Doll
An oft asked question is: “How far do you go in the decomposition. Do you have to go to the edge of the design process?” The only answer is, “Go as far as you need to and no further”.4
We use the UML Component view primarily to represent the modules encapsulating logical functionality and the ball/socket icons to represent the interfaces by which they are connected.
Once we have laid out the modules and their relationships via encapsulation and interfaces in sufficient detail to understand the components of the system, we represent data flow using UML sequence diagrams (a type of behavior diagram). It is generally very useful to distinguish interconnection / relationship from flow using UML structure diagrams to represent the former and behavior diagrams to represent the latter. Do not mix the two.