Simon Brown: C4 Architecture Model and Structurizr 🇬🇧🇺🇸

Okay, so welcome to another episode of, uh, Surface Tectum stream. Today, we have Simon Brown as our guest. Um, so Simon, do you want to say, first of all, thanks a lot for, for joining. Do you want to say a few words about yourself?

Sure. Um, yeah, thanks very much for inviting me. So I'm an independent consultant specializing in software architecture. So hopefully software architecture will come up a few times. The creator of the C4 model, uh, which I'm sure we'll get, we'll, uh, answer some questions about, and also a tool called Structurizr. So my background is basically as a, as a software developer working for consulting companies, uh, mostly building software with or for our customers. And for the last, kind of, ten years, I've been independent and doing consulting and training and workshops and other things. So, yeah, that's the short intro, I guess.

Excellent. Um, and so, of course, C4 and Structurizr will be the main topics that we are going to talk about today. Um, you did write a few books. So there is the book called "Software Architecture for Developers." What did you make, why did you write, write that book? I mean, software developers, at the end of the day, are not architects. So why should they care about architecture?

That's, that's very true. It's a good point. So I started writing the books back in about 2008. Um, I'd actually wrote some books prior to that, some Java books, which you can find on Amazon if you look hard enough. Uh, those were, uh, real printed books with publishing companies. And when the Agile Manifesto kind of came into play in the early 2000s, I noticed lots of people were either dropping architecture, and it's something that they weren't doing anymore. And I'm sure we'll talk about that later as well. And, and also at the time, I was trying to figure out how do we, so I was working for a consulting company, and I was trying to figure out how do I teach other developers on the teams about the stuff they should be doing as tech leads and software architects. And there are lots of books at the time. So you've got all the SEI Software Architecture in Practice books and, and there are lots of other books at the time. But I found they were very, kind of, research-driven and academic-biased books, and they didn't really answer my questions of, if I'm a software architect, what is it I actually need to do? So I was already doing some software architecture training at the time, and I had this idea for basically a book which would introduce the, the, the tools and techniques and processes of software architecture to software developers who were, you know, moving into tech lead roles and team lead roles and architecture roles. And I actually pitched this idea to a bunch of publishing companies back in 2008, and they all said no. They're like, "That sounds really boring, and it's out of fashion, and no one's going to read it." So I still published it on Leanpub and, and the rest is history. So, yeah, it's really a book targeted at software developers who want to know more about architecture. It's, it's not super advanced. It's not going to cover microservices and serverless and any of the, the kind of technical aspects. So it's a book really about, uh, the, the process and the techniques and, and things like that.

Yeah, and I think those basics are actually so very important. So, so that's great. I took a look at the chapters in your books, and there were two questions that caught my eye. So, one is, "Do agile teams actually need software architects?" Do they?

So, if, if you ask most people, well, let me step back. If you asked most people that question 10 years ago, a lot of the answers you'd get would be no, and a whole bunch of reasons would be given. If you ask that question now, I think you'll see more teams saying, "Actually, yes, we do need at least someone playing the role of architect." And it could be one person, it could be many people, that's a kind of different discussion. But every team needs some degree of technical leadership. And I think the software architecture role is what provides that technical leadership in many instances. And of course, the reason teams are realizing this now is because they, they've done the past 10 years and kind of forgotten about the architecture stuff. And our world's got a lot more complex, isn't it? We've got cloud services, we've got microservices, we've got serverless things, we've got Docker and Kubernetes and all this stuff. And people are just plowing it into their projects, plus all the front-end stuff of React and Angular and things. And, and a lot of these projects and products are just a complete mess now, and they've had no technical leadership. And, and I think teams are now thinking, "Actually, we should have done some more thinking in those earlier stages." So we need some degree of architecture. And also, we can't document and communicate what we have now because we don't really understand how it works. So, yeah, I think that the tide's turning on that front, thankfully.

Yeah, and I mean, software architecture is probably one of the things that you can't, that you, you will always do, even if you don't really do it, because at the end of the day, your system will have an architecture. There is actually a question from, from the audience by Forbodi on Twitch, and he asks, "Is there any chance that 'Software Architecture for Developers' will ever be available as a printed book?"

I get this question, uh, every couple of months. And, and, and the answer at the moment is still no, I'm afraid. Um, I kind of in two minds. One, one part of me says I should, I should, because although I asked all these publishing companies, uh, like back in 2008, "Would you like to publish a book?" and they all said no, most of them have actually approached me in the past 10 years asking if they could, uh, publish my book because they've seen the, the, the sales and reader numbers on Leanpub. It's always all published, of course. So part of me thinks I should do that, and then I'll be a printed book. And part of me thinks I should just do the print-on-demand thing. But the books are still not finished. So that, that's one of the reasons I'm kind of keeping them as ebooks. There's always little updates I'm making and stuff I'm figuring out and learning. So at the moment, the short answer is there's no printed version, um, in, in the works, I'm afraid. Sorry about that.

You could print each page out if you want to.

Yeah, yeah, I have seen people do that. Yeah.

