<Your System> - Arc42

succasunnakalamazooΗλεκτρονική - Συσκευές

25 Νοε 2013 (πριν από 3 χρόνια και 4 μήνες)

64 εμφανίσεις





Architecture Documentation





<Your System>










created by






<Your

Name>


Template Revision:
5
.0

EN

June 2011


We acknowledge that this document uses material from the arc 42 architecture

template,
http://www.arc42.de
. Created by Dr. Peter Hruschka & Dr. Gernot
Starke.






Page
2

of

26



Revision History



Version

Dat
e

Reviser

Description














Related documents


Do
c
ument

Description







Page
3

of

26



Table of Contents

1.

Introduction and Goals

................................
................................
................................
....

5

1.1

Requirements Overview

................................
................................
............................

5

1.2

Quality Goals

................................
................................
................................
............

6

1.3

Stakeholders

................................
................................
................................
.............

6

2.

Architecture Constraints

................................
................................
................................
.

7

2.1

Technical Constraints

................................
................................
................................

7

2.2

Organizational Constraints

................................
................................
........................

8

2.3

Conventions

................................
................................
................................
............

10

3.

System Scope and Context

................................
................................
..........................

11

3.1

Business Context

................................
................................
................................
....

11

3.2

Technical
-

or Infrastructure Context

................................
................................
........

12

4.

Solution Ideas and Strategy

................................
................................
..........................

12

5.

Building Block View

................................
................................
................................
......

12

5.1

Level 1

................................
................................
................................
....................

14

5.2

Level 2

................................
................................
................................
....................

15

5.3

Level 3

................................
................................
................................
....................

16

6.

Runtime View

................................
................................
................................
...............

16

6.1

Runtime Scenario 1

................................
................................
................................
.

17

6.2

Runtime Scenario 2

................................
................................
................................
.

17

6.3

...

................................
................................
................................
.............................

18

6.4

Runtime Scenario n

................................
................................
................................
.

18

7.

Deployment View

................................
................................
................................
..........

18

7.1

Infrastructure Level 1

................................
................................
..............................

18

7.2

Infrastructure Level 2

................................
................................
..............................

19

8.

Recurring or Generic Structures and Patterns

................................
..............................

19

8.1

Recurring or Generic Structure 1

................................
................................
.............

20

8.2

Recurring or Generig Structure 2

................................
................................
............

20

9.

Technical Concepts and
Architectural Aspects

................................
.............................

20

9.1

Persistency

................................
................................
................................
.............

20

9.2

User Interface

................................
................................
................................
.........

21

9.3

Ergonomics

................................
................................
................................
.............

21

9.4

Flow Control

................................
................................
................................
............

21

9.5

Transaction Procession

................................
................................
...........................

21

9.6

Session Handling

................................
................................
................................
....

21

9.7

Security

................................
................................
................................
...................

21



Page
4

of

26



9.8

Communications and Integration with other Software Systems

...............................

22

9.9

Distribution

................................
................................
................................
..............

22

9.10

Exception/Error Handling

................................
................................
......................

22

9.11

System Management and Administration

................................
..............................

22

9.12

Logging, Tracing

................................
................................
................................
...

22

9.13

Business Rules

................................
................................
................................
.....

23

9.14

Configurability

................................
................................
................................
.......

23

9.15

Parallelization and Threading

................................
................................
................

23

9.16

Internationalization

................................
................................
................................

23

9.17

Migration

................................
................................
................................
...............

23

9.18

Testability

................................
................................
................................
..............

24

9.19

Plausibility and Validity Checks

................................
................................
.............

24

9.20

Code Generation

................................
................................
................................
...

24

9.21

Build
-
Management

................................
................................
................................

24

10.

Design Decisions

................................
................................
................................
........

24

11.

Quality Scenarios

................................
................................
................................
.......

24

11.1

Quality Tree

................................
................................
................................
..........

25

11.2

Evaluation Scenarios

................................
................................
............................

25

12.

Technical Risks

................................
................................
................................
..........

26

13.

Glossary

................................
................................
................................
.....................

26


Remark: The Microsoft
-
Word™ variant of this template contains hidden remarks and
suggestions. You can toggle display of this text by the appropriate Word
-
command.






Page
5

of

26



1.

Introduction and Goals

The introduction to the architecture documentation should list the driving forces that software
architects must consider in their decisions.

This includes on the one hand the fulfillment of
functional requirements of the stakeholders, on the
other hand the fulfillment of or compliance with required constraints, always in consideration of the
architecture goals.



1.1

Requirements Overview

Short description of the functional requirements.

Digest
(
or abstract
)
of the requirements documents
.

Reference to complete requirements documents (incl. version identification and location).

Contents

A compact summary of the functional environment of the system. Answers the following questions (at
least approxim
ately):



