Der nachfolgende Text wurden mit KI erstellt und kann Fehler enthalten. Fehler gefunden? Bei GitHub editieren

Episode 36 - Simon Brown - C4 Architecture Model and Structurizr

Okay, so welcome to another episode of Software-Architektur im Stream.

Today we have Simon Brown as our guest.

So Simon, first of all, thanks a lot for joining.

Do you want to say a few words about yourself?

Sure.

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.

I’m the creator of the C4 model, which I’m sure we’ll answer some questions about, and also a tool called Structurizr.

So my background is basically as a software developer working for consulting companies, mostly building software with or for our customers.

And for the last kind of 10 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.

And so, of course, C4 and Structurizr will be the main topics that we are going to talk about today.

You did write a few books.

So there is the book called Software Architecture for Developers.

Why did you 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 very true.

That’s a good point.

So I started writing the books back in about 2008.

I’d actually written some books prior to that, some Java books, which you can find on Amazon if you look hard enough.

Those were real printed books with publishing companies.

And when 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 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 were lots of books out at the time.

So you’ve got all the SEI, software architecture and practice books.

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 tools and techniques and processes of software architecture to software developers who were 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 sort of published it on LeanPub, 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 not super advanced.

It’s not going to cover microservices and serverless and any of the kind of technical aspects.

So it’s a book really about the process and the techniques and things like that.

Yeah, and I think those basics are actually so very important.

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?

So do they?

So 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’ve done the past 10 years and kind of forgotten about the architecture stuff.

And our world’s got a lot more complex, hasn’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 through.

And people are just plowing it into their projects, plus all the front-end stuff, React and Angular and things.

And a lot of these projects and products are just a complete mess now, and they’ve had no technical leadership.

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 the tide’s turning on that front, thankfully.

Yeah.

And I mean, software architecture is probably one of the things that 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 the audience for Balti on Twitch, and he asks, is there any chance that software architecture for developers will ever be available as printed book?

I get this question every couple of months, and the answer at the moment is still no, I’m afraid.

I’m kind of in two minds.

One part of me says I should, because although I asked all these publishing companies, 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 publish my book because they’ve seen the sales and reader numbers on LeanPub, it’s all published, of course.

So part of me thinks I should do that, and then it’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’s one of the reasons I’m kind of keeping them as e-books.

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 in the works, I’m afraid.

Sorry about that.

You could print each page out if you want to.

I have seen people do that.

Yeah, I have to admit, 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, are available as print on demand.

But I do see where you’re coming from.

The other question in your book that caught my eye is, 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, 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 architecture role, but I was also part of the team who was 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 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 agreed to as a team.

So again, if you’re in the code base, you can kind of see what’s going on much, much easier.

So my ideal here 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.

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 happening in the code base.

So I worked on a project once and they wanted me to go in as a consultant architect.

And this was a customer team and all the developers worked for the customer.

So I went in as a consultant architect and this customer had, I think, three or four architects that they wanted me to kind of mentor.

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 did 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 why I’m, you know, it’s definitely possible, but I’m not a huge fan of that approach, I’m afraid.

I mean, I have to admit that, and that is why I really wanted to ask the question.

I have to admit that I have a different opinion, but maybe also a different reasoning.

So I think that as an architect, your primary goal is to communicate and to figure out what is… to talk to people.

And I don’t really feel that coding is strictly necessary.

So that is why I was interested in your opinion about that.

Yeah, different organizations, different companies, different teams have very different approaches.

So my approach is, 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.

But I’ve definitely seen organizations where they kind of disallow is maybe too strong a phrase, but they don’t encourage their architects to write code because they want them to be out there talking to people, meetings, communication, that sort of thing.

And maybe they’re playing a little bit of a higher level role of architects in their organizations.

Maybe they’re not working on a single team at a time, but maybe they will keep working across a portfolio of products, for example.

So yeah, lots of different aspects here.

Great.

So, but nowadays, you’re mostly focusing on C4, I guess, and Structurizr.

So I guess C4 is sort of the older project or the older idea.

So what is it?

So the C4 model is essentially a, 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, and part of 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 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.

And I think it’s a really, really good tool for the first six or eight years of my career.

Rational Roads and Select Enterprise and Rational Software Architects and all those tool sets.

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 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 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 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 really keeping it as simple as possible.

So if you look at the spectrum of approaches you could use on the one hand, you’ve got UML with a very kind of fixed and formal notation.

You’ve got lots of lots of syntactical variations.

Every tool does things maybe slightly differently.

And the UML specifications, 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 very slippery slope.

So the C4 model, it’s a set of hierarchical diagrams.

So C4 stands for context.

So the context of the software system you are looking to build or document.

Then containers and then components and then code.

And the C4 model itself actually does not prescribe a specific notation.