I have to admit, I'm, I'm, I'm a little bit more relaxed. So all of the books that I've written, even though I do change them from time to time, they're available as print-on-demand. But I, I do see where you're coming from. The, the other question in your book that caught my eye is, uh, "So do software architects code?"

So from my perspective, ideally, yes. And again, this goes back to the way I used to work. So when I used to work for consulting companies, uh, building software as a team, either with our customers or for our customers, I was always part of the team. So I might have had the software architect role, but I was also part of the team who's actually building the system as well and writing code. And I think that's hugely important because you get feedback on the decisions that you're making collectively as a team. So you can see where stuff's working, where stuff's not working. If, if you're not keeping a pulse on the code, you can't figure out if other team members have stopped following the guidelines and principles and constraints that we all agree to as a team. So again, if you're in the code base, you can kind of see what's going on, uh, much, much easier. So my, my ideal here is, is, you know, if you're doing software architecture, you should write some code. And also, it's a great way to keep skills up to date because everything's changing so quickly. So, yeah.

Um, so concerning the, I mean, you could also do code reviews, couldn't you? That would also be an option, then you wouldn't really code, and you would still see what is actually going, uh, happening in the code base. So, I, I worked on a project once, and they wanted me to go in as a consultant architect, and this is a customer team, and, and all the developers worked for the customer, right? So I went in as a consultant architect, and, and this customer had, I think, three or four architects that they wanted me to kind of mentor. And, and they didn't actually give me a computer on purpose because they didn't want me writing lots of code. And I can see what they did, and I can see why they did it. But that didn't make doing things like code reviews hard. And when I did get access to the source code, just doing code reviews is really boring. So that's, that's why it's definitely possible, but I'm, I'm not a huge fan of that approach, I'm afraid.

I mean, I have to admit that, and that is why, why I really wanted to ask the question. I have to admit that I have a different opinion, but maybe also a different, different reasoning. So I think that as an architect, your primary goal is to communicate and to figure out what, what is to talk to people. And I don't really feel that coding is strictly necessary. So that is why, why I was interested in, in your opinion about that.

Different, uh, different organizations, different companies, different teams have, have very different approaches. So my approach is, I, I definitely want to spend half my time doing the stuff you've just talked about, and half the time doing the coding stuff. And part of that is just because I still enjoy coding. Um, but I've, I've definitely seen organizations where they kind of disallow, is, is maybe too strong a phrase, but they, they don't encourage their architects to write code because they, they want to be out there, uh, talking to people, meetings, communication, that sort of thing. And, and maybe they're playing a little bit of a higher-level, uh, role of architects in their organizations, maybe not working on a single team at a time, but maybe they will keep working across our portfolio of products, for example. So, yeah, you've lots of different aspects here.

Great. Um, so, but nowadays, um, you're mostly focusing on, [Music] you're mostly focusing on C4, I guess, and, and Structurizr. Uh, so I guess C4 is sort of the, the, the older project, or the older idea. So what is it?

So the C4 model is essentially a technique for drawing a hierarchical set of software architecture diagrams at different levels of abstraction. So I'm going to step back again to about 2006, 2008. So I was running software architecture courses, uh, and part of the, the workshops I was running was, I was getting groups of people to, you know, like, "Here's some requirements, go do some design as a group, and then draw some diagrams to describe the solution you've come up with." And after doing that for a while, I noticed that all the diagrams were completely different. There was no consistency. I couldn't understand half of them. That, the groups that had drawn the diagrams couldn't understand the diagrams half the time as well. And I just figured that we have to do something here. UML is obviously UML, it's been around, uh, since the late '90s. I personally was a big UML fan. I used UML quite extensively for about the first six or eight years of my career, uh, Rational Rose and Select Enterprise and Rational Software Architect and, and all those toolsets. But after the Agile Manifesto came along, not a lot of teams want to use UML. And with that in mind, I think a lot of teams switched from doing the kind of UML-style diagram to something basically ad hoc. And you'll see this if you, if you go search the web, you'll see lots of people all those years ago is basically advocating, "You don't need to use UML, just go use a whiteboard and sketch ideas and have conversations and then erase the whiteboard when you're done." And that's fine. But the kind of point we got to is that we lacked any consistency and guidance around communicating and diagramming architectures. So basically, what I did was, I, I had a way that I drew my architecture diagrams that I thought worked quite well, and other people tended to like it. And I just thought that's the way everybody else did it as well. And it turns out that wasn't so. The C4 model is essentially a formalization of how I used to draw architecture diagrams post-UML. That's it.

And what I like, the, because you're comparing it so much to UML, what are the lessons learned from UML that you took, and where you did something different to make sure that it's actually used and also used in the long term?

