Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019

Summary

In this engaging talk at Agile on the Beach 2019, Simon Brown delves into the effective methods of diagramming and explaining software architecture using the C4 model. He criticizes the overuse and confusion surrounding UML and advocates for a focus on engineering rather than artistry in diagram creation. Brown introduces the C4 model—a hierarchical approach involving context, containers, components, and code diagrams—to better communicate software systems to various audiences, emphasizing the importance of clear storytelling, consistent notation, and meaningful diagrams.

Highlights

• Simon Brown shares the pitfalls of using UML for software architecture diagrams due to its complexity and the misunderstandings it often creates. ❌
• He introduces the C4 model, which prioritizes different abstraction levels to create meaningful diagrams. 🎯
• Brown humorously critiques poor diagramming practices, highlighting the universal issue of ineffective communication through diagrams. 😂
• The talk underscores the need for diagrams to stand alone, providing clear insights without requiring additional explanations. 🚦
• Brown advises against using general-purpose diagramming tools, advocating for software-focused solutions to depict architecture. ⚙️

Key Takeaways

• Simon Brown emphasizes the importance of storytelling in software architecture diagrams to ensure clear communication amongst diverse audiences. 🎨
• The C4 model, consisting of context, containers, components, and code diagrams, helps visualize different levels of a software system's architecture effectively. 📊
• A good architecture diagram should reflect reality and be understood by developers, not just architects. 🚀
• It's crucial to focus on abstractions first, before diving into notation when crafting diagrams. 💡
• Understanding and clarity in software architecture diagrams can prevent miscommunication and inefficiencies in team collaborations. 📞

Overview

Simon Brown captivates the audience by addressing a common issue in software development: the ineffective communication of software architecture. He introduces himself as a consultant who frequently encounters the misuse of UML and the resulting confusion. Brown charmingly critiques this reliance on outdated methods and pushes for more thoughtful approaches.

The core of his presentation revolves around the C4 model—a structured, multi-level diagramming approach. By focusing on context, containers, components, and ultimately code, Brown demonstrates how to construct diagrams that are not only informative but also visually cohesive. He embeds humor and real-world examples to emphasize the common mistakes and how these can be avoided through clear, structured diagramming.

In concluding his talk, Simon Brown emphasizes the significance of storytelling in software architecture. He insists that effective diagrams should be self-explanatory, reducing the need for accompanying narration. Brown’s advice challenges software professionals to rethink their current practices and adopt new, more effective ways to communicate complex systems within their teams.

Chapters

