Comment by bunsenhoneydew | Hacker News Reader

Comment by bunsenhoneydew | Hacker News Reader

As others have said the C4 model is a great way to address a number of these issues.

I can’t find the right video at the moment but Simon Brown (creator of C4) gives a great talk about creating his DSL, Structurizr, for C4, which he developed during COVID lockdown (if memory serves). There are many videos on YouTube of Simon talking about “C4 Models as Code” so I’m sure any one of those will suffice.

The focus is on creating the model of your system architecture, from which the diagrams you extract are a specific projection of that model. Rather than a diagram be the main artifact. It’s a simple but very powerful concept that I’m always surprised isn’t more widely used.

Structurizr models can also be exported to display as ilograph diagrams, mermaid diagrams and more. Also very much worth a mention is icepanel, a lovely tool for architectural model that implements the C4 model heavily.

I saw Simon talk at a conference in Sydney about 10-15 years ago and heard about C4 for the first time in that talk, it’s been one of the most influential talks I’ve been to in my career as it made a lot of fuzzy things in my head all start to come together in a way that just made sense.

https://c4model.com/

https://structurizr.com/

https://www.ilograph.com/

https://mermaid.js.org/

https://icepanel.io/

This is similar to the 4+1 views concept.

I’ve never seen modeling tools widely used. When it’s attempted it’s always a top-down initiative that always addresses management concerns, but always creates more risk for developers without generating value for them, and it never takes off outside of being a box on a process list to check off. Developers promptly stop using these tools as soon as their use is no longer enforced.

The long term destiny of models is that they will always diverge from the code, sometimes in ways that matter. In that situation, the best model of the code is the code it’s self because it’s a model that you can rely on. You can certainly update the diagrams, but that’s a priority call vs. what else you’re doing, and it doesn’t always win out over other tasks.

Some enterprising tool developers will make modeling tools that will generate code, therefore linking the diagrams and the model to the development of the code. When this is employed, it’s complex and it’s never a perfect implementation. Generated code can be buggy, or it may not do what you want. It may be a significant effort to make the models generate the code that is needed, and you may find your self further developing the code generation tools to generate the code you want. I’ve never seen this have a good benefit to cost ratio.

I actually built a site to auto generate up-to-date interactive visual diagrams for codebases.

It's pretty plug&play, using static analysis & LLMs we generate documentation + an interactive system diagram you can recursively explore.

https://vision.useadrenaline.com

All the auto-generated diagrams are exportable as mermaid

I really wanted to check this out (using redis as an example), but it appears I need an account.

Is there no public demo?

The example repos are free to use!

The problem with any of these tools is that they solve only one part of the puzzle. Take Structurizr for example, it doesn't automatically create the diagrams for you or notify you when it detects architectural drift (and automatically update the diagram).

Others miss other pieces of the puzzle, such as having a list all your APIs, all your system docs in a single place (ADRs, reqs, etc.), connecting to your repos, etc.

I recommend checking https://www.multiplayer.app/ as an alternative.

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

Thank you, but by that argument, I could that for any diagramming / whiteboarding tool. The point is having a tool that reduces work for me and does these things automatically.

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

Reply on news.ycombinator.com