The C4 model for visualising software architecture Simon Brown Thisbookisforsaleathttp://leanpub.com/visualising-software-architecture Thisversionwaspublishedon2022-05-28 ThisisaLeanpubbook.LeanpubempowersauthorsandpublisherswiththeLean Publishingprocess.LeanPublishingistheactofpublishinganin-progressebookusing lightweighttoolsandmanyiterationstogetreaderfeedback,pivotuntilyouhavetheright bookandbuildtractiononceyoudo. ©2015-2022SimonBrown Tweet This Book! PleasehelpSimonBrownbyspreadingthewordaboutthisbookonTwitter! Thesuggestedhashtagforthisbookis#sa4d. Findoutwhatotherpeoplearesayingaboutthebookbyclickingonthislinktosearchfor thishashtagonTwitter: #sa4d ForKirstie,MatthewandOliver Contents 1. Aboutthebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2. Abouttheauthor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Wehaveafailuretocommunicate . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1 WhathappenedtoSSADM,RUP,UML,etc? . . . . . . . . . . . . . . . . . . 4 3.2 Alightweightapproach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.3 Drawoneormorediagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 3.4 Wheredowestart?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.5 Someexamples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.6 Commonproblems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 3.7 Thehiddenassumptionsofdiagrams . . . . . . . . . . . . . . . . . . . . . . 20 4. Asharedvocabulary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.1 Commonabstractionsoveracommonnotation . . . . . . . . . . . . . . . . 21 4.2 Staticstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 4.3 Componentsvscode? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 4.4 Modulesandsubsystems? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 4.5 Microservices? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.6 Serverless?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 4.7 Platforms,frameworksandlibraries? . . . . . . . . . . . . . . . . . . . . . . 32 4.8 Createyourownsharedvocabulary . . . . . . . . . . . . . . . . . . . . . . . 32 5. TheC4model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 5.1 Hierarchicalmapsofyourcode. . . . . . . . . . . . . . . . . . . . . . . . . . 34 6. Level1:SystemContextdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 6.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 CONTENTS 6.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 6.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 6.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 7. Level2:Containerdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 7.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 7.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 7.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 7.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 8. Level3:Componentdiagram . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 8.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 8.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 8.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 8.4 Interactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 8.5 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 8.6 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 8.7 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 9. Level4:Code-leveldiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 9.1 Intent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 9.2 Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 9.3 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 9.4 Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 9.5 Requiredoroptional? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 10. Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 10.1 Titles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 10.2 Keysandlegends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 10.3 Elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 10.4 Lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 10.5 Layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 10.6 Orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 10.7 Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 10.8 Qualityattributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 CONTENTS 10.9 Diagramscope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 10.10 Listenforquestions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 11. Diagramsmustreflectreality. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 11.1 Themodel-codegap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 11.2 Technologydetailsondiagrams . . . . . . . . . . . . . . . . . . . . . . . . . 74 11.3 Wouldyoucodeitthatway? . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 12. Deploymentdiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 12.1 Networkandinfrastructurediagrams . . . . . . . . . . . . . . . . . . . . . . 79 12.2 Deploymentdiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 12.3 Cloudarchitecturediagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 13. Otherdiagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 13.1 Architecturalviewmodels . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84 13.2 SystemLandscape . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 13.3 Userinterfacemockupsandwireframes . . . . . . . . . . . . . . . . . . . . . 90 13.4 Businessprocessandworkflow. . . . . . . . . . . . . . . . . . . . . . . . . . 90 13.5 Domainmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 13.6 Runtimeandbehaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 13.7 Andmore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 14. AppendixA:FinancialRiskSystem . . . . . . . . . . . . . . . . . . . . . . . . . . 96 14.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 14.2 FunctionalRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 14.3 Non-functionalRequirements . . . . . . . . . . . . . . . . . . . . . . . . . . 97 1. About the book I graduated from university in 1996, a time when CASE and modeling tools were popular and in common use. I remember attending a training course about the Unified Modeling Language and the SELECT tooling soon after I started my professional career. A number oftheprojectsIworkedonmadeextensiveuseoftoolslikeSELECTandRationalRosefor diagramminganddocumentingthedesignofsoftwaresystems.Withbuggyuserinterfaces and ugly diagrams, the tooling may not have been brilliant back then, but it was still very usefulifusedinapragmaticway. I’mverymuchavisualperson.Ilikebeingabletovisualiseaproblembeforetryingtofind a solution. Describe a business process to me and I’ll sketch up a summary of it. Talk to meaboutabusinessproblemandI’mlikelytodrawahigh-leveldomainmodel.Visualising theproblemisawayformetoaskquestionsandfigureoutwhetherI’veunderstoodwhat you’resaying.Ialsolikesketchingoutsolutionstoproblems,againbecauseit’sagreatway togeteverythingoutintotheopeninawaythatotherpeoplecanunderstandquickly. Butthensomethinghappenedsomewhereduringtheearly2000s,probablyasaresultofthe ManifestoforAgileSoftwareDevelopmentthathadbeenpublishedafewyearsbeforehand. The way teams built software started to change, with things like diagramming and docu- mentation being thrown away alongside big design up front. I remember seeing a number ofsoftwaredevelopmentteamsreducingthequantityofdiagramsanddocumentationthey werecreating.Infact,IwasoftentheonlypersonontheteamwhoreallyunderstoodUML wellenoughtocreatediagramswithit. Fast forward to the present day, and creating software architecture diagrams seems to be somethingofalostart.I’vebeenrunningsoftwarearchitecturetrainingcoursesforanumber of years, part of which is a simple architecture kata where groups of people are asked to designasoftwaresolutionanddrawsomearchitecturediagramstodescribeit.Over10,000 peopleand30+countrieslater,Ihavegigabytesofanecdotalphotoevidence-themajority ofthediagramsuseanadhoc“boxesandlines”notationwithnoclearnotationorsemantics. Designingsoftwareiswherethecomplexityshouldbe,notcommunicatingit. Thisbookfocussesonthevisualcommunicationanddocumentationofsoftwarearchitecture. I’veseenanumberofdebatesovertheyearsaboutwhethersoftwaredevelopmentisanart, acraftoranengineeringdiscipline.AlthoughIthinkitshould beanengineeringdiscipline, Ibelievewe’reanumberofyearsawayfromthisbeingareality.Sowhilethisbookdoesn’t Aboutthebook 2 present a formalised, standardised method to communicate software architecture, it does provideacollectionoflightweightideasandtechniquesthatthousandsofpeopleacrossthe worldfinduseful.Thecoreofthisismy“C4model”forvisualisingsoftwarearchitecture. 2. About the author I’m an independent software development consultant specialising in software architecture; specifically technical leadership, communication and lightweight, pragmatic approaches to software architecture. In addition to being the author of Software Architecture for Developers, I’m the creator of the C4 software architecture model and I built Structurizr, which is a collection of tooling to help you visualise, document and explore your software architecture. I regularly speak at software development conferences, meetups and organisations around the world; delivering keynotes, presentations and workshops about software architecture. In 2013, I won the IEEE Software sponsored SATURN 2013 “Architecture in Practice” Presentation Award for my presentation about the conflict between agile and architecture. I’vespokenateventsand/orhaveclientsinoverthirtycountriesaroundtheworld. Youcanfindmywebsiteatsimonbrown.jeandIcanbefoundonTwitterat@simonbrown.