C4 models as code By Simon Brown

Summary

Highlights

• Traditional UML diagrams are impractical for agile environments, pushing for a shift to C4 models 🤓.
• C4 model's hierarchy: software systems, containers, components, and code 📊.
• Tools like PlantUML and Mermaid provide efficient methods for creating and managing diagrams-as-code 🖋️.
• C4 models allow for more intuitive and consistent architecture diagrams, aiding in various phase processes 🎨.
• Brown emphasizes modeling over simple diagramming, ensuring diagrams evolve with the project structure 🔄.

Key Takeaways

• C4 models revolutionize architecture diagrams by offering a structured, hierarchical approach 🗺️.
• Classic UML diagrams are seen as outdated and cumbersome, making way for more agile-friendly methods 🚀.
• Using tools like PlantUML and Mermaid enhances the automation and version control of diagrams ⚙️.
• Diagrams-as-code approach simplifies integration with CI/CD processes, enhancing productivity 🖥️.
• Strucutured, self-describing notation in architecture diagrams improves clarity and communication 🔍.

Overview

Chapters

• 00:00 - 00:30: Introduction to C4 Models as Code The chapter introduces the concept of C4 models as code, critiquing the traditional methods of creating diagrams, often humorously referred to as 'terrible' practices. It challenges the common reliance on whiteboards and suggests a more structured approach through C4 models.
• 00:30 - 01:00: Tooling Issues with Architecture Diagrams The chapter delves into the exploration of whether digital tools improve the quality of architecture diagrams compared to traditional methods. The author recounts their extensive experience conducting architecture diagramming workshops using pen and paper or whiteboards for over a decade globally. Despite suggestions from participants that employing digital tools might yield better diagrams, the facilitator initially upheld traditional methods. However, the unexpected shift to online workshops during the pandemic provided an opportunity to test this hypothesis using digital platforms like Meo and Mural. The outcomes from these online sessions reaffirmed the author's stance that the quality of the diagrams did not necessarily improve with digital tools, suggesting that the medium may not significantly impact the effectiveness of diagramming exercises.
• 01:00 - 02:00: UML and Its Decline The chapter discusses the decline of UML (Unified Modeling Language) and its decreasing popularity in the tech industry. It highlights the common perception that UML is not aligned with agile methodologies, although the origins of this belief are unclear. Additionally, the historical inadequacies of UML tools, like Rational Rose, which was known for its poor interface design, are also mentioned as a factor in its decline.
• 02:00 - 03:00: Introduction to C4 Model The chapter introduces the C4 model as an alternative to UML, highlighting the latter's tendency to involve excessive detail. The author recounts a personal experience where UML was considered outdated by a company. This sentiment contributes to the declining interest in UML, paving the way for the emergence of the C4 model. The C4 model was created by the author between 2006 and 2008.
• 03:00 - 05:30: Levels of Abstraction in C4 This chapter introduces the C4 model, emphasizing the importance of creating structured architecture diagrams without using UML. It highlights the need for using boxes and arrows in a way that has some degree of structure and is self-describing. The chapter aims to provide a quick introduction to the C4 model and acknowledges its utility for those already implementing it.
• 05:30 - 09:30: System Context and Container Diagrams The chapter introduces the concept of C4, which is composed of hierarchical abstractions vital for understanding certain tooling. The highest abstraction level in this hierarchy is a software system, characterized typically as something a single team is responsible for. This chapter emphasizes the importance of understanding these abstractions to effectively utilize the discussed tooling.
• 09:30 - 14:00: Diagramming Tools and Their Limitations The chapter titled 'Diagramming Tools and Their Limitations' discusses software systems' structural components and the challenges of clearly defining them. It highlights that software systems consist of one or more 'containers,' although this term can be confused with Docker's containers. However, the chapter stresses that the term was coined earlier in this context, and it points out the importance of standardization in deploying subsystems around ownership boundaries, synchronizing life cycle phases, and facing the inherent limitations in current diagramming tools to represent these complexities.
• 14:00 - 16:30: Diagrams as Code: PlantUML and Mermaid This chapter covers the topic of using diagrams as code with PlantUML and Mermaid. The chapter starts by describing the composition of team-built systems, highlighting that they consist of applications and data stores. Examples of these components include single-page apps running in web browsers or server-side apps like Spring Boot, Ruby on Rails, and others. Data perspectives are also discussed, mentioning database schemas on platforms like MySQL or Oracle, document collections in a graph or doc database, and storage solutions like Amazon buckets. The focus is on how diagrams can represent these systems effectively.
• 16:30 - 19:00: Modeling vs. Diagramming In this chapter, the author discusses the concepts of modeling and diagramming, focusing specifically on applications and data stores. The author introduces the term 'containers' to collectively refer to these components. The chapter goes on to elaborate on 'application containers,' which are primarily composed of 'components.' The usage of the term 'components' is acknowledged to be broad and potentially unclear, but it is used intentionally to describe more than just code, possibly including other facets such as configurations or dependencies that make up an application.
• 19:00 - 20:00: Structurizr DSL Introduction The chapter introduces the Structurizr DSL, focusing on its approach to defining software architecture. It emphasizes the concept of running applications within containers, where components are not separately deployable but are part of the container. The analogy is given with a Spring Boot application, where components such as interfaces and implementation classes work together as part of a single deployable unit. The chapter aims to provide a clean and well-defined interface for functionality within a container.
• 20:00 - 30:00: Creating Diagrams with Structurizr Lite This chapter explains the various abstraction levels within software systems using Structurizr Lite. It focuses on the code level, which is the fourth level of abstraction, involving the fundamental code elements like interfaces, classes, and functions in programming languages such as Java, C++, JavaScript, and functional languages like FOP or Haskell. These code elements are used to build components. The hierarchy described includes software systems being composed of containers, which in turn house components, illustrating the organized architecture in software development.
• 30:00 - 37:00: Rendering Tool Independence In the chapter titled 'Rendering Tool Independence,' the discussion revolves around the concept of creating hierarchical diagrams using the C4 model. The C4 model consists of four levels: context, containers, components, and code. These levels correspond to different abstractions that help in mapping out the structure of a system. The focus is on creating high-level diagrams and then zooming into specific components to explore their internal structure. The chapter highlights the importance of understanding these abstractions to effectively render tools and diagrams.
• 37:00 - 47:00: Advanced Modeling with Structurizr DSL The chapter discusses advance modeling techniques using Structurizr DSL, emphasizing the hierarchical and nested structure of modeling. It compares this concept to Google Maps, where a high-level view provides a big picture without overwhelming details. Starting with a broad view, the chapter suggests delving deeper into specifics, similar to navigating to more detailed maps. This analogy helps in managing complex project structures by introducing intricate details progressively.
• 47:00 - 50:00: Exploring Visualization Options The chapter titled 'Exploring Visualization Options' begins by discussing the overwhelming nature of handling extensive codebases, using the metaphor of stepping back from a detailed map view like Google Maps. By pinching to zoom out, users can move from a comprehensive view to a street-level perspective with accurate real-world correspondence. The author connects this concept to software architecture diagrams, expressing a desire for a similar tool that can provide various diagram levels catering to different audiences and storytelling needs.
• 50:00 - 51:00: Other Options for Modeling Tools In this chapter titled 'Other Options for Modeling Tools,' the discussion centers around the hierarchical nature of technical diagrams, emphasizing that higher-level diagrams are intended to be less technical, catering to a broader audience. As you delve deeper into the hierarchy, the details become more technically focused and are primarily targeted at developers. The chapter particularly introduces the two top-level diagrams, starting with the context or system context diagram, which outlines the system being built, documented, or described. The emphasis is on understanding the broad system context before getting into detailed technical modeling.

