System Architecture Document

Definitions

System Architecture Document
(a.k.a., System Architecture Specification)

the architecture document that formally documents the architecture of a system

Classification

As illustrated in the preceding figure, System Architecture Document is part of the following inheritance hierarchy:

• Type: Concrete
• Superclass: Document
• Subclasses:
  • None

Responsibilities

The typical responsibilities of a System Architecture Document are to:

• Formally document the system architecture including:
  • An overview of the system including its architectural drivers (e.g., quality requirements)
  • An overview of the overall architecture of the system
  • Relevant views of the system’s architecture
  • How the system architecture will support the achievement of the architectural drivers
  • Ancillary information about the system architecture
• Improve stakeholder understanding of (and communication concerning) the most important, pervasive, top-level, strategic decisions and inventions concerning:
  • The overall system structure in terms of its major component elements and their relationships.
  • How these architectural elements will collaborate to provide the required characteristics and behavior (i.e., fulfill the architecturally-significant requirements and constraints).
• Provide a foundation upon which to:
  • Base the design, implementation, integration testing, deployment, and maintenance of the system.
  • Estimate the system’s size, cost, and schedule.
  • Develop work assignments and subcontracts during the acquisition and development of the system.
• Support the analysis and verification of the system architecture.
• Support reuse of the architecture on other systems.
• Improve extensibility by providing a flexible foundation on which to extend the system as requirements change.
• Minimize the risk that necessary architectural decisions and inventions are either not made or made incorrectly.
• Ensure that the rationales (e.g., engineering tradeoffs) for architectural decisions are not lost, and therefore it lowers the risk that rejected architectural decisions will one day be revisited and selected after the original architects are gone.
• Provide an intermediate architectual viewpoint between that of the higher-level abstract architectures of operational units (e.g., DODAF operational views) and lower-level more-detailed architectures (e.g., views of CSCI or CSC software architecture)

Contents

The typical contents of a System Architecture Document vary based on the architect’s choice of architectural views and perspectives to be included:

• System Overview:
  A high-level description of the system including the:
  • System Background
  • System Purpose
  • System Context and Scope
  • System Functionality
  • Critical Architectural Drivers
    (e.g., important quality attributes, engineering and programmatic constraints)
  • System Type
    (i.e., system of systems, system of subsystems, family of systems)
  • Whether the system is:
    • New (i.e., ‘green-field’ development)
    • A replacement for an existing system
    • An upgrade of an existing system
• System Architecture Overview:
  A high-level description of the system architecture including the:
  • System Composition
    Configuration views providing an overview of the major top-level components of the system and their relationships
  • System Functions
    Function views providing an overview of the major top-level functions of the system and their relationships
  • System Modes
    Major system modes and states of operation including both normal and abnormal (e.g., error) modes
  • Sources of System Components
    Whether the system is being developed from scratch or being composed of reused components such as:
    • Legacy components
    • Commercial-Off-The-Shelf (COTS) components
    • Government-Off-The-Shelf (GOTS) components,
    • Government-Furnished-Equipment (GFE)
    • OPEN Source Software (OSS)
    • Or some combination
• Architecture of Tier X:
  Starting with the top tier and working hierarchially downwards, these sections (one per tier) document the architecture of a tier in the configuration architecture in terms of its components and associated views:
  • Overview of Tier X
  • Configuration View of Tier X
    showing the major components of tier X
  • Functional View of Tier X
    showing the major functions implemented by tier X
  • Component Y:
    These subsections document the architecture of individual components of a tier (i.e., component Y of tier X) in terms of its relevant views.
    • Overview of Component Y
    • Views
      These subsubsections document the different views comprising the architecture of an individual component at an individual tier. (See subsections below for descriptions of the different kinds of views that can be included here.)
    • Perspectives
      These subsubsections document the different perspectives of the views comprising the architecture of an individual component at an individual tier. (See subsections below for descriptions of the different kinds of perspectives that can be included here.)
