Documenting SW Architecture Ran Levy ran.levy@nsn.com

Why documenting the architecture? Content Why documenting the architecture? How to document the architecture? Preserving quality attributes using architecture document. Summary

Why Documenting the Architecture? Architecture is what makes the sets of parts work together as a successful whole; architecture documentation is what tells developers how to make it so.

Why documenting the architecture? Education. Basis for architecture analysis. Manifests the earliest set of decisions: Constraints on implementation. Dictates organizational structure. Supports SW maintainability: Understanding effect of changes.

Why Documenting the Architecture? Communication vehicle between stakeholders. Self SW Arch Document Requirements Eng. Managers Testers Designers & Architects Implementors

Content Why documenting the architecture? How to document the architecture? Preserving quality attributes using architecture document. Summary

Documenting the Arch - Preface You are NOT DONE when the document is done….

Documenting the Arch – The 7 Rules Documentation should be written from the point of view of the reader, not the writer. Avoid unnecessary repetition. Avoid ambiguity. Use a standard organization.

Documenting the Arch – The 7 Rules Con’t Record rationale (and considered alternatives). Important for tracking and remembering decisions. Prevents endless re-discussions about alternatives. Keep documentation current but not too current. Early review of the documentation.

Documenting the Arch IEEE 1471 - Recommended Practice for Architectural Description of Architectural Description of Software-Intensive Systems. “A Template for Documenting Software and Firmware Architectures” - HP, 2000.

Documenting the Arch – Views Key Point: Different stakeholders have different needs. Perhaps the most important concept associated with software architecture documentation is that of the view.

Documenting the Arch – Views Philippe Kruchten – “4+1” approach to architecture documentation: Logical view Process view Development view Physical/Deployment view Plus 1: binds all views together its end users. Designers decompose the system into a set of key abstractions, taken mainly from the problem domain. These abstractions are objects or object classes that exploit the principles of abstraction, encapsulation, and inheritance. In addition to aiding functional analysis, decomposition identifies mechanisms and design elements that are common across the system. • The process view addresses concurrency and distribution, system integrity, and fault-tolerance. The process view also specifies which thread of control executes each operation of each class identified in the logical view. The process view can be seen as a set of independently executing logical networks of communicating programs (“processes”) that are distributed across a set of hardware resources, which in turn are connected by a bus or local area network or wide area network. • The development view focuses on the organization of the actual software modules in the software-development environment. The units of this view are small chunks of software—program libraries or subsystems— that can be developed by one or more developers. The development view supports the allocation of requirements and work to teams, and supports cost evaluation, planning, monitoring of project progress, and reasoning about software reuse, portability, and security. • The physical view takes into account the system's requirements such as system availability, reliability (fault-tolerance), performance (throughput), and scalability. This view maps the various elements identified in the logical, process, and development views—networks, processes, tasks, and objects—onto the processing nodes.

Documenting the Arch – Logical View Primarily supports the functional requirements - what the system should provide in terms of services to its users. Designers decompose the system into a set of key abstractions – objects and relationships between them. In addition to aiding functional analysis, decomposition identifies mechanisms and design elements that are common across the system.

Documenting the Arch – Logical View Logical view is expressed by: Architecture styles (e.g. Layered, MVC, …) Components and interfaces description: CRC-R cards Object, class, package and components diagrams. For each section document the rationale: Why this architecture style was chosen? Why this component is not allowed to interact others? Why the interface is based on messages? …

Documenting the Arch – Logical View Example – CRC-R card Component Management I/F Responsibilities Provide support for management operations via SNMP and CLI. It provides Management Agents functionality together with unified management FW for allowing general way of accessing specific Network Services components. Provided Interfaces Configure node. Monitor node's configuration. Get node's statuses and statistics. Perform node's maintenance operations. Notify NE events to be delegated to the operator. Get response from NS on required operation. Rationale Management I/F components allow access of the operator to the NE for management operations. Unified Management FW allows single interface usage for accessing Network Service that will serve all Management Interfaces and allow extension to additional interfaces in the future. Collaborators Network Services Platform Services Components Operator Notes Quality Attributes Usability: Management I/F should be user friendly, include guideline/help during each operation and provide the ability to configure and to display the full relevant and mandatory values in one command. Management interfaces should allow range configurations. Portability: Separation of Management I/F from the NS via Management FW. Issues All supported Management Interfaces should be passed through Management FW, which allow single management interface for a Network Service which does not depend on type of the called management interface and should not be changed in case when additional management interface is added.

