Software Architecture Document		 The Software Architecture Document provides a comprehensive architectural overview of the system, using a number of different architectural views to depict different aspects of the system.
Worker: Architect
Template: MS-Word™ template, SoDA™ Template

Purpose To top of page

There is one Software Architecture Document for the system. This document is particularly important to the following people:

  • It is the primary artifact created and maintained by the architect, and serves as a communication medium between the architect and other developers.
  • Designers for a reference when creating use-case realizations, or defining responsibilities, operations, and attributes on classes, and when adjusting classes to the implementation environment.
  • Implementers, as input when implementing classes.
  • Managers for input when planning iterations.

Brief Outline To top of page

Here is an example outline for a Software Architecture Document for a large, distributed, real-time system:

1. Objectives

A brief description of the purpose of the Software Architecture Document.

2. Scope

A brief description of what the Software Architecture Document applies to; what is affected or influenced by this document.

3. References

A list of related or referenced documents.

4. Architectural Representation

A description of what the software architecture is for the current system, and how it is represented.

5. Architectural Goals and Constraints

A description of the software requirements and objectives that have significant impact on the architecture.

6. Use-Case View

A description of the use-case view of the architecture.

7. Logical View

A description of the logical view of the architecture.

8. Process View

A description of the process view of the architecture.

9. Deployment View

A description of the deployment view of the architecture.

10. Implementation View

A description of the implementation view of the architecture.

11. Data View (optional)

A description of the persistent data storage perspective of the system. This section is optional if there is little or no persistent data, or the translation between the Design Model and the Data Model is trivial.

12. Size and Performance

A description of the major dimensioning characteristics of the software that impact the architecture, as well as the target performance constraints.

13. Quality

A description of how the software architecture contributes to all capabilities (other than functionality) of the system: extendability, reliability, portability, and so on.

Timing To top of page

The representation and objectives of the software architecture is usually something that must be defined before the very first iterations, and then be maintained throughout the project. These architectural representation guidelines are documented in initial versions of the Software Architecture Document.

The Software Architecture Document is primarily developed during the elaboration phase, because one of the purposes of this phase is to establish a sound architectural foundation.

The use-case view within the document is likely to be considered before the other views, because the use cases drive the development and are an essential input to iteration planning. For systems with a large degree of concurrency and distribution, the process and deployment views are also likely to be considered early, because they then might have substantial impact on the entire system.

Responsibility To top of page

An architect is responsible for producing the Software Architecture Document, which captures the most important design decisions in multiple architectural views.

The architect establishes the overall structure for each architectural view: the decomposition of the view, the grouping of elements, and the interfaces between these major groupings. Thus, in contrast with the other workers, the architect's view is one of breadth, as opposed to depth.

The architect is also responsible for maintaining the architectural integrity of the system through the development process by:

  • Approving all changes to architecturally significant elements, such as major interfaces, described in the Software Architecture Document.
  • Being part of the "change-control board" decisions to resolve problems that impact the software architecture.

Tailoring To top of page

You should adjust the outline of the Software Architecture Document to suit the nature of your software:

  • Some of the architectural views may be irrelevant:
    • The Deployment View is not needed for single-CPU systems
    • The Process View is not needed if the system uses only a single thread of control
    • The Data View is not needed unless object persistence is a significant aspect of the system AND the persistence mechanism requires a mapping between persistent and non-persistent objects.
  • Some specific aspects of the software may require their own section, for example aspects related to data management or usability issues.
  • You may need additional appendices to explain certain aspects, such as the rationale of certain critical choices together with the solutions that have been eliminated, or to define acronyms or abbreviations or present general design principles.
  • The order of the various sections may vary, depending on the system's stakeholders and their focus or interest.

The advantages and disadvantages of each architectural view follow:

Use-Case View

  • Is important input to the selection of the set of scenarios and/or use cases that are the focus of an iteration.
  • Describes the set of scenarios and/or use cases that represent some significant, central functionality.
  • Describes the set of scenarios and/or use cases that have a substantial architectural coverage (that exercise many architectural elements) or that stress or illustrate a specific, delicate point of the architecture.
  • This view is mandatory.

Logical View

  • Describes the most important classes, their organization in packages and subsystems, and the organization of these packages and subsystems into layers.
  • Describes the most important use-case realizations, for example, the dynamic aspects of the architecture.
  • This view is mandatory.

Process View

  • Describes the tasks (processes and threads) involved in the system's execution, their interactions and configurations.
  • Describes the allocation of objects and classes to tasks.
  • More notational concepts for the developers to learn.
  • This view is optional. Use this view only if the system has more than one thread of control, and the separate threads interact or are dependent upon one another.

