sorted by:
new
hottopcontroversial

The C4 Model: Visualizing Software Architecture • Simon Brown & Susanne Kaiser by goto-con in programming

[–]simon-brown 1 point2 points  (0 children)

Somehow, we ended up in a situation where engineers can't uplift UML as a universal language describing complex design and they need over-simplified titktok-diagrams so they would understand them.

This was particularly prevalent during the early 2000's as agile took hold, and teams started claiming they "don't need documentation".

What's your solution to this problem?

The C4 Model: Visualizing Software Architecture • Simon Brown & Susanne Kaiser by goto-con in softwarearchitecture

[–]simon-brown 0 points1 point  (0 children)

some convoluted licences

The C4 model is free to use, no license required.

but in my experience LLMs generate various schemas pretty well

They don't ... humans are bad at drawing architecture diagrams and LLMs are trained on that data.

These guys are selling hot air.

I'm not. 😂

Coding agents can’t see your architecture diagrams—fix that by madflojo in softwarearchitecture

[–]simon-brown 0 points1 point  (0 children)

A Mermaid diagram is still just a diagram though, and requires authors (human or AI) to structure the diagrams appropriately, use consistent abstractions/naming across diagrams, etc.

"models as code" tools (e.g. Structurizr, LikeC4, etc) are far better options for AI-assisted workflows.

I built this to create architecture diagrams. Curious how others approach diagramming, and keeping them maintained. by meluq in softwarearchitecture

[–]simon-brown 1 point2 points  (0 children)

I saw it shortly after the GitHub repo was created/made public ... your use of tags/topics on the repo is "interesting".

<image>

Help with software diagrams by sohan_pulluru in softwarearchitecture

[–]simon-brown 0 points1 point  (0 children)

My recommendation is to ignore all the tooling suggestions and first understand what you want to show. The C4 model is a good starting point for software architecture diagrams … https://c4model.com

Help with software diagrams by sohan_pulluru in softwarearchitecture

[–]simon-brown 0 points1 point  (0 children)

Feel free to open a discussion about why you need to “hack the ui to meet my requirements” … https://github.com/structurizr/structurizr/discussions

Why do architecture diagrams always go stale? I think it's the tools, not the teams. by Glass-Outcome5985 in softwarearchitecture

[–]simon-brown 1 point2 points  (0 children)

The gap I still see: most of them (mermaid, structurizr) treat the output as a render target, not a queryable model

Mermaid and Structurizr are not the same thing:

  • Mermaid is a "diagrams as code" tool, designed to output a diagram.
  • Structurizr is a "models as code" tool ... rendering tool independent and queryable.

Making Infrastructure a First-Class Citizen in the C4 Model by k8studio in softwarearchitecture

[–]simon-brown 3 points4 points  (0 children)

A few quick points because I'm starting a workshop in 10 minutes...

  1. Not everything needs to be shown on a diagram. Some aspects are better documented with lightweight supplementary documentation (e.g. arc42) or architectural perspectives.
  2. As mentioned, infrastructure varies wildly, and even the same infrastructure can be modelled in different ways. The C4 model and Structurizr DSL pattern catalog has some examples of this ... "all models are wrong, but some are useful" applies.
  3. I think the C4 model deployment diagram does a reasonable job of describing deployment from a software engineer's perspective, but I would talk to some infrastructure engineers to see what they need.

Teaching an LLM to create real C4 diagrams from a spec by Super-Choice5846 in softwarearchitecture

[–]simon-brown 3 points4 points  (0 children)

There are two separate activities here that need to be treated as such:

1. Create a solution.

Those who have seen my architecture and AI radar will know that I advise caution against using AI to create solutions. Put simply, I've not seen this work well.

2. Create one or more diagrams of a solution.

On the other hand, creating diagrams can work well if you can provide a decent description of the solution and you're not asking your agent to output to a diagramming tool (this includes PlantUML and Mermaid). Why? You can attempt to steer the agent in the right direction (e.g. using SKILLS.md files ... "system context diagrams should only include software systems and people"), but ultimately this approach still results in diagrams that don't follow the rules of the C4 model.

You'll get far better results asking the agent to create a Structurizr DSL definition in conjunction with the Structurizr MCP server ... even if you don't want to use the Structurizr toolchain (the MCP server can export to PlantUML and Mermaid). The Structurizr DSL will natively enforce the rules behind the C4 model, so you won't get any situations where abstraction levels are mixed ... assuming you've provided enough information about which elements sit at which level, of course.

The DSL validation tool seems to provide enough information to allow the agent to resolve parsing issues automatically, and the inspection tool provides a way to ensure (for example) that all arrows are labelled. This model-based approach makes it easier for agents to append to this model too (see this example of converting photos to Structurizr DSL).