So the big one is, it is really keeping it as simple as possible. So if, if you look at the spectrum of approaches you could use, on one hand, you've got UML with a very, kind of, fixed and formal notation. You've got lots of, um, lots of syntactical variations. Every tool does things maybe slightly differently. And the, um, specification is like 750 pages or something when I last looked at it. On the other side, you've got whiteboards where people are just drawing boxes and arrows and kind of hoping for the best, and there's no consistency there. What I wanted to do is essentially bring some structure to those ad hoc and very imprecise diagrams that people were drawing on whiteboards. But I didn't want to basically reinvent UML. And of course, it's a very slippery slope. So the C4 model is, it's a set of hierarchical diagrams. So C4 stands for Context, so, uh, the context of the software system you are looking to build or document, then Containers, and then Components, and then, and then Code. And the C4 model itself actually does not prescribe a specific notation. So when you go into the c4model.com website, you'll see some example diagrams, and they're kind of boxes and lines diagrams with a little bit of formalism. But you can use any notation you want to. So if you want to, you could actually use the UML, uh, diagram types and syntax and tooling to create the C4 model style of diagrams. And that was kind of a, a conscious decision because the second you put a notation out there, you'll get a thousand people emailing you saying, "Your notation doesn't cover this particular edge scenario that I want to do," or, "It doesn't cover this type of diagram." So what, so the C4 model is really aimed at the kind of 80 or 90 majority who just want something structured and quick and simple. And then once they get past that and they want to do more complicated, more sophisticated, more precise stuff, um, then they should perhaps move into UML. So, so really, in, in essence, you know, from looking at, from one perspective, it's a simplified version of UML. Um, from another perspective, it's a stepping stone to UML. So there are different ways you can think about it, essentially.

Okay. Um, so if I understand correctly, what you're saying is there is no predefined graphical notation. It's up to you, and, and I could have boxes and arrows in any way that I like, and I could even use UML. So there is, okay. And so, so that is, um, that's one difference because, um, UML gives you a graphical notation. And the other one is that it's more lightweight, right? Because, but because you said that, that UML has this extensive specification, while you have, well, yours is much less, and it's just for diagrams, right? That's why it's called C4, or for, for how, how would you call that, artifacts, maybe, because it's not really diagrams, right? It's not about the graphic representation.

Yeah, yeah. Okay. It's, it's about, it's about different, different views at different levels of abstraction.

Great. So, so let's dive into, uh, those levels. And the first level is the system context, right? I think that's, yes.

Yeah. So the system context is basically the, the top level. And imagine you are working on building an internet banking system, and somebody asks you to draw a system context diagram. What you draw is a box representing the internet banking system, so the software system you're building, in the middle. And then to draw the rest of the diagram, you have to basically answer a bunch of questions. So question number one is, what types of users do we have, and, and how are they using the system? So you might have personal banking customers, and maybe business banking customers, and maybe support staff. So you kind of draw all the different user types on. And those user types could be real people, or roles, or actors, or personas. So again, there's lots of flexibility there. And then you also have to answer the question of, how does this system fit into the context around it? So, in other words, what other software systems does it use to do its work, or what other software systems, um, send it information? So, so really, it's just a very high-level map saying, "This is the, this is the thing we're building, and this is the context of how it fits into the, the environment around it." And that's it. It's just a super simple, high-level diagram, but it's a fantastic starting point, and it's understandable by everybody. So it's great for developers who are joining the team for the first time, it's great for architects who want to explain what they're doing to other teams, it's great for support staff and testers and product owners, and it's a diagram that everybody can understand. There's nothing technical about it at all.

Um, and as you said, there are basically four levels in, in C4. So this is one of them. So that means that, that in a way, you're saying that the system context is so very important, uh, because, so why is that? I guess you already gave sort of an explanation because you're saying that it's very useful for, for a lot of different people and different purposes. Are there other reasons why it's, um, why it's so very important to you?

Yeah, so two reasons, I guess. Um, I've seen lots of software architecture documentation in the past, and often you get halfway through the document, and you have no idea what the thing is you're building or how it fits into the world around it. So really, it's, it's an anchoring mechanism, first of all. So it's like, "This is, this is what we're building, this is the world around it, and now we can discuss what the thing is." So that's, that's a super important part of this. And the other one is, is really external system dependencies. So developers will know this, anytime you have an external system dependency, it's one of the most riskiest things you can possibly have in your codebase because if that dependency changes, if the external system goes down, you know, there's always some degree of risk, uh, inherent in talking to other external software systems. So the system context diagram also acts as a map. So here's the thing we're building, here are all our external dependencies, and then you can have those really useful conversations like, "Oh, we just heard that system X is going to be shutting down in three months. I can see there's an arrow between us, the system we're building, and system X. What's the impact?" So it allows you to do impact analysis. And again, lots of people don't have that system map, and then when something shuts down, they're super surprised that their system stops working.

Yeah, and I think that's, that's actually a very good point that you're defining things that are missing in your experience in a lot of cases, and that are very important. So I think that's, that's a very good approach. Okay. So the next level are containers, right? And, yeah, we are not talking about Docker here.