Deployment View

  • Describes the various physical nodes for the most typical platform configurations.
  • Describes the allocation of tasks (from the Process View) to the physical nodes.
  • More notational concepts for the developers to learn.
  • This view is optional. Use this view only if the system is distributed across more than one node.  Even in these cases, only use the deployment view where the distribution has architectural implications. For example, in cases where there is a single server and many clients, a deployment view only needed to delineate the responsibilities of the server and the clients as a class of nodes; there is no need to show every client node if they all have the same capabilities.

Implementation View

  • Describes an overview of the implementation model and its organization in terms of the components in implementation subsystems and layers.
  • Describes the allocation of packages and classes (from the Logical View) to the implementation subsystems and components of the Implementation View.
  • This view is optional. Use this view only in cases where the implementation is not strictly driven from the design, i.e. where there is a different distribution of responsibilities between corresponding packages in the Design and Implementation models. If the packaging of the design and implementation models are identical, this view can be omitted.

Data View

  • Describes an overview of the data model and its organization in terms of the tables, views, indexes, triggers and stored procedures used to provide persistence to the system.
  • Describes the mapping of persistent classes (from the Logical View) to the data structure of the database.
  • This view is optional. Use this view only if persistence is a significant aspect of the system. and the translation from the Design Model to the Data Model is not done automatically by the persistence mechanism.

