[jhund]

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document.

The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search).

I also use https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.

[noxvilleza]

Recently been doing the same Structurizr consolidation since amongst our various teams we had a mish-mash of Lucidchart, Miro, and other collaborative design tools.

One thing I was experimenting with (read: struggling with!) was a way to keep per-service (per-repo) architecture workspaces which are also synchronized on-commit to a central workspace and used !include to bind them together. The moving parts are not difficult - but writing your DSLs in a way that can handle this can be. This idea would let individual projects be self-sufficient and generate their own README doc diagrams as part of their own build process; but also have a central site which shows all the services as well as inter-service connectivity.

Did you ever consider https://github.com/avisi-cloud/structurizr-site-generatr to bring together your ADRs in with your architecture, or do you keep them separate?

[jeazy]

I strongly recommend appmap.io .. literally just go see for yourself.

[jhund]

I looked at the avisi stucturizr-site-generatr, however, decided to render the docs via structurizr-lite. It provides better interactivity for C4 model diagrams, e.g., drilling down into diagrams and tooltips. I found the ADR integration in structurizr-lite sufficient.

[rammy1234]

I use MermaidJS for flow chart and Sequence diagram. They have C4 in beta. I tried and it is hard adjust the layout and many features are not supported for C4 yet.

Visual Studio has good support for MermaidJS. https://mermaid.js.org/intro/

[FearNotDaniel]

I think you mean Visual Studio _Code_. Completely separate product. Not your fault of course, but the geniuses at Microsoft who gave the same name to two different IDEs in an environment where users of the second one are very unlikely to be aware of the existence of the first. Still, it's an important distinction worth knowing about because they have their own distinct extension ecosystems that are not mutually compatible.

[rammy1234]

Yes sorry I meant VS code. Good call out. - https://marketplace.visualstudio.com/items?itemName=vstirbu....

[jeazy]

Wow ya learn something new everyday. I had no idea but it did seem odd there were two options from our internal software portal to download ides with similar names but the same exact logo.

[midasz]

Yeah microsoft really have a knack for naming things

[rammy1234]

for C4 structurizr is the best so far I know. I use that for landscape , container diagrams. I got feedbacks that even CIOs are able to get the picture easy. If they have some ways to produce better layouts for large landscape it would be awesome.

[SnowProblem]

Structurizr looks popular but I don't love needing to learn yet another DSL. Does there exist a way to describe things in an existing language with a library?

To use the example on their website, I would like something like this in JS:

  let { Component, Container, Diagram, Person } = import 'c4'

  let user = new Person('User')
  let system = new Container('Software System')
  let webapp = new Component('Web Application')
  let database = new Component('Web Application')

  system.contains(webapp)
  system.contains(database)

  user.uses(webapp).via('Uses')
  webapp.uses(database).via('Reads from and writes to')

  export new Digram()
     .title('Software System')
     .theme('default')
     .shows([user, system])
     .type('container')

Edit: As it turns out, there are a couple libraries like this:

- Python: https://github.com/nielsvanspauwen/pystructurizr

- C#: https://github.com/8T4/c4sharp

Don't see one for JS though. Smells like an opportunity for someone.

[bentinata]

There is also https://diagrams.mingrammer.com/ using python.

[minhmeoke]

If you want to create diagrams from textual descriptions, https://kroki.io/ is very versatile and supports several different markup languages including C4.

Alternatively, if you want to stick to ASCII output, https://arthursonzogni.com/Diagon/#Sequence supports several formats (see the dropdown) which can pipe into something like Typogram (https://google.github.io/typograms/) for more beautiful output.

For example, input:

  Renderer -> Browser: BeginNavigation()
  Browser -> Network: URLRequest()
  Browser <- Network: URLResponse()
  Renderer <- Browser: CommitNavigation()
  Renderer -> Browser: DidCommitNavigation()

will output the following sequence diagram:

  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'
      |                     |             |    
      |  BeginNavigation()  |             |    
      |-------------------->|             |    
      |                     |             |    
      |                     |URLRequest() |    
      |                     |------------>|    
      |                     |             |    
      |                     |URLResponse()|    
      |                     |<------------|    
      |                     |             |    
      | CommitNavigation()  |             |    
      |<--------------------|             |    
      |                     |             |    
      |DidCommitNavigation()|             |    
      |-------------------->|             |    
  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'

and then you can perform further edits using something like https://asciiflow.com/ (web, free) or https://ivanceras.github.io/bob-editor/ (web, free) or https://monodraw.helftone.com/ (Mac only, proprietary) as mentioned in other comments from https://news.ycombinator.com/item?id=37040883.

[hollerith]

Huh. I find the input more readable than the output.

[BerislavLopac]

I recommend trying https://icepanel.io/

[bdg]

These DSL tools can be absolutely fantastic and feel powerful in the hands of one person, but the issues come when multiple people get involved.

I train teams to use C4 diagrams, one of the most common issues they tell me they had in the past is the ivory-tower: someone somewhere created all the diagrams alone and dumps them on everyone hoping it will make the world better. The problem is that mode lacks the collaboration and mutual context-building to get everyone on the same page. Not everything needs to be a team effort, but a lot of your diagram work should shift towards a day-to-day tactical discussion (the deeper the C4 level the faster moving things will be). Shifting to a culture of shared context and the discipline of speaking the same language lets everyone have high clarity and move quickly.

The problem with DSLs is they are often nudging people to work alone. Text editors like that are often not multi-player. You can get around it with a screen-share or even pair programming a diagram, but often the tools nudge behaviours of people into a mode where they just work alone and dump stuff out of the ivory tower.

When I train teams who are coming in new to something like C4 I will use Miro specifically because they don't need any special DSL knowledge, and also especially because it is multi-player (everyone gets to draw and move stuff around). I find often people get a bit shy about touching the diagrams but in the training it is really important to get the whole team into the practice of seeing "oh yeah, this is a diagram I can touch too".

For teams who've been through the basic training and gotten used to C4 diagrams to do specific jobs in their tech org, I move them into https://icepanel.io/ because the problems of that team have changed a lot. The initial problem was "I need to know how to structure a story and model my architecture at the same time". Once they got good at explaining their architecture they end up needing to model their architecture (a diagram is something different than a model) at a bigger scale (all those connections that make your diagrams too messy, the boxes that are important in context A but not context B, etc). I like IcePanel because I can slice out a "domain" of my model and show just that view of the world. For teams that have been trained to empower everyone to draw (instead of a single Benevolent Diagrammer For Life), having a multi-player system to manage the model and pick how to present a multi-dimensional subset of that better than just having a static DSL file or a Miro board (note: Miro is "fine" but it can quickly reach its limits). Basically, You get to keep the complexity of your model but only have a focused discussion on the relevant parts.

Beyond that, there's a whole world of techniques on how to actually read an architecture diagram to spot problems, but that's just too much stuff to post in a comment here.

The tl;dr is: Getting your teams to manage their architecture is multiple skills you need to build into the people on your team: collaborating, diagramming, modeling, analysis, and story-telling. I suggest starting in any tool where everyone can participate, and I don't think that's a DSL-based tool because of the UX. Those DSLs "nudge" your culture towards one where one person in the ivory tower drops an inaccurate and overly complicated one-size-fits-all diagram every 9 months and nobody knows with to do with it. It doesn't always happen, but it does increase the chances.

Full disclosure: I'm the trainer mentioned in the article. Happy to answer questions here if anyone wants to debate or pick my brain.