What happens in the system’s environment?



Why should the system exist? Why is the system valuable or important? Which problems does the
system solve?

Motivation

From the point of view of the end users a system is created or modified to improve exec
ution of a
business activity.

This essential architecture driver must not be neglected even though the quality of an architecture is
mostly judged by its level of fulfillment of non
-
functional requirements.

Form

Short textual description, probably in
tabular use
-
case format.

The business context should in any case refer to the corresponding requirements documents.

Examples

Short descriptions of the most important
:



business processes
,



fun
ctional

requirements
,



non
-
functional requirements and other constr
aints (the most important ones must be covered as
architecture goals or are listed in the “Constraints” section), and/or



quantity structures
.



Background information

Here you can reuse parts of the requirements documents


but keep these excerpts short and
balance
readability against avoidance of redundancy.






Page
6

of

26



1.2

Quality Goals

Contents

The top ten goals for the architecture and/or constraints whose fulfillment is of highest importance to
the major stakeholders.

Goals that define the architecture’s quality coul
d be:



availability



modifiability



performance



security



testability



usability

Motivation

If you as an architect do not know how the quality of your work can be judged …

Form

Simple tabular representation, ordered by priorities

Background Information

NEVER
start developing an architecture if these goals have not been put into writing and have been
signed by the major stakeholders
.

We have endured projects lacking defined quality goals much too often. We do
not like to suffer, therefore we are by now highly c
onvinced that the few hours
spent on collecting quality goals are well invested.

PH & GS.


Sources

The
DIN/ISO 9126 Standard
contains an extensive set of possible quality goals.

For everybody who is not interested in this level of detail: a readable excer
pt is contained in
"
Agile
Software
-
Entwicklung für Embedded Real
-
Time Systems mit der UML
" (Hruschka, Rupp, Carl
-

Hanser
-
Verlag, 2002
on page
9.

PH


1.3

Stakeholder
s

Contents

A list of the most important persons or organizations that are affected by can
contribute to the
architecture
.

Motivation

If you do not know the persons participating in or concerned with the project you may get nasty
surprises later in the development process.

Form

Simple table with role names, person names, their knowledge as perta
ining to architecture, their
availability, etc.



Page
7

of

26



Examples

see e.g. VOLERE
-
Stakeholder table in the downloads on

or see Chapter 5.2 in
"Requirements
-

Engineering und
-
Management"
by
Chris Rupp .



2.

Architecture
Constraints

Contents

Binds that constrain software architects in their freedom of design or development process.

Motivation

Architects should know exactly where they are free in their design decisions and where they must
adhere to constraints.

Constraints
must always be dealt with; they may be negotiable, though.

Form

Informal lists, structured by the sub
-
sections of this section.

Examples

s
ee sub
-
sections

Background Information

In the optimal case constraints are defined by requirements. In any case, at
least the architects must
be aware of constraints.

The influ



2.1

Technical Constraints

Contents

List all technical constraints in this section. This category covers hard
-

and software infrastructure,
applied technologies (operating systems, middleware, datab
ases, programming languages, …).


Hardware
-
Requirements


<
insert constraint here
>


<insert constraint here>

Software
-
Requirements


<insert constraint here>

Operating System Requirements


<insert constraint here>

Programming Requirements


<insert

constraint here>




Page
8

of

26



Examples


Constraint

Description

Hardware infrastruc
tur
e

Pro
c
essor
s
,
memory, networks, firewalls and other
relevant elements

Software

i
nfrastru
c
tur
e

Operating systems, database systems, middleware,
communications systems, transaction
monitors, web
servers, directory services

System

operations

Batch
-

or

o
nline

operations of the system or of required
external systems?

Availability of the runtime
environment

Data center with 7x24 uptime?

Will there be service times that cause reduced
availability
of the system or important parts thereof?

Graphical user interface

Are there any restrictions related to GUI (style guide)?

Libraries, frameworks,
components

Is there any COTS that must be used?

Programming languages

Object oriented,
structured, declarative, or rule
-
based
languages?

Compiled or interpreted languages?

Reference architec
ture
s

Are there any comparable or reusable reference projects
in the organization?

Analysis and design
methodologies

Object oriented or structured meth
odologies?

Data structures

Requirements for certain data structures, interfaces to
existing databases or files?

Software interfaces

Interfaces to existing applications

Programming requirements

Programming guidelines, fixed program structure

Technical c
ommunications

synchronous or asynchronous; protocols

Operating systems and
middleware

Required operating systems and middleware


2.2

Organizational Constraints

Contents

Enter all organizational, structural, and resource
-
related constraints. This category
also covers
standards and legal constraints that you must comply with.


Organi
z
ation
and Struc
tur
e


<insert constraint here>


Res
ource
s

(Budget,
Time
, Person
ne
l)



