Surveys of tools only go so far. At some point a team has to pick one, write a source file, run it through the build and live with the result. This part does that with one tool, Archify, using a claims flow from Mopane Medical Scheme. We use Archify for the interactive diagrams on this site, so the walkthrough describes something we actually run, including the parts that do not work as advertised in our own environment.
The aim is not to recommend Archify over the alternatives in Part 1. It is to show what the practical engineering of one typed diagram looks like: the source, the checks, the output and the limits. The most important lesson applies to every tool: a passing build tells you the diagram is well formed. It cannot tell you the diagram is true.
Mopane Medical Scheme is fictional, and its systems and figures are illustrative. Mopane's architects wanted one interactive diagram for the architecture review: how a claim moves from a provider's practice system, through the provider portal and the claims engine, to a decision, a payment notification in the member app and a record in the data warehouse.
What Archify is
Archify is an open-source agent skill. An AI coding agent, such as Claude Code, Codex CLI, Cursor or OpenCode, writes a typed JSON source for a diagram, and Archify's command-line tool validates the source and renders it into a single HTML file. Its own description, checked against the pinned version's README and skill file on 28 October 2026, covers ten native diagram types: architecture, workflow, sequence, data flow, lifecycle, ERD, class, tree, timeline and waterfall, plus a one-page explainer mode added in version 3.2.0.
The parts that matter for diagrams as code:
- A typed source. Each diagram type has a JSON schema. The source is the artefact that is versioned and reviewed. Archify can read Mermaid as input, but it reads Mermaid for meaning and writes fresh typed JSON rather than restyling it.
- Gates before delivery. Schema, layout, HTML, route and label checks must pass before a new output replaces the last good one.
- Machine-readable failures. A failing check returns a stable rule code, the exact element concerned, the measurement and the supported fixes, rather than a stack trace.
- A portable result. The output is one HTML file with dark and light themes and image and video exports. It can be opened in a browser without installing anything.
- Optional source evidence. For diagrams of a real repository, architecture nodes can cite files and line ranges pinned to one public commit.
Choosing the diagram type
The first decision is the type, and it shapes everything else. A claims flow could be drawn as a workflow (steps and decisions in lanes), a data flow (where claim data goes and how sensitive it is), or a sequence (who calls whom, in what order, and what comes back).
Mopane's review question was about interaction: which system calls which, synchronously or not, and where the claim reference is used to avoid paying twice. That is a sequence question, so the team chose a sequence diagram. A data flow would have been the right choice if the question had been about where health information is stored.
The typed source
A sequence source declares participants, messages and optional segments, activations and cards. A trimmed extract of Mopane's source:
{
"schema_version": 1,
"diagram_type": "sequence",
"participants": [
{ "id": "portal", "type": "frontend", "label": "Provider Portal" },
{ "id": "engine", "type": "backend", "label": "Claims Engine" },
{ "id": "registry", "type": "database", "label": "Member Registry" }
],
"messages": [
{ "id": "lodge", "from": "portal", "to": "engine", "y": 200,
"label": "lodge claim (ref C-2291)", "variant": "emphasis",
"note": "Claim reference is the idempotency key" },
{ "id": "eligibility", "from": "engine", "to": "registry", "y": 345,
"label": "check cover and benefit", "variant": "security",
"note": "Observed at a pinned commit" }
]
}
Three things are worth noticing. Every participant and message has a stable id, which is what a reviewer, a script or a later comparison refers to. Each message can carry a note, which Mopane used to record how well supported the message is: observed in the code, confirmed by an owner, or assumed. And the vertical positions are explicit, which gives the author control over spacing and gives the validator something to measure.
The gates
The build runs one command, finalize, which runs four gates in order and stops at the first failure:
- Validate: the source matches the schema for its type and passes layout rules.
- Deliver: a candidate HTML file is rendered next to the target and only replaces it if it passes.
- Check: the HTML and its provenance are checked against the source.
- Browser check: the page is opened in a real browser and inspected.
Mopane's first attempt failed at validation twice, and both failures were instructive. The first rejected a message from the claims engine to itself ("apply scheme rules"), because this sequence renderer only supports messages between different participants. The fix was not to invent a "rules engine" participant to make the arrow legal. It was to move the step into a note on the message that returns the benefit check, which is where it actually happens. The second failure reported that a note wrapped onto four lines and collided with the next message, and named the exact position the next message needed to move to.
Neither failure would have been caught by eye in a drawing tool until someone noticed an overlap on a projector. Both arrived as specific, machine-readable diagnostics.
One honest qualification. In our own Windows build environment, the browser check gate cannot attach to Chrome's debugging pipe, so finalize reports that gate as failed even when the first three pass. We accept the first three gate results and run a separate headless-browser check that loads each page at desktop and phone widths and fails on console errors or horizontal overflow. If you adopt any tool with a browser-based gate, test that gate in your actual CI runner before relying on it.
The result
The output is a single HTML file, embedded above, with the house diagram before it as the static fallback. The interactive version lets a reader focus on a participant, follow the messages and read the notes, including the one that marks the data warehouse event as assumed: owner confirmation outstanding.
Pinning the tool
A diagram toolchain is a dependency like any other, and it should be pinned like one. We pin Archify at version 3.2.0, at a specific commit, in our repository's tooling notes, and rebuild the local copy from that tag. Three practical points came out of doing this.
Disable network calls in the build. Archify can make a small request to check for a newer stable release and show a reminder; it never installs updates itself. Its README documents an environment variable, ARCHIFY_UPDATE_CHECK_DISABLED=1, that turns the check off. A build that must be reproducible should set it.
Check the licence of the exact version you pin. The project's current source is published under Apache-2.0, and its repository notes that earlier MIT grants remain in effect for previously published releases. The LICENSE file in the v3.2.0 checkout we pinned is MIT. Neither licence is a problem for most uses, but the version in your repository is the one whose terms apply, which is a reason to read the file rather than the project's landing page.
Upgrade deliberately. A new version can change validation rules, so a source that passed yesterday may fail tomorrow. Treat an upgrade as a change with its own record, as described in Pin the version before you trust the platform and Upgrade evidence belongs in the architecture record.
Before using any agent skill on confidential repositories, review it as you would any other executable dependency. Agent skills and MCP servers are executable dependencies sets out what to check.
What the gates prove, and what they cannot
When Mopane's claims flow passed, the team knew several things with confidence. The source matched the schema. Every message referred to a participant that existed. Labels fitted their space and routes did not collide. The output was one portable file, produced from that exact source.
They did not know whether the claims engine really sends a "claim decided" event to the warehouse. The diagram said so, and it passed every gate, but the note on that message still read "assumed". The gates check that the artefact is well formed and readable. They have no access to the running system, no knowledge of who owns the warehouse feed and no way to tell a current design from a two-year-old plan.
That is not a weakness of this tool in particular. It is the boundary of what any validator can do, and it is why the evidence levels from Architecture diagrams should be evidence, not artwork and a named human reviewer remain necessary. Mopane closed the gap the ordinary way: the warehouse owner confirmed the event in the review, and the note was updated in the source.
Next: Part 4, Architecture diagrams in the pull request. All parts are on the series page.
How CloudNala can help
We help teams set up typed diagram toolchains they can trust: choosing the diagram types for their questions, writing the first sources, pinning and reviewing the tool as a dependency, and making the build reproducible in their own CI. We are equally careful about the boundary, and help teams add the evidence and review steps that tooling cannot replace.
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