Documenting the Arch – Process View Maps logical view into execution unit. Takes into account quality attributes such as performance and availability. Addresses concurrency and distribution, system integrity, and fault-tolerance. Expressed by: Class diagrams (using thread and process annotations). Sequence Diagrams Communication Diagrams Activity Diagrams Timing Diagrams Interaction Overview Diagrams

Documenting the Arch – Process View Examples

Documenting the Arch – Development View Focuses on the organization of the actual software modules in the software-development environment. Help managers in work assignments and teams establishment. Expressed by: Components diagrams. Implementation mapping description.

Documenting the Arch – Development View Example Implementation Rules: For each logical component a directory is created that contains all code files belonging to that Header files should be places under pub directory. Implementation files under src directory. For each class (except inner class) a separate file is created.

Documenting the Arch – Physical/Deployment View Maps the various elements identified in the logical, process, and development views—networks, processes, tasks, and objects—onto the processing nodes. Focuses on distribution, communication and provisioning. Accommodates quality attributes such as availability, reliability, performance, throughput and scalability. Expressed by deployment diagrams.

Documenting the Arch – Physical/Deployment View Examples

Documenting the Arch – Scenarios This view represents the scenarios that tie the four views together. The scenarios describe sequences of interactions between objects, and between processes. They are used to identify architectural elements and to illustrate and validate the architecture design. They also serve as a starting point for tests of an architecture prototype. Expressed by use cases diagram.

Documenting the Arch – Scenarios Important scenarios to document: Init & upgrade. Scale up and down. Handling events with hard deadlines. Fault handling.

Documenting the Arch – Scenarios Example – System Initialization

Preserving quality attributes using architecture document. Content Why documenting the architecture? How to document the architecture? Preserving quality attributes using architecture document. Summary

Preserving Quality Attributes Be explicit In ALL relevant sections. Quality attributes requirements section: List all relevant attributes, detail them and specify how the architecture support each one. Availability: System shall support 99.999% up time. No data plane affect due to system failures. … The architecture of the system supports security by the following means: Hitless upgrade Support for specific module replacement without downtime.

Preserving Quality Attributes Logical View: Define the “rules” of the used architecture style. E.g.: Strict layered architecture to support maintainability, extensibility. Add to the CRC-R card quality attributes. E.g.: Logger component must not exceed 5% of CPU consumption. Document collaborators

Preserving Quality Attributes Process View: Add constraints to diagrams Time constraints, components that must be used as part of the sequence (e.g. Authentication), parallel execution… Use timing diagrams when needed.

Preserving Quality Attributes Scenarios: Documenting scenarios are a major key for many quality attributes. Do NOT skip this section: Upgrade Flow – supports availability and maintainability. Fault Management flows – supports availability, fault localization, security. Events handling flows – supports performance, scalability.

Content Why documenting the architecture? How to document the architecture? Preserving quality attributes using architecture document. Summary

Summary Documenting the architecture is very important as mean for communicating the architecture and translating the architects ideas into practice. Architecture documentation must be described by several views, that all together provides the complete view of the architecture. The architecture document is major key for preserving the quality attributes of the system.

References “Software Architecture in Practice”, Bass, Clements and Kazman, Addison Wesley, 2003. “Documenting Software Architectures”, Clements, Bachman, et al., Addison Wesley, 2001. “A Template for Documenting Software and Firmware Architectures”, Ogush, Coleman et al., Hewlett-Packard Product Generation Solutions, 2000. Wikipedia “Software Architecture - Why what and how”, Alexander Katz.

Thank You