Table Of ContentVisualise, document and explore your
software architecture
Software Architecture for Developers - Volume 2
Simon Brown
Thisbookisforsaleathttp://leanpub.com/visualising-software-architecture
Thisversionwaspublishedon2019-09-20
ThisisaLeanpubbook.LeanpubempowersauthorsandpublisherswiththeLean
Publishingprocess.LeanPublishingistheactofpublishinganin-progressebookusing
lightweighttoolsandmanyiterationstogetreaderfeedback,pivotuntilyouhavetheright
bookandbuildtractiononceyoudo.
©2015-2019SimonBrown
Tweet This Book!
PleasehelpSimonBrownbyspreadingthewordaboutthisbookonTwitter!
Thesuggestedhashtagforthisbookis#sa4d.
Findoutwhatotherpeoplearesayingaboutthebookbyclickingonthislinktosearchfor
thishashtagonTwitter:
#sa4d
ForKirstie,MatthewandOliver
Contents
Aboutthebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . i
Abouttheauthor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . iii
I Visualise
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1. Wehaveafailuretocommunicate . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1 WhathappenedtoSSADM,RUP,UML,etc? . . . . . . . . . . . . . . . . . . 2
1.2 Alightweightapproach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Movingfastrequiresgoodcommunication . . . . . . . . . . . . . . . . . . . 4
1.4 Drawoneormorediagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.5 Wheredowestart?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.6 Someexamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.7 Commonproblems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.8 Thehiddenassumptionsofdiagrams . . . . . . . . . . . . . . . . . . . . . . 19
2. Asharedvocabulary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1 Commonabstractionsoveracommonnotation . . . . . . . . . . . . . . . . 20
2.2 Staticstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.3 Componentsvscode? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.4 Modulesandsubsystems? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.5 Microservices? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.6 Serverless?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.7 Platforms,frameworksandlibraries? . . . . . . . . . . . . . . . . . . . . . . 31
2.8 Createyourownsharedvocabulary . . . . . . . . . . . . . . . . . . . . . . . 31
3. TheC4model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1 Hierarchicalmapsofyourcode. . . . . . . . . . . . . . . . . . . . . . . . . . 33
CONTENTS
4. Level1:SystemContextdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
5. Level2:Containerdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
5.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
5.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
6. Level3:Componentdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
6.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
6.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
6.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
6.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
7. Level4:Code-leveldiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
7.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
7.5 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
8. Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8.1 Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8.2 Keysandlegends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
8.4 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
CONTENTS
8.5 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.6 Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
8.7 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.8 Qualityattributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
8.9 Diagramscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
8.10 Listenforquestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
9. Diagramsmustreflectreality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.1 Themodel-codegap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
9.2 Technologydetailsondiagrams . . . . . . . . . . . . . . . . . . . . . . . . . 73
9.3 Wouldyoucodeitthatway? . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
10. Otherdiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
10.1 Architecturalviewmodels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
10.2 SystemLandscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
10.3 Userinterfacemockupsandwireframes . . . . . . . . . . . . . . . . . . . . . 84
10.4 Businessprocessandworkflow. . . . . . . . . . . . . . . . . . . . . . . . . . 84
10.5 Domainmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.6 Runtimeandbehaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
10.7 Infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
10.8 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
10.9 Andmore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
II Document
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
11. Softwaredocumentationasaguidebook . . . . . . . . . . . . . . . . . . . . . . . 94
11.1 Thecodedoesn’ttellthewholestory . . . . . . . . . . . . . . . . . . . . . . 94
11.2 Ourdutytodeliverdocumentation . . . . . . . . . . . . . . . . . . . . . . . 96
11.3 Lightweight,supplementarydocumentation . . . . . . . . . . . . . . . . . . 97
11.4 1.Maps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
11.5 2.Sights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
11.6 3.Historyandculture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
11.7 4.Practicalinformation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
11.8 Describewhatyoucan’tgetfromthecode . . . . . . . . . . . . . . . . . . . 101
11.9 Productvsprojectdocumentation . . . . . . . . . . . . . . . . . . . . . . . . 102
11.10 Keepingdocumentationuptodate . . . . . . . . . . . . . . . . . . . . . . . . 103
11.11 Documentationlength . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
CONTENTS
12. Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
12.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
13. FunctionalOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
13.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
13.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
13.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
14. QualityAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
14.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
14.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
14.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
14.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
14.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
15. Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
15.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
15.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
15.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
15.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
15.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
16. Principles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
16.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
16.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
16.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
16.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
16.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
17. SoftwareArchitecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
17.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
17.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
17.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
CONTENTS
17.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
17.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
18. Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
18.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
18.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
18.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
18.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
18.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
19. Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
19.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
19.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
19.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
19.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
19.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
20. InfrastructureArchitecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
20.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
20.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
20.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
20.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
20.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
21. Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
21.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
21.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
21.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
21.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
21.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
22. OperationandSupport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
22.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
22.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
22.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
22.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
22.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
23. DevelopmentEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
23.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
CONTENTS
23.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
23.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
23.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
23.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
24. DecisionLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
24.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
24.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
24.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
24.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
24.5 Required . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
III Tooling
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
25. Sketches,diagrams,modelsandtooling . . . . . . . . . . . . . . . . . . . . . . . 132
25.1 Sketches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
25.2 Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
25.3 Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
25.4 Reverse-engineeringthesoftwarearchitecturemodel . . . . . . . . . . . . . 138
25.5 Architecturedescriptionlanguages . . . . . . . . . . . . . . . . . . . . . . . 142
25.6 Structurizr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
25.7 Minimisethemodel-codegap. . . . . . . . . . . . . . . . . . . . . . . . . . . 155
26. TheC4modelwithothernotationsandtools . . . . . . . . . . . . . . . . . . . . 156
26.1 Boxesandlines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
26.2 UML(withamodelingtool) . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
26.3 UML(withPlantUML) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
27. Exploringyoursoftwarearchitecturemodel. . . . . . . . . . . . . . . . . . . . . 169
27.1 Staticstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
27.2 Dependencymaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
27.3 Componentsizeorcomplexity . . . . . . . . . . . . . . . . . . . . . . . . . . 173
27.4 Otherwaystoexplore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
28. AppendixA:FinancialRiskSystem . . . . . . . . . . . . . . . . . . . . . . . . . . 177
28.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
28.2 FunctionalRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
28.3 Non-functionalRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . 178
