Software Architecture: Documenting Architectures chapter 2

Definition and Scope of Software Architecture

  • Software Architecture Definition: According to the primary definition provided by Prof. Dr. Coen De Roover, "The architecture of a software system is the set of structures needed to reason about the system, which comprise software elements, relations among them, and externally visible properties of both."
  • Reasoning-Enabling Structures: Architecture is fundamentally about structures that enable reasoning. It is not merely a collection of components.
  • ANSI/IEEE 1471-2000 Standard: Defines architecture as the "fundamental organization of a system, embodied in its components, their relationships to each other and to the environment, and the principles governing its design and evolution."
  • Architectural vs. Non-Architectural Structures: A structure is considered architectural only if it supports reasoning about the properties of the software system. If a structure does not facilitate such reasoning, it is not part of the architecture.
  • Subjectivity of Architecture: No single structure can claim to be the system's only architecture. Different stakeholders require different structures to reason about various system properties, including:
    • Functionality: What the system achieves.
    • Availability: How the system behaves in the face of faults.
    • Modifiability: The level of difficulty in making specific changes.
    • Security: Resilience to attacks.
    • Performance: Responsiveness to user requests.
  • Common Relations in Structures: Typical relations between elements (e.g., A and B) include:
    • A calls B.
    • A instantiates B.
    • A sends a message to B.
    • A is a subtype of B.
    • B is a data repository and A is writing data to it.
    • A is a data repository and B is reading from it.

The Need for Standardized Architectural Views

  • Visualisation Challenges: Simon Brown (GOTO 2014) noted that software teams often struggle to effectively visualize the architecture of their systems, often resulting in inconsistent "box-and-line" diagrams that lack clear semantics.
  • The Medical Analogy: Architectural views are compared to medical imaging:
    • X-ray, MRI scan, and CT scan: These provide distinct views on different yet related physical structures.
    • Stakeholder Reasoning: Just as an orthopedist, cardiologist, and oncologist use different scans to reason about specific health systems, software stakeholders use different views to support specific types of reasoning.

Stakeholders and Documentation Uses

  • Stakeholder Definition: Anyone with a vested interest in the success of the system. They have specific concerns that the system must guarantee or optimize.
  • Exhaustive Stakeholder Roles and Documentation Uses:
    • Architect: Responsible for development and documentation of the architecture. Uses documentation for negotiating trade-offs among requirements/designs, recording decisions, and providing evidence of requirement satisfaction.
    • Business Manager: Responsible for the organizational entity owning the system. Uses documentation to understand the architecture's ability to meet business goals.
    • Conformance Checker: Assures adherence to standards and processes. Uses documentation as a basis for ensuring implementation faithfulness to architectural prescriptions.
    • Customer: Pays for the system. Uses documentation to assure functionality and quality, gauge progress, and estimate costs/schedules.
    • Database Administrator (DBA): Involved in data store design and administration. Uses documentation to understand how data is created, used, and updated, and to ensure quality goals are met.
    • Deployer: Makes the system operational at the site. Uses documentation to understand elements to be installed and their role in system function.
    • Designer: Applies the architecture to meet specific sub-requirements. Uses documentation to resolve resource contention and understand communication between parts.
    • Evaluator: Formally evaluates documentation against criteria. Uses documentation to check the architecture's ability to deliver behavior and quality attributes.
    • Implementer: Develops specific elements. Uses documentation to understand inviolable constraints and exploitable freedoms.
    • Integrator: Combines components. Uses documentation to produce integration plans and locate source of failures.
    • Maintainer: Fixes bugs and provides enhancements. Uses documentation to understand the ramifications of proposed changes.
    • Network Administrator: Maintains hardware and software network components. Uses documentation to determine network loads and understand network usage profiles.
    • Product Line Manager: Manages families of products. Uses documentation to determine if a new potential member is within the product family scope.
    • Project Manager: Plans, sequences, and schedules resources. Uses documentation to set budget/schedules and resolve development-time resource contention.
    • Representative of External Systems: Manages interoperability. Uses documentation to define agreements between systems.
    • System Engineer: Designs components where software interacts with hardware. Uses documentation to assure the system environment is sufficient for the software.
    • Tester: Verifies the system against requirements. Uses documentation to create tests based on element behavior and interaction.
    • User: End users (administrators, superusers, etc.). Use documentation (as reviewers) to check for functionality or aid in emergency field maintenance.

Documentation Frameworks and Standards

  • ISO/IEC/IEEE 42010:2022: The current standard for architecture description (replacing the 2011 version).
  • "Views and Beyond" Approach: This methodology advocates that architecture is not one view, but a collection of views. It consists of multiple parts (View 1 to View n) plus documentation "Beyond Views."
  • Standard View Templates: Documentation for any architectural view should include:
    • Primary Representation: Depicts elements and relations in the view's specific vocabulary.
    • Element Catalog: Details the elements shown in the primary presentation.
    • Context Diagram: Shows how the system relates to its environment (humans, other systems, physical objects).
    • Variability Guide: Explains how to exercise variation points in the architecture.
    • Rationale: Explains why the design exists, justifying choices such as specific patterns.

Categories of Architectural Structures

  • Module Structures: Show the system as a set of implementation or data units (modules) to be constructed or procured. Modules provide a coherent set of responsibilities (actions, knowledge, decisions).
  • Component-and-Connector (C&C) Structures: Show the system as elements with run-time behavior (components) and their interactions (connectors).
  • Allocation Structures: Show the relationship between software elements and non-software environmental elements (CPUs, file systems, teams).

