OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
OPEN Process Framework
Software Architecture Document
(SWAD)
Content and Format Standard
Version 1.0
Produced by:
Donald Firesmith
Public
 2000 by Donald Firesmith
Page 1
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
Revision History
Date
12/13/2000
Public
Version
1.0
Description
Initial Version
Author
Donald Firesmith
 2000 by Donald Firesmith
Page 2
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
Table of Contents
1
PREFACE TO THE STANDARD ............................................................................................ 4
1.1
1.2
1.3
2
OVERVIEW ............................................................................................................................... 4
DOCUMENT OBJECTIVES .......................................................................................................... 4
DOCUMENT AUDIENCE ............................................................................................................ 4
SWAD CONTENT AND FORMAT ......................................................................................... 5
2.1 TITLE PAGE .............................................................................................................................. 5
2.2 REVISION HISTORY .................................................................................................................. 5
2.3 TABLE OF CONTENTS ............................................................................................................... 5
2.4 TABLE OF FIGURES .................................................................................................................. 5
2.5 INTRODUCTION ........................................................................................................................ 5
2.5.1 Architecture Document Objectives.................................................................................... 5
2.5.2 Intended Audiences ........................................................................................................... 5
2.5.3 References ......................................................................................................................... 5
2.5.4 Architecture Document Overview ..................................................................................... 5
2.6 SOFTWARE ARCHITECTURE OVERVIEW .................................................................................. 5
2.7 MAJOR DRIVERS OF THE SOFTWARE ARCHITECTURE ............................................................. 6
2.7.1 Architecturally-Significant Operational Requirements..................................................... 6
2.7.2 Architecturally-Significant Quality Requirements ............................................................ 6
2.7.3 Architecturally-Significant Design Constraints ................................................................ 6
2.8 SOFTWARE COMPONENT ARCHITECTURE ............................................................................... 6
2.8.1 <Software Component Name> ......................................................................................... 6
2.8.1.1
Layers...................................................................................................................................................... 6
2.8.1.1.1 <Layer Name> ................................................................................................................................... 6
2.8.1.2
Packages.................................................................................................................................................. 6
2.8.1.2.1 <Package Name> ............................................................................................................................... 7
2.8.1.3
Frameworks............................................................................................................................................. 7
2.8.1.3.1 <Framework Name> .......................................................................................................................... 7
SOFTWARE CAPABILITY ARCHITECTURE ................................................................................ 7
2.9
2.9.1 Concurrency Architecture ................................................................................................. 7
2.9.2 Exception Architecture ...................................................................................................... 7
2.9.3 Persistence Architecture ................................................................................................... 8
2.9.4 Security Architecture ......................................................................................................... 8
2.9.5 Startup, Maintenance, and Shutdown ............................................................................... 8
2.10 REQUIREMENTS VERIFICATION ............................................................................................... 8
2.10.1 Operational Requirements ................................................................................................ 8
2.10.2 Quality Requirements ........................................................................................................ 8
2.10.3 Design Constraints ............................................................................................................ 8
2.11 APPENDICES ............................................................................................................................. 9
2.11.1 Open Issues ....................................................................................................................... 9
2.11.2 Major TBDs....................................................................................................................... 9
Public
 2000 by Donald Firesmith
Page 3
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
1 Preface to the Standard
1.1 Overview
This standard specifies the content and format of a formal Software Architecture Document (SWAD).
1.2 Document Objectives
The objectives of this document are:
 To document the required content and format for the SWAD.
 To improve the quality of the SWAD.
 To improve communication between the software architecture team and other project teams:
software requirements team, development team, independent test team, and management
team.
 To decrease the costs associated with the creation and maintenance of the SWAD.
 To be an incrementally developed standard that evolves as experience is gained in developing
and maintaining the SWAD.
1.3 Document Audience
The intended audience of this standard includes members of the following project teams:
 Requirements Team
 Architecture Team
 Development Team
 Independent Test Team
 Marketing Team
 Management Team
Public
 2000 by Donald Firesmith
