Mopane Medical Scheme's architecture team had a problem that every team with more than a few diagrams eventually has. The claims engine appeared in eleven diagrams. In three it was called "Claims System", in two "Adjudication Service", in one by the name of its deployment, and in the rest "Claims Engine". Two of those diagrams still showed a link to a legacy billing system that had been switched off. Nobody had lied. Each diagram had simply been drawn and updated on its own.
Moving those eleven diagrams into eleven text files would not have fixed this. Each file would still define the claims engine separately, and they would still drift apart. What fixes it is a model: one place where each element is defined once, with views that select from it. That is the difference between a diagram tool and a modelling tool, and it is the most valuable idea in diagrams as code.
Mopane Medical Scheme is fictional, and its systems and figures are illustrative.
Diagram tools and modelling tools
A diagram tool, whether a drawing canvas or a text syntax, produces one picture per file. If the same system appears in five pictures, it is defined five times. A modelling tool separates two things:
- The model: the elements (people, systems, containers, components, deployment nodes) and the relationships between them, each defined once.
- The views: selections from that model for a particular audience and question. A view says which elements to include or exclude. It does not define them.
Structurizr DSL makes this split explicit. Its documentation describes the workspace as the wrapper for a model block and a views block, and views use include and exclude statements that refer to element identifiers. The same idea can be applied with other tools, but only if the team adopts the discipline that elements are defined once and drawn many times.
We explained in One diagram cannot answer every question why each audience needs its own view. A model is how a team produces those views without maintaining each one by hand.
The C4 levels, named properly
The C4 model, created by Simon Brown and documented at c4model.com, is the most common framework for this kind of modelling. Its site, checked on 28 October 2026, names four levels of diagram:
- System context diagram: the system in its environment, with the people and other systems it interacts with.
- Container diagram: the applications and data stores that make up the system. In C4, a container is anything that runs or stores data, not only a Docker container.
- Component diagram: the main building blocks inside one container.
- Code diagram: classes or equivalent, usually generated and rarely worth maintaining by hand.
It also names three supplementary diagrams: the system landscape diagram, the dynamic diagram and the deployment diagram. The site describes the model as independent of notation and tooling, so a team can draw C4 in any style.
Using the official names matters more than it seems. When an architect says "the container view", every reader who knows C4 knows what level of detail to expect. When one team calls it the "logical view" and another the "application view", the vocabulary itself starts to drift.
One model, three views
For Mopane, the team defined one model containing the scheme's people (members, providers, the claims team), its software systems (the member app, claims engine, provider portal, member registry and data warehouse), the external systems it depends on (a payment bank and a pharmacy switching provider), and the relationships between all of them. The model also holds deployment nodes: the cloud region, the container platform, the managed database.
From that one model they generate three views most often:
- System context, for the executive committee and the board: Mopane's scheme, the members and providers who use it, and the external parties it exchanges data with. Containers are hidden.
- Container, for the architecture review and the engineering teams: the apps, engine, registry and warehouse, with the relationships between them labelled by protocol and purpose.
- Deployment, for operations and the security team: which containers run on which infrastructure, in which region.
A short Structurizr DSL sketch shows the shape:
workspace "Mopane Medical Scheme" {
model {
member = person "Member"
scheme = softwareSystem "Mopane scheme platform" {
app = container "Member app"
claimsEngine = container "Claims engine"
registry = container "Member registry"
}
member -> app "Submits and tracks claims"
app -> claimsEngine "Lodges claims"
claimsEngine -> registry "Checks cover and benefits"
}
views {
systemContext scheme { include * }
container scheme { include * }
}
}
The example is deliberately small and illustrative. The point is that claimsEngine is written once. Both views refer to it. A deployment view would refer to the same identifier when it places the claims engine on a node.
Identity is the real design decision
Once a team has a model, the most important decisions are not about notation. They are about identity: how each element is named and identified so that it stays the same thing across views, across time and across tools.
Mopane settled on four rules:
Every element has a stable identifier and a display name. The identifier, such as claimsEngine, does not change when the product is rebranded. The display name, "Claims engine", can. Other tools and scripts refer to the identifier.
One element, one name, everywhere. The model is the authority. If the operations team calls the claims engine by its deployment name, the deployment view shows that name as a property of the deployment node, not as a different element.
Owners are properties of elements. Each container carries a named owning team. That makes "which systems does the claims team own?" a query rather than a meeting.
External parties are labelled by role, not by vendor, in shareable views. The model can hold the vendor's name as a property. A view intended for a proposal or a public article shows "payment bank" or "pharmacy switch". That rule matters for a medical scheme, whose integration partners and topology are not public information.
These rules sound bureaucratic. In practice they are what make the rest of this series work. Lint rules in a pull request (Part 4) check them. Reconciling a model with what is actually deployed (Part 5) depends on matching identifiers. Checking whether an AI agent has invented a component (Part 6) depends on there being an authoritative list of components to check against.
What a view should not do
A view is a selection, so it should not add facts. Three habits break that rule:
- Drawing extra boxes directly onto a rendered view "just for this meeting". The fact is now in a picture and nowhere else.
- Defining a relationship inside a view that the model does not contain. Some tools allow this. It creates a fact that only one view knows about.
- Renaming an element in one view for an audience. If the audience needs a different term, use a property or a sanitised view generated by rule.
The useful exception is a target-state view. Proposed elements belong in the model too, marked as proposed, as described in Architecture diagrams should be evidence, not artwork. A view can then filter by that marking: current state only, or current plus proposed.
When a model is overkill
Not every team needs this. A single team with one service and two diagrams gains little from a model. Mermaid diagrams inside design notes, each describing one change, are often the right answer. The model starts to pay when:
- the same element appears in more than three or four diagrams;
- more than one team maintains diagrams of the same estate;
- diagrams are used as evidence in reviews, audits or proposals;
- or other tools need to read the architecture.
Mopane met all four. A small startup building one product might meet none of them yet. The model also has an organisational cost: someone has to own it, and the team has to agree identity rules and keep to them. In Mopane's case, the lead architect owns the model and the two solution architects own the views for their domains. The repository and its review process, the subject of The architecture repository is a management system, give that ownership something to hold on to.
A practical first model
To start, Mopane did not model everything. They modelled the claims journey: the people, systems and containers needed to explain how a claim moves from a provider to a payment. That covered about a fifth of the estate and most of the questions the architecture review actually asked. Other journeys were added as changes touched them.
That incremental approach is the right default. A model of everything, built before anyone needs it, is out of date before it is finished.
Next: Part 3, Archify in practice. All parts are on the series page.
How CloudNala can help
We help architecture teams set up their first model: choosing the scope, agreeing identity and naming rules, defining the views each audience needs, and deciding who owns what. We can facilitate the workshops where those rules are agreed and review an existing set of diagrams to find where the same element has drifted into several different ones.
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