Creating Architectural Descriptions

Outline Standardizing architectural descriptions: The IEEE has published, “Recommended Practice for Architectural Description of Software-Intensive Systems” (IEEE 1471). The standard does not specify what views an architectural description should have, but rather how those views should be specified. Creating an architectural description The architectural description is composed of views that address a set of stakeholders and their concerns, and which contain a model of some aspect of the system. Applying the architectural description The architectural description is necessary to perform an architectural assessment.

Introduction An architectural description is a set of representation models grouped into views. Views represent certain aspects of the system, each addressing a set of related concerns. Views are specified by viewpoints. A viewpoint identifies system stakeholders and the concerns addressed, as well se modeling languages and modeling techniques used to create views.

Standardizing Architectural Descriptions IEEE 1471 Elements Mission System Architecture Stakeholder Environment 1 … * fulfills has an inhabits influences 1 … * has Concern 1 … * is important to 1 … * has Architectural Description 1 described by Rationale provides Viewpoint 1 … * used to cover 1 … * identifies 1 … * selects Viewpoint Library 0 … 1 has source View conforms to Model participates in 1 … * organized by 1 … * is ad-- dressed to 1 … * participates in 1 … * consists of

Standardizing Architectural Descriptions (Cont’d) In the terminology of the IEEE 1471, a system has an architecture which is described by an architectural description. An architectural description is organized by one or more views, each of which consists of one or more models and conforms to a viewpoint. An architectural description selects one or more viewpoints, each of which covers one or more stakeholder concerns. The IEEE 1471 definition of an architectural description is “a collection of products to document an architecture.

Standardizing Architectural Descriptions (Cont’d) By applying the IEEE 1471 you can reduce the semantic gap between client’s requirements and implementation-oriented models. An effective architectural description identifies a target audience (the stakeholders) and their concerns. The stakeholders and their concerns define the scope and purpose for what software developers specify and a clear context in which to write them.

Creating an Architectural Description The initial activities: 1. Identify the architectural description, including version and overview information. 2. Identify stakeholders, their roles, and their architectural concerns. 3. Select viewpoints 4. Specify viewpoints 5. Specify views 6. Record known inconsistencies among the views. 7. Create a rationale for the architecture.

Identify the Architectural Description The IEEE 1471 recommends that the architectural description the following as it relates to all of the architectural description products as a whole: Date of issue and status Issuing organization Change history Summary Scope Context Glossary References

Identify Stakeholders The architectural description serves as the medium for communicating design decisions among stakeholders through the actual models of the description. As a minimum the identified stakeholders must include: Users of the system Acquirers of the system Developers of the system Maintainers of the system

Identify Stakeholders (Cont’d) The minimum concerns identified should include the following: The purpose of the application The appropriateness of the application for use in fulfilling its purpose The feasibility of developing the application The risks of application development and operation to the stakeholders Maintainability, deployment, and evolvability of the application

Select Viewpoints A viewpoint is a specification for the techniques and models of constructing views, i.e., a metamodel. A view is a set of models and diagrams that conform to the viewpoint. Viewpoints specify the rules and practices for creating, representing, and analyzing views. A viewpoint specifies the modeling languages to be used for describing or representing a view. In the language of the IEEE 1471, and architectural description selects one or more viewpoints, which are used to create its views. This selection is based on the stakeholders.

Specify Viewpoints The IEEE standard recommends specifying the following for each viewpoint: The viewpoint name The stakeholders addressed by the viewpoint The concerns addressed by the viewpoint The methodology for constructing a view based on the viewpoint The source of a library viewpoint, if applicable

Viewpoint Rationale According to IEEE 1471 a rationale should be included for each viewpoint selected. It should explain the extent to which the concerns of stakeholders are covered. Quality attributes can be expressed as system concerns if they are defined explicitly. Viewpoints can then be selected to reason about the qualities.

Viewpoints and Systems Knowledge The lowest level of systems knowledge is the knowledge of which dimensions of a system we wish to observe. In systems design these dimensions can be equated with viewpoints specifically designed for organizing and expressing system requirements. The views created based on these viewpoints are referred to as analysis models and represent knowledge at the data level of systems knowledge. Viewpoints and views that represent the solution are at the generative level of system knowledge and are referred to as the design models.

Interdependence of Views No single view can capture or represent a system. All views must be considered together. They are interdependent and a change to one may require changes to others. Isolating certain system aspects can facilitate reasoning about those aspects. Each view should be highly coherent and they should be loosely coupled

Traceability This is the capability to semantically relate design elements or concepts across models and views. In UML a trace is a dependency relationship between two modeling elements in different models that represent the same element or concept by at different semantic levels within and across views. In small-scale design, traces are implicit and are usually inherent in the naming conventions of elements in models. For larger designs automated tools are needed to effectively handle traces.

Methodologies and Viewpoints Methodologies (like OMT) typically specify viewpoints along with the methods for generating the models that form the design views. OMT (Object Modeling Technique) specifies three viewpoints: object, dynamic, and functional. The object view specifies the static structure of the system using object diagrams. The dynamic view specifies the behavioral aspects of the system using event trace diagrams, event flow diagrams, and state diagrams. The functional view specifies the data transformations within the system using data flow diagrams.

Methodologies and Viewpoints (Cont’d) These views are orthogonal, yet interdependent. The object view is the fundamental view and the starting point of design activities. These three view are used for both analysis and design which yields a total of six different viewpoints. Other methodologies have similar concepts of multiple views of a system that represent the problem and solution expressed in modeling notations and specified in diagrams. They bring together many different views and methods for generating those views along with methods for maintaining consistency across views.

Specify Views The architectural description will have one view per selected viewpoint containing the actual models of the system. According to IEEE 1471 a view should include identification and introductory information, a representation of the system and configuration information. An effective architecture model is one that is necessary and sufficient.

Record View Inconsistencies Consistency is desirable in an architectural description but not always achievable. Inconsistencies among the views should be documented. For example, an element in one view may not have an obvious representation in another.

Create Architectural Rationale The IEEE 1471 states that an architectural description should include a rationale for selected architectural concepts. Additionally, the reasons for particular design choices should be described. The rationale should answer the questions that stakeholders may typically ask.

Applying the Architectural Description The amount of information necessary to create an IEEE 1471 compliant architectural description is significant. The goal is not to produce extensive documentation but to guide the development of an effective architectural specification. The IEEE 1471 practice is a pattern or heuristic approach to figuring out what you should actually write down. It takes good judgment on the part of the architect to achieve a balance between what to specify an how much to specify

Creating an Architectural Description for an Existing System As an architect you may need to develop an architectural description for a system already well into development or to modify an existing system. If an architectural description does not exist you may need to reverse-engineer the system. Although design decisions may not have been documented it is important to understand the rationale that was used to take the chosen path to design of the system.

Performing an Architectural Assessment An architectural assessment is important in determining the quality of the architecture. It can help predict the quality of the application that will be developed. If the architectural description is not easy to understand, or inconsistent, or incomplete then an assessment may be difficult.

Specific Pragmatics Implementing an architectural description is difficult because there are too many ways to do it. You should consider an approach that balances the management of information with other factors like readability and searchability. Use automated tools where possible, like bug tracking tools to manage view inconsistencies. The biggest hurdle in creating an architectural description is in getting the recessary people to read it.

Summary The architectural description is a tangible set of products that comprise the architectural models and the information necessary to understand the models. The IEEE 1471 recommended practice may be excessive if followed completely, but it provides a practical set of guidelines that can help the architect to focus on the important goals of producing an architectural description.