Page 4
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
2 SWAD Content and Format
The following subsections of this standard document the required content and format of the Software
Architecture Document.
2.1 Title Page
The SWAD shall have a standard title page that identifies the customer, project, and the version
number, date, and status.
2.2 Revision History
The SWAD shall have a revision history table labeled “Revision History” that identifies each major
version, its date, its description, and author.
2.3 Table of Contents
The SWAD shall contain a table of contents labeled “Table of Contents” that includes the following
sections.
2.4 Table of Figures
The SWAD shall contain a table of contents labeled “Table of Figures” that lists each figure in the
SWAD.
2.5
Introduction
The SWAD shall contain a section labeled “1 Introduction” that introduces the SWAD to the reader
and that contains the following subsections:
2.5.1
Architecture Document Objectives
The “Introduction” section of the SWAD shall contain a subsection labeled “1.1 Architecture
Document Objectives” that documents the objectives of the SWAD.
2.5.2
Intended Audiences
The “Introduction” section of the SWAD shall contain a subsection labeled “1.2 Intended Audiences”
that documents the intended audiences (e.g., Requirements Team, Development Team, Testing Team)
of the SWAD.
2.5.3
References
The “Introduction” section of the SWAD shall contain a subsection labeled “1.3 References” that lists
all references.
2.5.4
Architecture Document Overview
The “Introduction” section of the SWAD shall contain a subsection labeled “1.4 Architecture
Document Overview” that describes both the organization of the SWAD and how to read it.
2.6
Software Architecture Overview
The SWAD shall contain a section labeled “2 Software Architecture Overview” that provides a high
level overview of the architecture of the software in terms of the software components, their
relationships, and their deployment.
Public
 2000 by Donald Firesmith
