Architecture documentation usually dies in one of two ways. In the first, it is written once for a project, approved, and never touched again. Within a year it describes a system that no longer exists. In the second, someone introduces a tool that generates diagrams from the code, the diagrams are always current, and the team quietly stops writing anything else. Within a year the documentation is accurate and nearly useless, because it shows what the system is without saying why, for whom, or where it is supposed to be going.
The goal is somewhere between: documentation that stays current where machines can keep it current, and stays meaningful where only people can make it meaningful.
Marula Commerce is fictional, and its systems and figures are illustrative. After the catalogue extraction (Part 2) and the new delivery service (Part 7), Marula's architecture had changed more in six months than in the previous three years. Its single architect could not keep the documentation current by hand, and the engineering lead proposed generating it all from the repositories.
What the code can tell you
A repository and its deployment configuration are good evidence for a specific set of facts:
- Modules and dependencies: which components exist and which import or call which.
- Routes and API surfaces: which endpoints are exposed and by whom.
- Deployed resources: what infrastructure exists, if it is defined as code.
- Calls between services: outbound URLs, queues, topics and connection strings.
Tools, including AI agents reading a repository, can extract these reliably and refresh them on every merge. That is genuinely valuable, because these are exactly the facts that drift fastest in hand-drawn diagrams.
What the code cannot tell you
The same repository is silent, or misleading, on a different set of facts:
- Why it was decided. The code shows that the delivery service calls two couriers. It does not say why a separate service was preferred to two direct integrations.
- Who owns what. Ownership lives in organisation charts, on-call rotas and budgets, not in import statements.
- Data classification. A field named
addrmay or may not hold a customer's home address. The code does not know whether it is personal information. - Intended target state. The code shows where the system is. The direction of travel lives in people's heads and in roadmaps.
- Operational dependencies outside the code. A nightly manual export, a spreadsheet the finance team relies on, a partner that phones in.
An AI agent asked to fill these gaps will often produce a plausible answer. That is the risk described in Part 6: an inferred ownership or classification presented with the same confidence as an observed dependency. Any generated documentation should mark what was derived and leave the rest visibly blank until a person fills it.
Two rhythms, not one
Marula settled on two rhythms.
On every merge, automatically. The pipeline regenerates the derived views (component map, dependencies, API surface) from the main branch, and compares them with the last approved baseline. Differences are not errors. They are flagged as drift, listed as a delta of the kind described in Part 7, and posted to the architecture channel.
On every significant decision, and at least quarterly, by people. When an architecture decision record is written, or at a fixed quarterly review, the architect and the relevant owners update the parts machines cannot: intent, ownership, classification and target state. They review the accumulated drift and either accept it into a new approved baseline or raise it as a problem.
The connection between the two is what makes it work. Automated drift detection gives the human review an agenda: "since last quarter, three new outbound dependencies appeared, one of them to a service nobody has classified". The human review gives the automated views their meaning.
What to keep, and where
| Artefact | Maintained by | Changes when |
|---|---|---|
| Derived component and dependency views | Pipeline | Every merge |
| Drift report against approved baseline | Pipeline | Every merge |
| Architecture decision records | Architect and team | Each significant decision |
| Ownership and support map | Architect with delivery leads | Team or service changes |
| Data classification per flow | Data owner with architect | New data or new flow |
| Target-state views | Architect | Quarterly, or with strategy |
| Approved baseline | Architecture review | Quarterly, or on acceptance of drift |
Most of this fits in the repository itself as Markdown and structured files, versioned alongside the code. Keeping it there means the documentation is reviewed in the same pull requests that change the system, which is the single most effective way to keep it alive.
Things to avoid
- Generating everything and calling it done. The derived views are the easy half.
- Hand-maintaining what can be derived. Every manually drawn dependency arrow will be wrong eventually.
- A wiki disconnected from the code. If documentation lives somewhere engineers never visit during normal work, it decays.
- Drift alerts nobody reads. If the quarterly review never happens, automated drift detection becomes noise and is switched off.
- Pretending the target state is current. Keep proposed elements visibly marked, as in Part 6.
Getting started in a month
Marula did not build all of this at once. The first month looked like this:
- Week one: create an
architecturefolder in each main repository, and move existing decision records and the current diagrams into it, marked with their last known review date. - Week two: add a pipeline step that generates a dependency view from the main branch and publishes it next to the hand-drawn one. Nobody deletes anything yet.
- Week three: compare the two. Every difference is either a stale hand-drawn element, a dependency nobody knew about, or a generator mistake. Each is recorded and resolved.
- Week four: approve the first baseline, write down who owns each service and which flows carry personal information, and book the first quarterly review.
The first comparison was the most valuable step. It found two outbound dependencies that nobody had documented, including a reporting job that still read the old catalogue tables directly, weeks after the extraction was supposed to have removed that path.
Bringing the series together
This series has moved from components to evidence. An API gateway is a control point with limits. A microservice is a trade of function calls for network failures. A checkout spanning four systems needs compensation and honest states. Logs, metrics and traces answer different questions. Status codes are instructions. And the diagrams and documents that describe all of this should be held to the same standard as the systems themselves: traceable, versioned, reviewed and clear about what is known and what is assumed.
Back to Part 1, What an API gateway actually does. All parts are on the series page.
How CloudNala can help
We help teams set up documentation that lives in the repository: derived views and drift detection in the pipeline, decision records and ownership maps maintained by people, and a review rhythm that connects the two. We also review existing architecture repositories for what is current, what is assumed and what is simply out of date.
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