C4 models as code - Simon Brown - NDC Oslo 2023

"Diagrams as code", as featured on the ThoughtWorks Tech Radar, is becoming a popular way to create software architecture diagrams for inclusion in long-lived documentation. The benefits of creating diagrams from text are well understood - text is version controllable, easy to diff, easy to integrate into build pipelines, and automatic layout facilities allow authors to focus on content. The majority of these tools (e.g. PlantUML and Mermaid) are focussed on diagramming though, and require you to create one text file per diagram, with only a limited ability to reuse diagram elements across multiple diagrams. At scale, this causes maintenance problems, and leads to inconsistencies between diagrams.

This talk will introduce and demonstrate the open source Structurizr DSL - a way to create a model of your software architecture using a textual DSL that's specifically targeted towards the C4 model. We'll also see how the DSL separates content from presentation, allowing you to render your diagrams with a number of tools, which in turn offers some answers for the tricky question of how to use the C4 model at scale.

Check out our new channel:
NDC Clips:
@ndcclips

Check out more of our featured speakers and talks at

[TheEyzic]

This is mindblowingly brilliant!!! I saw one of his talks before the Structurizr DSL existed and I remembered being impressed but I did not really now how to put it into practice. Now I do! Throughout the presentation it just gets better and better. I will definitely start using this. WOW! :D

[tyl]

This is exactly what I am looking for, thanks for the sharing!

[altugaecoffice]

is this DSL's grammar based on Hashicorp HCL's grammar?

[slavaslutsker]

Great work done and as well as the talk, nice tooling for software architects.
The main challenge I see is this type of docs need DSL and tools to be created and updated, so the dev team won’t update docs on regular base, it can lead to a point when you have diagrams that are out of sync with real system’s structure, which makes those diagrams less useful or even completely useless to devs.

[wyleong]

It’s like Graphvis went to the code gym, did some reps and grew some muscles.

[illyam]

Demo god was not kind 😂! But still great presentation as usual!

[szeredaiakos]

I am not sure why there is such focus on data modelling early on. The focus of information tech is to enhance and extend abilities. Data has a support role to that.

[ManfredWisniewski]

I am not old! The Rational Rose UI was horrible but still better than PlantUML. 🙄 Am I old?🤔

[duckmasterflex]

I understand Viso ain't going to cut it but why make it so incredibly over complicated to not just code but compile and setup. Onboarding stakeholders is a nightmare.