16 ms·

The C4 model for visualising software architecture

187 points by redact207 7y ago

gtirloni 7y ago
> 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 7y ago
  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 7y ago
    > 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 7y ago
      > 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!
- prepend 7y ago
  I’m not sure if it’s worse. There’s been a documentation gap as long as I’ve been thinking and working on this (1995+). I don’t think it’s complete but I think I see more documentation and diagrams so it out automatically from projects than the stuff that was consciously written by librarians or tech writers (or created as a result of following a CASE tool or Rational’s UML stuff). I have seen far fewer garbage diagrams that confused. If I had to choose between a pretty diagram and a hacked up json file that describes relationships, I’d take the semistructured data any day. I can always write a graph viz on top of the data that is always in sync, but it’s really expensive to try to spit out data from a graphic.
michelpp 7y ago
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/
lstamour 7y ago
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-O43G5VnJ0_CB8C&feature=share https://www.youtube.com/playlist?list=PL2miG2CzrxakbZswQH-O4... Also relevant, the Design Structure Matrix (DSM): https://dsmweb.org/ https://dsmweb.org/ and https://mitpress.mit.edu/books/design-structure-matrix-methods-and-applications https://mitpress.mit.edu/books/design-structure-matrix-metho... (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_Design.html?id=pD6-swEACAAJ&source=kp_cover&redir_esc=y https://books.google.ca/books/about/A_Philosophy_of_Software...
- raghava 7y ago
  Thanks, this is useful.
rixed 7y ago
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 7y ago
  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?
  - jimmcslim 7y ago
    Sequence diagrams?
  - rumanator 7y ago
    > 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".
choeger 7y ago
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 7y ago
  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.
Spearchucker 7y ago
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 7y ago
  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 7y ago
    UML already provides that, no?
    - Silhouette 7y ago
      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!
      - 7y ago
jwildeboer 7y ago
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 7y ago
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>
mannykannot 7y ago
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 7y ago
  > 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 7y ago
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 7y ago
  None of this is accurate. Keep in mind that he's talking about something he doesn't know.
  - contingencies 7y ago
    Better to just be precise. https://graphs.grevian.org/example https://graphs.grevian.org/example
  - Silhouette 7y ago
    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).
okcwarrior 7y ago
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.
jheriko 7y ago
(insert comment about smashing square pegs into round holes)

187 points by redact207 7y ago

> 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 7y ago
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 7y ago
  > 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 7y ago
    > 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!
prepend 7y ago
I’m not sure if it’s worse. There’s been a documentation gap as long as I’ve been thinking and working on this (1995+). I don’t think it’s complete but I think I see more documentation and diagrams so it out automatically from projects than the stuff that was consciously written by librarians or tech writers (or created as a result of following a CASE tool or Rational’s UML stuff). I have seen far fewer garbage diagrams that confused. If I had to choose between a pretty diagram and a hacked up json file that describes relationships, I’d take the semistructured data any day. I can always write a graph viz on top of the data that is always in sync, but it’s really expensive to try to spit out data from a graphic.

michelpp 7y ago

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/

lstamour 7y ago

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-O43G5VnJ0_CB8C&feature=share https://www.youtube.com/playlist?list=PL2miG2CzrxakbZswQH-O4... Also relevant, the Design Structure Matrix (DSM): https://dsmweb.org/ https://dsmweb.org/ and https://mitpress.mit.edu/books/design-structure-matrix-methods-and-applications https://mitpress.mit.edu/books/design-structure-matrix-metho... (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_Design.html?id=pD6-swEACAAJ&source=kp_cover&redir_esc=y https://books.google.ca/books/about/A_Philosophy_of_Software...

raghava 7y ago
Thanks, this is useful.

rixed 7y ago

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 7y ago
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?
- jimmcslim 7y ago
  Sequence diagrams?
- rumanator 7y ago
  > 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".

choeger 7y ago

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 7y ago
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.

Spearchucker 7y ago

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 7y ago
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 7y ago
  UML already provides that, no?
  - Silhouette 7y ago
    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!
    - 7y ago

jwildeboer 7y ago

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 7y ago

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>

mannykannot 7y ago

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 7y ago
> 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 7y ago

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 7y ago
None of this is accurate. Keep in mind that he's talking about something he doesn't know.
- contingencies 7y ago
  Better to just be precise. https://graphs.grevian.org/example https://graphs.grevian.org/example
- Silhouette 7y ago
  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).

okcwarrior 7y ago

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.

jheriko 7y ago

(insert comment about smashing square pegs into round holes)