• 00:00 - 01:00: Introduction to Software Architecture Diagramming The chapter introduces software architecture and the importance of diagramming in explaining and describing software architecture. Simon Brown, an independent consultant specializing in software architecture, leads the discussion. He starts by addressing the use of UML for creating these diagrams, noting that not everyone uses it, based on his observations while traveling globally.
• 01:00 - 05:00: Challenges with UML and Diagramming Practices The chapter discusses challenges associated with using UML (Unified Modeling Language) and diagramming practices in companies. It mentions that despite UML being a traditional tool, there are numerous reasons and excuses people give for avoiding its usage. A book titled '97 Ways to Sidestep UML' by No Formality is referenced as a source of various arguments against UML. Some excuses seem unreasonable, including the perception that using UML makes one appear old-fashioned.
• 05:00 - 09:00: Problems with Common Architecture Diagrams The chapter discusses the challenges associated with using common architecture diagrams in agile environments. It highlights the industry's tendency to avoid using UML (Unified Modeling Language) and the perpetuation of myths and excuses for not utilizing it. Instead, there is a recommendation to use a whiteboard for drawing architecture diagrams to convey software architecture, but it points out a critical gap: people are not taught how to effectively use whiteboards for this purpose.
• 09:00 - 12:00: The Importance of Clear Diagramming This chapter explores the significance of clear diagramming in software architecture. The narrator describes how they conduct diagramming exercises around the world, providing requirements and asking participants to draw architectural diagrams. Through this process, various types of diagrams are created, including one likened to the complexity of London's Heathrow Airport. The chapter emphasizes the importance of clear and logical visual representations of a system's business logic and structure.
• 12:00 - 18:00: Introducing the C4 Model In this chapter titled 'Introducing the C4 Model', the focus is on visualizing and understanding the C4 Model – a method for structuring the role of diagrams in software architecture. The transcript briefly hints at past experiences with diagrams that might have been confusing or extreme, suggesting the need for improvement and clarity that the C4 Model aims to address. While the specific details of the workshop mentioned are sparse, the overarching theme is the necessity of utilizing clear and structured diagrams for effective communication in software projects.
• 18:00 - 29:00: Using the C4 Model - Levels 1 to 3 In this chapter titled 'Using the C4 Model - Levels 1 to 3', the focus is on assessing and evaluating different diagrammatic representations within the context of the C4 model. The exercises involve switching and examining various diagrams with groups tasked to provide a score out of 10 for each diagram based on clarity and informativeness. For instance, a specific diagram received a score of 7, indicating it wasn't fully effective in conveying its intended message. The emphasis seems to be on honing the ability to critically analyze and rate structural representations as part of understanding and utilizing the C4 model effectively.
• 29:00 - 33:00: Dealing with Code-Level Detail (Level 4) The chapter "Dealing with Code-Level Detail (Level 4)" revolves around the topic of interpreting repetitive and nondescriptive numerical ratings, predominantly '7 out of 10', made by a group of people. The dialogue emphasizes that the repetitive number '7' isn't informative and is potentially fabricated, as the speaker humorously claims they're not making it up. The narrative suggests that, in the context of code-level details or evaluations, such consistent scoring does not provide meaningful insights without further context, possibly alluding to the need for a more nuanced approach in coding assessments.
• 33:00 - 45:00: Tips for Effective Diagram Notation This chapter discusses tips for creating effective diagram notation. It delves into the common misconceptions teams have about complex diagrams, noting that overly detailed diagrams can be confusing rather than helpful. Despite popular advice to keep diagrams simple, the chapter explains that such an approach might not always yield the best results, especially in short exercise sessions that span 69 to 90 minutes. It suggests that with more time or access to computer tools, teams might produce better diagrams. The chapter also touches on online resources like Google's software architecture diagrams, suggesting these as starting points for creating more comprehensible visuals.
• 45:00 - 55:00: Recommendations for Diagramming Tools This chapter critiques various diagramming tools, highlighting the common issues found in many of them. Despite these tools producing visually appealing diagrams with neat boxes and attractive colors, they suffer from the same problems as hand-drawn pictures. These problems include a lack of connecting lines between elements, unclear usage of different shapes, colors, and box sizes, and a lack of clarity in the layering of information both horizontally and vertically. Moreover, these diagrams often contain acronyms without explanations and lack descriptive titles, resulting in overall confusion and inefficiency in conveying the intended message.

Visualising software architecture with the C4 model - Simon Brown, Agile on the Beach 2019 Transcription

