Diagram tying the product requirements + decisions together

Problem/Motivation

First, go and read the issue summary of #3454669: Record Architecture Decisions — to scale to many people + many timezones.

Excerpt from there:

We need, at least:

1. product requirements broken down into concrete issues (a graph of issues, with concrete Task issues that can be implemented in a single MR) to work towards that first concrete goal (#3454094), ⚠️ knowing full well that these will be incomplete: we're first working towards that first concrete goal, then expanding scope
2. a record of decisions (and these decisions may need to be revisited too)
3. a diagram tying the product requirements + decisions together

This issue is realize that third point.

3 days ago, I wrote in Drupal Slack:

• My thinking: that diagram should be as useful as https://www.drupal.org/docs/8/api/render-api/the-drupal-8-render-pipeline (also by yours truly 🤓)
  • … but obviously not as definitive: it’ll have to evolve.

Steps to reproduce

N/A

Proposed resolution

Following that, @ctrlADel messaged me:

c4 diagrams https://c4model.com/ would be great. I don't find the render one particularly easy to digest but then again it's a complicated area. Happy to help make a pretty/cleaned up version of the diagram as well

… which led me down the path of first starting to build a C4 diagram in OmniGraffle — the same tool I used to create that render pipeline diagram years ago. But this made me realize that ideally the diagram could be edited by anyone, and ideally would be versioned.

So I searched and found … https://structurizr.com/ — which:

• is a DSL to define C4 diagrams, and can transform this to a wide variety of formats
• has a CLI tool to validate its DSL: https://docs.structurizr.com/cli
• has an open source version to view/edit diagrams: https://docs.structurizr.com/lite
• connects to ADRs! 🚀 https://docs.structurizr.com/dsl/adrs#architecture-decision-records-adrs
• appears to be easy to integrate with GitLab: https://docs.structurizr.com/cli/installation#gitlab

While maybe imperfect, this is clearly far better than multiple paying for an OmniGraffle license just to be able to edit a diagram, and neither versioned, nor diffable, nor exportable, etc.

So: let's try it.

Remaining tasks

• Get it working on GitLab CI at all: https://git.drupalcode.org/project/experience_builder/-/merge_requests/60
• Create a first draft of the diagram, after step 1 from the issue summary is done.

User interface changes

None.

API changes

None.

Data model changes

None.