No. And, and let's just get this out the way right now. So there's an unfortunate clash of naming here. So when I came up with this naming, it was like 2008, 2010, something like that, and Docker was not a thing yet. So Docker came along a few years later and, and stormed and stole the term. I had, so what do I mean by container? By container, I basically mean an application or a data store. That's the easiest way to think about this. So, so level two is a container diagram. And what you're basically doing is, you're, you're drawing a diagram, you're opening up the internals of the internet banking system, or the system that you are building, and you're showing the containers that make up that system. So by containers, I mean applications and data stores. So essentially, a container diagram shows high-level technical things like single-page applications, server-side applications, database schemas, collections, and document databases, buckets on Amazon S3, batch scripts, cron jobs. It's essentially separately runnable, deployable, often individual processes. And the reason I chose the word container is because I didn't want to use the word process, I didn't want to use the word application. So I, I tried to go for something a bit more generic. I was into Java at the time, and we talked about servlet containers and EJB containers, and I just kind of liked that term. Yeah. And, and I, I used the term container, and then Docker came along. So, yeah, it's a basic thing about it as applications and data stores, so things that have to be running for your system to work.

Yeah. What's just, it's just funny to be reminded about that, because I, I almost forgot about this, this term in, in the Java world. Um, so, and, and I guess that container diagram would include everything that belongs to my system, right? So it would be the, the stuff that is like, in, in the system context, it would, it would be the box that I'm building, and then I sort of zoom in and have these, uh, different technical things around it. Yeah. Um, which means that you're focusing on the, the technical side of things. Um, I would argue that it's actually quite important to separate your system into functional components, and, you know, there is Domain-Driven Design that puts a big emphasis on that. So, what do you think, um, or how would you include that, or would that be an alternative for, for a sort of second-level diagram?

So I don't want to say alternative, um, I want to say complementary. So if you look at something like 4+1, so hopefully people watching are familiar with 4+1. It's, uh, Philippe Kruchten, late 1990s. So I think what you're talking about is really kind of the, the logical view that says, "Here's all the functionality, and this is how it's broken up into logical things, maybe subsystems or components, whatever that might be." Useful thing to do in many teams, especially if you've got a very big system, you might want to show how the functionality is kind of logically split up across the system. And if that's useful to your team, then I would definitely recommend doing that as a complementary thing to the C4 diagrams. The thing I've noticed though, is, is when I've run my architecture workshops, people have drawn those kind of 4+1 logical style diagrams where they're showing functional blocks, and often those diagrams don't actually make sense, or they don't reflect the reality of what's actually going to be built. And I see this more often when I get teams to draw diagrams of their existing systems, and they do all these funny logical architecture diagrams, and then you say, "Right, how does this, you know, what does the code look like?" And they draw you something completely different. And, and what I wanted to do, and again, this is a very conscious choice, if you look at 4+1, you've got the logical view and the separate development view. I simply wanted to collapse them both together. So I wanted to draw a very real-world, technical-focused diagram that says, "We're building a system, and it's made up of three applications talking to a message queue, talking to a database." That's exactly the type of diagram that a developer wanted to draw, and that's the type of diagram that I found other developers responded well to. So if the logical, functional thing is useful, definitely do it. But I'm trying to do something very different here.

Okay. And, and what I do like about that is also the point that you're making that it's sort of that it is sort of like the, the objective truth, because you can go out there and look whether that's really what is running there and what, what that, what you have done built, yeah, based on the technology, or whether it's something different.

It also stops people lying as well, because, um, sometimes when I ask teams to draw me a picture of their software, they'll draw like a web application box, and they'll draw an API server box, and an awesome, you know, those two things separately deployable on infrastructure. And I'll say, "No, it's all one thing. So it's all one Visual Studio project, but we've drawn it as two separate logical boxes." And I said, "Well, that's, that's nice, but you, that's not the truth. You know, you've got one application, one deployable application with lots of stuff inside it, and that's the diagram I want you to draw because it reflects reality." So again, I'm, I'm all about, let's draw diagrams that actually make sense and that reflect the realities of the real world. And if you have one big monolith and everything's chunked inside it, let's draw that picture because it's useful, which it might be.

Another, another, um, difference to to UML, because, um, UML gives you all like a complete toolbox, while you're focusing on, on things that you think, or that you learned, are actually valuable to you.

The biggest problem with UML is that there's no guidance. You know, if you're starting out as a developer, as a developer, and you say, "Where do I start with UML?" There's just nothing. There's no good example diagrams, even for the developers. There's just nothing.

Okay. And, um, the next level are components, right?

Yeah. They're nice, vague term, components. Yeah. So once you've got your set of containers at level two, your container diagram, and maybe you've got a Java Spring web application talking to a database. So level three is basically, let's open up that Java Spring web application and see the components inside it. So there are lots of different definitions out there for components. In some definitions, a component is a separately deployable unit, and in other definitions, it's not. So I've, I've explicitly chosen the case where components in the C4 model are not individually deployable units. So all components in the C4 model have to run inside what I'm calling a container. So the container is the deployable executable process boundary. And then components are groupings of things, groupings of functionality, essentially running inside those containers. Now, of course, components are a vague term, and every codebase is going to have its own definition of components, and every team is going to have their own definition of components. But basically, so if I'm building like a Java Spring MVC type application, many of my components end up being a Java interface with one or more implementation classes sitting behind it. And it's those things that we, we can figure out with Spring notation, for example.

