
The C4 model for visualising software architecture - redact207
https://c4model.com/
======
lstamour
If you like this, you’ll probably also like [https://seilevel.com/business-
analyst-resources/rml-book/](https://seilevel.com/business-analyst-
resources/rml-book/) and various videos and webinars from Seilevel on YouTube
which I added to a playlist (not in any particular order so please scroll
through it):
[https://www.youtube.com/playlist?list=PL2miG2CzrxakbZswQH-O4...](https://www.youtube.com/playlist?list=PL2miG2CzrxakbZswQH-O43G5VnJ0_CB8C&feature=share)

Also relevant, the Design Structure Matrix (DSM):
[https://dsmweb.org/](https://dsmweb.org/) and
[https://mitpress.mit.edu/books/design-structure-matrix-
metho...](https://mitpress.mit.edu/books/design-structure-matrix-methods-and-
applications) (mostly learning by example, not all software-relevant,
available as an e-Textbook on Amazon) If you code in Java, IntelliJ has this
diagram included.

Finally if you’re looking on advice on how to break software into modules
based on making your API surfaces easier to use for yourself and other
programmers, have a look at A Philosophy of Software Design. It’s not
comprehensive, but it’s concise and relatively easy to read:
[https://books.google.ca/books/about/A_Philosophy_of_Software...](https://books.google.ca/books/about/A_Philosophy_of_Software_Design.html?id=pD6-swEACAAJ&source=kp_cover&redir_esc=y)

~~~
raghava
Thanks, this is useful.

------
gtirloni
_> An unfortunate and unintended side effect of the Manifesto for Agile
Software Development is that many teams have stopped or scaled back their
diagramming and documentation efforts_

This is tragic and too common, in my experience.

It's like code should document itself but it rarely does. And then we're back
to transmitting oral knowledge to every new hire.

~~~
sixstringtheory
Huh, I hadn't made this connection, and it still may be a case of ad hoc ergo
propter hoc. But they sure seem to go hand in hand.

I think the first team on which I ever experienced Agile– working on a CAD
program–was quite good with documentation. Ever since then–about 8 years–it's
been almost all bad. All my work since then has been on iOS, so I maybe
difference in domains has something to do with it too.

I often say code should "document itself," but I guess what I really mean is
that the code should be readable and understandable, without obfuscating
elements like anonymous identifiers, single letter variables etc, or needing
comments explaining _how_. Comments should explain higher-order ideas like
_why_. But, no one part of code can document the whole _system_ to which it
belongs, nor can e.g. Git commit logs (which I also highly value). For that, I
absolutely need diagrams and technical writing.

~~~
simon_brown
> But, no one part of code can document the whole _system_ to which it
> belongs, nor can e.g. Git commit logs (which I also highly value). For that,
> I absolutely need diagrams and technical writing.

Yes, that's exactly why I use the maps analogy when describing the C4 model.
If you were teleported into a random part of the country where you live, you'd
find it very time consuming to figure out where you are, and where you want to
go. The maps on your smart phone allow you to zoom-out and get some context.

It's the same with code. If you join a team with a million lines of code,
simply exploring the code to figure out what's going on is an incredibly time
consuming exercise. The diagrams and technical writing provide some zoomed-out
context, so you can better explore the codebase.

The trick, of course, is to not document everything. Travel guidebooks don't
explain everything about the place you're visiting, only the highlights.
Software documentation should do the same.

~~~
sixstringtheory
> The trick, of course, is to not document everything. Travel guidebooks don't
> explain everything about the place you're visiting, only the highlights.
> Software documentation should do the same.

This makes a lot of sense to me, I think I would do well to remember it,
thanks!

------
Spearchucker
Too complex. Architecture descriptions should make sense to everyone on the
project. It should not require you to learn a new design language or notation
to use.

Here's an example of a complex system that's easy to get your head around -
[https://www.wittenburg.co.uk/Design.aspx](https://www.wittenburg.co.uk/Design.aspx)

Unfortunately it won't do much for an architect's ego but, if the same
simplistic approach to diagrams is applied to all levels of abstraction, it
just may provide a thing all stakeholders can reason about and agree to.

~~~
Silhouette
_Too complex. Architecture descriptions should make sense to everyone on the
project. It should not require you to learn a new design language or notation
to use._

That seems a little strong. We're talking about a potentially complicated
system in a technical field. Some standardised notation and terminology could
be helpful to keep the visuals concise and unambiguous. I agree that this
looks far too complicated, though.

~~~
Spearchucker
UML already provides that, no?

~~~
Silhouette
Personally I find UML (in its full, standardised form) is still a lot more
complicated than is normally necessary too, but it does include versions of
several useful ideas.

I have often seen a group of developers discussing something and then someone
sketches a simple diagram showing entities and relationships, transitions of a
finite state machine, or message-passing similar to what UML would call a
sequence or communication diagram.

However, in my entire career, I have never seen anyone actually draw out fully
annotated UML diagrams using the official notation, nor any instance of some
of the numerous diagram types UML specifies. And that includes working at
places where everyone had been given UML training!

~~~
simon_brown
I've seen a number of organisations where everybody has been given UML
training, and mandated to use a specific UML tool. In reality though,
everybody is just abusing UML class diagrams as a way to draw ad hoc "boxes
and lines" diagrams instead! :-)

------
michelpp
In case, like me, the headline makes you think it's related, this is not the
same as Pieter Hintjen's C4 development process, the "Collective Code
Construction Contract":

[https://rfc.zeromq.org/spec:42/C4/](https://rfc.zeromq.org/spec:42/C4/)

------
rixed
UML for the last level does not seem particularly adapted for functional
languages or languages with a sophisticated module system though. Anyone knows
of some conventional description language that would be a better fit, or is
this a case where the code (higher level functions, often times forming some
DSL, or the higher level module interfaces) is legitimately the actual
description then?

~~~
skrebbel
I like to draw software. Nothing tells people what's going on at a glance
better than a bunch of boxes and arrows.

Some 5-10 years ago when UML went out of vogue (for good reasons; much of it
is overspecified and overcomplicated), and around the same time FP started
getting traction, I think we accidentally lost something.

I like FP and I also like using FP principles in not-strictly-FP language's
such as JavaScript, but I miss OO's drawability.

If anyone knows of a compelling diagram syntax for FP style software, I'm
deeply interested.

The best I've seen so far is abusing class diagrams for modules, which kinda
sorta works when you follow a convention (common in eg Elixir) of having each
module export one struct type plus some functions that operate on that struct.
It's basically OO without inheritance that way so not surprising that it fits.
But that feels a bit like shoehorning my FP into class diagrams rather than
anything else. Any takers?

~~~
rumanator
> Some 5-10 years ago when UML went out of vogue (for good reasons; much of it
> is overspecified and overcomplicated)

Perhaps UML ceased to be a fad for some, but to this day UML is still the best
tool (and practically only tool) that helps describe and document code
effectively and efficiently, from requirements to what classes comprised a
submodule.

The "oversimplified and overcomplicated" jab makes no sense at all. UML is
used to provide a view of a system without needing to go too much into detail
(that's what code is for), and just because a bunch of people did a great job
putting up a specification aimed at software developers intending to develop
UML editora and code generators it does not mean it is overcomplicated".
Anyone can use UML extensively if they can draw rectangles and lines on a
piece of paper, or click and drag around in an editor. That's hardly a
downside or a sign it's "overcomplicated".

~~~
skrebbel
I take it you never took a UML certification exam. Even the most useful UML
diagram, class diagrams, has so much syntax that you can express all of C++'s
weird ownership quirks plus some quirks no actual programming language has.

UML activity diagrams let you specify, in full detail, the semantics of a
trivial 3-line constructor using a ridiculously large amount of arrows and
boxes. You can get good at this (even though it serves no purpose whatsoever)
and get "UML Certified" stamps on your forehead.

UML use case diagrams, hardly useful for anything at all, have a rule that you
can put the name of the actor either above or below the actor stick figure.
The name of a use case (an ellipsis), however, may only be above or inside the
ellipsis, but not below. Put the name below the ellipsis and your UML is
syntactically incorrect. Volumes of books were written about nonsense like
this. The UML spec is many hundreds of pages. If you don't think this is
overspecified and overcomplicated then I want some of what you're smoking.

I believe it is these aspects of UML that made it unpopular among the "get
things done" crowd. I agree that UML class diagrams and UML state charts, when
you just use the normal, useful parts of them, are super useful and currently
underrated.

If the UML people had remembered they were making a communication tool and not
a programming tool, then maybe so many people hadn't run away screaming.

~~~
rumanator
> I take it you never took a UML certification exam.

You're either very disingenuous or deeply confused. You don't need to hold a
Master's degree in English to hold a conversation with English speakers. You
don't need academic certification to use a tool to communicate ideas.

It makes no sense to assert that the usefulness and ease of use of a language
is demonstrated by how far and how extensively it may be covered in an
academic setting.

Lines and boxes. It's not that hard, is it?

~~~
skrebbel
I don't understand why you insist on disagreeing so violently when we're
mostly on the same page. In fact I don't disagree with a single word in your
comment, except the part about disingenuous which baffles me.

We agree that UML has a subset of common features that are super useful to
communicate about software. That doesn't make UML as a whole any less
overcomplicated and overspecified, though!

Most people agree that languages like C++ or Scala are large and complicated.
The fact that you can choose to write C++ code that only uses functions and
structs and pointers doesn't change anything about that.

I said nothing about UML's ease of use. I said something about its drop in
popularity and about the swathes of useless features UML fans promoted when it
was at the peak of its hype cycle. I mean, I assume you agree that UML is less
popular now than it used to be?

Sidenote: nothing about UML was ever intended to be academic, I'm not sure
where you got that term from all of a sudden. It was all very industry driven.
People wanted to do "model driven development" and realized if only UML could
have super precise semantics, you could generate entire programs from UML.
This actually works and serious amounts of software have been painstakingly
written this way. It's totally nuts.

------
mannykannot
From everything that I have seen, any software architecture modeling model
that relegates dynamic behavior to a 'supplementary' status is suboptimal. One
of the ways that waterfall fails is that the architects come up with an
imposing, apparently comprehensive static structure that overlooks various
issues that arise when it is put in motion. These points of contention often
do not become apparent until one is trying to integrate the parts into a
coherent system.

Software design is always an interation between static and dynamic matters --
use informs structure, and structure informs use.

~~~
simon_brown
> any software architecture modeling model that relegates dynamic behavior to
> a 'supplementary' status is suboptimal

Another explanation is that the static structure diagrams are what give the C4
model its name: Context, Containers, Components, and Code. These diagrams
existed for a number of years, before the addition of the other diagram types,
which themselves supplement the static structure diagrams.

That said, I don't find myself using the dynamic diagram type all that often.
For software systems of any size/scale, I'm not going to create dynamic
diagrams for every use case/user story/feature/etc. Instead, I'll use dynamic
diagrams sparingly to describe overall patterns in use, significant use cases
only, or complicated sets of interactions between things.

To prevent the issues you mention about overlooking issues, especially when
doing any up front design, I recommend "dry-running" the significant usage
scenarios across the static structure diagrams and/or running a risk
identification exercise (e.g. risk-storming). Or you could use a formal
architecture evaluation technique.

------
contingencies
_UML - I know next to nothing about UML - but what I do know is the language
was invented first and then people came around and tried to give semantics to
the language. Well, in other words what that means is that the language was
invented first and it really didn 't mean anything. And then, later on, people
came around to try to figure out what it meant. Well, that's not the way to
design a specification language. The importance of a specification language is
to specify something precisely, and therefore what you write - the
specification you write - has to have a precise, rigorous meaning._ \- Leslie
Lamport

 _UML: a language that was invented first and then people came around to try
to get semantics._ \- Leslie Lamport

 _UML: fuzzy pictures of boxes and arrows._ \- Leslie Lamport

 _People use UML, things like UML, to model programs, but it 's not clear how
to translate them in to sequences of states, for concurrency. If you cannot
translate them in to sequences of states, it means you don't understand them,
and it may mean that there's nothing there. You know, there are lots of people
selling snake-oil, drawing boxes and arrows that make you feel good, but
ultimately have no real meaning. If something is really meaningful you should
be able to express it in mathematics._ \- Leslie Lamport

 _UML - Unnecessary Management Lingo._ \- @iamdevloper

... via
[https://github.com/globalcitizen/taoup](https://github.com/globalcitizen/taoup)

~~~
facorreia
None of this is accurate. Keep in mind that he's talking about something he
doesn't know.

~~~
Silhouette
When a giant like Leslie Lamport says he knows next to something about a
subject but then gives a view anyway, it's probably wise to consider that he
might just be being diplomatic. His comments about ambiguities in UML and the
difference between that and a rigorous mathematical specification are
reasonable in my experience (as someone who has both done significant work
with high reliability code and formal methods and also worked in enterprise
world with UML and all that).

------
jwildeboer
When I see C4 I still connect that moniker with the „Collective Code
Construction Contract“ [1] by the late Pieter Hintjens.

I find it a bit unpleasant how this project thinks it’s OK to redefine that
term without giving at least a nod to Pieter.

[1] [https://rfc.zeromq.org/spec:42/C4/](https://rfc.zeromq.org/spec:42/C4/)

------
hackerm0nkey
On of the tools that are built to combine the excellent PlatUML and the C4
model and achieve diagrams as code is
[https://github.com/RicardoNiepel/C4-PlantUML](https://github.com/RicardoNiepel/C4-PlantUML)

Definitely adding this to my toolbox <insert happy nerd laugh>

------
okcwarrior
I'm a big fan of this model - I've changed all my work architecture models to
C4 and they make sense instantly to other engineers. The plugin for draw.io is
really easy to use as well.

------
choeger
Nice approach but it seems to be rather focused on that modern web or mobile
app. How about a system with redundancies? Is a DB replication group a single
container? Or do I have to know exactly the number of DB nodes?

~~~
simon_brown
With the C4 model, you typically treat your database schema as a "container",
and save the deployment/infrastructure concerns (e.g. replication) for a
separate deployment diagram.

------
jheriko
(insert comment about smashing square pegs into round holes)

