Every organisation has a diagram that everyone trusts and nobody can verify. It sits in the architecture repository, the onboarding pack and the last three board submissions. It shows the systems, the arrows between them and the security zones around them. When someone asks whether it is still accurate, the honest answer is "probably, mostly".
That has always been a problem. It is becoming a bigger one, because AI agents can now produce polished architecture diagrams from a short description or a quick read of a repository. Drawing has become cheap. Being right has not.
We argued in The Architecture Is Not the Diagram that the real architecture lives in decisions, constraints and trade-offs, and in One diagram cannot answer every question that each view should serve one decision. This part asks a narrower question: when a diagram makes a claim about a system, what would it take for a reader to check that claim?
Marula Commerce is fictional, and its systems and figures are illustrative. Marula's architecture review board was presented with a current-state diagram of the shop platform, drawn with AI help from the repository and a few interviews. It was clear, well laid out and showed a fraud-check service between checkout and payment. When a board member asked which code called it, nobody could say. The fraud check had been proposed two years earlier and never built.
Why diagrams drift
Diagrams are usually maintained separately from the things they describe. Code changes through pull requests, infrastructure through pipelines, integrations through tickets. The diagram changes when someone remembers to update it, which is usually just before a review.
So a diagram can stay visually correct while becoming factually wrong. Nothing in the picture tells the reader which boxes were observed last week, which were confirmed by an owner a year ago, and which were someone's intention.
AI makes both sides of this sharper. An agent that reads a repository can genuinely reduce drift, because it can describe what is actually there. The same agent, given a vague prompt, can also add the component that "should" be there, such as a fraud check, a cache or a message queue, because the pattern is common. The result looks equally authoritative either way.
Four levels of support
The first step costs almost nothing: mark how well supported each element is.
- Observed: traced to code, configuration or a deployed resource, at a specific commit or date.
- Confirmed: stated by the system owner and recorded, with a name and date.
- Assumed: believed to be true, not yet checked. Marked visibly on the diagram.
- Proposed: a target state awaiting a decision or approval.
Marula's fraud check was "proposed" drawn as "observed". If the diagram had distinguished the two, the board would have seen a dashed box with a label and asked the right question: when will this be built, and what protects checkout until then?
A diagram needs a source model
The rendered image should not be the only artefact. A typed source model, a structured file listing nodes, relationships, boundaries and their metadata, can be versioned, compared, validated and re-rendered. It can carry evidence that an image cannot: the repository path behind a component, the commit it was observed at, the person who confirmed an integration, the decision record behind a boundary.
The pipeline then looks like this. Evidence is gathered from the repository, owners and documents. It is recorded in the typed source with levels of support. The source is validated. Views are rendered for each audience. An architect and the system owner review them. An approved version is recorded with a date. Corrections go back into the source, never into the picture.
Pin the revision
When a diagram claims to describe a codebase, it should say which version. "Observed in the shop platform at commit 4e1c9a2, 14 October" lets a later reader separate what the system looked like then from what it looks like now. Without that, a correct historical diagram and a wrong current one are indistinguishable.
Validation proves less than it seems to
Automated checks are valuable. They can catch missing references, disconnected nodes, relationships to components that do not exist, clipped labels, overlapping routes and broken exports. These are real defects, and machines find them faster than people.
But passing those checks proves that the artefact is well formed and readable. It does not prove that the architecture it shows is true. A perfectly validated diagram can still contain a fraud service that was never built. Only evidence and human review can address that.
One public example: Archify
Tools are starting to work this way. Archify, an open-source agent skill (version 3.2.0 at the time of writing, Apache-2.0 for current source), has an agent write a typed JSON source for an architecture, workflow, sequence or other diagram, then runs schema, layout, route and label checks before it will replace the last good output. For repository-backed diagrams, nodes can carry source evidence pinned to a specific public commit, which the reader can open from the diagram. It is explicit that its delta view "infers no impact, risk, or merge safety". That candour is the right posture: the tool checks the artefact, and people judge the architecture.
We used Archify for several interactive diagrams in this series, alongside our usual static diagrams. The interactive example below shows a small system where every component and relationship carries its level of support.
A tool is not a method, and we are not recommending one product. Before using any such tool on confidential repositories, review its dependencies, network behaviour and how it handles local data, and pin the version you use.
The evidence a reviewer should expect
| Element | Evidence expected |
|---|---|
| Component | Repository path, deployed resource, document or confirmed owner statement |
| Relationship | A call, event, query or data transfer that can be shown, or an approved design |
| Boundary | Network, trust, ownership or data boundary, with its basis |
| Technology | Detected in the implementation, or an approved selection |
| Risk | An observed weakness, missing evidence, or a reasoned exposure |
| Version | Commit, artefact version and verification date |
None of this requires a new tool. A spreadsheet and a discipline of marking levels on existing diagrams already closes most of the gap.
Public diagrams need clean sources
One caution for anyone publishing architecture, including in proposals and articles. A redacted screenshot of a real client architecture is not anonymised. Topology, naming patterns and security zones can identify an environment even after labels are blurred. Public diagrams should be rebuilt from a clean source model with neutral names and illustrative values, which is another reason to keep a source model at all.
The diagram is not the architecture record on its own. The record is the evidence, the source model, the decisions, the validation results and the approval, with the diagram as one view of them.
Next: Part 7, What changed in the architecture? Show me the delta. All parts are on the series page. For AI-generated documents more broadly, see Evidence Before Autonomy.
How CloudNala can help
We help architecture teams introduce evidence levels and source models into their existing diagrams, and review current-state architecture packs for claims that cannot be traced. Where AI tools are used to produce diagrams, we help set the review and evidence rules so that speed does not come at the cost of accuracy.
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