Okay. Um, but what, what you're saying, in a way, also with the example, is that there is no clear definition, because what you said is, "It ends up, you know, an interface with multiple implementations," but it could be something different. I, I guess there could be like one controller, one web controller, that you might also consider a component. And of course, people structure their codebases differently. Some do package by layer, some do package by feature. I do package by component and ports adapters, hexagonal. There's all, there's a whole bunch of different ways you can organize your codebase. So essentially, what I'm saying is, level three, the component level diagram, should reflect the high-level structure of your codebase.

I mean, one of the things that I think is important is that, that the diagram has a clear, it has clear semantics. Don't you lose that if, with, with the component diagram, because you're using that term component, and that is loosely defined anyway, and what you're, what you're saying in, in the discussion is, "Well, this might be a component or not." So if I look at the source code, it's not entirely clear whether this would be a component, it has to be in, in the diagram or not. And also, I guess, the other way around, so if there is something in the diagram, I'm, it might be in the code or not. So how do you deal with that, or what do you think?

There are two ways to deal with this. Um, number one, before drawing a component diagram, the team has to agree on what they think a component is. And therefore, they have to come up with a set of heuristics as to how do we, as a bunch of developers, identify components in our own codebase. Once you've come up with that set of heuristics, I don't think you should manually draw these component-level diagrams. I think you should auto-generate these component-level diagrams from your codebase itself. And then you get a nice one-to-one map, one-to-one mapping between the codebase and the diagram, if your heuristics are accurate. So level one and two of the C4 model, I think are useful for everybody. I was going to say mandatory, then, but that's not what I wanted to say. So I think levels one and two are useful for all teams, regardless of what they're building. Once you get down to levels three and four, I think there's less use here, and these are definitely optional levels of detail. One of the interesting things I found out over the past few years is, in order to auto-generate a component-level diagram from a codebase, you need to understand how you think about components. So you need to come up with that set of heuristics, so set of rules. So maybe in our codebase, every component has a named interface which has been annotated with a special marker interface, and then all of the implementation classes are part of that component. So once you identify those rules and those heuristics, you can then write some code to essentially automate that process for you, and then you get your diagram pop out essentially for free. The thing I've noticed is, once you do that, you often have to clean up your codebase because your heuristics don't work. Once your heuristics do work, and you can automate all the rules for generating a component diagram, because your codebase is now so clean, you don't actually need that component diagram.

Yeah, that's, that's that's kind of interesting. I thought. Yeah, yeah, that's a good one. So it basically means if, if you're building that, the component diagram, it's a good way, uh, to make sure that your code is actually, uh, sort of clean.

So I think that's, that's quite interesting what you're, what you're saying, because [Music] if I have a diagram, there are different purposes that it could fulfill. So there might be the purpose to use it in a design session, or to onboard new members, or what have you. And obviously, if you say that the, the component diagrams should be generated from the source code, then this is not really useful for design sessions, or are they? So, so what is your, sort of, overall goal? Which, which of the applications that you might have for diagrams are you focusing, or architecture models are you focusing on with C4?

With the top two levels, with the context and the container diagram, those are definitely useful for upfront design sessions. So if you, if you've got a problem statement or a set of goals, and you need to do some degree of design, the system context and the container diagrams are a great way to walk through the problem-solving process, to come up with solutions, to diagram the solutions, to get feedback. So I think those two diagrams are very useful for an upfront design exercise. And also subsequently, once you start having code, those diagrams are useful for a documentation perspective. So this is what we have built, this is how it works. When you get down to level three components, it's sometimes quite a lot of work to draw up those component diagrams in advance. So if you have no code, and you're using a whiteboard or a piece of paper, it's quite hard to come up with those component diagrams. So if you've got a small system, you can do that. So maybe if you've got like 20 or 30 or maybe 40 components, you can do like a CRC session, you could come up with a candidate set of components, you could draw a diagram which links all of your CRC cards together, take a photo, that might be a form of component diagram. In other cases, for upfront design, you might be better off saying, "These are the set of rules, so these are the heuristics, and this is the way we're going to structure our code, and then when we do identify components when we come to build this thing, that's how we're going to do it." So levels one and two, useful upfront and for documentation. Level three, again, starting to get down to it, might be useful, might not be useful. So you have to do it on a case-by-case basis. It depends how big the system is that you're building, we're trying to see the experience of the team, and all that sort of stuff.

Yeah, which also means that, that, um, yeah, it depends. So this, so that's good. So it's another toolbox that you can use. Let's just finish the different levels. So there is also level four, level four.

