Software Architecture Document

Definitions

Software Architecture Document (SWAD)

the architecture work product that formally documents the software architecture(s) of an application or one or more related software components

Objectives

The typical objectives of a software architecture document are to formally document the software architecture including the:

• Architectural Styles (Patterns)
• Architectural Views of the Software Architecture including:
  • Logical Views.
  • Source Code Views.
  • Runtime Views.
• Mechanisms of the software architecture.
• How the software architecture fulfills the architecturally significant requirements.

Benefits

The typical benefits of the software architecture document are:

• Improve communication among developers, configuration management, and integration testers by providing a big picture overview of the software structure.
• Improve extensibility by providing a flexible foundation on which to extend the software as requirements change.

Contents

The typical contents of the SWAD include:

• Software Architecture Overview:
  • Scope
  • Description (in terms of style and patterns)
• Logical Views:
  • Logical elements (e.g., layers, types, major functions), their responsibilities, and their logical interfaces.
  • Logical relationships (e.g., generalization, depends-on, aggregation, collection, membership, dataflow, control flow).
  • Deployment of logical elements to hardware components.
  • For example, this might include the following diagrams:
    • Logical Architecture Diagram.
    • Layer Diagram.
    • Class Diagram.
    • Deployment Diagram.
• Source Code Views:
  • Source code elements (e.g., classes, procedures), their responsibilities, and their physical interfaces.
  • Code-level relationships (e.g., procedure calls, method invocation, inheritance) and their responsibilities.
  • Allocation of source code elements to file structures.
  • Deployment of source code elements to hardware components.
  • For example, this might include the following diagrams:
    • Class Diagram.
    • Deployment Diagram.
• Runtime Views:
  • Runtime elements (e.g., processes, threads, objects, and agents).
  • Runtime relationships (e.g., communication links and protocols, data flows, and shared storage).
  • Deployment of runtime elements to hardware components.
  • For example, this might include the following diagrams:
    • Collaboration Diagram.
    • Activity Diagram.
    • State Transition Diagram.
    • Migration Diagram.
• Policies and Mechanisms (dealing with major architectural drivers and their validation):
  • General Policies and Mechanisms:
    
    • Startup and Shutdown.
    • Component Integration.
    • Persistence.
    • Concurrency.
    • Distribution.
    • Searching, Indexing, and Categorization.
    • System management and monitoring.
  • Policies and Mechanisms for Quality Requirements.
    
    • Developer-Oriented Quality Mechanisms (extensibility, portability, reusability, etc.)
    • User-Oriented Quality Mechanisms (robustness, scalability, operational availability, interoperability, performance, personalization, safety, security, etc.) with associated diagrams:
      • Operational Availability Architecture Diagram.
      • Scalability Architecture Diagram.
      • Security Architecture Diagram.
• Technology and Vendor Selections:
  • Communication APIs (e.g., CORBA, EJB, DCOM, TCP/IP, and WAP)
  • Databases (e.g., Relational, Extended Relational, Object, XML, IMS, and VSAM)
  • Internal Applications (e.g., eCommerce, security, application monitoring)
  • Languages (e.g., Java, C++, HTML, CSS, JavaScript, and WML)
  • Messaging (e.g., EDI, XML)
• Appendices:
  • Major Drivers of the Software Architecture
  • Requirements Trace
  • Major Unresolved Issues
  • TBDs
  • Assumptions

Stakeholders

The typical stakeholders of the SWAD are:

• Producer:
  • Architecture Team
• Evaluator:
  • Architecture Inspection Team
• Approvers:
  • Technical Leader
  • Project Manager
  • CustomerRepresentative
• Maintainer:
  • Architecture Team
• Users:
  • The customer organization uses the SWAD to understand the scope and structure of what is to be delivered.
  • The integration team uses the SWAD to plan integration and to generate integration tests.
  • The project management team uses the SWAD to manage project scope and to staff and schedule project activities.
  • The software development team uses the SWSAD to drive the design and implementation of the software.

Phases

The SWAD is typically incrementally and iteratively developed and maintained as follows:

• Initiation: Completed.
• Construction: Updated.
• Delivery: Maintained
• Usage: Maintained
• Retirement: Archived

Preconditions

The SWAD can be started if the following preconditions hold:

• A complete version of the application vision statement is available.
• All architecturally significant operational and quality requirements have been specified in the system requirements specification.
• The glossary exists.
• The software components have been identified in the system architecture document.
• Domain experts in the relevant packages are available.

Inputs

The typical inputs to the SWAD include:

• Work Products:
  • Application Vision Statement
  • System Requirements Specification
  • Glossary
  • System Architecture Document
• Stakeholders:
  • Development organization domain experts
  • Package Vendors

Guidelines

• This is a living document that is developed incrementally and iteratively in parallel with other work products (e.g., database design document).
• Different parts of this document are due at different times (i.e., during different phases).
• Some parts of this document are mandatory (mechanisms) and some parts are optional (requirements validation).
• Do not repeat anything that is in the system architecture document.

Conventions

• Work Flow
• Content and Format Standard
• MS Word Template
• XML Template
• Inspection Checklist

Examples

• Example Software Architecture Document