Documenting SW Architecture Ran Levy ran levynsn com

Documenting SW Architecture Ran Levy ran. levy@nsn. com I insert classification level Slide 1 Ran Levy © Nokia Siemens Networks / NWS / PN

Content § Why documenting the architecture? § How to document the architecture? § Preserving quality attributes using architecture document. § Summary I insert classification level Slide 2 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 3 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 4 Ran Levy © Nokia Siemens Networks / NWS/ PN

Why Documenting the Architecture? • Communication vehicle between stakeholders. Self Requirements Eng. SW Arch Document Testers Designers & Architects Implementors I insert classification level Slide 5 Ran Levy Managers © Nokia Siemens Networks / NWS/ PN

Content ü Why documenting the architecture? § How to document the architecture? § Preserving quality attributes using architecture document. § Summary I insert classification level Slide 6 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch - Preface You are NOT DONE when the document is done…. I insert classification level Slide 7 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – The 7 Rules 1. Documentation should be written from the point of view of the reader, not the writer. 2. Avoid unnecessary repetition. 3. Avoid ambiguity. 4. Use a standard organization. I insert classification level Slide 8 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – The 7 Rules Con’t 5. Record rationale (and considered alternatives). • Important for tracking and remembering decisions. • Prevents endless re-discussions about alternatives. 6. Keep documentation current but not too current. 7. Early review of the documentation. I insert classification level Slide 9 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch • IEEE 1471 - Recommended Practice for Architectural Description of Software-Intensive Systems. • “A Template for Documenting Software and Firmware Architectures” - HP, 2000. I insert classification level Slide 10 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 11 Ran Levy © Nokia Siemens Networks / NWS/ PN

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 I insert classification level Slide 12 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 13 Ran Levy © Nokia Siemens Networks / NWS/ PN

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: • • I insert classification level Slide 14 Ran Levy Why this architecture style was chosen? Why this component is not allowed to interact others? Why the interface is based on messages? … © Nokia Siemens Networks / NWS/ PN

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 1. Configure node. 2. Monitor node's configuration. 3. Get node's statuses and statistics. 4. Perform node's maintenance operations. 5. Notify NE events to be delegated to the operator. 6. 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 1. Network Services 2. Platform Services Components 3. Operator Notes Quality Attributes 1. 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. 1. 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. I insert classification level Slide 15 Ran Levy © Nokia Siemens Networks / NWS/ PN

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 I insert classification level Slide 16 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – Process View • Examples I insert classification level Slide 17 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 18 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 19 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 20 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – Physical/Deployment View • Examples I insert classification level Slide 21 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 22 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – Scenarios • Important scenarios to document: – – Init & upgrade. Scale up and down. Handling events with hard deadlines. Fault handling. I insert classification level Slide 23 Ran Levy © Nokia Siemens Networks / NWS/ PN

Documenting the Arch – Scenarios • Example – System Initialization I insert classification level Slide 24 Ran Levy © Nokia Siemens Networks / NWS/ PN

Content ü Why documenting the architecture? ü How to document the architecture? § Preserving quality attributes using architecture document. § Summary I insert classification level Slide 25 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. ▪… I insert classification level Slide 26 Ran Levy © Nokia Siemens Networks / NWS/ PN

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 I insert classification level Slide 27 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 28 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 29 Ran Levy © Nokia Siemens Networks / NWS/ PN

Content ü Why documenting the architecture? ü How to document the architecture? ü Preserving quality attributes using architecture document. § Summary I insert classification level Slide 30 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 31 Ran Levy © Nokia Siemens Networks / NWS/ PN

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. I insert classification level Slide 32 Ran Levy © Nokia Siemens Networks / NWS/ PN

Thank You I insert classification level Slide 33 Ran Levy © Nokia Siemens Networks / NWS / PN