We are considering using C4 for our architecture diagrams. Many diagramming tools (including Structurizr which was developed specifically for it) support C4. I wonder if there are others that use it and I would like to hear your experiences.
My initial assessment is as follows:
Pros
- Diagram as code is a great way to keep things open to change.
- It allows for better versioning
- It enforces semantics into the diagrams. Instead of just thinking in terms of boxes and arrows, one need to dig deeper
Cons
- It has a relative steep learning curve (one needs to study the DSL even though the end result is just boxes and arrows)
- The tooling is not perfect. One needs to run a docker container to be able to navigate within the diagram (solution: there is also a SaaS offering)
- Its view of architecture is somewhat limiting. It doesn’t seem to be catered for augmenting the diagrams with other forms of diagrams (flowcharts, etc.) or text.
I find keeping C4 diagrams in wikis often leads to them falling out of sync with the codebase. Ideally you’d keep the markup for the diagram in the relevant component repo and have a CI/CD process that keeps your diagrams up to date. I wrote a PlantUML Docker image for exactly that: https://github.com/robbell/plantuml-docker
Alternatively, Mermaid support is becoming more common—available in GitHub and Backstage TechDocs, and that allows you to embed diagrams in Markdown. Both PlantUML and Mermaid have support for linking to other diagrams I believe, and you could put your API definitions in your owning repos too using OpenAPI to keep everything together and in sync.