So when you go onto 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 diagram types and syntax and tooling to create the C4 model style of diagrams.

And that was kind of 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 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, then they should perhaps move into UML.

So really, in essence, you know, from looking at from one perspective, it’s a simplified version of UML.

From another perspective, it’s a stepping stone to UML.

So there are different ways you can think about it, essentially.

Okay.

So if I understand correctly, what you’re saying is there is no predefined graphical notation.

It’s up to you to, and I could have boxes and arrows and any way that I like, and I could even use UML.

Yep.

So there is, okay.

And so that’s one difference because UML obviously gives a graphical notation.

And the other one is that it’s more lightweight, right?

Because you said that UML has this extensive specification while yours is much less, and it’s just for diagrams, right?

That’s why it’s called C4.

Or for, how would you call that, artifacts, maybe?

Because it’s not really diagrams, right?

It’s not about the graphic representation.

Sure, yeah.

Yeah.

Okay, cool.

It’s about different views, different levels of abstraction.

Great.

So let’s dive into those levels.

And the first level is the system context, right?

I think that’s what you already said.

Yeah.

So the system context is basically 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 are 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 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 send it information?

So really, it’s just a very high level map saying, this is the thing we’re building.

And this is the context of how it fits into 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.

And as you said, there are basically four levels in C4.

So this is one of them.

So that means that in a way, you’re saying that the systems context is so very important.

So why is that?

I guess you already gave sort of an explanation because you’re saying that it’s so very useful for a lot of different people and different purposes.

Are there other reasons why it’s so very important to you?

Yeah, so two reasons I guess.

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 and how it fits into the world around it.

So really it’s an anchoring mechanism first of all.

So it’s like this is what we’re building, this is the world around it and now we can discuss what the thing is.

So that’s a super important part of this.

And the other one 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 code base because if that dependency changes, if the external system goes down, you know there’s always some degree of risk 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 of 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 actually a very good point that you’re defining things that are missing in your experience in a lot of cases and that is very important.

So I think that’s a very good approach.

Okay so the next level are containers, right?

And we are not talking about Docker here.

No and let’s just get this out of the way right now.

So there’s an unfortunate clash in 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 stormed it 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 level two is a container diagram and what you’re basically doing is 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 in 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 tried to go for something a bit more generic.

I was into Java at the time and we talked about serverless containers and EJB containers and I just kind of liked that term.

And I used the term container and then Docker came along.

So yeah, basically think of it as applications and data stores.

So things that have to be running for your system to work.

Yeah.

It’s just funny to be reminded about that because I almost forgot about this term in the Java world.

So I guess that container diagram would include everything that belongs to my system, right?

So it would be the stuff that is like in the system context, it would be the box that I’m building and then I sort of zoom in and have these different technical things around it.

Which means that you’re focusing on the technical side of things.

I would argue that it’s actually quite important to separate your system into functional components and there is domain driven design that puts a big emphasis on that.

So what do you think or how would you include that or would that be an alternative for a second level diagram?

I don’t want to say alternative.

I want to say complementary.

So if you look at something like 4 plus 1, so hopefully people watching are familiar with 4 plus 1.

It’s Philippe Kruchten, late 1990s.

So I think what you’re talking about is really kind of 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 or whatever.

That might be a 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 when I’ve run my architecture workshops, people have drawn those kind of 4 plus 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 draw 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 what I wanted to do, and again this is a very conscious choice, is if you look at 4 plus 1 you’ve got the logical view and the separate development view.

I essentially 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 I as 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 what I do like about that is also the point that you’re making that it is sort of like the objective truth because you can go out there and look whether that’s really what is running there and what you have built here based on the technology or whether it’s something different.

It also stops people lying as well because 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 I’ll ask them are those two things separately deployable on infrastructure and they’ll often 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 said well that’s nice but that’s not the truth.

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 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 might be another difference to UML because UML gives you a complete toolbox while you’re focusing on things that you think or that you learned are actually valuable to people.

The biggest problem with UML is that there’s no guidance.

If you’re starting out as a developer and you say where do I start with UML?

There’s just nothing.

There’s no good example diagrams in the developers, there’s just nothing.

Okay so and the next level are components, right?

Yeah, that nice vague term components.

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 again 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 code base 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 can figure out with Spring Notation, for example.

Okay, but 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 guess there could be like one controller, one web controller that you might also consider a component.

And of course people structure their code bases differently.

Some do package by layer, some do package by feature, I do package by component and ports and adapters, hexagons.

There’s a whole bunch of different ways you can organize your code base.

So essentially what I’m saying is level three, the component level diagram, should reflect the high level structure of your code base.

But I mean, one of the things that I think is important is that a diagram has clear semantics.

Don’t you lose that with the component diagram because you’re using that term component and that is loosely defined anyways.