Yeah, which is code. Uh, so again, um, it's just, it's just a zoom in. So all these things are zooming from one level to the next. So you take a single component, and then you zoom in, and you show what does the internals of this component look like. And this is where you might get your diagram basically saying, "Here's, uh, here's an interface, and here's one or more implementation classes." And, and for that, you may as well use UML if you're using an or language like C or Java or whatever, because that's the best way to do this. I, so level four is definitely optional. I don't advocate or recommend people do level four unless they really, really want to for a specific reason. So maybe have a bigger component, or a component that has a slightly weird or complicated internal structure, and you might want to document that. Or maybe you want to document the overall pattern, so all of your components are following. If you've got a nice consistent codebase, that might work too. In many cases, if you fire up your IDE, and you right-click a Java package or a C# namespace, you can often just generate a UML class diagram. And if you've got a good code structure, you can often just generate a level four diagram straight out of your IDE. So that would be my preferred approach. It's really a kind of on-demand level of detail. If you need it, you know where to get it. If you don't, don't worry about drawing these diagrams by hand.

Yeah. So, so that's, that's another good one. Um, also, what concerning the, I guess one of the, the things I, I forgot about to mention that, so with, with level three, is also sort of information reduction that you sort of have a graphical representation about the, the code that that might not be, and therefore makes things obvious that might not be that obvious if you just look at the code.

Um, Marcus Schneider asked a question that I think that, that I also have on, on my list. And that's, um, so how does C4 compare to arc42? Which is, yeah, probably I should say a few words about arc42. So that's another model that has a lot of different diagrams. And my colleague Gernot Starke is deeply involved in it. And it's a different means of architecture documentation. Maybe you want to, to add a few words, but that's sort of where it is. And it is something that is actually quite popular in, in particular in Germany, yeah, and Austria and Switzerland as well.

Yeah, right. I should have said the German. And again, I guess that's just historic, isn't it? So the way I think about arc42 is that it's essentially a, a template for documenting software architecture. And if you go to arc42.org, yes, um, it gives you all the section headings and tells you what sections are, what sorts of diagrams you have, you should have. So the C4 model does not cover the entirety of arc42. So arc42 talks about, uh, quality attributes and functional requirements and constraints and a whole bunch of other stuff. So, so arc42 is, is a complete documentation package, essentially describing the software system from lots of different angles. Where C4 and C, where C4 and arc42 are either complementary or complete, depending on your point of view, of course, is that in arc42, you have the building block view, which I think is section 5. And the building block view, from my understanding, basically says, "Draw a set of hierarchical diagrams that show the building blocks that make up your software system from level zero, level one, level two, level three." And it doesn't actually tell you what those levels should correspond to. It just gives you some kind of arbitrary abstract numbers. So what many teams I work with in Germany do is they use arc42, and I totally recommend arc42, there's absolutely nothing wrong with it. But instead of these generic, um, levels for the building block view, they use the C4 model diagrams as the building block view. So level zero becomes the system context diagram, level one is containers, level two components, and so on. And I think that's a really nice way to put these two things together. So you've got the kind of richness of the arc42 template, and then you've got the explicit named levels of abstraction that the C4 model gives you. So it's a, it's a best-of-both-worlds approach.

Okay, I see. I mean, I have to admit that that is another thing that I, I try to talk people into, or try to convince them that quality attributes and these kinds of things are actually quite important. Like, you could also call them non-functional requirements, like, "What happens if a server fails?" "What about security?" "Do you have to have data privacy?" Or is it about other security things like non-repudiation, where you can prove that some user did something? So that seems to be something that is not really part of the C4 model. What's, what's the reasoning behind that? Or because I would argue that ideally, you should be very aware of these points about the quality and your requirements in that regard.

I said, the C4 model was really just about diagramming. That's, that's the only reason it doesn't cover quality attributes and constraints and all that sort of stuff. So, uh, in my "Software Architecture for Developers" books, in the second volume, that the second volume is split into the first half is about the C4 model, and the second half is about documentation. And, and in there, I have a documentation template which actually looks really much like arc42, with different, um, different section headings and different orderings. And it's quite funny because I was completely unaware of arc42 when I wrote this. For having, having met, uh, the arc42 folks, we, we basically agreed on the same stuff, just in a different order. So I'll quite happily recommend my template, or the arc42 template, with some good diagrams in between. So, yeah, C4 model diagrams, and then all of the other stuff is really kind of supplementary documentation sitting around the diagrams. Something you can do, of course, is once you have a good set of diagrams, is you can, you can show perspectives on perspectives onto those diagrams. So although the C4 model, as I've described it so far, really just focuses on static structure, so it's system context, containers, components, code. If you go to c4model.com, there are also a bunch of supplementary diagrams. So there's a dynamic diagram that allows you to describe pretty much what you'd use a sequence diagram for, so sets of interactions for achieving workflows and user stories and features. And then there's a deployment diagram. And the C4 model deployment diagram shows you the mapping of C4 model containers to things in the infrastructure world, which could be Docker containers, of course. So you might have a C4 container sitting inside a Docker container. Once you have that as a diagram, then you can put some perspectives on it. So I wouldn't want to nick Buzzard's talk about this a lot in their "Software Systems Architecture" book. So you have a diagram, and you, you, you add some degree of layering of information on it. So you take your, your book standard deployment diagram, and then you only highlight the things that talk about security, for example. So you might have, uh, an additional layer of information that says, "These are all of the security aspects relating to this particular deployment." So there are ways to add additional information onto the diagrams, but obviously, you can't do that with a flat PNG file. You have to use something a bit more sophisticated, like a modeling tool.