Page
9

of

26




<insert constraint here>


Organi
z
at
ional
Standards


<insert constraint here>

Legal
Factors


<insert constraint here>


Examples


Constraint

Description

Organization and Structure

Sponsor’s o
r条ni
z
慴i潮

s瑲u
c
瑵t
e

m潴o湴n慬⁣h慮来s ⁲敳灯湳i扩li瑩敳?

䍨慮来s ⁣潮瑡t琠灥rs潮s?


Project team’s
o
r条ni
z
慴a潮
al
s瑲u
c
瑵t
e

睩瑨t睩t桯畴

s畢c潮瑲慣瑯牳

摥cision
-
maki湧⁰ 睥w ⁴ 攠er潪散琠t慮慧敲

䑥aisio渠nak敲e

bx灥ri敮c攠睩瑨tsimil慲⁰a潪散瑳



bxis瑩n朠 p慲瑮敲ahi灳 潲

-
潰敲慴i潮s

Ar攠 t桥r攠 慮y co
-
o灥r慴io湳 扥t睥敮 瑨攠 潲o慮iz慴a潮s 慮d
c敲瑡e渠n潦tw慲攠a潭灡湩敳?

p畣栠 灡r瑮敲e桩灳

潦瑥t i湦lu敮ce 灲潣畲敭敮琠 摥cisio湳
Ei湤e灥n摥n琠tf⁳ys瑥t⁲敱畩r敭敮瑳).

䥮f敲湡l d敶敬o灭敮琠 潲o
潵瑳潵rci湧

䑥a敬o瀠p湴nrn慬ly 潲畴uo畲u攠e漠ox瑥t湡l⁳敲eic攠eom灡湩敳?

䑥a敬o灭敮琠潦 愠灲潤畣琠
潲⁦潲⁩湴nr湡l 畳政

䥭灬i敳 摩ff敲敮琠 灲潣敳s敳 in r
敱畩r敭敮瑳 慮慬ysis a湤
摥cisio渠naki湧.

䥮f瑨攠e慳攠ef⁰牯 畣琠tevel潰m敮琺

乥w⁰牯摵c琠t潲⁡ew慲k整e

䥭灲潶敤⁰牯 畣琠t潲⁡渠oxis瑩湧慲k整e

mr潤畣tizin朠gf⁡ 數is瑩湧 Ei湴nrn慬)⁳yst敭?

䑥a敬o灭敮琠t潲⁩湴nr湡l⁵ 攠enly?

剥o潵rc敳
Bu摧整ⰠIim攬

m敲e潮n敬)

cix敤⁰ ic攠er⁴im支e晦潲琿

Is the project’s budget fixed or is it calculated by time or effort?

pc桥d畬e

䥳 瑨t sc桥d畬攠fl數ibl政 䥳 瑨tr攠a fix敤 摥liv敲y d慴a㼠t桩c栠
s瑡t敨潬摥rs⁣潮瑲ol⁴ 攠e敬iv敲y⁤慴a?

pc桥d畬攠es⸠.畮cti潮慬ity

th慴

桡s⁨ g桥r⁰ i潲楴y㨠W桥⁤敬iv敲y 摡瑥爠瑨攠e畮c瑩潮慬ity?

剥oe慳e
-
sc桥摵le

A琠whic栠摡t敳 s桯畬搠w桩c栠f畮c瑩潮ality b攠av慩la扬攠i渠which
r敬敡s敳  v敲ei潮s?

Project’s budget

cix敤爠 l數i扬政 t桡琠tm潵湴nis⁡vaila扬政



Page
10

of

26



Constraint

Description

Budget f
or technical
resources

Buy or rent development tools? (hardware and software)

Team

Number of team members, qualifications, motivation,
availability
.

Organizational Standards

Development process

Requirements concerning development process? This includes
internal stan
dards for modeling, documentation and
implementation.

Qualit
y
standards

Is the organization required to adhere to quality standards
(such as
ISO
-
9000)?

Development tools

Requirements related to development tools (such as
CASE
-
Tool,
database, IDE,
communications software, middleware,
transaction monitor
).

Configuration and version
management

Requirements concerning processes and tools

Test tools and processes

Requirements concerning processes and tools

Acceptance
-

and release
processes

Data
modeling and database design

User interfaces

Business processes (workflow)

Usage of external systems (e.g. write access to external
databases)

Service Level

Agreements

Requirements or standards related to availability or required
service levels?

Legal Fa
ctors

Liability

Are there any legal aspects related to usage or operations of
the system?

Could the system cause
loss of human life or hazard to human
health
?

Could the system impact the operations of external systems or
businesses?


Data privacy and
security

Does the system store or process any data worthy of protection

Auditing

Are any aspects of the system under legal obligation to present
evidence?

Aspects of international
law

