Keuze voor Structurizr DSL voor C4-architectuurdiagrammen¶

ID: ADR-0005
Status: geaccepteerd
Datum: 2026-07-07
Domein: Domeinoverschrijdend
Auteurs: Bas Meeuwissen

Context en Probleemstelling¶

In ADR-0003 is er besloten om architectuur diagrammen in code te beschrijven vanwege de goede onderhoudbaarheid. Er is echter nog niet besloten welke dsl en tool we gaan gebruiken hiervoor.

Beslissingsfactoren en constraints¶

Technische beperkingen: Docker containers zijn niet beschikbaar op lokale machines.
Financiële beperkingen: De aanschaf voor licenties voor betaalde pakketen is beperkt.
Organisationele beperkingen: We willen graag een architectuur pagina met o.a. architectuur diagrammen die begrijpbaar zijn voor alle bezoekers.

Overwogen Opties¶

Optie 1: Structurizr DSL
Optie 2: PlantUML met C4 plugin
Optie 3: Mermaid.js

Besluitvorming¶

Gekozen optie: Optie 1, omdat het ons in staat stelt om een scheiding te maken tussen het model (de structurele waarheid van onze architectuur) en de views (de visuele representatie). Door gebruik te maken van de Structurizr Docker kunnen we deze 'Single source or truth' via een CI/CD pipeline omzetten naar statische assets voor de static website. Dit voorkomt inconsistenties die ontstaan bij handmatige diagrammen en biedt een schaalbare manier om van landschap- naar component-view te navigeren zonder dubbel werk.

Consequenties¶

Positief, want: Positief gevolg, een enkel model waarmee verschillende views gegenereerd kunnen worden.
Positief, want: Positief gevolg, schaalt prima met een toenemend aantal systemen en componenten.
Negatief, want: Negatief gevolg, additionele configuratie en onderhoud voor het genereren van plaatjes. De DSL wordt niet ondersteund door markdown plugins.
Negatief, want: Negatief gevolg, de leercurve is hoger in vergelijking met de andere opties.