=== Use Structurizr for C4 diagrams

Date: 2025-05-08

==== Status

Accepted

==== Decision makers

* Eric Förster
* Stephan Weißenberger
* Ralf Hägele
* Marius Kort
* Andre Harms

==== Context

We currently use D2 (https://d2lang.com/) to generate C4 architecture diagrams. While D2 provides a concise DSL for general diagrams, it lacks built-in C4 abstractions (e.g. Software system, Container, Component, etc.). We need a tool that:

* Directly supports the C4 model
* Allows reuse of the same architecture definitions across views

==== Decision

We have decided to adopt the open-source version of Structurizr (using the DSL and Structurizr Lite) for authoring and maintaining C4 architecture diagrams. This decision was based on the following factors:

* **Native C4 Support:** Structurizr is specifically designed for the C4 model, providing built-in abstractions and validation.
* **Model-Driven Approach:**  Structurizr uses a model-driven approach, allowing us to define the architecture once and generate multiple views from the same model.
* **Extensibility:** Structurizr is extensible, allowing us to customize the diagrams and integrate with other tools.
* **Community Support:**  Structurizr has an active community and comprehensive documentation.


==== Consequences

* **Positive:**
** **Improved Diagram Accuracy:**  C4 model validation will help ensure the diagrams accurately represent the architecture.
** **Reduced Maintenance Overhead:**  The model-driven approach and code-as-configuration will simplify diagram maintenance.
** **Increased Consistency:**  Reusing architectural definitions across views will ensure consistency.

* **Negative:**
** **Learning Curve:**  Team members will need to learn the Structurizr DSL.
** **Migration Effort:** We will need to migrate existing D2 diagrams to Structurizr.
** **Potential Lock-in:**  Adopting Structurizr may create a dependency on the tool.