Will the system be used in an international context?

Are there varying

constraints on system usage in different
countries (example: use of encryption technology)?



2.3

Conventions

Contents

List all conventions that are relevant for the software architecture’s development.



Page
11

of

26



Form

Either insert the conventions directly in this
document or refer to relevant other documents.

Examples



Coding guidelines



Documentation guidelines



Guidelines for version and configuration management



Naming conventions



3.

System Scope and Context

Contents

The context view defines the boundaries of the sys
tem under development to distinguish it from
neighboring systems. It thereby identifies the system’s relevant external interfaces.

Make sure that the interfaces are specified with all their relevant aspects (what is communicated, in
which format is it comm
unicated, what is the transport medium, …), even though some popular
diagrams (such as the UML use case diagram) represent

only a few aspects of the interface.

Motivation

The interfaces to neighboring systems belong to the most critical aspects of a projec
t. Ensure early on
that you have understood them in their entirety.

Form



Various context diagram (see below)



Lists of neighboring systems and their interfaces
.

3.1

Business Context

Contents

Identify all
1

neighboring systems and specify all logical/business data that is exchanged with the
system under development. Add data formats and communication protocols with neighboring systems
and the general environment if these are not specified in detail with the
relevant components.

Motivation

Understanding of the information exchange with neighboring systems.

Form

Logical context diagram,

in UML e.g. simulated by class diagrams, use case diagrams, communications diagrams


i.e. all
diagrams that represent the sys
tem as a black box and explain its interfaces to neighboring systems
(in varying degrees of detail).

Examples






1

We often tend to a pragmatic approach


but here we insist on a list of all (a
-
l
-
l) neighboring systems.
Too many projects have failed because they were not aware of their neighbors.




Page
12

of

26



3.2

Technical
-

or
Infrastructure Context

Contents

Specification of the communications channels between your system, its neighboring systems, and the

environment.

Motivation

Understanding of the media used for information exchange with neighboring systems, and the
environment.

Form

E.g.
UML
d
eployment

diagram

describing channels to neighboring systems

Examples


4.

Solution Ideas and Strategy

Contents

A
summary and explanation of the fundamental solution ideas and strategy.

Motivation

Most architectures are based upon some specific solution ideas or strategies. These ideas should be
familiar to everyone involved into the architecture.

Form



Diagrams and /

or text, as appropriate


5.

Building Block View

Contents

Static decomposition of the system into building blocks (modules, components, subsystems,
subsidiary systems, classes, interfaces, packages, libraries, frameworks, layers, partitions, tiers,
functions,

macros, operations, data structures, …) and the relationships thereof.

Motivation

This is the most important view, that must be part of each architecture documentation. In building
construction this would be the floor plan.

Form

The building block view is

a hierarchical collection of black box and white box descriptions as shown in
the following diagram:



Page
13

of

26




Level 1 contains the white box description of the overall system (system under development / SUD)
made up of black box descriptions of the system’s buil
ding blocks.

Level 2 zooms into the building blocks of Level 1 and is thus made up of the white box descriptions of
all building blocks of Level 1 together with the black box descriptions of the building blocks of Level 2.

Level 3 zooms into the building b
locks of Level 2, etc.

The section is structured as follows:

============================

White
Box

Template:

Contains multiple building blocks with corresponding black box descriptions.

One or more black box templates
:

Each building block appearing in the

white box template should be described as follows:



Purpose / Responsibility:



Interface(s):



Implemented requirements
:



Variability:



Performance attributes
:



Page
14

of

26





Repository / Files
:



Other administrative information: Author, Version, Date, Revision History




Open
issues
:


5.1

Level

1

Here you describe the white box view of level 1 according to the white box template. The structure is
given below.

The overview diagram describes the inner structure of the overall system in terms of building blocks 1


n, as well as their

relationships and interdependencies.

It is also useful to list the most important reasons that led to this structure, esp. as relevant to the
interdependencies / relationships among the building blocks at this level.

You should also mention rejected alter
natives incl. reasons for their rejection.

The following diagram shows the main building blocks of the system and their interdependencies:

<
insert overview diagram here
>


Comments regarding structure and interdependencies at Level

1:


5.1.1

Building Block Name
1

(Black

Box

Description
)

Stru
c
tur
e

according to black box template
:



Purpose / Responsibility:



Interface(s):



Implemented requirements
:



Variability:



Performance attributes
:



Repository / Files
:



Other administrative information: Author, Version, Date,
Revision History




Open issues
:


<
insert the building block’s b
lack
b
ox
t
emplate
here
>

5.1.2

Building Block Name
2

(Black Box Description)


<insert the building block’s black box template here>

5.1.3

...


<insert the building block’s black box template here>



Page
15

of

26



5.1.4

Building Block Name
n