Okay, talking about more sophisticated tools, that's probably the point where we can talk about, uh, Structurizr. So, so what's that?

So Structurizr is, it's many things now. It's the easiest way to think about it is that it's a collection of tooling that mostly helps you create software architecture diagrams. Again, there's, there's some history here. So I was running all these workshops around the world, and up until about 2014, 2015, teams would always say, "We really like the C4 model, we can see it's really useful. What tooling do you recommend?" And up until that point, I was basically saying, "Well, just use a drawing tool, because it's all just boxes and lines." The problem with the drawing tool is that if you've got a system context diagram here, and a container diagram here, the set of elements should match. So if you've got a user called a user X, you should have user X on both diagrams. If you're creating multiple diagrams, there's potential, you know, if you rename something on one diagram, you forget to rename it on another diagram. And that's the big problem with most diagramming tools out there, including whiteboards, including Visio, on the graph, or draw.io, even PlantUML, Mermaid, all of these tools where you're just drawing diagrams, and you have individual either work, individual tabs, or individual files for defining a diagram. There's potential for all of that stuff to get out of sync. So what I wanted to do was to build some, some modeling tooling. And instantly, lots of people get turned off. They're like, "Oh, we don't want to do modeling again." But basically, what I wanted to do was, I wanted to to allow people to create a single definition of their thing with different levels of detail included in that single definition, and then generate those multiple levels of diagram automatically based upon that single model. So now all the diagrams are completely consistent and in sync with one another. And that's essentially what Structurizr allows you to do. So I think I've over complicated things now, because Structurizr is, is so many different things that have been built over the years. So there's a free part, and there's a paid part, and there's some proprietary stuff, and there's some open source stuff. So this, this model that we're building up, this model is, is documented and represented by an open source JSON format, and that's all on GitHub, and you can, you can see that it's all spec'd up in OpenAPI. And then there's a bunch of tooling that sits around that, and basically allows you to define a model, um, in a number of different ways, and they all generate that single, same JSON definition representing your model and the views into that model. So the ways you can create that JSON model are, there are some open source libraries for languages like Java, C#, there's a Go library now, there's a PHP library, there's a Python library. And what those things allow you to do is allow you to write some code in a, a kind of code-like domain-specific language. You run that code, and then it generates your JSON document. Something I did during lockdown last year was I created a text-based DSL. So it's called the Structurizr DSL, and that allows you to create a very succinct definition of a model with multiple views. And then you run that through some tooling, and it creates the same JSON document. What do you do with this JSON document now? You have a bunch of options. So I created some tooling which is available at structurizr.com. Structurizr.com is basically a cloud service, it's a software as a service platform. You upload your JSON document representing your software architecture model, and it will render some diagrams with an in-browser rendering engine. And there's also an on-premises version of that. Those, the cloud service and the on-premises version, uh, come in free and paid variants. So the free variant will will give you all the tools you

need to create diagrams, but you're going to miss out on basically the ability to share your diagrams with team members and role-based security and that sort of things.

Something else you can do, and again, something else I did during lockdown, was I wrote a a command line application for for Structurizer called the Structurizer CLI. And you install this thing as a little Java app, and basically what you do is you feed it the Structurizer domain-specific language, and it will either upload it to the cloud service or the on-premises Structurizer installation for you. And you get the in-browser diagrams, or there's also the capability to export the diagrams in that domain-specific language to PlantUML, Mermaid, Web Sequence Diagrams, and eGraph.

So from this one, so let's forget all the code stuff. So from this one textual domain-specific language, you define your software systems that contains the components and all the relationships between the stuff. You define a bunch of views. This is all in one single text file. And then you either upload it to my tooling, get some nice web-based diagrams that were all clickable and hierarchical and that sort of thing, or you can export all of the diagrams defined in that DSL file to a collection of PlantUML definitions, which you can then throw through PlantUML and get a consistent set of diagrams.

So that's the the tooling in a nutshell. It's it's a way to generate diagrams from a single model, a single view of the world. Okay. Um, so that basically means that you are actually really modeling the the system, and then you you generate the diagrams, which is sort of also the the core of C4, it seems. And how do you make sure that this stuff is actually consistent with with what is happening in in your system? So that means if you if you do some change, you would need to change the model. And I mean, that's sort of the basic problem that I guess you have with, um, yeah, architecture documentation anyways. Yeah, with documentation in general. Yeah. So if you are manually typing in either the code or the text, the the text-based DSL you write, as soon as you make a change to your actual codebase, your your text, your definition of your model, it's going to be out of date.