Page 5
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
2.7
Version: 1.0
Version Date: 12/13/2000
Major Drivers of the Software Architecture
The SWAD shall contain a section labeled “3 Major Drivers of the Software Architecture” that lists
the architecturally significant requirements and design constraints driving the software architecture.
2.7.1
Architecturally-Significant Operational Requirements
The “Major Drivers” section of the SWAD shall contain a subsection labeled “3.1 ArchitecturallySignificant Operational Requirements” that identifies the architecturally significant operational
requirements of the software.
2.7.2
Architecturally-Significant Quality Requirements
The “Major Drivers” section of the SWAD shall contain a subsection labeled “3.2 ArchitecturallySignificant Quality Requirements” that identifies the architecturally significant quality requirements
of the software.
2.7.3
Architecturally-Significant Design Constraints
The “Major Drivers” section of the SWAD shall contain a subsection labeled “3.1 ArchitecturallySignificant Design Constraints” that identifies the architecturally significant design constraints on the
software.
2.8
Software Component Architecture
The SWAD shall contain a section labeled “4 Software Component Architecture” that documents the
architecture of each software component.
2.8.1
<Software Component Name>
For each software component, the “Application Architecture” section of the SWAD shall contain a
subsection labeled “4.X <Software Component Name>” that documents the architectural decisions
regarding the component. Specifically, it will document the type of component, its abstraction, its
responsibilities, and its subcomponents (layers, packages, and frameworks.
2.8.1.1 Layers
If the software component contains multiple layers, the corresponding subsection of the SWAD shall
contain a subsection labeled “4.X.1 Layers” that documents these layers. A layer diagram may be
included.
2.8.1.1.1 <Layer Name>
Each “Layers” subsection of the SWAD shall contain a subsection labeled “4.X.1.Y <Layer Name>”
that documents the abstraction, responsibilities, relationships, interfaces, and strategic design
decisions regarding the layer.
2.8.1.2 Packages
If the software component contains multiple packages, the corresponding subsection of the SWAD
shall contain a subsection labeled “4.X.2 Packages” that documents these packages. A package
diagram may be included.
Public
 2000 by Donald Firesmith
Page 6
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
2.8.1.2.1 <Package Name>
Each “Packages” subsection of the SWAD shall contain a subsection labeled “4.X.2.Y <Package
Name>” that documents the abstraction, responsibilities, relationships, interfaces, and strategic design
decisions regarding the package.
2.8.1.3 Frameworks
If the software component contains multiple frameworks, the corresponding subsection of the SWAD
shall contain a subsection labeled “4.X.3 Frameworks” that documents these frameworks.
2.8.1.3.1 <Framework Name>
Each “Frameworks” subsection of the SWAD shall contain a subsection labeled “4.X.3.Y
<Framework Name>” that documents the abstraction, responsibilities, relationships, interfaces, and
strategic design decisions regarding the frameworks.
2.9
Software Capability Architecture
The SWAD shall contain a section labeled “5 Software Capability Architecture” that documents the
infrastructure architecture.
2.9.1
Concurrency Architecture
The “Infrastructure Architecture” section of the SWAD shall contain a subsection labeled “5.1
Concurrency Architecture” that documents the concurrency architecture of the software in terms of
the following topics (where appropriate):
 Processes
 Allocation of processes to hardware components
 Major threads of execution, including thread pools and maximum, average, and minimum
number of threads per process
 Allocation of threads to processes
 Process and thread scheduling (e.g., Rate monotonic scheduling)
 Identification of the classes that must be concurrent and/or thread safe
 Allocation of classes to threads
 Identification of process to process and thread to thread communication strategies:
 Handling information flow rate mismatches via queues, transporters, and pumps
 Sequential, synchronous (balking, and timed) , and asynchronous message passing
2.9.2
Exception Architecture
The “Infrastructure Architecture” section of the SWAD shall contain a subsection labeled “5.2
Exception Architecture” that documents the exception architecture of the software in terms of the
following topics (where appropriate):
 Assertions (e.g., ala. Design by Contract)
 Class hierarchies of exceptions
 Failover
 Persistence of error messages
Public
 2000 by Donald Firesmith
Page 7
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
2.9.3
Version: 1.0
Version Date: 12/13/2000
Persistence Architecture
The “Infrastructure Architecture” section of the SWAD shall contain a subsection labeled “5.3
Persistence Architecture” that documents the persistence architecture of the software in terms of files,
databases, and OO to relational mapping mechanisms (e.g., ODBC).
2.9.4
Security Architecture
The “Infrastructure Architecture” section of the SWAD shall contain a subsection labeled “5.4
Security Architecture” that documents the security architecture of the software in terms of the
following topics (where appropriate):
 User and data access
 Communications integrity
 Encryption/decryption
 Identification/authentication (e.g., via digital signatures), and authorization
2.9.5
Startup, Maintenance, and Shutdown
The “Infrastructure Architecture” section of the SWAD shall contain a subsection labeled “5.5
Startup, Maintenance, and Shutdown” that documents the architectural design decisions regarding
how the software shall handle:
 Startup
 Maintenance including support for upgrades while ensuring operational availability
 Shutdown.
2.10 Requirements Verification
The SWAD shall contain a section labeled “6 Requirements Verification” that documents how the
software architecture helps fulfill the architecturally significant requirements and design constraints.1
2.10.1 Operational Requirements
The “Requirements Verification” section of the SWAD shall contain a subsection labeled “6.1
Operational Requirements” that documents how the software architecture fulfills the architecturally
significant operational requirements.
2.10.2 Quality Requirements
The “Requirements Verification” section of the SWAD shall contain a subsection labeled “6.2
Quality Requirements” that documents how the software architecture fulfills the architecturally
significant quality requirements.
2.10.3 Design Constraints
The “Requirements Verification” section of the SWAD shall contain a subsection labeled “6.3 Design
Constraints” that documents how the software architecture fulfills the architecturally significant
software design constraints.
1 Do not redundantly repeat here the verification that is documented in the System Architecture Document.
This especially holds true for the verification of the quality requirements, which typically requires system
architecture, rather than software architecture, to implement. Only document software-specific architecture
verification here.
Public
 2000 by Donald Firesmith
Page 8
OPEN Consortium
Document ID: SWADS
Software Architecture Document (SWAD) Standard
Version: 1.0
Version Date: 12/13/2000
2.11 Appendices
The SWAD shall contain a section labeled “Appendices” that provides the following ancillary
information:
2.11.1 Open Issues
The appendices of the SWAD shall contain a subsection labeled “A. Open Issues” that lists the major
open issues in the SWAD to be resolved.
2.11.2 Major TBDs
The appendices of the SWAD shall contain a subsection labeled “B. Major TBDs” that lists the major
TBDs in the SWAD to be completed.
Public
 2000 by Donald Firesmith
Page 9