Annotated Outline  To top of page

  1. Brief Description

    Defines the role or purpose of the Software Architecture Document, in the overall project documentation, and briefly describes the structure of the document.  The specific audiences for the document should be identified, with an indication of how they are expected to use the document.

  2. References

    Lists documents that are related or referenced to or from the Software Architecture Document. If there are a larger number of references, structure the section in subsections:

    1. external documents
    2. internal documents
    3. government documents
    4. non-government documents
    5. etc.
  3. Architectural Representation

    This section describes what software architecture is for the current system, and how it is represented. Of the Use-Case, Logical, Process, Deployment, and Implementation Views, it enumerates the views that are necessary, and for each view, explains what types of model elements it contains.

  4. Architectural Goals and Constraints

    This section describes the software requirements and objectives that have some significant impact on the architecture: use of an off-the-shelf product, portability, distribution, and reuse. It also captures the special constraints that may apply: design and implementation strategy, development tools, team structure, schedule, legacy code, and so on.

  5. Use-Case View

    This section lists use cases or scenarios from the use-case model if they represent some significant, central functionality of the final system, or if they have a large architectural coverage - they exercise many architectural elements, or if they stress or illustrate a specific, delicate point of the architecture.

    You should list the use cases by package, if they are packaged, and briefly describe each package.

    For each significant use case, include a subsection with the following information:

    1. The name of the use case.
    2. A brief description of the use case.
    3. Significant descriptions of the Flow of Events of the use case. This can be the whole Flow of Events description, or subsections of it that describe significant flows or scenarios of the use case.
    4. Significant descriptions of relationships involving the use case, such as include- and extend-relationships, or communicates-associations.
    5. An enumeration of the significant use-case diagrams related to the use case.
    6. Significant descriptions of Special Requirements of the use case. This can be the whole Special Requirements description, or subsections of it that describe significant requirements.
    7. Significant Pictures of the User Interface, clarifying the use case.
    8. The realizations of these use cases should be found in the logical view.
  6. Logical View

    This section describes the architecturally significant parts of the design model, such as its decomposition into subsystems and packages. And for each significant package, its decomposition into classes and class utilities. You should introduce architecturally significant classes and describe their responsibilities, as well as a few very important relationships, operations, and attributes. This section has three subsections:

    1. Overview

      This subsection describes the overall decomposition of the design model in terms of its package hierarchy and layers. If the system has several levels of packages, you should first describe those that are significant at the top level. Include any diagrams showing significant top-level packages, as well as their interdependencies and layering. Next present any significant packages within these, and so on all the way down to the significant packages at the bottom of the hierarchy.

    2. Architecturally Significant Design Packages

      For each significant package, include a subsection with the following information

      1. Its name.
      2. A brief description.
      3. A diagram with all significant classes and packages contained within the package. For a better understanding this diagram may show some classes from other packages if necessary.
      4. For each significant class in the package, include its name, brief description, and, optionally a description of some of its major responsibilities, operations and attributes. Also describe its important relationships if necessary to understand the included diagrams.
    3. Use-Case Realizations

      This section illustrates how the software works by giving a few selected use-case (or scenario) realizations, and explains how the various design model elements contribute to their functionality. The realizations given here are chosen because they represent some significant, central functionality of the final system; or for their architectural coverage - they exercise many architectural elements - or stress or illustrate a specific, delicate point of the architecture. The corresponding use cases and scenarios of these realizations should be found in the use-case view.

      For each significant use-case realization, include a subsection with the following information

      1. The name of the realized use case.
      2. A brief description of the realized use case.
      3. Significant descriptions of the Flow of Events - Design of the use-case realization. This can be the whole Flow of Events - Design description, or subsections of it that describe the realization of significant flows or scenarios of the use case.
      4. An enumeration of the significant interaction or class diagrams related to the use-case realization.
      5. Significant descriptions of Derived Requirements of the use-case realization. This can be the whole Derived Requirements description, or subsections of it that describe significant requirements.
  7. Process View

    This section describes the system's decomposition into lightweight processes (single threads of control) and heavyweight processes (groupings of lightweight processes). Organize the section by groups of processes that communicate or interact. Describe the main modes of communication between processes, such as message passing, interrupts, and rendezvous.

    For each network of processes, include a subsection with the following information:

    1. Its name.
    2. The processes involved.
    3. The interactions between processes in the form of collaboration diagrams, in which the objects are actual processes that encompass their own threads of control. For each process, briefly describe its behavior, lifetime and communication characteristics.
  8. Deployment View

    This section describes one or more physical network (hardware) configurations on which the software is deployed and run. At a minimum for each configuration it should indicate the physical nodes (computers, CPUs) that execute the software, and their interconnections (bus, LAN, point-to-point, and so on.) Also include a mapping of the processes of the Process View onto the physical nodes.

    For each physical network configuration, include a subsection with the following information:

    1. Its name.
    2. A deployment diagram illustrating the configuration, followed by a mapping of processes to each processor.
    3. If there are many possible physical configurations, just describe a typical one and then explain the general mapping rules to follow in defining others. You should also include, in most cases, descriptions of network configurations for performing software tests and simulations.
  9. Implementation View

    This section describes the decomposition of the software into layers and subsystems in the implementation model. It contains two subsections:

    1. Overview

      This subsection names and defines the various layers and their contents, the rules that govern the inclusion to a given layer, and the boundaries between layers. Include a component diagram that shows the relations between layers.

    2. Layers

      For each layer, include a subsection with the following information:

      1. Its name.
      2. An enumeration of the subsystems located in the layer. For each subsystem, give its name, abbreviation or nickname, and a brief description.
      3. A component diagram shows the subsystems and their import dependencies.
      4. If appropriate, indicate its relationship to elements in the logical or process view.
  10. Data View (optional)

    This section describes the architecturally significant parts of the data model:

    • The mapping from key persistent design classes, especially where the mapping is non-trivial.
    • The architecturally significant parts of the system which have been implemented in the database, in the form of stored procedures and triggers.
    • Important decisions in other views which have data implications, such as choice of transaction strategy, distribution, concurrency, fault tolerance. For example, the choice to use database-based transaction management (relying on the database to commit or abort transactions) requires that the error handling mechanism used in the architecture include a strategy for recovering from a failed transaction by refreshing the state of persistence objects cached in memory in the application.

    You should present architecturally significant data model elements, describe their responsibilities, as well as a few very important relationships and behaviors (triggers, stored procedures, etc.).

  11. Size and Performance

    In this section, list the critical size and performance dimensions of the project that shape the architecture. The information presented may include:

    • The number of key elements the system will have to handle (such as the number of concurrent flights for an air traffic control system, the number of concurrent phone calls for a telecom switch, the number of concurrent online users for an airline reservation system, etc.).
    • The key performance measures of the system, such as average response time for key events;  average, maximum and minimum throughput rates,  etc.
    • The footprint (in terms of disk and memory) of the executables - essential if the system is an embedded system which must live within extremely confining constraints.

    Most of these qualities are captured as requirements; they are presented here because they shape the architecture in significant ways and warrant special focus. For each requirement, discuss how the architecture supports this requirement.

  12. Quality

    In this section, list the key quality dimensions of the system that shape the architecture. The information presented may include:

    • Operating performance requirements, such as mean-time between failure (MTBF).
    • Quality targets, such as "no unscheduled down-time"
    • Extensibility targets, such as "the software will be upgradeable while the system is running".
    • Portability targets, such as hardware platforms, operating systems, languages.

    For each dimension, discuss how the architecture supports this requirement. You can organize the section by the different views (logical, implementation, and so on), or by quality.

 

Display Rational Unified Process using frames

 

© Rational Software Corporation 1998 Rational Unified Process 5.1 (build 43)