Till the turn of the century, structured design processes that focused on iterative, incremental development were popularly adopted in the software industry. Examples were ‘Structured Systems Analysis and Design’ (SSAD) and Rational Unified Process (RUP). While these moved away from waterfall, they still focused on completing the bulk of the design in the early stages.
They also popularised model driven development with UML. UML was a way of visually documenting the software design.
Models aid visual learners by providing a high-level visualisation of the domain.

Cut to the 2000s. The Agile Manifesto was published and Agile adoption largely replaced structured development.
The way teams built software changed.
Up-front design was discarded, and with it the practice of diagramming was deemed irrelevant. Today, most people don’t construct even basic UML models such as class diagrams. Instead they construct box and line diagrams.

But what is it that you are building?

‘Creating software architecture diagrams seems to be a lost art’ [c4 founder refnc]

Ask someone in the software industry to ‘draw an architecture diagram to describe your system’, you get an ad-hoc collection of boxes and lines, with no clear notation or semantics.
Some diagrams are high level abstractions, some reflect low-level details. Some depict static structure, others runtime and behavioural aspects. Some show technology aspects, most don’t.

In contrast, ask someone in the construction industry to visually communicate the architecture of a building, and you will likely get site plans, floor plans, elevation views, cross-section views, detail drawings. All reflecting what is being built and has been built. They plan what they build and build to the plan. This is a rarity in software architecture, because the development often diverges from the initial models. You might be looking at a conceptual abstraction that bears no resemblance to the structure of the code.

To be useful, models (diagrams) need to reflect reality. And architects need to develop the skill of effective visual communication of software architecture, that helps:

This is important because we need to ensure everybody is contributing to the same end-goal. And a big piece of that is effectively communicating the vision of what it is that you are building. Agility comes when you can communicate it efficiently as well.

The problem is the need to represent varying levels of abstraction, structural vs dynamic aspects, technology choices, etc.

Agile modelling with C4

C4 was developed as an agile (efficient & effective) modelling solution for documenting and visualising architecture.

Visualising

Mermaid.js

Mermaid is a Javascript library that lets you: a) define flowcharts/models as text (in a markdown-like format) b) visually renders the model definition using the JS library

This approach fits well with JAMstack and Jekyll’s markdown driven workflow.

To integrate Mermaid in Jekyll (credits Natalie Somersall, 2023):

  1. add this expression in _includes/head.html to check for YAML front-matter on pages

    {% if page.mermaid %}
        {% include mermaid.html %}
    {% endif %}
  1. create the file _includes\mermaid.html
<script type="module">
	import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
    let config = {
        startOnLoad: true,
        theme: "dark",
        flowchart: {
            useMaxWidth: true,
            htmlLabels: true
        }
    };

    mermaid.initialize(config);
    
    await mermaid.run({
        querySelector: '.language-mermaid',
    });
</script>

Now you can add the front-matter property mermaid: true to any page where you want to load Mermaid, and on the page have a snippet like:

<div class="mermaid">
flowchart LR
    A(fa:fa-laptop-code Developer) --> B(fab:fa-github GitHub<br>code/issues/etc)
    B --> C(fa:fa-server Build)
    C --> D(fa:fa-server Deploy)
    D --> E(fa:fa-user Environment)
</div>

rendered as:

flowchart LR A(fa:fa-laptop-code Developer) --> B(fab:fa-github GitHub
code/issues/etc) B --> C(fa:fa-server Build) C --> D(fa:fa-server Deploy) D --> E(fa:fa-user Environment)

Backticks are also supported by virtue of querySelector: '.language-mermaid'. While Mermaid looks for a mermaid class,
Jekyll adds a language- prefix to the mermaid class when using code blocks with language tag (the three back-ticks).
The querySelector instructs Mermaid to attach to the language-mermaid class instead of mermaid.

For example:

```mermaid
graph TD

	subgraph row1[" "]
		direction RL
		ELM["Evaluation Lifecycle Manager"] --> EB["Evaluation Builder"]
	end

	subgraph row2[" "]
		direction LR
		ERev["Evaluation Reviewer"] --> ELM
		ERes["Evaluation Responder"] --> ELM
	end
```

rendered as:

graph TD

	subgraph row1[" "]
		direction RL
		ELM["Evaluation Lifecycle Manager"] --> EB["Evaluation Builder"]
	end

	subgraph row2[" "]
		direction LR
		ERev["Evaluation Reviewer"] --> ELM
		ERes["Evaluation Responder"] --> ELM
	end

Or, use mermaid.live to create graphs, export to SVG, upload to post as normal image,
or the older jekyll-mermaid plugin for backtick processing

```mermaid
```

Glossary

Artefacts: architecture deliverables such as models, templates

Blogroll