Documenting Software Architectures

SlsLema de 1elegesLln de usuarlos glna 1
SMA81C8lu ulseno de la arqulLecLura del SlsLema de 1elegesLln y Medlda


ConLenldo
1 arL l A CollecLlon of SofLware ArchlLecLure SLyles 3
11 1hree CaLegorles of SLyles 3
Module vlews 10
121 Cvervlew 10
122 12 LlemenLs 8elaLlons and roperLles of Module vlews 11


1. Part I: A CoIIection of Software Architecture StyIes
1he sLarLlng polnL of archlLecLure deslgn ls mosL ofLen a preexlsLlng package of deslgn declslons very
few archlLecLs deslgn sysLems compleLely by closlng Lhelr eyes Lhlnklng hard and con[urlng up a
brandnew deslgn
A mosL useful package of deslgn declslons ls Lhe otcbltectote style Chapters 1SpresenL a range of
lmporLanL and wldely used archlLecLure sLyles 1he emphasls here ls on how Lo documenL a vlew LhaL
resulLs from Lhe use of a sLyle
1.1. Three Categories of Styles
Chapters 1S are organlzed along Lhe llnes of Lhe Lhree caLegorles of sLyles we dlscussed ln Lhe
prologue module sLyles (Chapters 1 and 2) componenLandconnecLor (CC) sLyles (Chapters
3 and 4) and allocaLlon sLyles (Chapter S) lan for your documenLaLlon package Lo lnclude aL leasL
one module vlew aL leasL one componenLandconnecLor vlew and aL leasL one allocaLlon vlew
Modules are Lhe prlmary elemenLs of modu|e sty|es A module ls an lmplemenLaLlon unlL LhaL
provldes a coherenL seL of responslblllLles A module mlghL Lake Lhe form of a class a collecLlon of
classes a layer an aspecL or any decomposlLlon of Lhe lmplemenLaLlon unlL Lvery module has a
collecLlon of properLles asslgned Lo lL 1hese properLles are lnLended Lo express Lhe lmporLanL
lnformaLlon assoclaLed wlLh Lhe module as well as consLralnLs on Lhe module Sample properLles are
responslblllLles vlslblllLy lnformaLlon and auLhor or owner 1he relaLlons LhaL modules have Lo one
anoLher lnclude ls pott of JepeoJs oo and ls o

A modu|e sty|e ls a klnd of sLyle LhaL lnLroduces a speclflc seL of module Lypes and speclfles rules
abouL how elemenLs of Lhose Lypes can be comblned
Module sLyles are descrlbed ln Chapters 1 and 2

Componentandconnector sty|es express runLlme behavlor 1hey are descrlbed ln Lerms of
componenLs and connecLors A componenL ls one of Lhe prlnclpal processlng unlLs of Lhe execuLlng
sysLem ComponenLs mlghL be servlces processes Lhreads fllLers reposlLorles peers or cllenLs and
servers Lo name a few A connecLor ls Lhe lnLeracLlon mechanlsm among componenLs ConnecLors
lnclude plpes queues requesL/reply proLocols dlrecL lnvocaLlon evenLdrlven lnvocaLlon and so
forLh ComponenLs and connecLors can be decomposed lnLo oLher componenLs and connecLors 1he
decomposlLlon of a componenL may lnclude connecLors and vlce versa

A componentandconnector sty|e ls a klnd of sLyle LhaL lnLroduces a speclflc seL of componenL and
connecLor Lypes and speclfles rules abouL how elemenLs of Lhose Lypes can be comblned
AddlLlonally glven LhaL CC vlews capLure runLlme aspecLs of a sysLem a CC sLyle ls Lyplcally also

assoclaLed wlLh a compuLaLlonal model LhaL prescrlbes how daLa and conLrol flow Lhrough sysLems
deslgned ln LhaL sLyle
CC sLyles are descrlbed ln Chapters 3 and 4

A||ocat|on sty|es descrlbe Lhe mapplng of sofLware unlLs Lo elemenLs of an envlronmenL ln whlch Lhe
sofLware ls developed or execuLes 1he envlronmenL mlghL be Lhe hardware Lhe flle sysLems
supporLlng developmenL or deploymenL or Lhe developmenL organlzaLlon(s)
l2 SLyle Culdes A SLandard CrganlzaLlon for Lxplalnlng a SLyle
SLyles presenLed LogeLher for comparlson and selecLlon should be descrlbed conslsLenLly wlLh each
oLher ln Lhls way an archlLecL can beLLer make an lnformed declslon abouL whlch one(s) Lo use 1hls
ls an appllcaLlon of Lhe fourLh rule for sound documenLaLlon use a sLandard organlzaLlon 1he
ouLllne used for descrlblng a sLyle ls called a sty|e gu|de

An a||ocat|on sty|e ls a klnd of sLyle LhaL descrlbes Lhe mapplng of sofLware unlLs Lo elemenLs of an
envlronmenL ln whlch Lhe sofLware ls developed or execuLes
AllocaLlon sLyles are descrlbed ln Chapter S

1he sLyles ln Chapters 1S are presenLed uslng Lhe form of a sLyle gulde 8elow ls Lhe ouLllne for LhaL
sLyle gulde
CuLllne lor a SLyle Culde
etlew 1he overvlew ln a sLyle gulde explalns why Lhls sLyle ls useful lL dlscusses whaL lL
ls abouL a sysLem LhaL Lhe sLyle addresses and how lL supporLs reasonlng abouL sysLems

A sty|e gu|de ls Lhe descrlpLlon of an archlLecLure sLyle LhaL speclfles Lhe vocabulary of
deslgn (seLs of elemenL and relaLlonshlp Lypes) and rules (seLs of Lopologlcal and semanLlc
consLralnLs) for how LhaL vocabulary can be used

LlemenL Lypes relaLlon Lypes and properLles
L|ements are Lhe archlLecLure bulldlng blocks naLlve Lo Lhe sLyle A sLyle gulde deflnes one
or more elemenL Lypes lnsLances of whlch wlll populaLe an archlLecLure LhaL uses LhaL
sLyle
ke|at|ons deLermlne how Lhe elemenLs work LogeLher Lo accompllsh Lhe work of Lhe

sysLem A sLyle gulde deflnes one or more relaLlon Lypes LhaL apply Lo Lhe sLyle's elemenL
Lypes An archlLecLure uslng Lhe sLyle wlll descrlbe Lhe relaLlons (lnsLances of Lhe relaLlon
Lype) LhaL deLermlne how Lhe elemenLs can work LogeLher and any lmporLanL properLles
of Lhose relaLlons 1he sLyle gulde provldes rules on how elemenLs can and cannoL be
relaLed

An e|ement ls an archlLecLure bulldlng block naLlve Lo Lhe sLyle An elemenL can be a
module a componenL or connecLor or an elemenL ln Lhe envlronmenL of Lhe sysLem
whose archlLecLure we are documenLlng 1he descrlpLlon of an elemenL Lells whaL role lL
plays ln an archlLecLure llsLs lLs lmporLanL propert|es and furnlshes guldellnes for
effecLlve documenLaLlon of Lhe elemenL ln a vlew
A re|at|on deflnes how elemenLs cooperaLe Lo accompllsh Lhe work of Lhe sysLem 1he
descrlpLlon of a relaLlon names Lhe relaLlons among elemenLs and provldes rules on how
elemenLs can and cannoL be relaLed
A property conLalns addlLlonal lnformaLlon abouL elemenLs and relaLlons A sLyle deflnlLlon
lncludes Lhe properLy name and descrlpLlon When an archlLecL documenLs a vlew based
on LhaL sLyle Lhe properLles wlll be glven values roperLy values are ofLen used Lo analyze
an archlLecLure for lLs ablllLy Lo meeL quallLy aLLrlbuLe requlremenLs

oosttolots 1hls secLlon of Lhe sLyle gulde llsLs Lhe rules for puLLlng Lhe elemenLs and
relaLlons LogeLher Lo form a valld lnsLance of Lhe sLyle lor example ln a plpeandfllLer
sLyle a plpe ls allowed Lo aLLach Lo a fllLer buL noL Lo anoLher plpe ln a layered sLyle Lhe
layers are lald ouL ad[acenLly ln a sLack noL scaLLered abouL randomly ln a work
asslgnmenL sLyle every sofLware unlL has Lo be allocaLed Lo aL leasL one organlzaLlonal
elemenL
wbot lts fot 1hls secLlon of Lhe sLyle gulde descrlbes Lhe klnd of reasonlng supporLed by
vlews ln Lhe sLyle 1he lnLenL ls Lo help Lhe archlLecL undersLand Lo whaL purpose(s) a vlew
ln Lhls sLyle may be puL 1hls mlghL be how uslng Lhe sLyle helps ln Lhe developmenL
process (for example Lhe uses" sLyle ls good for reasonlng abouL modlflablllLy) Cr lL
mlghL be abouL how Lhe sLyle helps Lhe producL (for lnsLance plpeandfllLer ylelds good
performance when processlng a serles of daLa elemenLs)
Nototloos 1hls secLlon of Lhe sLyle gulde wlll glve descrlpLlons of graphlcal and/or LexLual
represenLaLlons LhaL are avallable and useful Lo documenL vlews ln Lhe sLyle ulfferenL
noLaLlons wlll also supporL Lhe conveyance of dlfferenL klnds of lnformaLlon ln Lhe vlew
kelotloo to otbet styles 1hls secLlon of Lhe sLyle gulde descrlbes how vlews derlved from
Lhls sLyle mlghL be relaLed Lo vlews derlved from dlfferenL sLyles lor example vlews from
Lwo dlfferenL sLyles mlghL convey dlfferenL buL relaLed lnformaLlon abouL a sysLem and
Lhe archlLecL would llke a way Lo choose whlch one Lo use 1hls secLlon mlghL also lnclude

warnlngs abouL oLher vlews wlLh whlch a parLlcular vlew ls ofLen confused Lo Lhe
deLrlmenL of Lhe sysLem and lLs sLakeholders (Layers and Llers are a good example of Lhls
1hey are fundamenLally dlfferenL buL are ofLen mlsused lnLerchangeably)
omples 1hls secLlon provldes or polnLs Lo an example of a documenLed vlew derlved
from Lhe glven sLyle

l3 Chooslng Whlch LlemenL and 8elaLlon roperLles Lo uocumenL
1he dlscusslon ln Chapters 1S heavlly emphaslzes sLyles whlch are documenLed ln publlshed sLyle
guldes 8uL as you read abouL Lhe sLyles ln art I remember LhaL Lhe end game ls Lo produce vlews
based on Lhe chosen sLyle 8ecall LhaL a vlew ls a represenLaLlon of a sLyle applled Lo a parLlcular
sysLemln Lhls case Lhe sysLem whose archlLecLure ls belng documenLed

When documenLlng a vlew declde on Lhe llsL of properLles Lo documenL abouL Lhe elemenLs ln LhaL
vlew Choose properLles LhaL wlll ald Lhe analysls you wlsh Lhe documenLaLlon Lo supporL
uocumenLlng a vlew Lhen lncludes documenLlng Lhe values for Lhe properLles you chose

Cne of Lhe Lasks ln documenLlng a vlew ls decldlng whlch properLles of elemenLs Lo documenL 8ecall
from our precedlng dlscusslon of sLyle guldes LhaL properLles are addlLlonal lnformaLlon abouL Lhe
elemenLs and Lhelr relaLlons LhaL are useful Lo documenL 1he sLyles of Chapters 1S are each
descrlbed wlLh a seL of properLles llkely Lo be useful conslder Lhem suggesLlons
roperLles almosL always lnclude Lhe name of Lhe elemenL as well as some descrlpLlon of lLs role or
responslblllLy ln Lhe archlLecLure lor example properLles of a layeran elemenL of Lhe layered sLyle
whlch ls one of Lhe module sLylesshould lnclude Lhe layer's name Lhe unlLs of sofLware Lhe layer
conLalns and Lhe naLure of Lhe capablllLles LhaL Lhe layer provldes A layered vlew wlll Lhen for each
layer speclfy lLs name Lhe unlLs of sofLware lL conLalns and Lhe capablllLles lL provldes
8eyond Lhese baslc properLles however are properLles LhaL wlll supporL archlLecLurebased analysls
lf you wanL Lo analyze an archlLecLure for performance Lhen properLles ln some vlews probably
should lnclude an elemenL's besL and worsLcase response Llmes or Lhe maxlmum number of evenLs
an elemenL can servlce per Llme unlL lf you wanL Lo analyze an archlLecLure for securlLy Lhen you
probably wanL Lo documenL properLles LhaL explaln levels of encrypLlon and auLhorlzaLlon rules for
dlfferenL elemenLs and relaLlons
So lf you care abouL quallLy aLLrlbuLe Lhen deflne properLles LhaL wlll leL you analyze for ln Lhe
vlews LhaL are relaLed Lo achlevlng
Also as you read Chapters 1S remember LhaL a vlew may represenL more Lhan one sLyle ln facL
Lhls ls Lhe norm Slnce all nonLrlvlal sofLware sysLems employ many sLyles aL once mandaLlng LhaL

each vlew come from [usL one sLyle would resulL ln a pleLhora of vlews and a very Lhlck archlLecLure
documenL Some sLyles can be frulLfully comblned and LhaL comblnaLlon used Lo creaLe a vlew
ComponenLandconnecLor sLyles ln parLlcular Lend Lo comblne well and many archlLecLs produce a
slngle componenLandconnecLor vlew for Lhelr sysLem LhaL reflecLs all of Lhe CC sLyles Lhey used

ect|on 66 dlscusses whlch sLyles go LogeLher well Lo produce comblned vlews

8y learnlng Lhe pure" (uncomblned) sLyles however you can make more lnformed cholces abouL
whlch ones Lo comblne Lach comes wlLh lLs own vocabulary (of elemenL and relaLlon Lypes) you can
use Lhese vocabularles Lo bulld meanlngful comblned vlews LhaL carry forward Lhe pedlgree of each
of Lhelr consLlLuenL sLyles
l4 noLaLlons for ArchlLecLure vlews
noLaLlons for documenLlng vlews dlffer conslderably ln Lhelr degree of formallLy 8oughly speaklng
Lhere are Lhree maln caLegorles of noLaLlon

1hlnk carefully abouL Lhe cholce of deslgn noLaLlon for each dlagram ln your archlLecLure
documenLaLlon Conslder avallable Lool supporL Lhe knowledge and Lhe needs of Lhe documenLaLlon
sLakeholders and Lhe purpose of Lhe dlagrams (for example lmplemenLaLlon guldance analysls or
model and code generaLlon) Some archlLecLure lnformaLlon can be documenLed more effecLlvely
wlLh oLher noLaLlons

ofotmol oototloos vlews are deplcLed (ofLen graphlcally) uslng generalpurpose dlagrammlng and
edlLlng Lools and vlsual convenLlons chosen for Lhe sysLem aL hand 1he semanLlcs of Lhe descrlpLlon
are characLerlzed ln naLural language and cannoL be formally analyzed
5emlfotmol oototloos vlews are expressed ln a sLandardlzed noLaLlon LhaL prescrlbes graphlcal
elemenLs and rules of consLrucLlon buL does noL provlde a compleLe semanLlc LreaLmenL of Lhe
meanlng of Lhose elemenLs 8udlmenLary analysls can be applled Lo deLermlne lf a descrlpLlon
saLlsfles synLacLlc properLles unlfled Modellng Language (uML) ls a semlformal noLaLlon ln Lhls
sense
lotmol oototloos vlews are descrlbed ln a noLaLlon LhaL has a preclse (usually maLhemaLlcally based)
semanLlcs lormal analysls of boLh synLax and semanLlcs ls posslble 1here are a varleLy of formal
noLaLlons for sofLware archlLecLure avallable alLhough none of Lhem can be sald Lo be ln wldespread
use Cenerally referred Lo as arch|tecture descr|pt|on |anguages (AuLs) Lhey Lyplcally provlde boLh a
graphlcal vocabulary and an underlylng semanLlcs for archlLecLure represenLaLlon ln some cases
Lhese noLaLlons are speclallzed Lo parLlcular sLyles ln oLhers Lhey allow many sLyles or even provlde
Lhe ablllLy Lo formally deflne new sLyles 1he usefulness of AuLs lles ln Lhelr ablllLy Lo supporL

auLomaLlon Lhrough assoclaLed LoolsauLomaLlon Lo provlde useful analysls of Lhe archlLecLure or
auLomaLlon Lo asslsL ln code generaLlon
ueLermlnlng whlch form of noLaLlon Lo use lnvolves maklng several Lradeoffs 1yplcally moreformal
noLaLlons Lake more Llme and efforL Lo creaLe buL Lhey repay Lhls efforL ln reduced amblgulLy and
beLLer opporLunlLles for analysls Conversely morelnformal noLaLlons are easler Lo creaLe buL Lhey
provlde fewer guaranLees

An arch|tecture descr|pt|on |anguage ls a language for represenLlng a sofLware and/or sysLem
archlLecLure AuLs are usually graphlcal languages LhaL provlde semanLlcs LhaL enable analysls and
reasonlng abouL archlLecLures ofLen uslng assoclaLed Lools
Append|x C descrlbes one parLlcular archlLecLure descrlpLlon language called AAuL ln depLh 1he
Ior Iurther kead|ng" secLlon of Chapter 3 provldes resources for learnlng abouL oLher AuLs

We'll see examples of vlews rendered ln Lhese dlfferenL klnds of noLaLlons LhroughouLart I

1here ls no greaLer lmpedlmenL Lo Lhe advancemenL of knowledge Lhan Lhe amblgulLy of words
1homas 8eld ScoLLlsh phllosopher

l3 Lxamples
1hroughouL Lhls book buL especlally ln art I we wlll presenL many examples of archlLecLure
documenLaLlon fragmenLs exLracLed from real sysLems When you look aL Lhese examples please
keep ln mlnd Lhe followlng noLes
1he goal ls for you Lo undersLand Lhe klnds of lnformaLlon Lhe example conveys and how Lhe chosen
noLaLlon ls used Lo deplcL dlfferenL Lypes of elemenLs and relaLlons
1he goal ls usually noL for you Lo undersLand Lhe meanlng of Lhe speclflc elemenLs and relaLlons LhaL
ls Lhe responslblllLles Lhey saLlsfy Any sofLware sysLem uses acronyms and lnLernal [argon LhaL
become parL of Lhe vocabulary of Lhe sLakeholders famlllar wlLh LhaL sysLem 1he examples ln Lhe
book should allow you Lo recognlze whaL lnformaLlon Lhe archlLecL wanLed Lo capLure wlLhouL
knowlng Lhe meanlng of Lhese Lerms
lor each example Lhe plece exLracLed from Lhe orlglnal archlLecLure documenLaLlon ls Lyplcally [usL a
dlagram 1o LhaL dlagram we add a brlef descrlpLlon wlLh lnformaLlon LhaL can'L really be lnferred by
Lhe dlagram alone 1hls lnformaLlon comes from oLher parLs of each sysLem's archlLecLure
documenLaLlon LhaL are noL reproduced ln Lhe book A dlagram ls noL enough Lo documenL a vlew!

We chose dlagrams LhaL we Lhlnk are good examples of dlfferenL sLyles and noLaLlons Powever Lhey
may noL be perfecL wlLh respecL Lo noLaLlon cholce and usage dlagrammlng aesLheLlcs and quallLy
of Lhe deslgn lLself
very ofLen archlLecLure dlagrams do noL show a slngle sLyle ln lLs pure form ln many of our
examples you wlll be able Lo flnd vesLlges of sLyles oLher Lhan Lhe one Lhe dlagram ls lllusLraLlng
1haL's normal
1he example does noL necessarlly show Lhe laLesL verslon of Lhe deslgn


Module Views

ln Lhls chapLer we look aL Lhese aspecLs of module vlews
LlemenLs relaLlons and properLles
urpose
noLaLlon
8elaLlon Lo oLher vlews
1.2.1. Overview
ln Lhls chapLer and Lhe nexL we look aL ways Lo documenL Lhe module sLrucLures of a sysLem's
sofLware Such documenLaLlon enumeraLes Lhe prlnclpal lmplemenLaLlon unlLs or modules of a
sysLem LogeLher wlLh Lhe relaLlons among Lhese unlLs We refer Lo Lhese descrlpLlons asmoJole
lews As we wlll see Lhese vlews can be used for each of Lhe purposes ouLllned ln Lhe prologue
educaLlon communlcaLlon among sLakeholders and Lhe basls for consLrucLlon and analysls
1he way ln whlch a sysLem's sofLware ls decomposed lnLo manageable unlLs remalns one of Lhe
lmporLanL forms of sysLem sLrucLure AL a mlnlmum lL deLermlnes how a sysLem's source code ls
decomposed lnLo unlLs whaL klnds of assumpLlons each unlL can make abouL servlces provlded by
oLher unlLs and how Lhose unlLs are aggregaLed lnLo larger ensembles lL also lncludes global daLa
sLrucLures LhaL lmpacL and are lmpacLed by mulLlple unlLs Module sLrucLures ofLen deLermlne how
changes Lo one parL of a sysLem mlghL affecL oLher parLs and hence Lhe ablllLy of a sysLem Lo supporL
modlflablllLy porLablllLy and reuse

1he archlLecL musL be a propheL a propheL ln Lhe Lrue sense of Lhe Lerm lf he can'L see aL leasL
Len years ahead don'L call hlm an archlLecL
lrank Lloyd WrlghL

lL ls unllkely LhaL Lhe documenLaLlon of any sofLware archlLecLure can be compleLe wlLhouL aL leasL
one module vlew
We begln by conslderlng module vlews ln Lhe general form @ab|e 11 summarlzes Lhe dlscusslon ln
Lhe followlng secLlons abouL Lhe elemenLs relaLlons consLralnLs and purpose of Lhe module vlews
ln Chapter 2 we provlde Lhls lnformaLlon speclflc Lo each of a number of ofLen used module sLyles


@ab|e 11 ummary of the modu|e v|ews
L|ements Modules whlch are lmplemenLaLlon unlLs of sofLware LhaL provlde a coherenL
seL of responslblllLles
ke|at|ons s pott of whlch deflnes a parL/whole relaLlonshlp beLween Lhe submoduleLhe
parLand Lhe aggregaLe moduleLhe whole
uepeoJs oo whlch deflnes a dependency relaLlonshlp beLween Lwo modules
Speclflc module sLyles elaboraLe whaL dependency ls meanL
s o whlch deflnes a generallzaLlon/speclallzaLlon relaLlonshlp beLween a more
speclflc moduleLhe chlldand a more general moduleLhe parenL
Constra|nts ulfferenL module vlews may lmpose speclflc Lopologlcal consLralnLs
What It's
Ior
rovldlng a blueprlnL for consLrucLlon of Lhe code
laclllLaLlng lmpacL analysls
lannlng lncremenLal developmenL
SupporLlng requlremenLs LraceablllLy analysls
Lxplalnlng Lhe funcLlonallLy of Lhe sysLem and Lhe sLrucLure of Lhe code base
SupporLlng Lhe deflnlLlon of work asslgnmenLs lmplemenLaLlon schedules and
budgeL lnformaLlon
Showlng Lhe sLrucLure of lnformaLlon Lo be perslsLed

1.2.2. 1.2. Elements, Relations, and Properties of Module Views
... Flementx

A module ls an lmplemenLaLlon unlL of sofLware LhaL provldes a coherenL seL of responslblllLles
A responsibility ls a general sLaLemenL abouL an archlLecLure elemenL and whaL lL ls expecLed
Lo conLrlbuLe Lo Lhe archlLecLure 1hls lncludes Lhe acLlons LhaL lL performs Lhe knowledge lL
malnLalns Lhe declslons lL makes or Lhe role lL plays ln achlevlng Lhe sysLem's overall quallLy
aLLrlbuLes or funcLlonallLy


SysLem deslgners use Lhe Lerm module Lo refer Lo a wlde varleLy of sofLware sLrucLures
lncludlng programmlng language unlLssuch as C programs !ava or C# classes uelphl unlLs and
L/SCL sLored proceduresor slmply general grouplngs of source code unlLssuch as !ava packages
or C# namespaces ln Lhls book we adopL a much broader deflnlLlon
We characLerlze a module by enumeraLlng lLs seL of responsibilities whlch are
foremosL among a module's properLles 1hls broad noLlon of responslblllLles ls meanL Lo encompass
Lhe klnds of feaLures LhaL a unlL of sofLware mlghL provlde LhaL ls lLs funcLlonallLy and Lhe
knowledge lL malnLalns
Modules can be aggregaLed and decomposed Lach of Lhe varlous module sLyles ldenLlfles a dlfferenL
seL of modules and relaLlons and Lhen aggregaLes or decomposes Lhese modules based on relevanL
sLyle crlLerla lor example Lhe layered sLyle ldenLlfles modules and aggregaLes Lhem based on
an allowed-to-use relaLlon whereas Lhe generallzaLlon sLyle ldenLlfles and aggregaLes
modules based on whaL Lhey have ln common
ln Chapter 2 Lhe s-a relaLlon ls reflned Lo generallzaLlon ln Lhe generallzaLlon sLyle
... Relutlonx
Module vlews have Lhe followlng Lypes of relaLlons
s part of. 1he s-part-of relaLlon deflnes a parL/whole relaLlonshlp beLween Lhe
submoduleLhe parLand Lhe aggregaLe moduleLhe whole ln lLs mosL general form Lhe s-
part-ofrelaLlon slmply lndlcaLes aggregaLlon wlLh llLLle lmplled semanLlcs

ln Chapter 2 Lhe s-part-of relaLlon ls reflned Lo a decomposlLlon relaLlon ln Lhe
decomposlLlon sLyle

epends on. A depends on 8 deflnes a dependency relaLlon beLween A and 8
Many dlfferenL speclflc forms of dependency can be used ln module vlews LaLer we look aL four ln
parLlcular uses, allowed to use, crosscuts and daLa
enLlLy relatonshps ln Lhe module uses layered aspecL and daLa model sLyles
respecLlvely 1he loglcal assoclaLlon beLween classes (ln a uML class dlagram for example) also
deplcLs a dependency beLween Lhe classes


ln Chapter 2 Lhe depends-on relaLlon ls reflned Lo uses" ln Lhe uses sLyle
allowed Lo use" ln Lhe layered sLyle and crosscuL" ln Lhe aspecL sLyle

s a. 1he s-a relaLlon deflnes a generallzaLlon/speclallzaLlon relaLlonshlp beLween a more
speclflc moduleLhe chlldand a more general moduleLhe parenL 1he chlld ls able Lo be used ln
conLexLs ln whlch Lhe parenL ls used LaLer we look aL Lhls relaLlon ln more deLall ln Lhe
generallzaLlon sLyle Cb[ecLorlenLed lnherlLance and lnLerface reallzaLlon are speclal cases of
Lhe s-a relaLlon

... Propertlex
roperLles of modules LhaL help Lo gulde lmplemenLaLlon or are lnpuL Lo analysls should be recorded
as parL of Lhe supporLlng documenLaLlon for a module vlew 1he llsL of properLles may vary buL ls
llkely Lo lnclude Lhe followlng
ame. A module's name ls of course Lhe prlmary means Lo refer Lo lL A module's name ofLen
suggesLs someLhlng abouL lLs role ln Lhe sysLem a module called accounL_mgr" for lnsLance
probably has llLLle Lo do wlLh numerlc slmulaLlons of chemlcal reacLlons ln addlLlon a module's
name may reflecL lLs poslLlon ln a decomposlLlon hlerarchy Lhe name A8C" for example refers Lo
a module C LhaL ls a submodule of a module 8 lLself a submodule of A
#espons-lty. 1he responslblllLy properLy of a module ls a way Lo ldenLlfy lLs role ln Lhe
overall sysLem and esLabllshes an ldenLlLy for lL beyond Lhe name Whereas a module's name may
suggesL lLs role a sLaLemenL of responslblllLy esLabllshes lL wlLh much more cerLalnLy
8esponslblllLles should be descrlbed ln sufflclenL deLall Lo make clear Lo Lhe reader whaL each
module does

uocumenLlng sofLware lnLerfaces ls dlscussed ln Chapter 7

's-lty of nterface(s). When a module has submodules some lnLerfaces of Lhe
submodules may have lnLernal purposes LhaL ls Lhe lnLerfaces are used only by Lhe submodules
wlLhln Lhe encloslng parenL module 1hese lnLerfaces are noL vlslble ouLslde LhaL conLexL and
Lherefore do noL have a dlrecL relaLlonshlp Lo Lhe parenL lnLerfaces ulfferenL sLraLegles can be used
for Lhose lnLerfaces LhaL have a dlrecL relaLlonshlp Lo Lhe parenL lnLerfaces 1he sLraLegy shown

ln igure 1.1(a) ls encapsulaLlon 1he parenL module provldes lLs own lnLerfaces and
maps all requesLs Lo Lhe capablllLles provlded by Lhe submodules 1he faclllLles of Lhe enclosed
modules are noL avallable ouLslde Lhe parenL AlLernaLlvely Lhe lnLerfaces of an aggregaLe module
can be a subseL of Lhe lnLerfaces of lLs submodules 1he aggregaLe module selecLlvely exposes some
of Lhe lnLerfaces of Lhe submodules Layers and subsysLems are ofLen deflned ln Lhls way lor
example lf module C ls an aggregaLe of modules A and 8 C's lmpllclL lnLerface wlll be a subseL of Lhe
lnLerfaces of modules A and 8 (see igure 1.1(b))
Figuie .. (a) Nouule C pioviues its own inteiface, hiuing the inteifaces of mouules A anu B. (b)
Nouule C exposes a subset of the inteifaces of mouules A anu B as its inteiface.

mplementaton nformaton. 8ecause modules are unlLs of lmplemenLaLlon
lL ls useful Lo record lnformaLlon relaLed Lo Lhelr lmplemenLaLlon from Lhe polnL of vlew of managlng
Lhelr developmenL and bulldlng Lhe sysLem LhaL conLalns Lhem AlLhough Lhls lnformaLlon ls noL
sLrlcLly speaklng archlLecLural lL may be useful Lo record lL ln Lhe archlLecLuredocumenLaLlon where
Lhe module ls deflned lmplemenLaLlon lnformaLlon mlghL lnclude
,opploq to sootce coJe oolts 1hls ldenLlfles Lhe flles LhaL consLlLuLe
Lhe lmplemenLaLlon of a module lor example a module named
AccounL lf lmplemenLed ln !ava mlghL have several flles LhaL
consLlLuLe lLs lmplemenLaLlon lAccounL[ava (an lnLerface)
AccounLlmpl[ava (an lmplemenLaLlon of AccounL funcLlonallLy)
AccounL8ean[ava (a class Lo hold Lhe sLaLe of an accounL ln memory)
AccounLCrmMapplngxml (a flle LhaL deflnes Lhe mapplng beLween
AccounL8ean and a daLabase Lableob[ecLrelaLlonal mapplng) and
perhaps even a unlL LesL AccounL1esL[ava

ln addlLlon Lo ldenLlfylng Lhe lmplemenLaLlon unlLs one also needs Lo ldenLlfy where Lhey reslde ln a
pro[ecL's flllng scheme a dlrecLory or folder ln a flle sysLem a u8L ln an lnLraneL or a locaLlon ln a
conflguraLlon managemenL sysLem's sLorage space 1hls lnformaLlon ls ln Lhe purvlew of Lhe
lmplemenLaLlon sLyle dlscussed ln $ection 5.5

@est lofotmotloo 1he module's LesL plan LesL cases LesL scaffoldlng
and LesL daLa are lmporLanL Lo sLore

,oooqemeot lofotmotloo A manager may need lnformaLlon abouL
Lhe module's predlcLed schedule and budgeL
mplemeototloo coosttolots ln many cases Lhe archlLecL wlll have a
cerLaln lmplemenLaLlon sLraLegy ln mlnd for a module or may know
of consLralnLs LhaL Lhe lmplemenLaLlon musL follow 1hls lnformaLlon
ls prlvaLe Lo Lhe module and hence wlll noL appear for example ln
Lhe module's lnLerface
Module sLyles may have properLles of Lhelr own ln addlLlon Lo Lhese Also you may flnd oLher
properLles useful LhaL are noL llsLed
arL l A CollecLlon of SofLware ArchlLecLure SLyles
The starting point of architecture design is most often a preexisting
package of design decisions. Very few architects design systems
completely by closing their eyes, thinking hard, and conjuring up a
brand-new design.
A most useful package of design decisions is the archtecture
style. Chapters 15 present a range of important and widely
used architecture styles. The emphasis here is on how to document a
view that results from the use of a style.
l1 1hree CaLegorles of SLyles
Chapters 15 are organized along the lines of the three
categories of styles we discussed in the prologue: module styles
(Chapters 1 and 2), component-and-connector (C&C) styles
(Chapters 3 and 4), and allocation styles (Chapter 5). Plan
for your documentation package to include at least one module view, at
least one component-and-connector view, and at least one allocation
view.
Modules are the primary elements of module styles. A module is
an implementation unit that provides a coherent set of responsibilities.
A module might take the form of a class, a collection of classes, a
layer, an aspect, or any decomposition of the implementation unit.
Every module has a collection of properties assigned to it. These
properties are intended to express the important information
associated with the module, as well as constraints on the module.
Sample properties are responsibilities, visibility information, and author

or owner. The relations that modules have to one another include s
part of, depends on, and s a.

A module style is a kind of style that introduces a specific set of
module types and specifies rules about how elements of those types
can be combined.
Module styles are described in Chapters 1 and 2.

Component-and-connector styles express runtime
behavior. They are described in terms of components and connectors.
A component is one of the principal processing units of the executing
system. Components might be services, processes, threads, filters,
repositories, peers, or clients and servers, to name a few. A connector
is the interaction mechanism among components. Connectors include
pipes, queues, request/reply protocols, direct invocation, event-driven
invocation, and so forth. Components and connectors can be
decomposed into other components and connectors. The decomposition
of a component may include connectors and vice versa.

A component-and-connector style is a kind of style
that introduces a specific set of component and connector types and
specifies rules about how elements of those types can be combined.
Additionally, given that C&C views capture runtime aspects of a
system, a C&C style is typically also associated with a computational
model that prescribes how data and control flow through systems
designed in that style.
C&C styles are described in Chapters 3 and 4.

llocation styles describe the mapping of software units to
elements of an environment in which the software is developed or
executes. The environment might be the hardware, the file systems
supporting development or deployment, or the development
organization(s).
l2 SLyle Culdes A SLandard CrganlzaLlon for Lxplalnlng a SLyle

Styles presented together for comparison and selection should be
described consistently with each other. In this way, an architect can
better make an informed decision about which one(s) to use. This is an
application of the fourth rule for sound documentation: Use a standard
organization. The outline used for describing a style is called a style
guide.

An allocation style is a kind of style that describes the mapping
of software units to elements of an environment in which the software
is developed or executes.
Allocation styles are described in Chapter 5.

The styles in Chapters 15 are presented using the form of a
style guide. Below is the outline for that style guide.
CuLllne lor a SLyle Culde
;er;ew. The overview in a style guide explains why this style is
useful. It discusses what it is about a system that the style
addresses and how it supports reasoning about systems.

A style guide is the description of an architecture style that
specifies the vocabulary of design (sets of element and
relationship types) and rules (sets of topological and semantic
constraints) for how that vocabulary can be used.

lement types, relaton types, and propertes.
lements are the architecture building blocks native to the
style. A style guide defines one or more element types,
instances of which will populate an architecture that uses that
style.
Relations determine how the elements work together to
accomplish the work of the system. A style guide defines one or
more relation types that apply to the styles element types. An
architecture using the style will describe the relations (instances
of the relation type) that determine how the elements can work

together, and any important properties of those relations. The
style guide provides rules on how elements can and cannot be
related.

An element is an architecture building block native to the style.
An element can be a module, a component or connector, or an
element in the environment of the system whose architecture
we are documenting. The description of an element tells what
role it plays in an architecture, lists its important properties,
and furnishes guidelines for effective documentation of the
element in a view.
A relation defines how elements cooperate to accomplish the
work of the system. The description of a relation names the
relations among elements and provides rules on how elements
can and cannot be related.
A property contains additional information about elements and
relations. A style definition includes the property name and
description. When an architect documents a view based on that
style, the properties will be given values. Property values are
often used to analyze an architecture for its ability to meet
quality attribute requirements.

onstrants. This section of the style guide lists the rules for
putting the elements and relations together to form a valid
instance of the style. For example, in a pipe-and-filter style, a
pipe is allowed to attach to a filter, but not to another pipe. In a
layered style, the layers are laid out adjacently in a stack, not
scattered about randomly. In a work-assignment style, every
software unit has to be allocated to at least one organizational
element.
hat ts for. This section of the style guide describes the kind of
reasoning supported by views in the style. The intent is to help
the architect understand to what purpose(s) a view in this style
may be put. This might be how using the style helps in the
development process (for example, the "uses style is good for
reasoning about modifiability). Or it might be about how the
style helps the product (for instance, pipe-and-filter yields good
performance when processing a series of data elements).
otatons. This section of the style guide will give descriptions of

graphical and/or textual representations that are available and
useful to document views in the style. Different notations will
also support the conveyance of different kinds of information in
the view.
#elaton to other styles. This section of the style guide describes
how views derived from this style might be related to views
derived from different styles. For example, views from two
different styles might convey different but related information
about a system, and the architect would like a way to choose
which one to use. This section might also include warnings
about other views with which a particular view is often
confused, to the detriment of the system and its stakeholders.
(Layers and tiers are a good example of this. They are
fundamentally different, but are often [mis]used
interchangeably.)
amples. This section provides or points to an example of a
documented view derived from the given style.

l3 Chooslng Whlch LlemenL and 8elaLlon roperLles Lo uocumenL
The discussion in Chapters 15 heavily emphasizes styles, which
are documented in published style guides. But as you read about the
styles in Part I, remember that the end game is to produce views
based on the chosen style. Recall that a view is a representation of a
style applied to a particular system-in this case the system whose
architecture is being documented.

When documenting a view, decide on the list of properties to document
about the elements in that view. Choose properties that will aid the
analysis you wish the documentation to support. Documenting a view,
then, includes documenting the values for the properties you chose.

One of the tasks in documenting a view is deciding which properties of
elements to document. Recall from our preceding discussion of style
guides that properties are additional information about the elements
and their relations that are useful to document. The styles of

Chapters 15 are each described with a set of properties likely to
be useful; consider them suggestions.
Properties almost always include the name of the element as well as
some description of its role or responsibility in the architecture. For
example, properties of a layer-an element of the layered style, which
is one of the module styles-should include the layers name, the units
of software the layer contains, and the nature of the capabilities that
the layer provides. A layered view will then, for each layer, specify its
name, the units of software it contains, and the capabilities it provides.
Beyond these basic properties, however, are properties that will
support architecture-based analysis. If you want to analyze an
architecture for performance, then properties in some views probably
should include an elements best- and worst-case response times, or
the maximum number of events an element can service per time unit.
If you want to analyze an architecture for security, then you probably
want to document properties that explain levels of encryption and
authorization rules for different elements and relations.
So: If you care about quality attribute , then define properties that
will let you analyze for in the views that are related to achieving .
Also as you read Chapters 15, remember that a view may
represent more than one style. In fact, this is the norm. Since all
nontrivial software systems employ many styles at once, mandating
that each view come from just one style would result in a plethora of
views and a very thick architecture document. Some styles can be
fruitfully combined, and that combination used to create a view.
Component-and-connector styles in particular tend to combine well,
and many architects produce a single component-and-connector view
for their system that reflects all of the C&C styles they used.

$ection 6.6 discusses which styles go together well to produce
combined views.

By learning the "pure (uncombined) styles, however, you can make
more informed choices about which ones to combine. Each comes with
its own vocabulary (of element and relation types); you can use these
vocabularies to build meaningful combined views that carry forward the
pedigree of each of their constituent styles.

l4 noLaLlons for ArchlLecLure vlews
otations for documenting views differ considerably in their degree of
formality. Roughly speaking, there are three main categories of
notation:

Think carefully about the choice of design notation for each diagram in
your architecture documentation. Consider available tool support, the
knowledge and the needs of the documentation stakeholders, and the
purpose of the diagrams (for example, implementation guidance,
analysis, or model and code generation). Some architecture
information can be documented more effectively with other notations.

nformal notatons. Views are depicted (often graphically)
using general-purpose diagramming and editing tools and visual
conventions chosen for the system at hand. The semantics of the
description are characterized in natural language and cannot be
formally analyzed.
Semformal notatons. Views are expressed in a standardized
notation that prescribes graphical elements and rules of construction,
but does not provide a complete semantic treatment of the meaning of
those elements. Rudimentary analysis can be applied to determine if a
description satisfies syntactic properties. Unified Modeling Language
(UML) is a semiformal notation in this sense.
Formal notatons. Views are described in a notation that has a
precise (usually mathematically based) semantics. Formal analysis of
both syntax and semantics is possible. There are a variety of formal
notations for software architecture available, although none of them
can be said to be in widespread use. Generally referred to as
architecture description languages (ADLs), they
typically provide both a graphical vocabulary and an underlying
semantics for architecture representation. In some cases these
notations are specialized to particular styles. In others they allow many
styles, or even provide the ability to formally define new styles. The
usefulness of ADLs lies in their ability to support automation through
associated tools-automation to provide useful analysis of the
architecture, or automation to assist in code generation.
Determining which form of notation to use involves making several
trade-offs. Typically more-formal notations take more time and effort

to create, but they repay this effort in reduced ambiguity and better
opportunities for analysis. Conversely, more-informal notations are
easier to create, but they provide fewer guarantees.

An architecture description language is a language for
representing a software and/or system architecture. ADLs are usually
graphical languages that provide semantics that enable analysis and
reasoning about architectures, often using associated tools.
ppendix C describes one particular architecture description
language, called AADL, in depth. The "or urther Reading
section of Chapter 3 provides resources for learning about other
ADLs.

Well see examples of views rendered in these different kinds of
notations throughout Part I.

There is no greater impediment to the advancement of knowledge than
the ambiguity of words.
-Thomas Reid, Scottish philosopher

l3 Lxamples
Throughout this book, but especially in Part I, we will present many
examples of architecture documentation fragments extracted from real
systems. When you look at these examples, please keep in mind the
following notes:
The goal is for you to understand the kinds of information the example
conveys and how the chosen notation is used to depict different types
of elements and relations.
The goal is usually not for you to understand the meaning of the
specific elements and relations, that is, the responsibilities they satisfy.
Any software system uses acronyms and internal jargon that become
part of the vocabulary of the stakeholders familiar with that system.
The examples in the book should allow you to recognize what

information the architect wanted to capture without knowing the
meaning of these terms.
For each example, the piece extracted from the original architecture
documentation is typically just a diagram. To that diagram we add a
brief description with information that cant really be inferred by the
diagram alone. This information comes from other parts of each
systems architecture documentation that are not reproduced in the
book. A diagram is not enough to document a view!
We chose diagrams that we think are good examples of different styles
and notations. However, they may not be perfect with respect to
notation choice and usage, diagramming aesthetics, and quality of the
design itself.
Very often architecture diagrams do not show a single style in its pure
form. In many of our examples, you will be able to find vestiges of
styles other than the one the diagram is illustrating. Thats normal.
The example does not necessarily show the latest version of the
design.

1 Module vlews

In this chapter, we look at these aspects of module views:
Elements, relations, and properties
Purpose
otation
Relation to other views
11 Cvervlew
In this chapter and the next, we look at ways to document the module
structures of a systems software. Such documentation enumerates the
principal implementation units, or modules, of a system, together with
the relations among these units. We refer to these descriptions as

module ;ews. As we will see, these views can be used for each of
the purposes outlined in the prologue: education, communication
among stakeholders, and the basis for construction and analysis.
The way in which a systems software is decomposed into manageable
units remains one of the important forms of system structure. At a
minimum, it determines how a systems source code is decomposed
into units, what kinds of assumptions each unit can make about
services provided by other units, and how those units are aggregated
into larger ensembles. It also includes global data structures that
impact and are impacted by multiple units. Module structures often
determine how changes to one part of a system might affect other
parts and hence the ability of a system to support modifiability,
portability, and reuse.

The architect must be a prophet . . . a prophet in the true sense of the
term . . . if he cant see at least ten years ahead dont call him an
architect.
-Frank Lloyd Wright

It is unlikely that the documentation of any software architecture can
be complete without at least one module view.
We begin by considering module views in the general form. %able
1.1 summarizes the discussion in the following sections about the
elements, relations, constraints, and purpose of the module views. In
Chapter 2 we provide this information specific to each of a number
of often used module styles.
1able 11 Summary of Lhe module vlews
lements Modules whlch are lmplemenLaLlon unlLs of sofLware LhaL provlde a coherenL seL of
responslblllLles
Relations
s part of, which defines a part/whole relationship between
the submodule-the part-and the aggregate module-the
whole.
epends on, which defines a dependency relationship
between two modules. Specific module styles elaborate

1able 11 Summary of Lhe module vlews
lements Modules whlch are lmplemenLaLlon unlLs of sofLware LhaL provlde a coherenL seL of
responslblllLles
what dependency is meant.
s a, which defines a generalization/specialization
relationship between a more specific module-the child-
and a more general module-the parent.
Constraints ulfferenL module vlews may lmpose speclflc Lopologlcal consLralnLs
What It's
or
Providing a blueprint for construction of the code
Facilitating impact analysis
Planning incremental development
Supporting requirements traceability analysis
Explaining the functionality of the system and the structure
of the code base
Supporting the definition of work assignments,
implementation schedules, and budget information
Showing the structure of information to be persisted

Documenting Software Architectures

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Documenting Software Architectures

Uploaded by

Copyright:

Available Formats

SlsLema de 1elegesLln de usuarlos glna 1

SMA81C8lu ulseno de la arqulLecLura del SlsLema de 1elegesLln y Medlda

You might also like