• Technology and Vendor Selections:
  • Communication APIs
    (e.g., CORBA, EJB, DCOM, TCP/IP, WAP)
  • Databases
    (e.g., Relational, Extended Relational, Object, XML, IMS, VSAM)
  • Internal Applications
    (e.g., eCommerce, security, application monitoring)
  • Languages
    (e.g., Java, C++, HTML, CSS, JavaScript, WML)
  • Messaging
    (e.g., EDI, XML)
  • Tools
    (e.g., architectural modeling tools, simulation tools, architecture description languages)
• General Mechanisms:
  • System startup and shutdown
  • Component integration
  • Concurrency
  • Distribution
  • System management and monitoring
• Support for Architectural Drivers
  Summary of compelling evidence of how the elements of the architectural collaborate to support the architecturally-significant:
  • Functional Requirements (e.g., via use cases, use case paths, or scenarios)
  • Data Requirements
  • Interface Requirements
  • Quality Requirements (e.g., architectural part of safety case)
  • Constraints
  • Programmatic Drivers:
    • Costs (e.g., development, operations, and retirement)
    • Schedule
    • Resource Availability
• Appendices:
  • Index
  • Requirements Trace
  • Major Open Issues
  • TBDs
  • Assumptions

The architecture of system is too large and complex to be understood in terms of a single view point. Instead, the architecture of the system is primarily documented in terms of a set of architectural views, whereby these views can be hierarchically organized by tier and component. For more information on the contents of the individual types of views, see the following subsections:

• Summary Views:
  • Configuration Views
  • Function Views
  • Interface Views:
    • Programmatic Interface Views
    • User Interface Views
  • State Views
• Element Type Views:
  • Data Views
  • Hardware Views
  • Personnel View
  • Software Views
• Discipline-Specific Perspectives:
  • Content Management Perspectives
  • Safety Perspectives
  • Security Perspectives

Summary Views

Summary views of the architecture or parts of the architecture summarize aspects of the overall architecture. Summary views include:

• Configuration Views
• Function Views
• Interface Views:
  • Programmatic Interface Views
  • User Interface Views
• State Views

Configuration Views

The configuration views of the architecture or parts of the architecture can be documented as follows:

• Overview,
  which provides an introduction to the hierarchical configuration of the tier or component in terms of its lower-level tiers and components
• View Diagrams,
  which show the hierarchial configuration of the tier or component in terms of its lower-level tiers and components and the relationships (e.g. hierarchical decomposition, data flow, control flow, interaction sequencing) between them:
  • Configuration Diagram,
    which shows the hierarchical decomposition structure of the tier or component
  • Data Flow Diagram,
    which shows the flow of data between elements in the configuration
  • Sequence Diagram,
    which shows the sequential communication between elements in the configuration
• Element Catalog,
  which lists and describes the relevant architectural elements:
  • Components in terms of their externally-visible characteristics, behavior, and component type: systems, subsystems, segment, subsegment, assembly, subassembly, data, hardware, personnel, software, procedures, materials, and facilities (whereby hardware includes computer hardware, network hardware, devices such as sensors and actuators, equipment, structural elements, etc.)
  • Relationships between components including decomposition, data flow, and communication
• View Context,
  which shows how the components of the configuration interface with externals