This is a bit more of an advanced use case now. I think this is a step way too far from most teams out there. But what you can do, what you can look at, is auto-generating that model based upon your actual codebase. [Music] It turns out that actually quite hard to do from a practical perspective. So if you give me, so let's say you send me all of the source code for a project you're working on, and it's a big IntelliJ file with all the source code. If I fire up that IntelliJ file and I load it into my my IDE, there's not enough information in that codebase to say to allow me to draw a context diagram. So nowhere in your codebase is is it is it easy to parse out, "We're building a system X, it talks to systems one, two, and three, and it has these user types." So that level of information is not actually present in the codebase.

So this is one of the big issues with auto-generating software architecture documentation. At the container level, you might be able to do that. So if you give me your IntelliJ file and I load it up into my IDE, I can see there are some public static void main program entry points, so I can assume that those things might be containers. On my container diagram, you might have some some DDL to create a database definition, so I can make some assumptions there. But again, that information is not very explicit in the codebase. So I I have to make some guesses, make some assumptions. When we get down to level three, I should be able to start to identify components. If we go back half an hour in our discussion, right? We talked about those rules and those heuristics. So if you have a way to do that, you can start to auto-generate that that third level. But it turns out the top two levels are quite hard to or to generate anyway.

So this is either really advanced. So now we have to think about adding additional levels of metadata into our codebase so that we can auto-generate these things all the time, or we perhaps take a hybrid approach where we manually specify the top two levels that are quite abstract, and then we use reflection and static code analysis to generate that third level, and we put all the thing together as a single model and have that as part of that build process. So I see teams doing that. I see teams only manually specifying the top two levels because they don't change as much, they're not as volatile. I don't think I've seen any teams generating the entirety of their architecture documentation completely automatically. Yeah, I think that's a great goal. I just don't know how to get there. Yeah.

Um, I think it's interesting that that you're sort of focusing on on the generating uh those those diagrams and those elements. I mean, an alternative would be to to solve their problem on the process level, you know, trying to do some reviews or trying to. So that's the easiest way to do it. If you've got a definition of done for your tasks, you just add lines at the bottom, have you update the architecture diagrams and documents? You're right, sometimes process trumps automation, right? So so that would be another. Yeah, yeah. I mean, at the end of the day, we are we are in the business because we want to build software, right? So, you know, trying to solve problems with software seems to be sort of natural, maybe.

Um, but if I understand correctly, or I I looked it up on the web, um, it actually said that Structurizer can also do and architecture decision records and other types of documentation. So that's that's another. Okay. So as part of the cloud service and the on-premises installation, in addition to the browser-based diagrams, there's also a way to include in your single model definition a bunch of Markdown or AsciiDoc documentation files, or a bunch of Markdown or AsciiDoc architecture decision records. And essentially, the cloud service and the on-premises installation act as a publishing platform for seeing that stuff. So, you know, if you've got a project and you're using now prices ADR tools command line tool, that's great. You get a whole bunch of Markdown files, but they're not easy to visualize. So basically, I built a way to visualize architecture decision records. You get a nice web-based view, you can navigate through them and text search and that sort of thing.

Yeah, we should probably say a few words about architectural decision records. It's basically what what the name suggests, right? So it basically says, "This is what we've decided. These are the reasons. This is why why we came to that conclusion." Those are some negative results. And, um, I think that that's pretty much it, right? Or am I? That's pretty much it. And and what a lot of teams are tending to find now is their minimum set of architecture documentation consists of a set of ADRs because that that tracks the history. Something like arc42, which gives you a nice lightweight template to describe non-functional stuff and constraints. And then the C4 diagrams. And that as a collection is is kind of many teams' minimum architecture documentation set, which is actually quite nice because it's quite light.

With the Structurizer tooling, it's all text-based as well. So you can now keep all of this stuff in version control. You can export to different diagram formats. So yeah, there's actually quite a lot of flexibility there. And you get all the consistency of building stuff off a model. And you can also attach documentation to model elements as well, if you want to. And I think that's also a good point. Uh, that that other stuff is basically plain text, or I mean, at the end of the day, some SQL file that you can put in in version control, that you can version together with your source code, and that you can run this on and these kinds of things.

Excellent. Um, I think we are pretty much done with all the questions that I had in mind. Is there anything else that you want to add? Anything that I forgot to ask you anymore? Not really. Nothing nothing springs to mind anyway. I think we've chatted around lots of things. Yeah, so we've we've probably done as a sort of full full circle around that. Um, it doesn't seem like there are any more questions on on on the chat. Um, so I think we are pretty much done. I'm just trying to figure out whether there's anything else. Um, I think that's pretty much it. Um, so thanks a lot. Thanks a lot for joining us. Welcome. Thank you. And, uh, yeah, thanks a lot for putting all the work in in C4 and Structurizer and so on. And, um, I will publish the the links to the tools that we mentioned and C4 on the website, so you can look it up there. And, uh, yeah, I hope you have you have a great weekend. And, um, next week we won't have a show because I have something different to do. And the week afterwards, I'm not entirely sure. Maybe I will talk about, um, technical debt. So that's another one because the last one was also about technical debt. So the next one will be will be me just talking about technical debt properly. Okay. Thanks a lot. And thanks again for being on the show. Thank you.