Documenting sw acrchitecture

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

Ran Levy Nokia Siemens Networks / NWS/ PN
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.
SW Arch
Document
Requirements Eng.
Designers &
Architects
Implementors
Testers
Managers
Self

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

• 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?
• …

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

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
Create
Basic
Services
HW
Packages/Operations
OS
Status at end
of phase
Services register each
other ready for
restoration
Services:File System, Transaction Management,
CDB, System upgrade (e.g. CDB convert), SFC
redundancy, FTP,TFTP, TELNET, Error trace,
Recording.
Service objects
created and ready to
register each other
Ready for internal
services creation in
case of active init or
ready to cold take over
in case of standby init
Card is ALIVE, BIT
passedCreate drivers to perform Deep BIT
Resource Management, OS, Serial, basic memory,
card basic HW initialization, Seabridge OS
wrappers
Restore
Pre
Active
System long operations before active (e.g. upgrade
LICs, internal transaction for converts in application
layer, apply restored configuration; in case of
hot-standby perform transient data full sync from
active)
Ready to be active in
short period. The card
in Hot Standby state
Active
Move required services into active state (e.g.
Cards Management starts to load cards
configuration)
The card is in Active
state. Except specific
services that require to
pass Post Active state
Enhance
Services
Services fully restored
ready to be executed
Create,Init
Create,Init
Basic
Services
Phase
1
Retrieve
ShelfConf
Basic
Services
Phase
2
Shelf configuration is
ready to be used by
external/internal services
Services created,
wait for external
configuration
ColdStandbyHotStandbyActive
Active
Init as standby
Init as active
Retreive SFC shelf information e.g., IP and MAC
addresses; redundancy role
CDB Convert, SFC redundancy perform NVRAM
full sync in case of standby init
Run
Services are ready to
operate
Services restore internal data from CDB
Services register to each other creating
relationships between serivces
Services creates internal structure.
Services moved into RUN state
PostActive
Provide a way to support late activation for
specific services that do not support hot-standby.
These services require to perform init phases
starting from the restore up to active state.
All services in the
SFC are in active
state.

Content
 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.
▪…

• 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

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

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

Ran Levy Nokia Siemens Networks / NWS / PN
Thank You

Documenting sw acrchitecture

Recommended

Recommended

More Related Content

What's hot

What's hot (14)

Similar to Documenting sw acrchitecture

Similar to Documenting sw acrchitecture (20)

More from Ran Levy

More from Ran Levy (6)

Recently uploaded

Recently uploaded (20)

Documenting sw acrchitecture

Editor's Notes