• Variability Guide,
  which documents how the hierarchical decomposition structure of the tier or component provides any necessary variability (e.g., when the architecture is used to support multiple systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the hierarchical decomposition structure was selected (e.g., functional decomposition of the configuration with “form following function”). This section briefly lists the relevant architectural drivers and provides compelling evidence that the configuration architecture fullfils them
• Alternatives Considered and Rejected,
  which briefly describes alternative hierarchical decomposition structures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the hierarchical decomposition structure was based

Function Views

The functional architecture of the system is the structure of the system’s functions and their subfunctions and how they are related. The functional architecture defines the execution sequencing of the functions, the conditions for control or data flow between the functions, and the performance characteristics of the functions that are needed to satisfy the system requirements, especially the functional requirements.

The function view of the architecture (i.e., the functional architecture) of a tier or component can be documented as follows:

• Overview,
  which provides an introduction to the functional architecture of the system in terms of its major functions and how they collaborate to fulfill the functional requirements
• View Diagrams,
  which show the functional architecture of the tier or component in terms of its major functions and the relationships (e.g. functional decomposition, data flow, control flow) between them:
  • Activity Hierarchy Diagram,
    which shows the functional decomposition of the functions
  • Functional Flow Diagram (a.k.a., process flow diagram),
    which shows the sequencing of function execution
  • Data Flow Diagram,
    which shows the flow of data among functions
  • Control Flow Diagram,
    which shows the flow of control among functions
  • Sequence Diagram,
    which shows the sequential communication between functions
• Element Catalog,
  which lists and describes the functions in terms of their externally-visible characteristics and behavior and which clarifies the relationships between the functions.
• View Context,
  which shows how the functions interface with externals and other components
• Variability Guide,
  which documents how the functions provide any necessary variability (e.g., when the architecture is used to support multiple systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the functional decomposition was selected. This section briefly lists the relevant architectural drivers and provides compelling evidence that the functional architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative functional decompositions that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the functional decomposition was based

Interface Views

The interface views of the architecture of a tier or component may include the:

• Programmatic Interface Views
• User Interface Views

Programmatic Interface Views

The programmatic interface views of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the interface architecture of the tier or component in terms of its programmatic interfaces, their characteristics, and how they are connected
• View Diagrams,
  which show the elements of the tier or component, their programmatic interfaces, and the relationships (e.g., communication paths, communication methods, and data flows) between them:
  • Interface Diagrams,
    which shows the programmatic interfaces and how they are connected
  • Systems Interface Description,
    which shows the system components and the communication paths connecting interfaces between them
  • Systems Communications Description,
    which shows the system components and the communication mechanisms connecting interfaces between them
• Element Catalog,
  which lists and describes the individual programmatic interfaces in terms of their interface specifications:
  • Definition
  • Interface Direction
    (i.e., inbound, outbound, or bidirectional)
  • Service Requests:
    • Syntax (a.k.a., Signature):
      • Parameters with type and direction
      • Return type
    • Semantics:
      • Meaning
      • Protocol in terms of:
        • Assertion (e.g., preconditions, postconditions, invariants)
        • State models
        • Concurrency semantics:
          • Sequential vs. Concurrent
          • Synchronous (e.g., Ada rendezvous) vs. Asynchronous
          • Need for Reservation of Resources
          • Critical Regions
  • Exceptions Raised:
    • Syntax
    • Semantics
  • Interface-specific data with data types (or object with classes)
  • Quality Attributes
    (e.g., performance, security, safety, and reliability)
• View Context,
  which shows how the programmatic interfaces are used by and use other elements of the architecture
• Variability Guide,
  which documents how the programmatic interfaces provide any necessary variability (e.g., when the programmatic interfaces are used to support internationalization and personalization)
• Analysis and Rationale,
  which documents the reasons why the programmatic interfaces were selected and have the properties that they do. This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative programmatic interfaces that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the programmatic interfaces were based

User Interface Views

The user interface views of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the user interface architecture of the tier or component in terms of the individual user interface modules
• View Diagrams,
  which show the user interface architecture of the tier or component in terms of the major user interface units and the relationships (e.g., data content, navigability) between them:
  • Summary Site Map,
    which lists the individual user interfaces in some reasonable organization
  • User Interface Architecture Diagram,
    which shows the static and dynamic allocation of content to units of the user interfaces
  • Navigation Diagram,
    which shows how users can effectively navigate between and within the individual user interfaces
• Element Catalog,
  which lists and describes the user interfaces (e.g., screens, webpages of a website), any organizational, visual, and functional metaphors used, the allocation of content (data) to the user interfaces, and the navigation linkages between and within the user interfaces This section may also document any standard user interface (e.g.webpage) conventions:
  • Cascading Style Sheets
  • Standard webpage layout grid(s)
  • Implementing frames or tables
• View Context,
  which shows how the user interfaces are used by and use other elements of the architecture
• Variability Guide,
  which documents how the user interfaces provide any necessary variability (e.g., when the user interfaces are used to support internationalization and personalization)
• Analysis and Rationale,
  which documents the analysis techniques used (e.g., usability analysis, user-experience, or task analysis), the reasons why the user interfaces were selected, and the reasons why they have the properties that they do. This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative user interfaces that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the user interfaces were based (e.g., existence of access control, technology used, user profiles, etc.)

State Views:

The state view of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the state models of the architectural elements of a tier or component
• View Diagrams,
  which show the states and the relationships (e.g., transition) between them:
  • State Transition Diagram,
    which shows the states and the relationships (e.g., transition) between them
• Element Catalog,
  which documents the components of the state models (e.g., states, transistions, guards)
• View Context,
  which shows how the state models interact with the state models of other system components and externals of the system
• Variability Guide,
  which documents any variability in the state models (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the state models was selected This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative state models that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the state models were based

Element Type Views

Summary views of the architecture or parts of the architecture summarize aspects of the overall architecture. Summary views include:

• Data Views
• Hardware Views
• Personnel View
• Software Views

Data Views

The data view of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an introduction to the data architecture of the system in terms of its relevant components and how they collaborate to provide persistence
• View Diagrams,
  which show the data architecture of the system:
  • Data Architecture Diagram,
    which shows the system elements that handle persistence and their relationships
  • Entity Relationship Diagram,
    which shows the logical database schema of relational databases
  • Class Diagram Diagram,
    which shows the logical database schema of object databases
• Element Catalog,
  which lists and describes the architectural elements providing persistence in terms of their externally-visible characteristics and behavior. These elements can be: databases, files, database wrappers, stored procedures, etc. For each database, document its name, responsibilities, types (e.g., relational, object, or XML), logical database schemas, vendors, and allocation to hardware. For each file, document its name, responsibilities, types, and allocation to hardware. Describe mechanisms for searching, indexing, and categorization.
• View Context,
  which shows how components supporting persistence interface with other components
• Variability Guide,
  which documents how the data architecture provides any necessary variability (e.g., when the architecture is used to support multiple systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the data architecture was selected (e.g., reason for choice of type of database). This section briefly lists the relevant architectural drivers and provides compelling evidence that the data architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative data architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the data architecture was based

Hardware (a.k.a., Network) Views

The hardware views of a tier or component can be documented as follows:

• Overview,
  which provides an introduction to the hardware and network architecture of the tier or component in terms of its major hardware components and how they are networked together. The overview also summarizes how the hardware components are connected in terms of:
  • Network types (e.g., WAN, MAN, LAN, PAN, intranet, extranet, Internet)
  • Networking models (e.g., peer-to-peer, server-based)
  • Organizational models (e.g., centralized, distributed, collaborative)
  • Logical and physical topologies (e.g., bus, star, ring, peer-to-peer, or mesh/grid)
• View Diagrams,
  which show the hardware architecture of the tier or component in terms of the major hardware components and the relationships (e.g., decomposition, dependency, and network connectivity) between them:
  • Hardware Architecture Diagram
  • Tier Diagram
• Element Catalog,
  which lists and describes the hardware elements (e.g., hardware configuration items, components, and parts) in terms of their externally-visible characteristics and behavior.
  • Hardware Components:
    For each type of hardware component (e.g., clients, servers, mass storage devices, network connection devices, sensors, actuators, equipment, structural elements, etc.), provide definitions, responsibilities, numbers, characteristics, models, processors, RAM, hard drives, models, and vendors.
  • Connections between Hardware Components:
    For each connection between hardware devices (especially over a network), document the technology used:
    • Transmission Media
      (e.g., shielded or unshielded twisted-pair cable, Thinnet or Thicknet coaxial cable, fiber-optic cable, telephone, microwave, radio, infrared, or laser)
    • Communications and hardware technology
      (e.g., Ethernet, TokenRing)
    • Networking protocols
      (e.g., TCP/IP, NFS, IPX, DLC, SMB, AppleTalk, etc.)
    • Network connection devices
      (e.g., repeaters, bridges, routers, brouters, gateways, switches, accellerators, firewalls, etc.)
• View Context,
  which shows how the relevant hardware components interface with other components
• Variability Guide,
  which documents how the hardware architecture provides any necessary variability (e.g., when the hardware architecture is used to support multiple systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the hardware architecture was selected This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative hardware architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the hardware architecture was based

Personnel View:

The personnel architecture view of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the human components of the tier or component
• View Diagrams,
  which show the organizations and the relationships (e.g., direction, coordination, collaboration) between them:
  • Organization Chart,
    which shows the relevant human components of the tier or component and how they are related to each other
  • Personnel Diagram
    which shows the relevant human components of the tier or component and how they relate to other architectural components
• Element Catalog,
  which documents the component organizations, teams, and roles, their definitions, responsibilities, tasks, etc.
• View Context,
  which shows how the roles, teams, and organizations interface with other system components and externals of the system
• Variability Guide,
  which documents any variability in the organization chart (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the organizational structure was selected This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative organizational structures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the organizational structure was based

Software Views

The software views of the architecture of a tier or component may include the:

• Logical Views
• Source Code Views
• Runtime Views

Logical Views

The logical software views of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the logical software components of the tier or component
• View Diagrams,
  which show the logical software components and the relationships between them:
  • Layer Diagram
  • Class Diagram
• Element Catalog,
  which documents the:
  • Logical Elements:
    (e.g., layers and types), their responsibilities, and their logical interfaces
  • Logical Relationships:
    (e.g., generalization, depends-on, may depend on, aggregation, collection, membership, dataflow, or control flow)
• View Context,
  which shows how the relevant logical elements interface with other system components and externals of the system
• Variability Guide,
  which documents any variability in the logical software architecture (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the logical software architecture was selected. This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative logical software architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the logical software architecture was based

Source Code Views

The source code software views of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the source code software elements of the tier or component
• View Diagrams,
  which show the source code software elements and the relationships between them:
  • Class Diagram
  • Deployment Diagram
• Element Catalog,
  which documents the:
  • Source code elements
    (e.g., classes, procedures, agents, aspects), their responsibilities, and their physical interfaces
  • Code-level relationships
    (e.g., procedure calls, method invocation, inheritance, pointer, reference, allocation of code to file structure)
• View Context,
  which shows how the relevant source code elements interface with other system components and externals of the system
• Variability Guide,
  which documents any variability in the source code software architecture (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the source code software architecture was selected. This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative source code software architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the source code software architecture was based

Runtime Views

The runtime software views of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of the run time software elements of the tier or component
• View Diagrams,
  which show the runtime software components and the relationships between them:
  • Collaboration Diagram
  • Activity Diagram
  • State Transition Diagram
  • Migration Diagram
• Element Catalog,
  which documents the:
  • Runtime elements
    (e.g., processes, threads, and objects)
  • Runtime relationships
    (e.g., communication links and protocols, data flows, shared storage, static allocation to hardware, dynamic migration between hardware elements)
• View Context,
  which shows how the relevant run time elements interface with other system components and externals of the system
• Variability Guide,
  which documents any variability in the run time software architecture (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the run time software architecture was selected. This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative run time software architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the run time software architecture was based

Perspectives

Discipline-specific subsets of views that capture a perspective of the architecture or parts of the architecture by documenting those elements of the architecture that are relevent to the associated quality. Perspectives could include:

• Quality Requirement Perspectives:
  • Capacity Perspectives,
    which document how the system architecture meets its allocated capacity requirements
  • Extensibility Perspectives,
    which document how the system architecture meets its allocated extensibility requirements
  • Interoperability Perspectives,
    which document how the system architecture meets its allocated interoperability requirements
  • Operational Availability Perspectives,
    which document how the system architecture meets its allocated operational availability requirements
  • Performance Perspectives,
    which document how the system architecture meets its allocated performance requirements
  • Reliability Perspective,
    which document how the system architecture meets its allocated reliability requirements
  • Safety Perspectives,
    which document how the system architecture meets its allocated safety requirements
  • Scalability Perspective,
    which document how the system architecture meets its allocated scalability requirements
  • Security Perspective,
    which document how the system architecture meets its allocated security requirements
• Other Perspectives:
  • Content Management Perspectives
  • Operations Perspectives,
    which document how the system architecture supports the tasks of the operator
  • Reuse Perspectives,
    which identify the elements of the architecture that are reused

Content Management Perspectives

The content management perspectives of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an introduction to the content management architecture of the system in terms of its relevant components and how they collaborate to provide content management functionality
• View Diagrams which show the system elements that handle content management and their relationships:
  • Content Management Architecture Diagram,
    which shows the system elements that handle content management and their relationships
• Element Catalog,
  which lists and describes the architectural elements providing content management in terms of their externally-visible characteristics and behavior. These elements can be: systems, subsystems, data, hardware, personnel, software, and procedures, whereby hardware can be computer hardware, network hardware, devices, equipment, facilities, etc.
• View Context,
  which shows how components supporting content management interface with externals
• Variability Guide,
  which documents how the content management architecture provides any necessary variability (e.g., when the architecture is used to support multiple systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the content management architecture was selected (e.g., functional decomposition of the configuration with “form following function”). This section briefly lists the relevant architectural drivers and provides compelling evidence that the content management architecture fullfils them
• Alternatives Considered and Rejected,
  which briefly describes alternative content management architectures that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the content management architecture was based

Security Perspectives:

The security [perspectives of the] architecture of the system consists of the subset of the system architecture having security responsibilities or ramifications. The security perspectives of the architecture of a tier or component can be documented as follows:

• Overview,
  which provides an overview of how the architectural elements of the tier or component collaborate to provide necessary security
• View Diagrams,
  which emphasizes the architectural elements needing security (e.g., database storing classified data) or implementing security controls (e.g., firewall, component implementing encryption/decryption) and the relationships (e.g., flow of classified data) between them:
  • Security Architecture Diagram,
    which documents the security-related architectural elements and their relationships
  • Data Flow Diagram,
    which shows the flow of classified data between architectural elements
• Element Catalog,
  which documents the security aspects of the relevant architectural elements including security-related elements, their security responsibilities, etc.
• View Context,
  which shows how the roles, teams, and organizations interface with other system components and externals of the system
• Variability Guide,
  which documents any variability in the security architecture (e.g., among systems within a product line)
• Analysis and Rationale,
  which documents the reasons why the security controls were selected This section briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them.
• Alternatives Considered and Rejected,
  which briefly describes alternative security architectures and security controls that were considered and rejected including the reasons for their rejection
• Assumptions,
  which briefly lists any assumptions on which the security architecture was based

Stakeholders

The typical stakeholders of a system architecture document are:

• Producer:
  • Architecture Team
• Evaluator:
  • Architecture Inspection Team
• Approvers:
  • Technical Leader
  • Project Manager
  • Customer Representative
• Maintainer:
  • Architecture Team
• Users (Intended Audiences):
  • Architecture Team,
    which uses it as an input when producing the software architecture document. It also enables future architects to come up to speed.
  • Customer Management Team,
    which uses it to understand, evaluate, and approve the scope and structure of the application to be delivered.
  • Database Team,
    which uses it to as an input when producing the information architecture document.
  • Deployment Team,
    which uses it to understand the components that it must install and configure.
  • Environments Team,
    which uses it to determine the requirements for the production environment.
  • Hardware Development Team,
    which uses it to understand the hardware components that it must acquire or fabricate.
  • Independent Test Team,
    which uses it as an input when generating integration test cases.
  • Integration Team,
    which uses it to understand the components that it must integrate.
  • Metrics Team,
    which uses the components in it as an input when estimating the size and scope of endeavor.
  • Product Standards Committee,
    which uses it to determine what potentially standardizable components are in use.
  • Project Management Team,
    which uses it as an input when managing project scope and schedule project activities.
  • Reuse Team,
    which uses it to identify potentially reusable components.
  • Retirement Team,
    which uses it to identify and understand the components it must retire.
  • ReviewTeam,
    which uses it to understand the application that it must review.
  • SecurityTeam,
    which uses it to prepare for security testing.
  • Software Development Team,
    which uses it as an input when producing the software architecture prototype and to drive the design of the software.
  • User Support Team,
    which uses it to learn what components it must support.

Phases

A System Architecture Document is typically developed during the following phases:

• Business Strategy: Not Applicable
• Business Optimization: Not Applicable
• Initiation: Started and approximately 80% completed including all top-level views and all-views that are critical for implementing the architectural drivers. Vendors, Commercial Off-The-Shelf (COTS) components, and technologies are evaluated and chosen.
• Construction: Completed. The logical and physical architectures are iterated. Minor mechanisms and requirements trace are added. TBDs are completed, and unresolved issues are resolved. Architectural decisions and inventions are validated, and assumptions are verified.
• Delivery: Maintained
• Usage: Maintained
• Retirement: Archived

Preconditions

A System Architecture Document can typically be started if the following preconditions hold:

• The initiation phase has started.
• The architecture team has been staffed and trained in system architecting.
• A relatively complete version of the application vision statement is available.
• An initial domain model document is available.
• A initial system requirements specification containing a significant number of the architecturally significant operational and quality requirements is available.
• The glossary exists.
• Domain experts in the relevant commercial components are available.

Inputs

The typical inputs to the System Architecture Document include:

• Work Products:
  • Application Vision Statement for the function model
  • Domain Model Document for the class model
  • System Requirements Specification for architecturally significant requirements
  • Glossary
• Stakeholders:
  • Domain Experts
  • Package Vendor Organizations

Guidelines

• Document Scope
  The system documented in a system architecture document can be:
  • Systems of Systems
  • Networks of Systems
  • Families of Systems
  • Systems of Subsystems
  • Subsystems of Segments
  • Segments of Subsegments
  • Subsegments of Assemblies
  • Assemblies of Subassemblies
  • Subassemblies of Configuration Items
  • Configuration Items of Components
• Document Structure
  System architecture documents are typically organized according to the configuration view as follows:
  • First by tiers in the configuration view
  • Second by components at the same tier
  • Third by views of the components
• Because of there potential complexity and large size, system architecture documents can be decomposed into smaller and simpler volumes or documents. For example, there can be an overview volume and then subvolumes documenting the architecture at different tiers. Some information may be supplied by reference to other documentation.
• View Structure
  The typical standard view should have the following content:
  • Overview,
    which names the type of view, states the scope of the view, and defines the view (e.g., a configuration view of the system that shows how the system is decomposed into collaborating subsystems).
  • View Diagram,
    which is a diagram that documents the relationships between the relevant architectural elements and which includes a legend defining the notation used (i.e., the icons for all nodes and arcs) on the diagram.
  • Element Catalog,
    which lists and describes the relevant architectural elements (i.e., the nodes and arcs between nodes on the view diagram) in terms of their externally-visible characteristics and behavior.
  • View Context,
    which shows how the architectural elements shown in the view are related to elements external to the view.
  • Variability Guide,
    which documents how the view of the architecture provides any necessary variability (e.g., when the architecture is used to support multiple systems within a product line).
  • Analysis and Rationale,
    which documents the reasons why the part of the architecture described by the view were selected (e.g., which briefly lists the relevant architectural drivers and provides compelling evidence that the architecture fullfils them).
  • Alternatives Considered and Rejected,
    which briefly describes alternative architectures that were considered and rejected including the reasons for their rejection.
  • Assumptions,
    which briefly lists any assumptions on which the chosen architecture was based.
• Tailoring
  The recommended contents should be tailored and interpreted by the architecture team so that it only includes appropriate and necessary information.
  • Some parts of the system architecture document are typically mandatory whereas some parts are optional.
  • Not every view is appropriate for every component at every tier. For example, personnel and data views are not appropriate for documenting the architecture of pure hardware components.
  • When a view can have multiple view diagrams, they all may not be necessary.
• This is a living document that is developed incrementally and iteratively in parallel with other work products (e.g., system requirements specification).
• Different parts of this document may be due at different times (i.e., before different milestones).
• Systems architecture documents can be:
  • Documented directly on paper (the traditional approach)
  • Documented using webpages to support easy navigation via links
  • Automatically generated from repositories (relational, object, or XML databases) using templates
• The systems architecture document can be created as a single document or separate subsections can be created as separate documents.
• Systems “come and go, but bad architecture is timeless.” Harris Kern 2002.
• Every architecture decision should documented with an associated rationale.
• Part of the data architecture may have already been developed as part of the object model in the domain model document.
• The requirements trace can be localized in the appendix (e.g., as a requirements traceability matrix) or spread throughout the body of the document.

Conventions

System Architecture Document is typically constrained by the following conventions:

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

Examples

• Example System Architecture Document