A source file in a repository is only half of diagrams as code. The other half is what happens when someone changes it. If architecture changes are still reviewed in a monthly meeting, from screenshots, the source file has bought version history and little else. The real gain comes when an architecture change travels through the same pull request as the code that causes it, is checked by the same pipeline and is approved by the people who own that part of the architecture.
Our view: the pull request is the right place for architecture review of incremental change, and the pipeline should do every check a machine can do, so that the human review is spent on meaning. The architecture review board still has a role, for significant decisions and quarterly baselines, but it should not be the first place anyone sees a new dependency.
What changed in the architecture? Show me the delta covered what a reviewer should see. This part covers the plumbing that produces it.
Mopane Medical Scheme is fictional, and its systems and figures are illustrative. After building its first C4 model (Part 2), Mopane's architecture team of three wanted changes to reach them without asking eight development teams to remember to tell them.
Where the source lives
The first decision is placement. There are two workable patterns.
Next to the code. Each service repository holds the part of the model that describes that service, and a central build combines them. Changes arrive in the same pull request as the code. The cost is a combining step and the risk that teams name things inconsistently.
In one architecture repository. The whole model lives in one place. Consistency is easier, but changes arrive in a separate pull request from the code, and the link between the two depends on discipline.
Mopane chose a hybrid that suits a small architecture team. The model lives in an architecture/ folder in the claims platform's main repository, where most change happens. The member app and provider portal teams make architecture changes there by pull request, linked to their own code changes. If the scheme grows, the model can be split later.
The pipeline
The pipeline for a pull request that touches architecture/ runs four steps.
1. Validate the source. The tool's own parser or schema check runs first. A source that does not parse should fail in seconds, before anything else runs. For Structurizr DSL that means parsing the workspace. For a typed JSON source it means schema validation. For Mermaid it means rendering each block and failing on errors.
2. Lint the model. Schema validity is not enough. A source can be perfectly valid and still contain an element nobody connects to, or a relationship to an identifier that was renamed. Lint rules check the house conventions, described below.
3. Render the views. The pipeline renders every view from the source, so the pictures in the repository are always the pictures the source produces. Nobody exports a diagram from a laptop. Rendered images are attached to the pull request as build artefacts, and the pipeline posts a comment linking to them.
4. Compute the delta. The pipeline compares the model on the branch with the model on the main branch and lists what was added, removed and changed. That list goes in the pull request comment above the images.
The whole pipeline should run in a few minutes. If it takes longer, people start skipping it.
Lint rules worth failing a build on
Lint rules are where a team encodes its conventions. Mopane started with five:
- Naming. Element display names follow the house pattern, and identifiers are lower camel case. This is the rule that stopped "Claims System" and "Adjudication Service" reappearing.
- Orphan elements. Every element has at least one relationship. An orphan is usually a leftover from a deletion or an element added in a hurry.
- Undeclared relationships. Every relationship refers to identifiers that exist in the model. Most tools catch this at parse time; where they do not, the linter must.
- Owners. Every container carries a named owning team. Without an owner, nobody can answer the questions an added component raises.
- Evidence. Every element carries a support level: observed, confirmed, assumed or proposed. Mopane made this a warning for the first quarter, because the existing model had none and failing every build on day one would have caused the rule to be switched off.
That last point generalises. Introduce a new rule as a warning, measure how often it fires, fix the backlog, then make it fail. A rule that fails everything on the day it arrives does not survive.
Lint rules are usually a short script that reads the model. Structurizr workspaces can be exported to JSON; typed JSON sources can be read directly. A few dozen lines of code are enough for these five rules.
Model diffs, not pixel diffs
A tempting shortcut is a visual diff: render the main branch and the pull request branch, compare the images and highlight the pixels that changed. It rarely works well for architecture diagrams.
Automatic layout means a single added element can move half the boxes on the page. The pixel diff then lights up everywhere, and the reviewer is back to comparing two pictures by eye. Layout also varies between tool versions, so an upgrade produces a diff on every view without any architectural change.
A model diff compares elements and relationships by identifier. Adding a fraud-scoring service produces one added element and two added relationships, regardless of where the layout puts them. That is the delta the reviewer needs. Some tools produce this directly, as the delta article describes. Where a tool does not, a script that compares the exported model by identifier gives the same list.
Pixel diffs still have one use: catching a rendering regression after a tool upgrade, when the model has not changed and the pictures should not either.
Review rules and CODEOWNERS
The pipeline checks form. People check meaning. The review rules decide which people.
On GitHub, a CODEOWNERS file assigns owners to paths. GitHub's documentation, checked on 28 October 2026, says the file can sit in the .github/, root or docs/ directory, that owners are automatically requested for review when a pull request changes files they own, and that a branch protection rule or ruleset can require code owner approval before merge. Other platforms have equivalents.
Mopane's file is short:
# Architecture model and views
/architecture/ @mopane/architecture
/architecture/views/deployment/ @mopane/architecture @mopane/platform-ops
Three details matter in practice:
- Approval from any one listed owner satisfies the requirement. Listing two teams on a line means either can approve, not both. If both must approve, the code owner requirement alone will not enforce it; check what other review controls your platform and plan offer, or add a pipeline check.
- The file that counts is the one on the base branch. A pull request cannot change its own reviewers by editing
CODEOWNERS. - Pull requests not yet marked ready for review do not request owners. Owners are notified when the pull request is marked ready.
Mopane added two review rules on top. An architecture change must link to the code change or decision record that motivates it. And a pull request that changes infrastructure code or service manifests without touching architecture/ triggers a non-blocking reminder in the pipeline, asking whether the model should change too. Part 5 replaces that reminder with something more precise.
The interactive version
What the pipeline does not do
A green pipeline means the model is well formed, follows the conventions, renders and has a computed delta. It does not mean the change is a good idea, that the new dependency is acceptable, or that the model matches what is running. Those remain the reviewer's job, and the review record should show a named person's decision, not only a passed check. Comments are not approval: designing the review record covers that distinction in the context of AI-generated documents, and it applies here unchanged.
There is also a risk of review fatigue. If every small change to a label requests the architecture team, they will start approving without reading. Mopane reduced that by letting the delta decide: a pull request whose delta contains only property changes, such as a corrected description, needs one architecture approver; a delta with added or removed elements or relationships also needs the owner of each affected container.
Next: Part 5, Generated from reality. All parts are on the series page.
How CloudNala can help
We help teams wire architecture models into the delivery pipelines they already run: placement of the source, validation and lint rules, rendering in CI, model diffs, and CODEOWNERS and branch rules that put the right reviewers on each change. We can also review how architecture changes reach your review board today, and where they slip past it.
Work with CloudNala
CloudNala helps organisations move from technology ambition to practical execution across cloud, AI, data, platform engineering and digital services.
Whether you are exploring AI, modernising your cloud environment, building a public-sector digital service, or turning an idea into a working MVP, we can help you shape the roadmap and deliver the next step.
Request an Architecture Review or write to us at consult@cloudnala.co.za