(Black Box Description)


<insert the building block’s black box template here>

5.1.5

O
pen Issues

5.2

Level
2

Describe all building blocks comprising level 1 as a series of white box templates. The structure is
given below for three building
blocks and should be duplicated as needed.

5.2.1

Building Block Name
1 (White

B
ox

Description
)

Shows the inner workings of the building block in form of a diagrams with local building blocks 1


n,
as well as their relationships and interdependencies.

It is also

useful to list the most important reasons that led to this structure, esp. as relevant to the
interdependencies / relationships among the building blocks at this level.

You should also mention rejected alternatives incl. reasons for their rejection.


<ins
ert diagram
of building block 1
here>

Building Block Name

1.1 (Black

Box
Description
)

Stru
c
tur
e

according to black box template
:



Purpose / Responsibility:



Interface(s):



Implemented requirements
:



Variability:



Performance attributes
:



Repository / Files
:



Other administrative information: Author, Version, Date, Revision History




Open issues
:

Building Block Name 1.
2

(Black Box Description)

Stru
c
tur
e

according to black box template

...

Building Block Name 1.
n

(Black Box Description)

Stru
c
tur
e

according to bla
ck box template

Description of Relationships

Open Issues

5.2.2

Building Block Name 2

(White

B
ox

Description
)





Page
16

of

26




<insert diagram
of building block 2
here>

Building Block Name

2.1

(Black

Box
Description
)

Stru
c
tur
e

according to black box template

Building Block
Name 2
.
2

(Black Box Description)

Stru
c
tur
e

according to black box template

...

Building Block Name 2
.
n

(Black Box Description)

Stru
c
tur
e

according to black box template

Description of Relationships

Open Issues

5.2.3

Building Block Name 3

(White

B
ox

Description
)




<insert diagram
of building block 3
here>

Building Block Name

3.1

(Black

Box
Description
)

Stru
c
tur
e

according to black box template

Building Block Name 3
.
2

(Black Box Description)

Stru
c
tur
e

according to black box template

...

Building Block Name 3
.
n

(Black Box Description)

Stru
c
tur
e

according to black box template

Description of Relationships

Open Issues

5.3

Level
3

Describe all building blocks comprising level 2 as a series of white box templates. The structure is
identical to the structure of level 2.
Duplicate the corresponding sub
-
sections as needed.

Simply use this section structure for any additional levels you would like to describe.


6.

Runtime View

Contents

alternative
terms
:



Page
17

of

26





Dynamic view



Process view



Workflow view

This view describes the behavior
and interaction of the system’s building blocks as runtime elements
(processes, tasks, activities, threads, …).

Select interesting runtime scenarios such as:



How are the most important use cases executed by the architectural building blocks?



Which instance
s of architectural building blocks are created at runtime and how are they started,
controlled, and stopped.



How do the system’s components co
-
operate with external and pre
-
existing components?



How is the system started (covering e.g. required start
scripts, dependencies on external systems,
databases, communications systems, etc.)?


Note: The main criterion for the choice of possible scenarios (sequences, workflows) is their
architectural relevancy
. It is
not

important to describe a large number of s
cenarios. You should rather
document a
repres
entative

selection.

Candidates are
:

1.

The top
3



5 use cases

2.

System startup

3.

The system’s behavior on its most important external interfaces

4.

The system’s behavior in the most important error situations


Motivation

Esp. for object
-
oriented architectures it is not sufficient to specify the building blocks with their
interfaces, but also how instances of building blocks interact during runtime.

Form

Document the chosen scenarios using UML sequence, activity or communi
cations diagrams.

Enumerated lists are sometimes feasible.

Using object diagrams you can depict snapshots of existing runtime objects as well as instantiated
relationships. The UML allows to distinguish between active and passive objects.

6.1

Runtime Scenario
1



Runtime diagram

(or other adequate description of scenario!)



Description of the notable aspects of the interactions between the building block instances
depicted in this diagram.


6.2

Runtime Scenario 2



Runtime diagram

(or other adequate description of scenario!)



Description of the notable aspects of the interactions between the building block instances
depicted in this diagram.




Page
18

of

26



6.3

...


6.4

Runtime Scenario n



Runtime diagram

(or other adequate description of scenario!)



Desc
ription of the notable aspects of the interactions between the building block instances
depicted in this diagram.


7.

Deployment View

Contents

This view describes the environment within which the system is executed. It describes the geographic
distribution of

the system or the structure of the hardware components that execute the software. It
documents workstations, processors, network topologies and channels, as well as other elements of
the physical system environment. The deployment view shows the system fr
om the operator’s point of
view.

Please explain how the systems’ building blocks are aggregated or packaged into deployment artifacts
or deployment units.

Motivation

Software is not much use without hardware. The minimum that is needed by you as a software