Detailed: Module Structures

  • Elements: Modules (Implementation units with coherent responsibilities).
  • Relations:
    • Is-part-of: Defines a part/whole relationship (submodule to aggregate).
    • Depends-on: Defines dependency; specific views detail the nature of the dependency (e.g., "uses").
    • Is-a: Defines generalization (child/parent or inheritance/realization).
  • Constraints: Specific views may impose topological constraints, such as limiting visibility between modules.
  • Documenting Module Properties:
    • Name: May suggest roles (e.g., account_mgr) or hierarchy (e.g., A.B.C).
    • Mapping to Source Code: e.g., Module Account maps to IAccount.java, AccountImpl.java, and AccountOrmMapping.xml.
    • Visibility of Interfaces:
      • Encapsulation: The parent module provides its own interface and maps requests to submodules. Submodule facilities are hidden from the outside.
      • Selective Exposition: The aggregate module selectively exposes a subset of submodule interfaces as its own.
    • Implementation Information: Non-architectural but useful data for management, such as build details.
  • Module Notations:
    • UML (Unified Modeling Language): Uses class diagrams (with attributes/operations), stereotypes like «use» or «interface», and packages.
    • DSM (Dependency Structure Matrix): A grid where row/column intersections show dependencies. Usually, a "1" in a cell indicates that the module in the corresponding column uses the module in the corresponding row.
  • Uses of Module Views:
    • Construction: Serves as a blueprint for source code and physical directories.
    • Planning: Defining work assignments, schedules, and budgets; planning incremental development.
    • Analysis: Change-impact analysis and requirements traceability (mapping functional requirements to module responsibilities).
    • Communication: Conveying system functionality and data management structure.

Detailed: Component-and-Connector (C&C) Structures

  • Elements:
    • Components: Principal processing units and data stores. They possess ports for interaction.
    • Connectors: Pathways of interaction. They possess roles indicating how components use the connector.
  • Relations:
    • Attachments: Associating component ports with connector roles.
    • Interface Delegation: Associating component ports (or connector roles) with internal sub-architecture ports/roles.
  • Constraints:
    • Components must attach to connectors, not directly to other components.
    • Connectors must attach to components, not other connectors.
    • Attachments must be between compatible ports and roles.
    • Connectors cannot exist in isolation.
  • Documenting C&C Properties:
    • Reliability: Likelihood of failure.
    • Performance: Response times, latency, and throughput.
    • Resource Requirements: Processing and storage needs.
    • Functionality: Specific functions performed.
    • Security: Encryption, audit trails, and authentication features.
    • Concurrency: Execution as separate processes or threads.
    • Tier: Residing tier in a tiered topology (e.g., Web GUI tier, EJB tier).
  • C&C Notations:
    • Simple Notation: Basic lines for connectors.
    • Rich Notation: Depicting connectors as complex components themselves.
  • Mapping to Modules: The relationship between modules and components is generally $M$-to-$N$.
    • Example: A client-server system might have only two modules (Client and Server) but result in 11 runtime components (1 Server instance and 10 Client instances).

Detailed: Allocation Structures

  • Elements: Software elements (from Module or C&C views) and environmental elements.
  • Relations: Allocated-to (mapping software to environment).
  • Three Main Allocation Styles:
    1. Deployment Style: Mapping software architecture (usually C&C processes) to hardware (processors, communication channels). Used for reasoning about performance and availability.
      • Example: ATIA-M (U.S. Army Training Information Architecture-Migrated) system, where components are deployed to WebLogic on the NIPRNET network.
    2. Install Style: Mapping modules to file structures in development or production environments (e.g., file systems, configuration control).
      • Example (Duke's Bank): Java applications deployed as .ear (Enterprise archive), .war (Web archive), or .jar (Java archive) files. UML uses «artifact» and «manifest» stereotypes for this.
    3. Work Assignment Style: Assigning module implementation and integration responsibility to specific teams. Defines communication pathways (wikis, email lists).

The Architectural Influence Cycle

The cycle asserts: "An architecture has influences that lead to its creation, and its existence has an impact on the architect, the organization, and the industry."

  • Influences ON Architecture:
    • Business Goals: Profit, market capture, long-term technical investment.
    • Technical Environment: Prevalent practices (e.g., today's focus on cloud, social networking, and mobility).
    • Project Context: Current engineering activities (e.g., legacy system recovery).
    • Professional Background: The architect’s knowledge and skills (e.g., familiarity with Service-Oriented Architecture).
  • Influences BY Architecture:
    • Business: Creating opportunities for product lines; allowing organizations to adjust goals based on expertise.
    • Technical: Stakeholders may relax requirements to gain economies (e.g., using shrink-wrapped software).
    • Project: Architecture dictates organizational structure (team formation based on software units).
    • Professional: Success or failure influences the architect’s future design choices.

Core Importance of Architecture

  1. Enables or inhibits driving quality attributes.
  2. Allows early prediction of system qualities through analysis.
  3. Enhances communication among stakeholders.
  4. Serves as a foundation for training new team members.
  5. Provides the basis for reasoning about and managing system evolution.
  6. Carries the earliest, most fundamental design decisions (hardest to change).
  7. Defines constraints on subsequent implementation.
  8. Provides a basis for evolutionary prototyping.
  9. Allows reasoning about cost and schedule.
  10. Shifts focus from creation to the assembly of components.