And what you’re saying 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 the diagram or not.

And also, I guess, the other way around.

So if there is something in the diagram, it might be in the code or not.

So how do you deal with that?

Or what do you think about that?

There are two ways to deal with this.

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 code base.

Once you’ve come up with that set of heuristics, I don’t think you should manually draw these components level diagrams.

I think you should auto-generate these components level diagrams from your code base itself.

And then you get a nice one-to-one mapping between the code base 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 code base, you need to understand how you think about components.

So you need to come up with that set of heuristics, so a set of rules.

So maybe in our code base, 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 code base because your heuristics don’t work.

Once your heuristics do work and you can automate all the rules for generating component diagram, because your code base is now so clean, you don’t actually need that component diagram.

That’s kind of interesting, I thought.

Yeah, that’s a good one.

So it basically means if you’re building that component diagram, it’s a good way to make sure that your code base is actually sort of clean.

Yeah.

So I think that’s quite interesting what you’re saying because 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 components diagrams should be generated from the source code, then this is not really useful for design sessions or are they?

So what is your sort of overall goal?

Which of the applications that you might have for diagrams are you focusing or architecture models are you focusing on with C4?

So with the top two levels, with the context and the container diagram, those are definitely useful for upfront design sessions.

So if you’ve got a problem statement or 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 components 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, it might not be useful.

So you have to do it on a case-by-case basis.

Depends how big the system is that you’re building.

Which also means the experience of the team and all that sort of stuff.

Yeah, which also means that it depends.

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.

So again, it’s just a zoom in.

So all these things are zoomed in 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 an interface and here’s one or more implementation classes.

And for that, you may as well use UML if you’re using an OO language like C Sharp or Java or whatever, because that’s the best way to do this.

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 that all of your components are following.

If you’ve got a nice consistent code base, that might work too.

In many cases, if you fire up your IDE and you right click a Java package or a C Sharp 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 that’s another good one.

Also, I guess one of the things I forgot to mention that with level three is also sort of information reduction, that you sort of have a graphical representation about the code that might not be, and therefore makes things obvious that might not be that obvious if you just look at the code.

Yeah.

So Marcus Schneider asked a question that I think that I also have on my list.

And that’s, so how does C4 compare to ARC 42?

Which is, yeah, probably I should say a few words about ARC 42.

So that’s another model that has a lot of different diagrams.

And my colleague, Gernot Stark, is deeply involved in it.

And it’s a different means of architecture documentation.

Maybe you want to add a few words, but that’s sort of where it is.

And it is something that is actually quite popular in particular in Germany.

Yeah.

And Austria and Switzerland as well.

Yeah, right.

I should have said the German-speaking countries.

And again, I guess that’s just historic, isn’t it?

So the way I think about arc42 is that it’s essentially a template for documenting software architecture.

And if you go to arc42.org, is that a website?

Yes.

It gives you all the section headings and tells you what sections are and what sorts of diagrams you should have.

So the C4 model does not cover the entirety of arc42.

So arc42 talks about quality attributes and functional requirements and constraints and a whole bunch of other stuff.

So really arc42 is a complete documentation package essentially, describing the software system from lots of different angles.

Where C4 and arc42 are either complementary or compete, 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 0, level 1, level 2, level 3.

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, that there’s absolutely nothing wrong with it.

But instead of these generic levels for the building block view, they use the C4 model diagrams as the building block view.

So level 0 becomes the system context diagram, level 1 is containers, level 2 components, and so on.

And I think that’s a really nice way to put these two things together.

So you’ve got the 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 best-of-both-worlds approach.

Okay, I see.

I have to admit that that is another thing that I try to talk people into, or try to convince them, that quality attributes and these kinds of things are actually quite important.

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 the reasoning behind that?

Because I would argue that, ideally, you should be very aware of these points about the quality and your requirements in that regard.

Yeah, so the C4 model was really just about diagramming.

That’s the only reason it doesn’t cover quality attributes and constraints and all that sort of stuff.

So in my Software Architecture for Developers books, the second volume is split in two.

The first half is about the C4 model, and the second half is about documentation.

And in there, I have a documentation template, which actually looks really much like arc42 with different section headings and different orderings.

And it’s quite funny because I was completely unaware of arc42 when I wrote this.

But having met the arc42 folks, we basically agreed on the same stuff, just in a different order.

So I’m quite happy to recommend my template or the arc42 template with some good diagrams in between.

So yeah, C4 models, 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 show 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 Eoin Woods and Nick Rozanski talk about this a lot in their software systems architecture book.

So you have a diagram, and you add some degree of layering of information on it.

So you take your box standard deployment diagram, and then you only highlight the things that talk about security, for example.

So you might have 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 Structurizr.

So what’s that?

So Structurizr is many things now.

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 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 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 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 one diagram, you forget to rename on another diagram.