C4 models as code By Simon Brown Transcription

• 00:00 - 00:30 good afternoon thank you for joining me C4 models as code AR to diagrams we've all been there we've all done it historically and traditionally they are terrible I'm imagining a bunch of you have white boards a look like this back in your offices don't tell me if you do that's not for the place for discuss this
• 00:30 - 01:00 um this is not a tooling issue either so I've been running architecture diagramming workshops all around the world for the past uh 10 15 years and during those architecture diagramming workshops we use pen and paper whiteboards whatever and people have always asked me well if you let people use a tool during your workshops do you think you get better diagrams the answer is no and I know this for a fact now because during the pandemic I did some online workshops and instead of using pen and paper and whiteboard to be using Meo and mural uh and tools like that so
• 01:00 - 01:30 this isn't a tooling thing uml has massively gone out of fashion I've heard tons and tons of reasons why people don't want to use uml these days uh a lot of people think it's not expected in agile in our quotes not really sure where that comes from uh but it's very common very prevalent uh the tooling has historically been horrendous uh anyone use rashal rose in the past yeah Yellow Boxes weird pink purple borders who thought that looked pretty
• 01:30 - 02:00 uh there's something about uml that kind of drags you into lots and lots of detail I had a company say to my face if you use uml here you'll be seen as old and oldfashioned which was quite funny so lots of people don't want to use uml there's a lack of appetite for anymore essentially so that's where C4 comes into play uh C4 model is something I created around about 2006 2008 something like that I'm not entirely sure when it kind of um was created to be honest with you you can find more information C4
• 02:00 - 02:30 model C model.com the principle that underlies C4 model is this if you don't want to use uml but you do need to create some architecture diagrams try to do so in a structured way so make sure your boxes and arrows have some degree of structure and make sure your notation is self-describing that's essentially C4 in a nutshell who's using C4 here by the way that's a good Chun hands awesome hopefully you find it useful as well I'm going to do a quick intro to C4
• 02:30 - 03:00 for those of you who might not be familiar with it because the tooling I'm going to show you kind of requires this as some prerequisite knowledge so C4 is essentially two things thing number one is a set of hierarchical abstractions and there are four of them the highest level abstraction is what I call a software system this is the hardest of these abstractions to Define clearly and cleanly but essentially a software system is typically something that we as a single team are respons responsible
• 03:00 - 03:30 for producing so it's something that we as a team can see the implementation details of maybe there's a life cycle thing so everything we produce as a team is is lock step deployed at the same time typically there's an ownership boundary around something we're delivering if we look inside these things I call software systems I'm going to say they are made up of one or more containers now I'm not talking about Docker there's an unfortunate Clash of naming here you've heard the story I got the name first that's irrelevant now but I can tell I basically mean an
• 03:30 - 04:00 application or a data store so the things we build as a team they are made up of applications and data stores so your single page apps angular or reacts running in a web browser your server side apps like spring boot spring MVC Ruby on Rails C asp.net etc etc so that's what I mean by App application and from a data perspective it's something like a database schema on MySQL or Oracle it could be a collection of documents in a graph database or doc database it could be a bucket on Amazon
• 04:00 - 04:30 S3 or could could be a folder on a file share so the things we make as teams are made up of applications and data stores collectively I call these things containers if we look inside the containers specifically the code focused containers the application containers they are essentially made up of components now components is a massively overused ambiguous vague word I get that but I want to use the word component here to mean this a group grouping of
• 04:30 - 05:00 related functionality hopefully a nice clean well finded interface is the way into that functionality running inside a container so in this set of abstractions in this approach components are not individually separately Deployable things it's the container it's the application that's the runable thing so if you're building a spring boot application your components might be an interface with a bunch of implementation classes behind it which leads me on to
• 05:00 - 05:30 level four level four is code so if we look inside these components we're building they're just made up of code level elements in in Java and c and C++ it's interfaces classes enums in JavaScript it's objects and functions in fop or hascal the functional languages its functions so that bottom level represents the code level constructs we have in the languages that we're using to build our components and that's it that's the set of abstractions software systems made up of containers containers can contain components that's where the
• 05:30 - 06:00 naming comes from and components are built from code so that's the abstractions once you have the abstractions you can now create a set of hierarchical diagrams that basically map onto those abstractions and C4 is named after this set of this set of hierarchical diagrams not the abstractions so it's context containers components and code four levels of diagrams that map onto the four levels of abstractions and what we're doing here is we're drawing a high level diagram and then we're taking a box and we're zooming in to show the internals of that
• 06:00 - 06:30 box and then we're taking another box and we're zooming down further to show the internals of that box so again it's it's nested it's hierarchical the concept here is Maps so I live in Jersey in the CH islands and if you open up Google Maps and you do a search for Jersey you're probably going to get that picture that's great if you want to know where the airport is and where the major roads are but if you've never heard of Jersey it's too much detail too quickly this is like turning up to your project on day one on Monday and somebody says hey just add this
• 06:30 - 07:00 feature here's half a million lines of code like oh okay thanks can we step back a bit how do we fix that problem with Google Maps well stepping back is easy you pinch the zoom out on the flip side you can zoom in and if you zoom in far enough you get down to Google Street View which is a onet to one mapping with the real world when the photos were taken I want to do the same thing with software architecture diagrams I want different levels of diagrams that allow me to tell different stories to different audiences the top level
• 07:00 - 07:30 diagrams are relatively non-technical and as you progress down into the hierarchy it's much more technical detail so it's much more developer Focus the further you go down the hierarchy and that's just a natural um way of working for um many of us as software developers I'm going to introduce the top two level diagrams in a little bit more detailed the top level diagram is a context or rather a system context diagram and the system context diagram basically says here's the system we are building or documenting or describing or
• 07:30 - 08:00 designing and here is the world around it in terms of people and other software systems so in other words other way to think about this is if you want to draw a system context diagram for something you are building you have to answer these types of questions so what's the scope of the thing we're building so what features sit inside our boundary and what features sit outside of our boundary in other systems in the environment in our landscape of systems who is using our system so who are the users the roles the actors the
• 08:00 - 08:30 personas the real named people who are using the thing that we are building how are they getting value from our system and what are our system integration points so how does the thing we are building talk to something else that other team is Building inside or outside of our environment answer those questions and you can draft up a system context diagram this is an example diagram from one of my Workshops the red box represents the the system that this
• 08:30 - 09:00 group uh was designing it's a little case study around a Financial Risk system they've correctly identified the two types of users there's a business user and a a kind of advanced business user that condition condition configuration of parameters and the black boxes represent the system integration points in their environment so it's a nice high level diagram it's very light on technology choices it's a great diagram you can use to start all conversations to pretty much all audiences but as developers we want more
• 09:00 - 09:30 information so what we want to do now of course is take that red box pinch the zoom in and drop down to level two level two is a container diagram and it's showing us the applications and data stores that make up our systems so now it's a different set of questions so what are those major Technology Building Blocks what are the applications and data stores that need to be running for our system to work what are the responsibilities of those things are they processing business logic are they storing data that sort of thing and how
• 09:30 - 10:00 do they communicate answer those questions and you can drop down and draw a container diagram so this is the container diagram from that same solution from the same group the red box is now bigger because we've zoomed into the contents of that red box and now we are showing things like um react apps running on a front end and there's a Java spring there and a bunch of data stores and some Java command line apps so those are the applications and data stores the C4 containers that sit inside that
• 10:00 - 10:30 particular solution few more Tech choices now integration protocols so we've lost all of our non-technical people but now this is great for U us as developers Architects Ops staff devops infrastructure etc etc so that's C4 and a nutshell it's notation independent that's one of the big things I want to say here because there is a misconception that C4 equals blue and
• 10:30 - 11:00 gray boxes and that's my fault because all of the example diagrams I show are blue and gray boxes but a lot of people have have written blog posts on this and they've said the se4 notation is boring because it's blue and gray boxes so if you go to se4 model.com now and you click refresh a bunch of times you'll get different colored versions of the examples and I did that because I was utterly Fed Up of this whole blue gray box thing you don't have to use fancy shapes and colors you could use uml if you wanted to so uml has its own set of
• 11:00 - 11:30 boxes and lines and semantics and notations there's nothing stopping you taking C4 abstractions and diagram types and applying them to uml I don't see people doing this but you could do if you want to so tooling if you go to c.com there's a tooling link I've tried to assemble on the C4 model.com website a list of all of the tooling that provides some degree of specific support for the C4
• 11:30 - 12:00 model there are different types of tools here some are diagramming tools some are modeling tools so let's get into that most teams typically use Vio Lucid chart diagrams. Net draw.io who's using these tools yeah that's going to be a big chunky right these tools are very common they're very popular they're easy to get hold of the barrier to entry is very very low most teams have uh free access to these sorts of tools I don't recommend them if you're using C4 model for drawing architecture d
• 12:00 - 12:30 for a bunch of reasons I'm going to justify this so reason number one these tools don't know what you are doing these tools just see shapes and arrows they can't help you they don't know the few rules of C4 and they can't guide you in the right direction so for example one of the rules in C4 is if you are drawing a system context diagram the only two elements you really should have on that diagram are people and software systems that's it if you draw a system context diagram in a tool like viio
• 12:30 - 13:00 there's nothing stopping you putting a little loging component on there right please don't do that but viio can't help there if you want to draw two diagrams in a tool like viio you need to open two tabs to worksheets to diagram canvases and one of the things you might notice with with C4 is you have to copy elements across different diagrams so I'll have a bunch of people on my context diagram and the same bunch of people on on my on my container diagram
• 13:00 - 13:30 in a tool like Vio you have to now copy and paste those people across both diagrams if you rename one of those people you'll probably forget to do it on all of the diagrams where that person exists so again the tool can't help enforce consistency that's entirely on your shoulders this goes without saying if you've ever tried to dump these files out into a text format to stick them into git you'll know they're an absolute nightmare
• 13:30 - 14:00 and they do mix content at presentation if you change the color of a box for example you get an entirely different file which of course makes it hard to diff which makes it hard to put these things into PO requests etc etc and these tools are really hard to automate these tools are typically grab the mouse click here click here drag here they're very interactive from a user perspective imagine you have an AWS environment and you want to point Vis at the AWS environment and scrape some data
• 14:00 - 14:30 out and magically create a deployment architecture diagram that's really hard to do with a tool like Vio you can do it with things like draw.io diagrams. net you can create a CSV file and push a CSV file and Magic happens but there's quite a few opportunities that you're missing if using these types of tools they can't easily be plugged into cicd build processes and they're a pain in the ass right that's the biggest problem with these tools there are pain in the ass because you draw a diag and you try and make that Arrow straight
• 14:30 - 15:00 and it's not straight it's one pixel out and you'll spend 10 minutes trying to fix it by moving the entire diagram around and then you'll realize the text in that in that person is a bit too wide and you want to change it how do you change it do you change the font size in just that one element no because then you want the font size to match everywhere and it just it's just Rabbit Hole so diagrams this code uh in I think it was was October 2020 diagrams as code as
• 15:00 - 15:30 a content blipped on the uh thought Works tech radar diagrams as code is essentially instead of using a UI to create a diagram you write some degree of code or text and some tooling generates you a diagram automatically the most common ones are plant uml who's using plant uml yeah big chunky and mermaids us using mermaid it's funny isn't it mermaids mermaids just you there's native support in
• 15:30 - 16:00 things like GitHub Pages for mumay now but plant umil is still the tool I see people using the most but maybe that Chang in the future so diagram say code is great because it's easy to author so we can type some text and get a diagram we don't have to worry about things like layout uh so most of these tools are automatic layout they're they're text these files are text uh so we can stick them in Version Control they're easy to diff and many of these tools are command line driven so we can now easily integrate them in our cicd pipelines so
• 16:00 - 16:30 for example you could write some code to scrape your AWS environment generate a plant uml definition check that in have it rendered on your build C4 plant gml is probably the one a lot of people will find first it's set of extensions or macros for the plant uml tooling and it really gives you a C4 style domain specific language that you can use to craft up your diagrams so you talk about person and system and
• 16:30 - 17:00 relationship so that's a nice starting point plant uml and mermaid and most of the other diagrams as code tools are still diagramming tools like Vio what I mean by this is if you want to create two diagrams like a context diagram and a container diagram you have to create two text files if you rename an element that appears in both those text files you have have to make sure you rename it twice in in each text file
• 17:00 - 17:30 now as developers we have Fantastic Tools we can use Global search and replace uh plant youil will allow you to include common elements but this doesn't work as well as it should do a lot of the time so again if you want consistency that's on your shoulders I want to shift the narrative away from diagramming and back to he says nervously back to modeling now
• 17:30 - 18:00 modeling is something we used to do in the late 1990s early 2000s tools like rashal rose Ral software architect we used to spend like months and months plowing all this data into these big heavyweight expensive ugly looking modeling tools to generate some diagrams which would then be out of date but tell me went to write some code so it's no wonder the that these big expensive loated modeling tools fell out of fashion especially when the whole agar thing came around of course but the concept of having a model is super super
• 18:00 - 18:30 powerful think about a model as being nothing more than a dictionary you have a single dictionary definition of all of your people and software systems and containers and components and links between them and then if you want a bunch of different diagrams these are just views onto parts of that model you want to rename something you rename your single definition and all your diagrams magically changed they're kept up to date and kept consistent that's the power of having a model so during the pandemic so as I
• 18:30 - 19:00 said I I usually fly around the world and do architect diagramming workshops it turns out that's incompatible when there's a pandemic so I did a few things online but um mostly I just kind of went surfing and stuff I also created this thing called the structurized DSL which is a text based um kind of diagrams as codes tool that's specifically focused on Building architecture diagrams for the C4 model with PL EML you want two diagrams you
• 19:00 - 19:30 create two text files with this tooling you create a single model and the tooling generates you multiple diagrams multiple views of that single model so it's really a kind of text based modeling tool a lightweight modeling tool that you can use to create architecture diagrams as I said a lots of people start with plant uml C4 plant uml and that works really well if you got a couple of small diagrams but once you start getting bigger systems or you want to start modeling uh Landscapes of
• 19:30 - 20:00 systems you want to start reusing elements across multiple systems uh it does start to get quite complicated so that's a kind of word of caution if you are starting out a fresh have a look at plant uml but but maybe keep it in your back pocket fation I'll come back to that statement in a second so really this is models as code or more accurately C for models as code and there's one concept we're going to be showing in the demos here and that concept is a workspace and workspace is really nothing more more than a rapper for three things a model a set of views
• 20:00 - 20:30 and some supplementary documentation so the model is your definition of people software systems containers components relationships and things like deployment nodes and infrastructure nodes so this tooling also does support the uh Dynamic and deployment diagrams that are described on C4 model.com but I'm not going to show that today there's a set of views and again all of the standard C4 views are um supported and you can have markdown and asky do documentation architecture deis records and a bunch of other stuff that I'm also not going to talk about
• 20:30 - 21:00 today this toolings kind of interesting because the workspace is stored in a Json document there's an open API 3 Swagger style um Works uh Json definition you can create that Json document using a whole manner of different toolings I'm going to show you the structurized DSL but there's also some other tooling that you can find on GitHub that will allow you to author these things and create a Json document which is compatible with all of the rendering tools so one of the nice
• 21:00 - 21:30 things about the structu tooling is that it's rendering tool agnostic so I'm going to show you first my own rendering Tool uh which is the same one you that I use for the example diagrams but it's also possible to create a bunch of plant uml diagrams from a single structurize model a single structurize definition which I think it's is quite a powerful use case so let's ditch the slides and let me show you my desktop which believe it
• 21:30 - 22:00 or not is empty yes so the foot the tool I'm going to use here is called structurizing light structurizing light is it's written Java it's a spring boot app it's all on it's all open source it's all on GitHub I'm running the docker version so there's two builds I I um I I create here there's a a Docker image and there's a a kind of spring boot W so I'm using the docker image because it's a little bit easier all I'm basically doing here is I'm spinning up the docker image doing a standard Port map and I'm going to mount
• 22:00 - 22:30 a volume on my desktop a folder on my desktop into a volume on the docker image so what I'm going to do is I'm going to start up light against a folder that doesn't yet exist on my desktop called devox so start R light is going to boot up we go back here and now that folder's created and this thing called a workspace dodsl file has been created so this is the structurized DSL here's our
• 22:30 - 23:00 workspace it consists of a model and a set of views in this case so let me just briefly explain what this means in this example so this is just a template that's created for you we are defining a person with the name user and we're signing out to a variable called user we are defining a software system with the name Software System please come up with better names yourself and uh we're defining a relationship between the user and the software system with a description of users again please use better descriptions so that's my model it's a person a system and a
• 23:00 - 23:30 relationship and we are defining a single system context view here the scope is that Software System uh this is just a diagram identifier and we're saying include star what include star here does is it says include the software system in scope which is this thing and include automatically anything connected to it so because we're building up a model here we can just Traverse the model it's a force directory graph and include or exclude elements as we need to so that's an
• 23:30 - 24:00 example DSL file if I go to Chrome and I go to locost 8080 the structu light interface will boot up and here's my diagram so I created this tooling with manual layout in mind I don't like automatic layout it always puts boxes in the wrong place or the lines overlap I I want I when I'm drawing an architecture diagram I want to tell a story I want my users here my outputs over here and I and I want consistency when I'm creating multiple
• 24:00 - 24:30 diagrams so for example I always want my people in the top left across all my diagrams for example so this tooling is really built with manual layout in mind and you can do things like add vertexes vertices to the lines and you can change the rooting of lines and and move boxes around and all that good stuff now what I can do is I can go to my DSL far and I can change the name of this element to Simon go back refresh and now it's updated some of you might be thinking well
• 24:30 - 25:00 where's the layout like I've got some XY coordinates sitting beneath this box somewhere and it just came back so what happens is there's a a merging algorithm built into the structurer light tooling that tries to figure out what you just changed based upon a whole bunch of different things the layout information is actually stored in the Json version of that uh workspace which if I open up it's just a big Json file surprise surprise um here is our person called Simon bunch of information here's our
• 25:00 - 25:30 Software System this is the definition of our context View and here we can see all the XY coordinates so what you do is you you take that folder that's just been created you check it into G and now anybody on the team can fire up that same exact architecture diagram so I'm a big fan of manual layout and there's a whole bunch of tools in the UI that help you line the boxes up for the purposes of this demo I'm going to turn on automatic lay out just because it makes it easier so there
• 25:30 - 26:00 is support for automatic layout it kind of works okay you'll see all the toolbar buttons have have disappeared now um but this is not my recommended approach for using this tooling so let's change the name of this to buness user and we'll change this to be Financial Risk system and let's do F FRS bu this Mak a bit more realistic Buu has a link to F FRS F FRS hopefully that should
• 26:00 - 26:30 work so rinse repeat you can now add more people more systems etc etc so imagine we've done our context diagram defining the thing we're building and the people who are using it when it comes to adding containers or drawing a container diagram what we can do now is we can open up a c cly braces the curly brace needs to be on the same line I'm sorry if you don't like that but that's that's the way it is uh and now we can start adding containers inside this software system definition so we can say
• 26:30 - 27:00 web app equals container web app let's call it web application again please come up with better names and let's have a database which is going to be a container and we're going to say database schema and let's say that the business user has a link to the web app uses and the web app has a link to the database reads from and and wres to so if I save
• 27:00 - 27:30 this and refresh what's going to happen nothing so the reason nothing happens is because I've added a bunch of things to my model but I don't have a view that allows me to see those things so what I want to do is I want to create a container view how do I do that the easiest way to do this is to copy this block paste it in change this to container so we want to create a
• 27:30 - 28:00 container view the scope is still the the FRS the Financial Risk system and we'll need to change the identifier include start is going to do something different this time include start is going to include all the containers inside this software system and include things that live outside that have a link to those containers so if I go back and now refresh my diagram you'll notice there's a little magnifying glass thing here so I can double click and I can drop down to my container diagram so
• 28:00 - 28:30 this shows our business user using our web application and the web application talking to the database now don't repeat yourself is a mantra we always talk about when we're doing software development and I've just broken it here I've essentially copied and repeated that relationship orbe at two different levels of abstraction and I don't like that so what I'm going to do is I'm going to delete one of them now you have to
• 28:30 - 29:00 delete the right one I'm going to delete the top level one so I'm going to define the link between the user and the web app and the web app and the database if I save this go back here refresh so these two arrows are the two arrows in this text file those are the ones we've explicitly defined if I go back to my context diagram this arrow is still here so this is a feature I created called implied relationships because there is a relationship between the user and the web application which
• 29:00 - 29:30 is a container of the Software System there is an implied link between the user and the Software System itself and you can customize this and and turn it off and and do whatever you want to it's basically just a bunch of java code running under the scenes and you can plug in different strategies if you want to but yeah it's a really nice powerful feature that reduces the number of relationships that you have to Define manually when you're creating your architecture diagrams uh so that's pretty cool something I never show in my demos is is
• 29:30 - 30:00 include with different things so in in all of the conference soures and demos and tutorials I've done I've just left this as include star and it always raises lots of questions so include Star as I said it it varies on on the context of the The View type that you're defining here I can change this to say include the Buu the web app and the database and that will still work so you can include things individually if you want to we could also do includes um on separate lines so that's
• 30:00 - 30:30 also going to work we can also do something like element. type equals container so there's a little expression language built into the DSL which allows you to do a bunch of different things which is going to give us the same result we can also do things like elements. parent equals F FRS that's going to give us the same result and the this is the one I like the
• 30:30 - 31:00 most so we'll include web app which gives a that box if we add an arrow before and an arrow afterwards we get all our boxes back so this is the power of having a little expression language on top of that model it's a force directed graph so we can just basically go Traverse the model so what this says is include things coming into web app of the appropriate type for the GU for the diagram you have and include things coming out of the web app so the afren
• 31:00 - 31:30 and the Efren couplings if you want to use that terminology so yeah there's a whole bunch of cool Expressions that you can use to slice and dice your models not particularly useful here but I'll come back to this feature later on because it's a great way to uh partition and create diagrams for much more larger and complicated software systems so that's my context and container diagram and there's a bunch of stuff you can do through this UI you can export it to PNG file and SVG files and a whole bunch of other stuff you can just fire up and have a play if you want
• 31:30 - 32:00 to gray boxes right we need to fix gray boxes I I I know I said that C4 is notation independent but this has no notation currently it's just gray boxes so let's let's try and fix that let's add some color as a starting point what I'm going to do is I'm going to add a Styles block now what goes in the Styles block if I enable this little button here tool tips and hover the mouse over you'll see a little tool tip and it says element and person so these are text
• 32:00 - 32:30 based tags associated with that element the Financial Risk system element has an element tag and a software system tag remember you have done front-end development HTML and CSS you have a HTML element and a bunch of CSS classes it's exactly the same concept so what we need to do now is essentially create an element style for a specific tag and the style will be reflected where that tag is present in the model so we can say create an element style for the element tag so we can we can um Target
• 32:30 - 33:00 everything and we can say background green color white so now we've got white on green we can change the shape as well so we can say shape rounded box give it some Web 2.0 around the corners and that's that's applied to all all of our elements El here let's change the uh shape of the person to a person
• 33:00 - 33:30 shape uh it's just the same deal we're going to create an element style for the person tag and the shape is going to be person so that's our person go down to our container diagram this kind of looks okay but it'd be really nice if we had like a database shape how do we do a database shape uh tool tips element and person tags element and container tags element and container tags so I can't Target
• 33:30 - 34:00 container because that's going to hit web app and database I need to add a new tag uh so I can Target the style accordingly so how do I do that go back up here tags database that should work go back save refresh tool tips element container database tags so now we can create an element style for the database tag and the shape is going to be any
• 34:00 - 34:30 ideas cylinder who said database no cylinder so there's our our cylinder shape and if we want to make that a different color we absolutely can do so one the things I said is c4 is notation dependent as demonstrated I also said make sure you use a self-describing notation now I've used a blue cylinder to represent a database but that might not be obvious to some of you this tooling generates you a diagram key
• 34:30 - 35:00 automatically based upon the tags in the model and the styles that you create so this is a really nice way to have that all taken care of if you're using tools at Visio you have to make sure your diagram key provided you create one of course uh matches your diagrams what they actually look like and there's a bunch of stuff you can do here you can add icons and change border Styles and there's yeah there's lots of stuff you can do here if you want to so that's that's the kind of basics of the structurize of DSL uh different views
• 35:00 - 35:30 I've showed you some of the expression syntax and and how to do some of that styling what I want to do now is I want to just show you that this is all rendering tool independent so this is the structurer light renderer also on GitHub is a bunch of tooling called the structu CLI there's a lot of command line interface it's basically a little Java wrap and it embeds all all of the uh the libraries that I built again which are all open all on GitHub and you can use the structurer CLI to export
• 35:30 - 36:00 views defined in a workspace to different formats so I've got the CLI already installed we can say structurize our export the workspace is going to be that same example we just showed you so we pointed to the um the workspace DSL file and the format is going to be fromat plant uml so what this does now now is it creates you a bunch of plant uml files which you can basically just
• 36:00 - 36:30 drop into plant uml as before and you get your diagrams now rather than me copying this out onto my clipboard going into PL email and firing it all up I'm going to show you the structurized demo page which is structurize DSL going to take my work space we were just creating I'm going to copy it in fingers crossed we get the same diagram so this the same diagram we just had in the
• 36:30 - 37:00 local structu of light tooling going to hide that so here's our plant em export so the export utilities it's just another Java Library it's also on GE tab all open source this demo page basically embeds the same function functionality as the CLI so here's our plant gml um uh definition for that system context diagram so that's the system context diagram there so there's the diagram there's a key so
• 37:00 - 37:30 what you'll notice is the different rendering tools different rendering engines give you a different set of shapes so I've tried to make the exports as close to the structurized versions as possible but that's not the case um across all of the different rendering engines so that's the context diagram and this is the container diagram which should should have the blue database and there's the diagram key so this is a really nice way to create all your plant uml files from a single model so you can still use your plant uml tooling but you you're just not writing the plant uml
• 37:30 - 38:00 files by hand that's the difference here there is an export to C4 plant DL that's also supported so this will generate you a shorter more succinct uh plant DL definition based on the C4 plant uml macros for those of you who are mermaid fans there is also a mermaid export so here is the system context diagram and here is the container diagram there's an export to dots so if you're a fan of kind of raw Dot and graph is
• 38:00 - 38:30 tools there's an export for that and if you have Dynamic diagrams so um like thing a calls thing B calls thing C sends responses back you can export those to sequence diagrams for use uh for rendering with weap sequence diagrams if you want to so that's another really nice feature it's rendering tool independent if you have your own tool you want to build absolutely just Slurp in the model and then you can render it however you want to which is kind of quite nice um what else do I want to show you
• 38:30 - 39:00 probably just a couple more things one of the big questions I get with this tooling is well how does it work when you get bigger more complicated models can you do things like include uh yes you absolutely can do so what we can do if we go back to our devox example we can take this whole thing out uh open up a new file we'll save that as model. DSL and we can go back and we can just
• 39:00 - 39:30 do include model. DSL so that will hopefully still give us the same result so there support for includes here and all include does is it kind of inlines the file that you point it at you can also point it at a folder one of the things to bear in mind with the structurized DSL is that ordering is important the reason is important is because it affects how and and when and whether those implied relationships are defined so with that in mind if you point the
• 39:30 - 40:00 the exclamation mark include statement to a folder of DSL files you need to make sure they are in the right order from a kind of file name alphabetical perspective just a little gut that kind of catches people out if you want to do kind of Enterprise wide modeling um what you can do is let's create another file so we can say workspace model let's create a software
• 40:00 - 40:30 system called a so imagine we have a a landscape of systems in our environment we can create a DSL file that basically defines all the systems in our environment so who's using backstage Spotify backstage or a service catalog it's the same kind of concept you want to go and register all of your systems in a central place and then what we can do with our workspace is we can say um we extend
• 40:30 - 41:00 landscape and we can do things like what have I done I've just wrecked my demo that's fine what we can do is we can say model and we can do exclamation mark ref a so basically go and find Software System a that's defined in the landscape and now we can add our web application so this is very nice because now you can have a central definition of all of your
• 41:00 - 41:30 software systems and then have each team produce their own DSL file that that documents the internals of that Software System containers components relationships and then they can own that but you still have your central definition there are some interesting decisions that you need to make here when you take this approach and one of those decisions is where do you put the relationships so in your landscape do you justify software systems or do you also Define all of the potential people
• 41:30 - 42:00 and roles and actors and personas that use all of the software systems in your landscape if you want to do that where do you find the relationships between them it's really do you want a centralized model of your architecture or a decentralized model my preference is to go for a decentralized model so your landscape file just defines systems and then every team defines people and relationships to those systems the question then comes well how do I generate myself a nice big single landscape diagram that has all of the
• 42:00 - 42:30 links between people and between systems and the answer is you write yourself a DSL plug-in for example that goes and loads all of the child workspaces and figures out what the relationships are and kind of creates a landscape um model of all of your actual data so there's a there's a bunch of kind of advanced stuff that you can get into there if you want to so let me shut this Docker container down and I want to show you another a little example so this is really how how do we
• 42:30 - 43:00 deal with like bigger systems where we've got more things more Boxes Etc so I have like a um a Services style example so let's go structure a light so imagine we have some sort of a service-based architecture now this is a bit of a weird service based architecture imagine we have one Software System that's the little grain line you probably we can't see that on the screen and inside that one software system is a bunch of services
• 43:00 - 43:30 microservices if if you want to use that term I'm saying here that every service is comprised of an API thing and a database thing and in this particular example our software system is made up of eight services and there are some links between each of those eight services and this is what my all containers diagram looks like it's showing me all of the API applications and all of the data stores associated with all of the services inside our Software System foundary now this doesn't look too bad we only have eight
• 43:30 - 44:00 Services here but imagine we started adding service 9 service 10 service 11 service 20 service 50 this diagram would start to get complicated quite quickly so the question then becomes for how do we deal with a growing um a growing Software System in terms of scale and complexity so this diagram is showing you one diagram with eight Services what you could do instead is you could draw one diagram per service so here is a container diagram just focused on service one things
• 44:00 - 44:30 coming into service one and things coming out of service one here was a service two version same deal here was a service 3 version you get the picture so the question becomes how do you do that and of course with a tool like Vis it's it's impossible you basically have to start copy and pasting elements and and arrows across all of your different uh diagram canvases with this particular example which is the services example here let me show you the workspace DSL file so
• 44:30 - 45:00 there's a feature here that allows you to scope your variables used to identify elements uh as hierarchical I'll explain that in a second here is service one so in this in this demo I've said that service one is comprised of an API container and a database container and I'm using a concept in the DSL called a group to say this group of two things equals service
• 45:00 - 45:30 one this is kind of important because when many people use C4 they want to Define Service as an abstraction and they'll typically do that by saying a service equals a container and then the API thing and a database schema are components inside that container but that's not correct according to the C4 definition because components are not separately Deployable things so that leads to this situation where the API thing and the database schema
• 45:30 - 46:00 are the containers and it's really just the grouping of these two things that is the system so that's service one service two is defined in the same way service three is defined in the same way as a service four etc etc and to create the example I created a bunch of links between the services this is the all containers definition it says incl uh draw me a container View for the software system include all containers this is the service one version so it's including service one so we're referring
• 46:00 - 46:30 to that combination of the API and the data store things coming into that group and things leaving that group so this is why the expression language is quite powerful if you have a large and complicated model of your system whether it's a components in a month or set services in a distributed architecture or even systems in a landscape you can use the Expression functionality here to slice and dice your model to produce those subs it's all partition views so it's a really nice feature it's really powerful you get all the consistency of
• 46:30 - 47:00 the of of the model based approach the downside of this and again it's all trade-offs the downside is in this view you get the big picture you get everything but as you add more boxes it gets more complicated to see what's going on you have more overlapping lines etc etc this view is simpler but now you lack context around it so like you have a set of blinkers on it and you'll just focus on a tiny portion of your of your software model here so it's all
• 47:00 - 47:30 trade-offs and maybe have a set of diagrams of each type another approach is to click this little button here and we get that how cool is that so this is a d3js force director graph showing you exactly the same information this is a a C4 model container view not rendered now as a traditional diagram but instead
• 47:30 - 48:00 rendered as a force directed graph which is interactive so we can start clicking on things to see nearest neighbors there's a quick find feature so this is a really nice way to again explore and navigate a larger data set so if you have a complicated distributed architecture or you have a complicated uh portfolio in your landscape this is another visualization approach that you can use and again this is why I said the structurized tooling is rendering tour independent there's one more thing I'm going to show you here and to do this
• 48:00 - 48:30 I'm going to go back to the DSL demo page because it's easier for me I'm going to click the microservices link at the bottom so if you want to see this example it's linked to on the on the page that's example I showed you before that's the graph again as I said this is all rendering tool independent you can produce the plant versions if you want to I'm going to go to igraph export to the igraph format I'm going to go to to app.com click new diagram paste mine in Click static
• 48:30 - 49:00 structure so this is an export to the igraph tool which is a really nice uh UI for exploring and visualizing a hierarchical data set the C4 model is a hierarchical data set so actually turns out this works really well and it's interactive so now we can start clicking around and trying to find nearest neighbors relationships and all that sort of thing and and if we go to the demo page again and go to the big Bank example so the big Bank example are the
• 49:00 - 49:30 diagrams you will see on the C4 website if I go export to igraph go back here copy this in Click static structure so here is the big Bank examples in igraph where we've now got multiple levels of abstraction we've got software systems containers and components and now we can start to drill in and zoom in even further on things so again you have a bunch of visualization options depending on what you are trying to do here and that's something that's worth keeping in mind it's people often tell me that C4 doesn't scale it's not
• 49:30 - 50:00 C4 not being able to scale it's the rendering tool that you're using to tell the story that you want to tell so I have one minute left and a couple of slides which is just perfect so I've given you a quick demo of the structurized DSL there are some other options that you might want to look at uh the first is called overarch or overarch uh this gives you the ability to do the same type of thing uh rendering with plant gml and you find your model in this format which is the extensible data notation edn which is
• 50:00 - 50:30 not something I've come across much but that's one option uh there's something called rdb modeling which gives you the ability to generate the same sort of thing generate a model create a model as a yaml file I don't think I can recommend people do that and where's where's Bruno when you need him um there's something called pulmer which is a way to create a model on top of plant uml I don't really understand how this works and it looks quite complicated but if you're big into the C4 plant JL ecosystem uh that might
• 50:30 - 51:00 be something you want to use and there's something called like C4 which is essentially a clone of the structurized DSL but it doesn't limit you to the four levels of abstractions you can add more levels of abstractions and even customize what those abstractions are called there are trade-offs with doing that come towards me afterwards about those trade-offs uh and the igraph tool which I showed you so again there are a bunch of options out there so thank you very much hope you fan it useful if you want to get started str.com DSL thank
• 51:00 - 51:30 [Applause] you