architect is sufficient detail of the underlying (hardware) deployment so that you can assign each
software building block that is relevant for the system’s operations to some hardware element. (This
also holds for any COTS that is a prerequisite for the
operations of the overall system.) These models
should enable the operator to properly install the software.

Form

The UML provides deployment diagrams for describing this view. Use these


possibly in a nested
manner if necessary. (The top level deployment

diagram should already be part of your context view,
showing your infrastructure as a single black box. Here you are zooming into this black box with
additional deployment diagrams.)

Diagrams by your hardware
-
oriented colleagues who describe processors an
d channels are also
usable. You should abstract these to aspects relevant for software deployment.

7.1

Infrastru
c
tur
e

Level
1

7.1.1

Deployment Diagram Level
1



Shows the deployment of the overall system to 1


n processors or sites as well as the physical
connections

among these elements.



Lists the most important reasons that led to this deployment structure, i.e. the specific selection of
nodes and channels.



Should also mention rejected alternatives incl. reasons for their rejection.


7.1.2

Pro
c
essor 1

Stru
c
tur
e

according to
node

template
:



Description



Page
19

of

26





Performance attributes



Assigned software building blocks



Other administrative information



Open issues

7.1.3

Pro
c
essor 2

Stru
c
tur
e

according to
node

template
:

7.1.4

...

7.1.5

Pro
c
essor n

Stru
c
tur
e

according to
node

template
:

7.1.6

Channel
1

Contents

Specification of the channel’s attributes, as relevant for software architecture.

Motivation

Specify at least those attributes of the communications channels that you need for proving fulfillment
of non
-
functional requirements such as maximal thr
oughput, probability for faults, etc.

Form

Use a structure similar to the node template.

Often you will refer to a standard (e.g.
CAN
-
Bus, 10Mbit Ethernet,
IEEE 1394
, ...).

7.1.7

Channel
2

7.1.8

...

7.1.9

Channel

m

7.1.10

Open Issues

7.2

Infrastru
c
tur
e

Level
2

Contents

Additional
deployment diagrams with similar structure as above
.

Motivation

To describe additional details of the infrastructure, as needed by software deployment
.


8.

Recurring or Generic Structures and Patterns

Sometimes a hierarchical decomposition of building blocks
is insufficient for giving an overview of
detailed interdependencies between individual building blocks. The following sections are intended to
describe generic or specific dependencies among any set of building blocks


possibly even across
different leve
ls.



Page
20

of

26



We call a dependency
generic
if it appears more than once in the architecture, and
specific
if it is
unique.

Form:

Use building block models (class diagrams, package diagrams, component diagrams, etc.) and related
descriptions in the same way as in the

hierarchical decomposition.

Often it is pracital to support understandability by adding specific rruntime views to these recurring
structures.


8.1

Recurring or Generic Structure

1

<
insert diagram and descriptions here
>


8.2

Recurring or Generig Structure 2

<
inse
rt diagram and descriptions here
>



9.

Technical Concepts and Architectural Aspects

Contents


The following chapters cover examples of frequent cross
-
cutting concerns or aspects.

Fill in these chapters if there is NO building block that covers this aspect. If

some of the aspects are
not relevant for your project mention this fact instead of removing the section.

Motivation

Some aspects cannot be “factored” into a separate building block of the architecture (e.g. the topic
“security”). This section of the templ
ate is the location where you can cover all concepts for such
topics in a central place.

Form

.. can be varied
.
Some concept articles with free structure, some wide
-
ranging models/scenarios using
notations that are also applied in architecture views.


9.1

Pers
isten
cy

Persistency means moving data from (volatile) memory to a durable storage medium (and back).

Some of the data that a software system is processing must be written to and read from persistent
storage media.



Volatile storage media (main memory or cac
he) are not designed for permanent storage.

Dat
a is
lost if the hardware is switched off.



The amount of data processed by commercial software systems normally exceeds the capacity of
main memory.



Hard disks, optical media and tapes often contain large amou
nts of existing business data that
represent a significant investment.



Page
21

of

26



Persistency is a technical issue that normally does not appear as part of the actual business
functionality. An architect must deal with this issue nevertheless because most software sy
stems
require efficient access to persistently stored data. This is relevant for essentially all commercial and
most technical systems; embedded systems on the other hand often differ in their data management
requirements.


9.2

User Interface

Software systems
that are used interactively by (human) users require a user interface. These can be
graphical, textual, or voice user interfaces.


9.3

Ergonom
ics

Ergonomics

of software systems deals with the improvement (optimization) of their usability with
respect to object
ive and subjective factors. Key ergonomic factors are user interface, reactivity
(subjective performance) as well as availability and robustness of the system.


9.4

Flow Control