• 00:00 - 00:30 right good morning thank you for joining me so this talk is about software architecture and specifically diagramming and describing and explaining software architecture for those of you who don't know me my name's Simon Brown I'm an independent consultant specializing software architecture show of hands who here uses UML that's more than I was expecting which still not everybody so when I asked this question in my travels around the world it's typically a little bit
• 00:30 - 01:00 lower than this and maybe this is a sign of why companies get me in so typically it's about Tim set of people who use UML and there are lots of reasons for this and I think I've heard every single reason you can possibly imagine as to why people don't want to use UML anymore and there's a book about this you can go by it's called 97 ways to sidestep UML by no formality and I've literally heard all of these different excuses some of these are just crazy you know you'll be seen as old-fashioned if you use UML
• 01:00 - 01:30 it's not expected in agile the value is in the conversation and you know since we've been doing the outdoor thing we perpetuated lots of these myths and lots of these excuses for not using UML and of course one of the recommendations for drawing architecture diagrams to explain your software to other people is to just use a whiteboard and although that kind of makes sense on the face of it we don't teach people how to do this so one
• 01:30 - 02:00 of the things I do is I get to travel the world and I run software architecture diagramming Carter's exercises where we give people requirements and I say go draw some pictures and we get diagrams like this and that and this one which is my favorite I think that's like London Heathrow Airport this one here shows that our system does business logic the logical view
• 02:00 - 02:30 Stormtroopers whatsit crossing out renaming these are real pictures and real works that sort of run over the years and to be fair some of these are the more extreme diagrams because I'm trying to make a point let me show you some diagrams from a workshop I did last month it's not as bad as some of the
• 02:30 - 03:00 diagrams I've just shown part of the exercises we get we switch diagrams so every group gets different set of diagrams to look at and we rcent to give these diagrams a score out of 10 what school would you give this diagram out of 10 8 7 6 this is called a 7 it's not great doesn't tell you anything all right this one what score do you give that for 8
• 03:00 - 03:30 note 7 this one 7 that one 7 there doesn't tell you anything this one here 7 I did not I'm not making this up all of these people scored other group 7 out of 10 this one here 7 this one here no 6 and the funny thing about this diagram
• 03:30 - 04:00 it is actually has more detail than the others and for some reason the teams thought now this is too much and we don't understand it so we're gonna grate it lower so this whole just use a white ball thing doesn't necessarily work very well now the exercises I run they tend to be quite short they're like 69 to 90 minutes so maybe people had more time or they had a tool they were allowed to use computers they could draw better diagrams and unfortunately that's not the case so if you go to Google and you do a search for the software actitude diagram it goes sure here are some
• 04:00 - 04:30 diagrams for you and these are all garbage well so they look nice they're all Nina nice squarish boxes and stuff and we've got nice colors they all have exactly the same problems as the hand-drawn pictures we have boxes and no lines we have different shapes but we don't know why different colors we don't know why different sizes of boxes we have layers both horizontally vertically we have acronyms no titles there's just our whole bunch of stuff going wrong with all of these diagrams the building
• 04:30 - 05:00 industry if we look at the building industry if you ask an architect to draw you a floor plan of where you live you'll get a floor plan and you can look at the floor plan and go yes I'm windows doors I get this if we were asked to draw a floor plan we go yeah sure here you go he's a floor plan of my house it's like what but logically and conceptually speaking this makes perfect sense so these little red dots here
• 05:00 - 05:30 that's my Wi-Fi hot spot because it's important but don't ask me all the dash lines mean I have no idea so I think we need to take a little bit of a kind of back-to-basics approach because we should be engineers and we're trying to be artists and I think we should do something a bit more engineering and the whole point of this of course is if we want to be lean and agile we want to move fast as a team unit we need to communicate well and I've visited lots
• 05:30 - 06:00 of organizations recently where their lack of communication is literally slowing them down because teams don't have a common vision of even what they are going to build or what they are building or what they have built one of the other things against UML potentially is that it's very technical in nature and if you want to describe your software systems to developers and architects that's fine if you want to talk to product owners scrum masters testers whatever there's a whole audience out there that doesn't necessarily know UML so we need to
• 06:00 - 06:30 target again the storytelling we need to target our stories of different types of audiences so our top tip in all of this is when you're drawing architecture diagrams don't think like an architect think like a developer and this won't affect counterintuitive but when I'm running these design exercises the developers and the people who attend my workshops they can do the design part so they can design a solution but when you ask them to draw it they forget everything they've ever known they put their architects hat on and they start
• 06:30 - 07:00 drawing all these really high-level fluffy conceptual pictures that literally make no sense and one of my goals here is when I when I get when I'm asking if you have to draw acted two diagrams good architecture diagrams I want them to reflect reality so when you show them into another developer they go yes and that's exactly what we're building I think in order to do this we could look at UML UML gives you a sense set of things and a standard notation to diagram those things I think the things
• 07:00 - 07:30 the abstractions is actually much more important than the notation and one of the reasons people cite for not using UML is that the notation is very complicated so I'm a abstractions first kind of person here notation second and although this might sound a bit foolish if we go get two local maps of this area the two local maps are going to show you the same things aren't they the towns the train lines the bus routes the schools the churches the museums the
• 07:30 - 08:00 points of interest the two maps will show the same things the same abstractions but they'll likely use different color coding line styles notations shading icon symbols and so on and the key to understanding a map is the key there's a key legend on the map and it tells you we know when you see this sign that's what it means and I think that's a really really powerful and simple concept that we can just borrow so what are the abstractions when I'm thinking about describing and
• 08:00 - 08:30 documenting and explaining a software system for me that software system is made up of one or more containers not docker so I've been teaching this approach for well over 10 years now and docker got popular and kind of stole the word container by container I basically mean an application or a datastore so something to runs your code something you need to deploy and run somewhere or something where your data is being
• 08:30 - 09:00 stored so in real terms a container might be a mobile app running on your mobile device back-end server side app a console app a Windows service written c-sharp a Python script a database schema a folder on a file share and Amazon s3 buckets a dynamo DB you know all of that type of stuff that's what I mean by container we look inside these containers I'm going to say they are made up of components so components is a hugely overloaded word but basically what I mean by component
• 09:00 - 09:30 is a grouping with stuff yeah modularity nice boundary nice clean simple interface running inside a containers that's the important part here we've got a hierarchy and if we look inside components they're mostly made up of code level elements so if you're building your Java apps you have a bunch of components built with Java classes and interfaces for example and that's it it's a simple hierarchy a hierarchy of structural elements so we can then use
• 09:30 - 10:00 to describe software architecture and then that leads me to the c-4 model which is in the title of this talk so if you want to point other people at the c4 model you can go to c4 model dot-com c4 stands for context containers components and code and it's four levels of diagram that map ons those levels of abstraction as Tendai said in the keynote I'm going
• 10:00 - 10:30 to tell you a story and that story is going to be linear the one thing I do not want you to take away is Simon says we must draw diagrams in this order because a lot of people do that and then they kind of superimpose Simon therefore says we should do design in this order as well and that's not what I'm saying so this is just the collective diagrams you can draw in any order to describe your software systems at different levels of detail that's basically what this is all about and it's essentially the way I think about this is diagrams as maps so I live in Jersey in the
• 10:30 - 11:00 Channel Islands and if you open up your your Maps app on your smartphone and you do search for Jersey you'll get that picture by default so Google Maps for example zoom straight in says are you interested Jersey this is what Jersey looks like if you want to know what the major places are in Jersey where I live that's useful if you've never heard of it and you've done the where Jersey is it's pointless you have no context so you get to zoom out or zoom in to tell different stories to get different levels of information and it's the same thing with these diagrams
• 11:00 - 11:30 we have different levels of diagrams to tell different stories different audiences and the purpose of this talk is really just to show you the sea for kind of core diagrams the static structural diagrams but once you have a good idea of your static structure and you're able to talk about your static structure you can then use these same concepts to draw runtime diagrams sequence diagrams deployment diagrams and so on and so forth so this is kind of really nice starting place I'm going
• 11:30 - 12:00 to show you a bunch of example diagrams based upon an internet banking system so imagine we work for a bank and the bank wants us to build an internet banking system so I'm going to start from the top again storytelling and I'm going to draw a level 1 system context diagram and the system context diagram basically shows the thing you are working on or building and stuff around it in terms of other systems it talks to and the people who use your system so we're going to start with a
• 12:00 - 12:30 box in the middle and this represents our internet banking system as a software system don't worry about notation and shapes and color coding I'll cover all of those tips later so in order to draw this diagram we now need to ask a bunch of questions like who's using it so now we look at roles or users or personas and we come up with a bunch of people who are gonna be using our software system so in this example let's say there's only one type of user it's personal users of the personal banking customers so you and I as
• 12:30 - 13:00 account holders we want to use the internet banking system to get information about our accounts and maybe make some payments where does this system get its information from well let's say the bank has an existing software system a mainframe back-end banking system and that's where all of the core banking data is stored so we're going to have some interaction with that let's also imagine for the purposes of this story that we need to send emails to our customers and rather than creating our an email system we just can use the bank's internal email system so that's a
• 13:00 - 13:30 really nice simple example of a system context diagram it basically shows you that's the thing we are working on and this is the environment the context around it in terms of people and other software systems for large environments you have more boxes and there's a longer question there about how do you deal with larger diagrams and we can we can cover that in a Q&A if you want to so that's that's level one it's nice and high level nice and straightforward not much tech choices on here it's great for a really wide range of audiences
• 13:30 - 14:00 so it's developers and architects we now want more detail so what's inside the interbank you system you know what tech is it made of how does it work so now what we're going to do is we're going to pinch to zoom in to that internet banking system box and we're going to drop down to level 2 and level 2 is a container diagram and this is showing you all of your apps and safe and data stores and how they relate and run at runtime and we're going to build this up piece by piece so the currently empty
• 14:00 - 14:30 looking box here that is the internet banking system box from the previous diagram that's the thing we're going to look into and we're still going to show the people and the external systems we have some one dependency on caveat time what you're about to see is how I might design an internet banking system you might not agree with my design that's fine park those thoughts but this is how I might design the diagram and of course
• 14:30 - 15:00 I needed to do that in order to show you a diagram so first we're gonna have a deployable web application so imagine you open up your web browser you go to my bank comm forward slash internet banking you get a bunch of static content back in your browser HTML CSS JavaScript that's gonna be served from this back-end web app which I'm going to say is a Java spring MVC app once you get all of the static content back into your browser I'm going to say that actually that's going to be a single page app essentially running client-side
• 15:00 - 15:30 in your browser so I'm going to model that as a separate box in this diagram so now I've got a bunch of JavaScript code essentially running on my web browser that's my UI for my interbank Inc system it's a single jab in this case it's JavaScript and angular how about we give people a mobile app as well so let's build a separate mobile application using this case the cross-platform xamarin framework and that's an alternative UI that we can present present to our customers how do the single page app and
• 15:30 - 16:00 the mobile app gets data from the backend banking system well they need to go through something so I'm gonna say we're gonna have a separate API application exposing a bunch of jason that over HTTP endpoints that's a separately deployable Java spring MVC web application so now we have two web applications where we're deploying server-side you could have one I'm choosing two we need to sign in so we go to the front page we need to add username password imagine we work for
• 16:00 - 16:30 the bank we go ask the bank can we put our usernames and passwords in your back-end banking system they say no so we need to somewhere to store our own data so let's have our own database schema to do that so that's basically in this case an example contain a diagram it's showing you the various applications and data stores the technologies that built with a bit about responsibilities on there and how they connect at runtime so each of these containers is mostly no I'll tell you
• 16:30 - 17:00 later why I'm using the word mostly mostly a separately deployable thing and the links the lines between the containers are mostly inter-process communication calls so something with a network involved somewhere typically that's level 2 let's imagine that we are now in a team and we are working on the API application and we want to see how that code base is structured so now we're going to pinch to zoom in and we're going to down so we're going to
• 17:00 - 17:30 drop down to level 3 and I'm now going to draw you a components diagram for that API application now I'm going to do the same thing so this currently empty box here represents the API application box from the previous diagram it's used by the single page app and the mobile app and we're going to add some other stuff to this picture so you open up the mobile app you need to sign in so I'm going to say we need some sort of sign-in API so we can have a sign-in controller that's going to use
• 17:30 - 18:00 some sort of security component we're just going to do authentication against our credentials in the database hopefully using hash passwords and all the rest of it once you signed in you get a list of your accounts let's imagine that that's serviced by a separate accounts summary controller again that's providing another API endpoint and that's going to use this really horribly names mainframe banking system facade component which talks to the horrible back in banking system if somebody wants to reset the password
• 18:00 - 18:30 yeah we'll give them the way to do that as well in a more real-world example you could seed have many many more components on this diagram and again there's another question here about how do you deal with larger systems but this is a nice simple example of the components that sit inside that API application it's at this point of course that we now need to start talking about lower-level text choices so we got spring beans and spring MVC rest controllers and there's some other high-level Czech tech choices and
• 18:30 - 19:00 frameworks on here if I were to open the code base for this API application I would expect to see very clearly these six things somewhere in my codebase so at level 3 at the component level your architecture diagram now needs to start reflecting your code structure at a high level so it needs to be a nice one to one mapping between concepts on this diagram and concepts in your code base whether those concepts are language level modules maven modules Gradle
• 19:00 - 19:30 modules components packages namespaces jar files dll's so there has to be some organization structure which is reflect on your diagram South's level 3 level 4 so I don't recommend doing level 4 I'm going to say that again because people always miss this I do not recommend doing level 4 because it's not worth it
• 19:30 - 20:00 and often you could just generate level 4 automatically from your IDs to show to tell the story I'm going to show you an example so let's imagine we are working on this horribly names of mainframe banking system facade component thing and we want to see inside it class diagram so this is where UML is super useful for documenting and diagramming those low-level aspects if you want to diagram level 4 for complicated components or when there's
• 20:00 - 20:30 something bit funky going on feel free but in most in 99% of situations do not draw a level 4 diagrams just automate them for your your IDs so that's the diagrams system context containers components code and we're done notations important and there's lots of subtleties in the notation and the example diagrams I wanted to go through very very quickly so some tips for notation tip number one put titles on
• 20:30 - 21:00 pictures I know this sounds super obvious but when I run my workshops 80% of diagrams first time rounds do not have a title and you have no idea what you're looking at so when I'm titling a diagram I want to be very explicit about two things what type of diagram is this and what's the scope so if I'm drawing a system context diagram for a financial risks and I'll let you leave it like that so I'm very specific and very clear here layout if you don't have access to
• 21:00 - 21:30 whiteboards you know if you're writing on paper it's kind of hard to raise you can use sticky notes and then index cards represent your boxes move them around get a like you like that's fine I wouldn't necessarily deliver diagrams as a collection of sticky notes because they will fall off and it just kind of looks a bit cluttered I will try to aim for some visual consistency so if I've got multiple levels of detail I will try to always keep my people in the same visual location on the diagram cameras
• 21:30 - 22:00 for example and I'll try to use the same color codings and shapes across all of my levels of diagram and you would have seen that in the examples I just showed you be super careful with acronyms if you are targeting your diagrams at technical people like developers and architects don't worry about explaining MVC and ASP and JDBC and all that stuff because we probably get that focus more on the domain-specific acronyms the
• 22:00 - 22:30 business acronyms or the funny jargon that lives in your companies so code names for systems or code names for teams that sort of stuff catches our new joiners really really quickly boxes and lines so that start with boxes or more specifically elements when I'm drawing a diagram for the first time I'm going to forget about shape and color and I'll
• 22:30 - 23:00 talk about why in a second but I'm going to just draw plain boring boxes and inside my boring boxes is a bunch of text if you look at the top three levels of the C for diagrams so context contains components these are basically the only four types of elements I expect to see on the diagrams so it's a very simple language you can teach people so the system contexts diagram shows people and software systems the container diagram shows people software systems
• 23:00 - 23:30 and containers and the component diagram tension shows all of these things so every box is going to have a name a naming is hard and whatever but hopefully we're going to give everything a nice simple easy to remember name I'm also going to be very explicit about the type of the elements so I'm going to write in the box this is a person or this is a software system because then we know what we're getting and there's no guessing for the two technical things
• 23:30 - 24:00 down here the containers and the components this is where we can start to weave in those text choices so this is a database scheme or this is a spring MVC app the rest of the text in the box is a short description either as a sentence like you see here or maybe just so you know five or seven bullet points to list out the key responsibilities of that element and it's at this point people say well why are you putting so much text in your boxes because that's not how we do actor two diagrams well that's why they're a problem so here are two example Arteta diagrams
• 24:00 - 24:30 this is the one on the left is what we typically do it's just a bunch of named boxes and I do something like that on the right if I if you saw this diagram on the left for the very first time and I said to you can you describe what the content of data does your response would be it updates content yes what about the file system what is a file system do it stores files so the names are not particularly helpful but over on the right-hand side
• 24:30 - 25:00 here we've got more text so even if the names are a bit odd and a bit ambiguous and bit vague at least we can now read the text and go okay the name doesn't make sense but now I know what the thing does so we're adding a degree of explicitness to our diagrams but do keep that short I've seen people writing entire essays in the boxes and that's not what our employer either lines pay some attention to lines because lines give you structure lines glue your boxes your elements together my preference
• 25:00 - 25:30 here is you need directional lines only so all of my arrows go one way so you'll never see my diagrams with straight lines for now arrowheads or lines with arrowheads on both sides and this raises an interesting question we're twenty point arrows and it's up to you so there are no hard and fast rules in any of this my preference is for thing a calls thing B or thing a depends on thing B if you want to show events or messages or
• 25:30 - 26:00 information flow that's absolutely fine just make sure the direction of your arrow matches the text you put on the arrow to describe it the other kind of catch here is that most relationships are actually bi-directional aren't they so if we think back to the intent banking system we've got the single page app and that's making a request to the API app and the API app is sending a response back essentially so two bi-directional relationship and although that makes sense if we show both directions for every relationship we
• 26:00 - 26:30 came to get a very very cluttered diagram really really quickly so what I'm going to do instead is I'm going to summarize the intent of those two arrows in a single arrow so I would rather say something like that the single page application makes API calls using the API application I will try to avoid users again uses is quite a general vague generic term so I'll try to be as specific as I can but keep it short and
• 26:30 - 27:00 having said all of this sometimes you do want to show both directions so if you're if you know you've got a bi-directional relationship but those two directions are very different in nature very different in its intent then I will show those directions so maybe we have two micro-services a and B and maybe at startup time a can request a list of stuff and be using a synchronous call so that's one relationship and then
• 27:00 - 27:30 maybe at runtime as events are coming in we've got a kind of rule cast thing going on as well so because those are two very different types and relationships I want to show those very clearly on the diagram another trap people fall into is they kind of hide the two-story so imagine you drawing a container diagram you've got a microservices architecture everything was going into and out of a message bus you tend to get hub-and-spoke diagrams that look a lot like this and again although that's factually correct you know we've got a
• 27:30 - 28:00 couple of micro versus here if stuffing things into a barson stuff coming out we may be missing some really important information so what I'd rather do is perhaps draw something like this instead so miss off the message bus and instead say actually there's a point-to-point relationship here between a and B and we're just using Kafka or rabbit as the messaging mechanism for doing that so again there are no hard and fast rules here it's really do the diagrams tell the story that you want to tell and add
• 28:00 - 28:30 more words a lot of this is adding more words to make stuff much more explicit and a really good simple tip here is just read your diagrams out aloud so in this case the trade data system sends trade trade data to the financial risk system and because that makes sense as a sentence we could have a key legend so every set of diagrams should have a consistent key and to describe shapes colors line styles
• 28:30 - 29:00 borders acronyms and so on even if it seems obvious to you so we're not a hawk tetra Carters we kind of draw some diagrams in the morning and everybody's using different color Sharpie markers then we go for lunch and then they come back and like why is this line red they drew two hours ago but they've forgotten this is an example of a diagram keyer diagram legend so this is my container diagram up here for the interbank II system and that's the key of the legends
• 29:00 - 29:30 that I would use to describe this diagram so that - box is the system we got these various blue boxes here for showing containers and I'm using different shapes to show different types of containers people-people gray boxes are external software systems in this case I'm just saying there are relationships and I'm not being specific about relationships but you can be so if you want to show synchronous relationships different from asynchronous relationships you could do something like solid lines for
• 29:30 - 30:00 synchronous relationships and and dash lines for asynchronous and you'd have that in your key or a lot or your legend if you wanted to use different colors for different protocols so maybe green lines are secured by HTTPS and red lines are insecure then feel free do watch out for colorblindness especially red-green color blindness and also watch out for black and white printers because that will happen at some point so with that in mind my advice is to use shape and
• 30:00 - 30:30 color to complement a diagram that already makes sense so in other words if you take a diagram and you remove all of its color and you remove all of the shapes the diagram should still make sense and the reason it makes sense is because a lot of the texts we add to the diagram helps it make sense to versions of the same diagram which one D tend to prefer that one on the right yeah it
• 30:30 - 31:00 kind of looks nicer it's a bit more aesthetically pleasing because you can't read the text so I can't read the text from here either by the way because you can't read the text looking at the diagram on the right you're you're able to kind of understand it and comprehend it a bit quicker because you're confirming what you think you're seeing so we think those things that top look like people I guess they're people when you read sex these things look like data storage things
• 31:00 - 31:30 down here so and again that the shapes help but fundamentally these diagrams have the same level of information and that information is captured in the text all of this advice goes for icons as well do you ever see people drawing these diagrams with the Amazon AWS icon set or the Azzurri I can set they kind of look pretty and they're great if you want to show all of their own Amazon services you're using but they're basically pointless because I don't understand what half the icons mean and
• 31:30 - 32:00 I don't know why these things have been chosen anyway so these diagrams don't tell me enough from a software architecture perspective so what I'm gonna do here is if you do want to use icons feel free but use the icons to again add an additional level or layer of information so here's an alternative version of my inset banking system container diagram now we've removed the color and I'm now using some icons instead so if you know what the icons mean you can see there's a couple of Java spring apps there's a database schema we've got angular and xamarin if you have no idea what the icons mean it
• 32:00 - 32:30 doesn't matter because all they're all the informations in in there in the text and your key or your legend should have examples of what those things mean of course and the whole point that this is what what I'm trying to do is make the diagrams able to stand on their own so whenever I see arced it two diagrams you normally have to have a conversation to explain what the diagram means because the diagrams are basically hopeless and that's fine if you're there but often what happens is people draw a diagram on a whiteboard I take a photo stick on
• 32:30 - 33:00 confluence and that's where it lives forever more someone new joins your team send them to confluence they have no idea what the diagram means they have to go find the person who drew the diagram Oh guess what they quit four months ago so what we do is we'll spend another three hours with a different group of people at the same whiteboard redrawing the same one not the same picture something that we hope looks like the same sort of picture and we just repeating whistling as I was down any
• 33:00 - 33:30 narrative you give any presentation you give any supplementary documentation he write again should tell stories on top of a diagram that already makes sense so what I'm trying to do is I'm trying to make us spend our time telling more valuable stories rather than why's that box blue and this one's red well let's let's just get that stuff down next time you draw a diagram there's a notation checklist you can find at c4 model of comets or a single page PDF completely free to download run through
• 33:30 - 34:00 this answers them yes-or-no questions and this will hopefully give you some tips on how you can improve your software architecture documents I have a couple of slides left and then we can open the floor for Q&A a lot of people ask me what tooling do I recommend I'm going to give you two recommendations recommendation one I'm gonna give you three recommendations recommendation one do not use Visio and by Visio I mean Visio OmniGraffle lucidchart
• 34:00 - 34:30 draw the i/o and Gliffy all of those stuff please do not use them because they're general-purpose diagramming tools and they don't know anything about software architecture so those are the worst categories of tools you can use they're the most common but they're the worst categories of tools you can use so my first recommendation there's a whole bunch of tooling out there for the c4 model c4 plant two UML so if you come across plant to your mail it's a way to draw UML diagrams or not I'm using text so you write some text you throw it
• 34:30 - 35:00 through a tool and it does automatic layout thing for you so someone created a set of macros a set of plugins for plant UML and they allow you to draw the c4 diagrams using a kind of c4 model ish domain-specific language all complete battle applying UML so that's my recommendation number one recommendation number two is my own tooling sorry so I've been dissatisfied with a lot of the tooling out there for drawing acted two diagrams so I've got a whole bunch of tooling I've built myself some of its
• 35:00 - 35:30 free something's open saw some of its commercial but there's a whole bunch tooling out that you can find that helps you draw software architecture diagrams specifically targeted to add the c-4 model no matter which tooling you do use abstractions first notation second so if you take this back to your team so anyone to adopt it make sure everybody understands those four levels of abstractions the four key diagram types tell them not to use level four and then just go forward from there and that's me thank you very much [Applause]