And that’s the big problem with most diagramming tools out there, including whiteboards, including Visio, OmniGraph, or Draw.io, even PlantUML, Mermaid, all of these tools where you’re just drawing diagrams, and you have 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 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 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 overcomplicated things now, because Structurizr 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 model that we’re building up, this model is documented and represented by an open source JSON format.

And that’s all on GitHub.

And 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 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, there are some open source libraries for languages like Java, C Sharp.

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 they allow you to write some code in 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.

The cloud service and the on-premises version come in free and paid variants.

So the free variant 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 command-line application for Structurizr called the Structurizr CLI.

And you install this thing.

It’s a little jar of wrap.

And basically what you do is you feed it the Structurizr domain-specific language, and it will either upload it to the cloud service or the on-premises Structurizr 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 plant UML, Mermaid, WebSequence diagrams, and Ilograph.

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 this 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 are 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 plant UML definitions, which you can then throw through plant UML and get consistent set diagrams.

So that’s the tooling in a nutshell.

It’s a way to generate diagrams from a single model, a single view of the world.

Okay.

So that basically means that you’re actually really modeling the system and then you generate the diagrams, which is sort of also the core of C4, it seems.

And how do you make sure that this stuff is actually consistent with what is happening in your system?

So that means 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 architecture documentation anyways.

Yeah.

With documentation in general.

Yeah.

So if you are manually typing in either the code or the text, the text-based DSL, you’re right.

As soon as you make changes to your actual code base, your text, your definition of your model is going to be out of date.

This is a bit more of an advanced use case.

And I think this is a step way too far for most teams out there.

But what you can look at is auto-generating that model based upon your actual code base.

It turns out that’s actually quite hard to do from a practical perspective.

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 IDE, there’s not enough information in that code base to say, to allow me to draw a context diagram.

So nowhere in your code base is it easy to parse out.

We’ve got in a system X, it talks to systems 1, 2, and 3, and it has these user types.

So that level of information is not actually present in the code base.

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 DDL to create a database definition, so I can make some assumptions there.

But again, that information is not very explicit in the code base.

So I have to make some guesses, make some assumptions.

When we get down to level 3, I should be able to start to identify components.

If we go back half an hour in our discussion, we talked about those rules and those heuristics.

So if you have a way to do that, you can start to auto-generate that third level.

But it turns out the top two levels are quite hard to auto-generate anyway.

So this is either really advanced, so now we have to think about adding additional levels of metadata into our code base 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 things together as a single model and have that as part of our 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, and it’s volatile.

I don’t think I’ve seen any teams generating the entirety of their architecture documentation completely automatically.

I think that’s a great goal.

I just don’t know how to get there.

Yeah.

I think it’s interesting that you’re sort of focusing on generating those diagrams and those elements.

I mean, an alternative would be to solve that problem on the process level, trying to do some reviews or trying to That’s the easiest way to do it.

If you’ve got a definition of done for your tasks, you just add a line at the bottom, how you update the architecture diagrams and documents.

You’re right.

Sometimes process trumps automation.

Right.

So that would be another option to do that.

Yeah.

I mean, at the end of the day, 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.

But if I understand correctly, or I looked it up on the web, it actually said that Structurizr can also do architecture decision records and other types of documentation.

So 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 ASCII doc documentation files or a bunch of markdown or ASCII doc 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 Nat Pryce’s 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, basically, you can navigate through them and text search and that sort of thing.

Yeah, we should probably say a few words about architecture decision records.

It’s basically what the name suggests, right?

So it basically says, this is what we’ve decided.

These are the reasons.

This is why we came to that conclusion.

Those are some negative results.

And I think that’s pretty much it, right?

That’s pretty much it.

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 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 kind of many teams’ minimum architecture documentation set, which is actually quite nice, because it’s quite light.

With the Structurizr 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, if you want to.

And I think that’s also a good point, that all this stuff is basically plain text or, I mean, at the end of the day, some SQ 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.

I think we’re 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?

Not really.

Nothing springs to mind anyway.

I think we’ve chatted around lots of things.

Yeah.

So we’ve probably done the sort of full circle around that.

It doesn’t seem like there are any more questions on the chat.

So I think we are pretty much done.

I’m just trying to figure out whether there’s anything else.

I think that’s pretty much it.

So thanks a lot.

Thanks a lot for joining.

Welcome.

Thank you.

And yeah, thanks a lot for putting all the work in C4 and Structurizr and so on.

And I will publish the links to the tools that we mentioned and C4 on the website, so you can look it up there.

And yeah, I hope you have a great weekend.

And 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 Technicadept.

So that’s another one.

Because the last one was also about Technicadept.

So the next one will be me just talking about Technicadept probably.

Okay.

Thanks a lot.

And thanks again for being on the show.