Flow control of software systems is related to visible flows (on the
-

graphical
-

user interface) as well
as the flow of background activities. Therefore this section should cover control of the user interface
as well as control of workflows.


9.5

Transaction Procession

A transactions is a sets of operations or activities that must be proc
essed either in its entirety or not at
all. The term is especially relevant in the database area with the important notion of ACID
-
transactions
(atomic, consistent, isolated, durable).


9.6

Session

Handling

A session identifies an active connection between a
client and a server. The session state must be
preserved, which is esp. important if stateless protocols such as HTTP are used for communications.
Session handling is a critical challenge esp. for intra
-

and internet
-
systems and can strongly influence
the
performance of a system.


9.7

S
ecurity

The security of software systems deals with mechanisms that ensure data confidentiality, integrity, and
availability.

Typical issues are:



How can data be protected during transport (e.g. via open networks such as the
internet)?



How can communicating entities ensure mutual trust?



How can communicating entities identify each other and be protected against faked identities?



How can communicating entities prove data provenience or certify validity of data?



Page
22

of

26



The topic of IT
-
security often touches upon legal aspects, sometimes even international law.


9.8

Communications and Integration with other Software Systems

Communication: Exchange of data between system components. Covers communications within one
process or address space, b
etween different processes (inter
-
process communication


IPC), and
between different systems.

Integration: Combination of existing systems in a new context. Also known as:
(Legacy) Wrapper,
Gateway, Enterprise Application Integration (EAI).


9.9

Distribution

Distribution: Design of software systems whose parts are executed on different


physically separated


hardware systems.

Distribution covers issues such as calling methods on remote systems (remote procedure call


RPC
or remote method invocation


RMI),
the transfer of data or documents among distributed parties, the
choice of optimal modes of interaction or communications patterns (such as synchronous /
asynchronous, publish
-
subscribe, peer
-
to
-
peer).


9.10

Exception/Error Handling

How are exceptions and error
s handled systematically and consistently?

How can the system reach a consistent state after an error? Is this done automatically or is manual
interaction required?

This aspect is also related to logging and tracing,

Which kind of exceptions and errors are

handled by the system? Which kind of errors are forwarded to
which external interface and which are handled fully internally?

How are the exception handling mechanisms of your programming language used? Do you use
checked or unchecked exceptions?


9.11

System
Management
and
Administr
ation

Larger software systems are often executed in controlled environments (data centers) under oversight
of operators or administrators. These stakeholders require specific information on the applications’
states during runtime as

well as special means of control and configuration.


9.12

Logging, Tracing

There are two ways of documenting an application’s status during runtime:
Logging

and
Tracing
. In
both cases the application is extended with function or method calls that write state
information, but
there is a difference in their usage:



Logging
can cover business or technical aspects or any combination of both.



Business logs are normally prepared for end users, administrators or operators. They contain
information on the business
processes that are executed by the application. This kind of
logging may also be related to auditing.



Page
23

of

26





Technical logs contain information for operators or developers. These are used for error
detection and system optimization.



Tracing
is intended to provid
e debugging information for developers or support personnel. It is
primarily used for error detection and analysis.


9.13

Business Rules

How do you deal with business logic and business rules? Is business logic implemented in the
corresponding business classes
or is it handled in a central component? Do you use a rule engine for
the interpretation of business rules (production system, forward
-
/backward
-
chaining)?


9.14

Configurability

The flexibility of a software system is influenced by its configurability, i.e. the

possibility to make
certain decisions about usage of the system at a late point in time.

Configurability can occur at the following events:



During development: For example server, file, or directory names could be stored directly in the
code (“hard
-
coded”
).



During deployment or installation: Configuration information for a specific installation (such as the
installation path) can be given.



At system startup: Information can be read dynamically before or during system startup.



During application execution:
Configuration information is queried or read during runtime.


9.15

Paralleli
zation and
Threading

Applications can be executed in parallel processes or threads. This creates a need for synchronization
points. The theory of parallel processing serves as a
foundation for this aspect. The architecture and
implementation of parallel systems needs to consider many technical details such as address spaces,
applied mechanisms for synchronization


guards, semaphores, etc.


processes and threads,
parallelism in t
he operating system, parallelism in virtual machines. etc.


9.16

Internationali
zation

This section covers support for usage of the system in different countries, i.e. adjusting the system to
country specific attributes. Internationalization (often abbreviated a
s “i18n” where “18” refers to the
eighteen characters between the I and the n) covers translation of text, usage of character encodings,
display of fonts, writing of numbers and dates, and other (external) aspects.


9.17

Migration

In many cases a new software s
ystem is intended to replace an existing legacy system. As an
architect you should not only consider your shiny new architecture but also all organizational and
technical aspects that must be considered for the introduction or migration of the architecture
.

Examples:



Concept, process, or tools for data transfer and initial data creation.



Page
24

