HN Theater @HNTheaterMonth

The best talks and videos of Hacker News.

Hacker News Comments on
Diagrams as Code 2.0 • Simon Brown • GOTO 2021

GOTO Conferences · Youtube · 57 HN points · 2 HN comments
HN Theater has aggregated all Hacker News stories and comments that mention GOTO Conferences's video "Diagrams as Code 2.0 • Simon Brown • GOTO 2021".
Youtube Summary
This presentation was recorded at GOTO Copenhagen 2021. #GOTOcon #GOTOcph

Simon Brown - Author of "Software Architecture for Developers" & Creator of the C4 Software

Diagrams as code is becoming a popular way to diagram software architecture, particularly for long-lived high-level documentation. You write the diagram source in a text-based domain specific language (e.g. PlantUML or Mermaid) or a programming language, and render diagrams using web-based or command line tooling.
The benefits are well understood – writing the diagram source as text allows for easy integration into software development practices and toolchains, plus the automatic layout facilities allow authors to focus on content.
The problem with this approach is that it's easy for diagrams to get out of sync. Enter "diagrams as code 2.0" — a way to define a model of our software architecture and the views that we'd like to see, ultimately resulting in a consistent set of diagrams that are generated for us. [...]

00:00 Intro
02:09 C4 Model
06:05 Diagramming vs modelling
07:54 Domain concepts
08:41 Model-based (DRY)
12:41 HTML & CSS
15:44 Diagrams as code 1.0
16:02 Diagrams as code 2.0
20:13 More advanced features
24:04 Enterprise-wide modelling?
25:09 Scripting support
26:36 Plugin support
28:58 Custom tooling
30:23 Usage scenarios
31:24 Interactive diagrams
35:19 Closing thoughts
38:49 Outro

Download slides and read the full abstract here:

Simon Brown • Software Architecture for Developers Vol. 2 •
David Farley • Modern Software Engineering •
Dave Farley & Jez Humble • Continuous Delivery •
Woods, Erder & Pureur • Continuous Architecture in Practice •
George Fairbanks • Just Enough Software Architecture •
#SoftwareArchitecture #DevOps #SimonBrown #Microservices #Monolith #ModularMonolith #Complexity #BoundedContext #C4Model #SoftwareEngineering #Programming #SoftwareDevelopment #UML #DRY #Structurizr

Looking for a unique learning experience?
Attend the next GOTO conference near you! Get your ticket at
Sign up for updates and specials at

SUBSCRIBE TO OUR CHANNEL - new videos posted almost daily.
HN Theater Rankings

Hacker News Stories and Comments

All the comments and stories posted to Hacker News that reference this video.
Jun 23, 2022 · adolph on Diagram as Code
I just watched the below video from last year partly about Structurizr. Below are other tabs about the topic I still have open.

Diagrams as Code 2.0 • Simon Brown • GOTO 2021:

The C4 model for visualising software architecture:

Intro to Structurizr:

Jun 20, 2022 · 54 points, 9 comments · submitted by brunojppb
I was exposed to the C4 Model a year ago and it just clicked. It gave a framework that I could use to expose diagrams to the architecture audience that actually helped aid understanding instead of just being mothballed.

Love seeing others exposed to it.

For the last few months my team and I have been working on standing up a system of libraries that other teams in our organization will use. From the beginning we decided that documentation was necessary from 2 perspectives:

1. Internal maintenance; to understand the system's depths and how it came to be in its current state

2. External consumption; to see the pieces of the system, how they work together, and how to use them

In my research I stumbled across several viable documentation techniques/patterns that seemed to help us reach our doc goals. We decided to combine 3 of those techniques:

1. C4 Model (

2. Architectural Decision Records (

3. arc42 (

The result feels like more documentation than anyone will ever read, but it has allowed us to create a complete self-service set of documents that should allow our library to be used broadly across the org without our team becoming something like a tool support team.

While demonstrating or describing our system to people across the org (not just devs) we found that pointing to the top 2 levels of our C4 diagrams has been incredibly useful at helping describe the system and the work we're doing in the system. We've also received fantastic positive feedback from our audience regarding the diagrams and their ability to help clarify the concepts being described.

We decided to embed our diagrams directly into our markdown docs. The raw markdown looks like this:


## How It Works

A person uses the app, the app is compiled from the code, the code is maintained by developers.


@startuml example-diagram

!include <C4/C4_Container>

Person(dev, "Developer", "A software developer")

Person(user, "User", "A person that uses the application")

System(app, "Application", "The application")

System(code, "Code", "Code repository")

Rel(dev, code, "Maintains", "Git")

Rel(code, app, "Produces", "Azure")

Rel(user, app, "Uses", "Web Browser")





This ends up being completely readable as a plain markdown file, but is enhanced by having a markdown preview tool like any of the major Git hosts (GitHub, ADO, etc.) because the PlantUML is hidden, but the diagram is presented graphically as a .png image. It also allows us to keep our documentation close to the code it represents, which has been a huge benefit in the organizing of documentation (vs adding another doc to the pile of outdated docs in our internal wiki).

Wait, do you mean that if you write inline PlantUML source such as in your example, an "example-diagram.png" is generated from that code and loaded by the image tag?

That sounds too advanced although I could see an Sphinx doc plugin being able to do that, but not the more basic Markdown viewer in most hosts... so I'll guess that you meant to copy the embedded PlantUML lines to a temp file, and generate a .png, that gets stored together with the .md file.

I recently came across the C4 model, I believe from a Hacker News comment responding to a request for architecture diagramming methods when I was performing a web search for the same. The talk I watched was another one, but I pretty quickly became sold on it. I am trying to implement it for a system that I am new to.

Really, the main struggle is tooling. So far, I am using PlantUML with a C4 model plugin. It's okay. I am thinking of switching to a visual diagramming tool, even though the author of the C4 model recommends against it, for some reason that I don't quite understand.

It seems this talk, which I'll have to watch later, is own the author's own tooling called Structurizr. While nice, the pricing is a bit strange. The on premise version is $50 minimum per month and is twice the cloud version. I feel like it's going to be hard enough selling the C4 model, and I don't think the pricing model works for something that will have a lot of work in the beginning and then become relatively static for mature products. I'd like to see a one-time purchase perpetual license.

> I am thinking of switching to a visual diagramming tool, even though the author of the C4 model recommends against it, for some reason that I don't quite understand.

Not the speaker in the video, but the main reasons to not use drag-and-drop diagramming tools are summarized here:

While I totally agree with the sentiment, it's hard to produce diagrams using code-to-diagram tools that convey as much meaning and story. I'd welcome anyone to challenge me on this, but the styling options you have for tools like PlantUML, Mermaid, and so on (excluding expensive online-only tools here) are just too limited.

Yeah, you can argue that simple is better (I really loved, but you still need _some_ ways to produce diagrams people will actually find pleasing. Diagrams to tell a story, with blocks that make sense in terms of looks, colors, and orientation. I want an open-source code-to-diagrams that can output as pretty diagrams as I make with LucidChart!

Totally agree. Plantuml Sparx etc just don't scale on the conceptuality axis. and their ilk do.
Isn't the main reason against visual tools the underlying DSL that describes the overall system and then defines multiple views (on the various "C" levels) against it, with the ability to generate diagrams in a view different diagramming tools? If you switch to a visual diagramming tool, you lose that ability.

As for pricing, there's, which is free, no?

For a visual tool I'd recommend giving IcePanel [0] a try.

For the diagrams as code solution, happily it looks like mermaid will soon support C4 [1] so their should be native support in lots of places soon (github, gitlab and lots more have built in support for mermaid)



Over last 10 years have used Freemind & (last few years) Xmind to kind of make superfast flow charts in the tools dressed as mindmap tools. So i can see the appeal of knoted here for quick jotting down of thought flows.

But have also enjoyed making nice diagrams in mermaidjs especially the sequence diagrams. Prefer markdown to digram for code maintainability. Was recently seeing a youtube talk from C4 author on composable diagrams and agree to a lot of what was said in the talk. Src:

Keyboard to diagram is much faster than mouse based diagram tools and have found them better for long term use cases. Quick diagraming in excalidraw or figjam doesn't hurt though when brainstorming especially with not very technical folks as they can easily contribute.

Mermaid? I like mermaid, but it is not fun, it is not fast and it is not comfortable, especially when you have bigger diagrams or must edit them.
Jun 16, 2022 · 3 points, 0 comments · submitted by kiyanwang
HN Theater is an independent project and is not operated by Y Combinator or any of the video hosting platforms linked to on this site.
~ [email protected]
;laksdfhjdhksalkfj more things ~ Privacy Policy ~
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.