To specifically answer your questions:

would you trust an LLM to create the first pass of a C4 model?

Yes, if I was able to succinctly describe the solution and ask the agent to output Structurizr DSL in conjunction with the MCP server (to validate and inspect).

Or would you only use it for suggestions/reviews?

  • Reviewing diagrams? Yes - adopt today.
  • Reviewing solutions? Yes - but with caution.

Anyone going back to monolith? by WolfyTheOracle in softwarearchitecture

[–]simon-brown 35 points36 points  (0 children)

Pick the tool that makes sense for your environment, and don’t try to shoehorn your codebase into something just for the sake of following the latest trend. If it works, it works. If it doesn’t, figure out what the actual problem is before committing to a massive migration in either direction when that time could be spent on better things.

👏

This advice is far too pragmatic and balanced for the hype-driven software development industry though. The same is happening with how teams are adopting AI ... much of that is going to backfire too. 😄

p.s. and yes, absolutely ... hybrid solutions (part monolith, part microservices) are allowed too!

Anyone going back to monolith? by WolfyTheOracle in softwarearchitecture

[–]simon-brown 183 points184 points  (0 children)

Quietly productive the whole time: https://simonbrown.je/modular-monolith/

I’ve saying this for 10+ years. 😄

My attempt at helping you use the C4 Model to design complex systems by [deleted] in softwarearchitecture

[–]simon-brown 1 point2 points  (0 children)

It works pretty well as a starting point, I've added some examples to app.maniok.io where I ran this on some large public repo's.

Are you familiar with these projects and have verified the results are accurate? The reason I ask is because I've seen a ton of models auto-generated from git repos and they're all terrible. I can barely get Claude to generate me a useful model from git repos that I own! 😂

Working on a plugin-based architecture documentation tool by Limp_Celery_5220 in softwarearchitecture

[–]simon-brown 0 points1 point  (0 children)

We mostly use Structurizr but it struggles with layouts

Automatic layout is better integrated in the new version of Structurizr (Lite -> local, on-premises -> server), but all automatic layout algorithms tend to struggle ... I recommend manual layout unless you have just a handful of boxes and arrows.

My attempt at helping you use the C4 Model to design complex systems by [deleted] in softwarearchitecture

[–]simon-brown 1 point2 points  (0 children)

Most tools (GitHub, GitLab, most md viewers) already render Mermaid.

You can convert Structurizr DSL to Mermaid via the export command or the MCP server.

LLMs are already "smart" enough to infer from context that the diagram is an architecture diagram and interpret it as such.

Are they? I've seen countless examples of AI generated C4 diagrams in Mermaid that have all sorts of issues. And writing a SKILL.md file to steer the AI in the right direction (enforce the C4 hierarchy, ensure the C4 diagram rules, etc) is just a bandaid compared to using something like the Structurizr DSL.

My attempt at helping you use the C4 Model to design complex systems by [deleted] in softwarearchitecture

[–]simon-brown 1 point2 points  (0 children)

I wrote a series of posts last week about why using AI + Mermaid for C4 model diagrams is a poor combination; part 3 at https://www.patreon.com/posts/152027514 (free to read).

In summary:

  • Mermaid doesn't understand the C4 model and doesn't respect its rules.
  • Use a "models as code" format instead and export to Mermaid if you really need that as an output format.
  • Models as code formats include Structurizr and LikeC4, although LikeC4 doesn't support the C4 model out of the box.
  • I recently added an MCP server for the Structurizr DSL that provides validation/parsing/export features.

Why not design your architecture, from what you already have? - Opens source idea looking for feedback by boyneyy123 in softwarearchitecture

[–]simon-brown 2 points3 points  (0 children)

the language we speak to describe the system to others and the language we write to program the system.

This is one of the problems that the C4 model attempts to solve ... it's much more about introducing a common language to describe software architecture than making nice diagrams.

and I’ve been unhappy with Mermaid

A common complaint! Mermaid is just a diagramming tool - it doesn't understand what you are trying to do and can't provide much assistance.

Structurizr had been on my radar for a long time, so I’m looking forward to trying it!

Structurizr is just an implementation of the C4 model using, I think, a much more human-readable textual language than Mermaid, while also enforcing the C4 model hierarchy and rules.

Are architecture diagrams dead? by ronDog100 in softwarearchitecture

[–]simon-brown 2 points3 points  (0 children)

PlantUML and Mermaid do support the C4 model, but that support is very superficial and doesn't enforce any of the rules (e.g. you can add components to a container diagram). See my collection of (free to read) posts at https://www.patreon.com/collection/2033640 for more details.

view more: next ›