of

26





Concept for system introduction or temporary parallel operations of legacy system and new
system.


Is it necessary to migrate existing data? How do you execute any needed s
yntactic or semantic
transformations?


9.18

Test
ability

Support for simple (and if possible automated) tests. This aspect is the basis for the important
implementation pattern of “continuous integration”. Projects should support at least daily build
-
and
-
test
cycles. Important keywords for this aspect are unit tests and mock objects.


9.19

Plausibili
ty and Validity Checks

How and where do you check plausibility and validity of (input) data, esp. user inputs?


9.20

Code

Generation

How and where do you use code generators
to create parts of the system from models or domain
specific languages (DSL’s)?


9.21

Build
-
Management

How is the overall system created from is (source code) building blocks? Which repositories contain
source code, where are configuration files, test cases,
test data and build scripts (make, ant, maven)
stored?



10.

Design Decisions

Contents

Document all important design decisions and their reasons!

Motivation

It is advantageous if all important design decisions can be found in one place. It is up to you to deci
de
if a decision should be documented here or rather locally (e.g. in the white box descriptions of building
blocks). In any case avoid redundancies.

Form

Informal list, if possible ordered by the decisions’ importance for the reader.


11.

Quality Scenarios

Th
is chapter summarizes all you (or other stakeholders) might need to systematically evaluate the
architecture

against the quality requirements.



Page
25

of

26



11.1

Quality Tree

11.2

Evaluation Scenarios

Contents

Scenarios describe a system’s reaction to a stimulus in a certain situation. They thus charac
terize the
interaction between stakeholders and the system. Scenarios operationalize quality criteria and turn
them into measurable quantities.

Two scenarios are relevant for most software architects:



Usage scenarios (also called application scenarios or
use case scenarios) the system’s runtime
reaction to a certain stimulus. This also includes scenarios that describe the system’s efficiency or
performance. Example: The system reacts to a user’s request within one second.



Change scenarios describe a modifi
cation of the system or of its immediate environment.
Example: Additional functionality is implemented or requirements for a quality attribute change.

If you design safety critical systems a third type of scenarios is important for you:



Boundary or stress
scenarios describe how the system reacts to exceptional conditions.
Examples: How does the system react to a complete power outage, a serious hardware failure,
etc.


Figure: Schematic depiction of scenarios
(
cf.
[Bass+03])

Scenarios comprise the following major parts (according to
[Starke05],
original structure from
[Bass+03]):



S
timulus
:
Describes a specific interaction between the
(stimulating) stakeholder and the system.
Example: A user calls a functions, a developer implements an extension, an administrator installs
or configures the system.



Source

of the stimulus
:
Describes where the stimulus comes from. Examples: internal or
external,
user, operator, attacker, manager.



Environment
:
Describes the system’s state at the time of arrival of the stimulus. This should list all
preconditions that are necessary for comprehension of the scenario. Examples: Is the system
under normal or
maximal load? Is the data base available or down? Are any users online?



System

a
rtifact
:
Describes the part of the system is affected by the stimulus. Examples
:
The whole
system, the data base, the web server
.



System
response
:
Describes the system’s reacti
on to the stimulus as determined by the
architecture. Examples: Is the function called by the user executed. How long does the developer
need for implementation? Which parts of the system are affected by the installation /
configuration?



R
esponse measure
:
Describes how the response can be measured or evaluated. Examples
:
Downtime in hours, correctness yes/no, time for code change in person days, reaction time in
seconds
.

Motivation

You need scenarios for the evaluation and review of architectures. They take

the role of a
“benchmark” and aid in measuring the architecture’s achievement of its objectives regarding the non
-
functional requirements and quality attributes.

Source

of

the

Stimulus

System

artifact

Response

measure

Stimulus

Response



Page
26

of

26



Form

Tabular or free text. Explicitly highlight the scenario’s elements (source, environment,

artifact,
response, measure).

Background Information

There are relations between scenarios and the runtime view. Often you can use scenarios of the
runtime view fully or as a basis for evaluation. Evaluation scenarios additionally contain response
measure
s that are often not considered in the pure execution focus of runtime scenarios.


12.


Technical Risks

Contents

A list of identified technical risks, ordered by priority

Motivation

“Risk management is project management for grown
-
ups”

(Tim Lister, Atlantic Systems Guild.)

This
should be your motto for systematic detection and evaluation of technical risks in the architecture,
which will be needed by project management as part of the overall risk analysis.

Form

List of risks with probab
ility of occurrence, amount of damage, options for risk avoidance or risk
mitigation, …

13.

Glossar
y

Contents

The most important terms of the software architecture in alphabetic order.

Motivation

It should not be necessary to explain the usefulness of a glossa
ry …

Form

A simple table with columns
<
Term
>
a
nd <Definition>