simon_brown

Most software architecture diagrams are a mess ... partly due to ad hoc notation, and partly because it's very unclear what the boxes represent. C4 resolves the latter problem by introducing a small number of predefined abstractions. This sounds limiting, but the power of C4 is that limited set of abstractions, and the conversations it forces architects/developers to have.

The less prescriptive approach of LikeC4 sounds very appealing, because it provides a way to define your own abstractions. But I don't recommend this approach for most teams -> https://c4model.com/abstractions/faq#can-we-add-more-abstrac...

> Thank you, but by that argument, I could that for any diagramming / whiteboarding tool.

In theory, sure, but the majority of diagramming/whiteboarding tools are not easily manipulated via code/an API. Structurizr is a modelling tool, and the model can be authored by a number of methods ... manual authoring, reverse-engineering, or a hybrid of the two.

> The point is having a tool that reduces work for me and does these things automatically.

I do hope that we will see some tooling that can do these things automatically, but we're not there yet ... fully-automatic (as opposed to semi-automatic) comes with some serious trade-offs.

Thank you! :-)

> Take Structurizr for example, it doesn't automatically create the diagrams for you

The Structurizr DSL is designed for manual authoring (which is what most people tend to do), but there's nothing preventing you from writing some code (using one of the many open source Structurizr compatible libraries) to reverse-engineer parts of the software architecture model from source code, binaries, your deployment environment, logs, etc.

> or notify you when it detects architectural drift

If you do the above, there's then nothing preventing you from writing some tests to notify of architectural drift, etc.

I don't have the full context of what you're trying to model, but "two components deployed as one service" might be better represented as a container. If that's not the case, you can use the "group" concept to group components together -> https://docs.structurizr.com/dsl/cookbook/groups/

Alternatively, https://likec4.dev provides a way to create an arbitrary number of abstraction levels (although I wouldn't recommend such an approach).

> But C4 seems almost too lightweight to merit a name.

Fun fact ... it actually didn't have a name for the first few years, and was just the approach I used and taught people on my software architecture workshops.

Many of the comments here seem to assume that "diagrams as code" == automatic layout. That doesn't need to be the case.

I know a number of organisations who have done/are doing this, and my key piece of advice is to look at modelling rather than diagramming. Note that I'm not necessarily suggesting a traditional UI-driven modelling tool here. My open source Structurizr DSL is a "models as code" tool that allows you to define a model+views, and have them rendered using a number of tools (e.g. Structurizr, PlantUML, Mermaid, D2, etc). I have some conference talks on YouTube that provide an overview if you want to learn more; e.g. https://www.youtube.com/watch?v=0-gVFWONnQw

C4 model creator here ... in a nutshell, the C4 model is: 1. a hierarchical set of abstractions to describe software systems, and 2. a hierarchical set of diagrams to visualise those abstractions. Benefits include it providing teams with a lightweight common vocabulary to describe/visualise software architecture, with the resulting diagrams being "developer-friendly". It's also independent of any specific notation and tooling. My top tip is that you don't need to use all four levels ... the first two are usually sufficient for most teams.

I agree, diagrams as code is very powerful, and that would be my recommendation for teams looking for tooling ... the Structurizr DSL being the tooling that I created specifically to create multiple diagrams based upon the C4 model, in multiple output formats, from a single DSL source file. You can see a demo at https://structurizr.com/dsl and there are more details at https://structurizr.org

Some teams do like the familiarity of diagramming/modelling via a UI though, and that's where something like IcePanel fits in.

I created the C4 model (https://c4model.com) as a way to help teams agree upon a set of abstractions and diagram types to describe software architecture. That website also has a tooling section with some suggestions, but you might start with the open source Structurizr CLI and DSL combo ... it provides a way to create multiple diagrams from a single model, and those diagrams can be rendered with a number of tools. See https://structurizr.org for more.

> but there are existing solutions and frameworks out there, from the terrible (6 Sigma or EDS' BCL Framework) to the excellent (MSF 3, parts of the UML).

That's a fair point, and I'm occasionally asked why I'm "reinventing" UML too. Again, that's a totally valid question. If teams are using one of the existing approaches/notations, and it's working for them, I recommend that they stick with it.

But the majority of the teams I work with either (1) have no diagrams/documentation at all or (2) use collections of ad hoc "boxes and lines" diagrams ... usually "because we're agile". In many cases UML, ArchiMate, SysML, MSF, etc are not even on their radar. In others the teams are simply not interested in using these existing approaches, for a number of reasons.

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

> I didn't get the feeling that it has to be 4 diagrams and I pick and choose myself.

Correct. I get the feeling that most teams using the C4 model tend to stick to the top two levels - System Context and Containers (these levels also "age" slower than the others too).

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

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! :-)

+1 for DFDs ... UML was designed with OO programming languages in mind, and doesn't really fit well for diagramming functional languages (unless you start creating your own custom UML profile, which I don't see many people doing).

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.

As some background, the rationale behind creating the C4 model was to create software architecture diagrams that would be easy for anybody on the project team to understand. The example diagram you linked to is fairly typical of what most teams seem to do today unfortunately, and exhibits the following problems: ambiguously named boxes, unclear responsibilities, unexplained symbols, ambiguous relationships between elements, no key/legend, unclear abstractions, etc.

To solve these problems, you do need some sort of common language. Switching to UML potentially solves many of these problems, but teams don't want to do this for various reasons. As noted on the website, the C4 model is an abstraction-first approach (with only 4 levels to learn), although the simple notational tips do aid comprehension.