Documenting sw acrchitecture

Slide 1 Ran Levy Nokia Siemens Networks / NWS / PNI insert classification level © Nokia Siemens Networks

Documenting SW ArchitectureRan Levy

[email protected]

Slide 2 Ran Levy Nokia Siemens Networks / NWS/ PNI insert classification level © Nokia Siemens Networks

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 documentationis what tells developers how to make it so.



• 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.

SW Arch Document

Requirements Eng.

Designers & Architects

Implementors

Testers

Managers

Self


Content




Summary


Documenting the Arch - Preface

You are NOT DONE when the document is done….


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.


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.

5. Keep documentation current but not too current.

6. 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.

Adobe Acrobat Document


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


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 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 Services2.Platform Services Components3.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.


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

• 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.

• Example


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.



• Important scenarios to document:– Init & upgrade.

– Scale up and down.

– Handling events with hard deadlines.

– Fault handling.



• Example –

System Initialization

Layer Phase

Init

Creat

e

Basic

Servic

es

HW

Packages/Operations

OS

Status at endof phase

Services register eachother ready forrestoration

Services:File System, Transaction Management,CDB, System upgrade (e.g. CDB convert), SFCredundancy, FTP,TFTP, TELNET, Error trace,Recording.

Service objectscreated and ready toregister each other

Ready for internalservices creation incase of active init orready to cold take overin case of standby init

Card is ALIVE, BITpassedCreate drivers to perform Deep BIT

Resource Management, OS, Serial, basic memory,card basic HW initialization, Seabridge OSwrappers

Resto

re

Pre A

ctive

System long operations before active (e.g. upgradeLICs, internal transaction for converts in applicationlayer, apply restored configuration; in case ofhot-standby perform transient data full sync fromactive)

Ready to be active inshort period. The cardin Hot Standby state

Active

Move required services into active state (e.g.Cards Management starts to load cardsconfiguration)

The card is in Activestate. Except specificservices that require topass Post Active state

Enhance

Servic

es

Services fully restoredready to be executed

Creat

e, In

it

Creat

e, In

it

Basic

Service

s

Phase 1

Retrie

ve

Shelf C

onf

Basic

Servic

es

Phase 2

Shelf configuration isready to be used byexternal/internal services

Services created,wait for externalconfiguration

Co

ld S

tan

db

yH

ot S

tan

db

yA

ctiv

e

Act

ive

Init as standby

Init as active

Retreive SFC shelf information e.g., IP and MACaddresses; redundancy role

CDB Convert, SFC redundancy perform NVRAMfull sync in case of standby init

Run Services are ready tooperate

Services restore internal data from CDB

Services register to each other creatingrelationships between serivces

Services creates internal structure.

Services moved into RUN state

Post A

ctive

Provide a way to support late activation forspecific services that do not support hot-standby.These services require to perform init phasesstarting from the restore up to active state.

All services in theSFC are in activestate.


Content




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




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 FirmwareArchitectures”, Ogush, Coleman et al., Hewlett-Packard Product Generation Solutions, 2000.

• Wikipedia

• “Software Architecture - Why what and how”, Alexander Katz.

Slide 33 Ran Levy Nokia Siemens Networks / NWS / PNI insert classification level © Nokia Siemens Networks

Thank You