Most architecture work in South Africa is judged by a picture. A vendor presents a set of neatly aligned boxes, colour-coded by layer, with arrows flowing left to right from users to data. The steering committee nods. The diagram goes into the business case, the tender response or the board pack, and everyone leaves the room with the feeling that the hard thinking has been done.
Six months later the same organisation discovers that nobody decided where customer records would actually be stored, that the integration between the new platform and the twenty-year-old ERP was drawn as a single arrow but needs eleven interfaces, and that the "resilient" design assumed a data centre that goes dark for four hours during stage 6 load-shedding.
The diagram was not wrong. It simply was not the architecture. It was a summary of an architecture that, in many cases, was never fully worked out.
Why diagrams feel like progress
Diagrams are seductive because they compress complexity into something a non-technical executive can absorb in thirty seconds. That is a genuine strength. A good diagram is one of the most useful communication tools an architect has, and nothing in this article argues against drawing them.
The problem is what diagrams leave out. An arrow between two boxes says that two systems talk to each other. It says nothing about whether that conversation is synchronous or queued, what happens when one side is unavailable, who owns the contract, how data is validated, or what it costs per transaction. A box labelled "AI service" says nothing about which model, hosted where, processing which categories of personal information, under whose approval.
Every one of those unanswered questions is a decision that someone will eventually make. The only question is whether it is made deliberately, early, by someone accountable for the whole system, or accidentally, late, by a developer under deadline pressure who simply picks whatever is quickest. In our experience, the accidental route is where most delivery overruns originate. Not in the technology itself, but in the space between what the diagram implied and what the system actually required.
What the architecture actually consists of
If the diagram is the summary, the architecture itself is the set of significant decisions that shape the system, together with the reasoning behind them. Those decisions answer questions that matter to the business, not only to engineers.
Where will the data live, and what does POPIA require of that choice? A diagram can show a database. The architecture explains whether personal information is processed in South Africa, whether it is transferred across borders under section 72, and which safeguards make that lawful. For a medical scheme, a municipality or a bank, this is not a detail. It is the difference between a system that can go live and one that stalls at the information officer's desk.
How will the system behave when things go wrong? The architecture should state what happens during a power outage at the primary site, a fibre cut on a key route, or a third-party API that times out during month-end. South African systems carry resilience requirements that global reference architectures rarely anticipate, and the honest answer is often a trade-off rather than a guarantee. A retailer may accept that its loyalty platform degrades gracefully during an outage while its point-of-sale must continue offline. That choice should be written down and agreed, not discovered.
What will it cost to run, in rand, over time? A diagram does not show that a design depending heavily on cross-region data transfer will be exposed to dollar-denominated egress charges every month, or that a rand that weakens by fifteen percent quietly increases the operating budget by the same amount. Cost is an architectural property. It is determined by structural choices made early and is very expensive to change later.
Who will own and operate each part? An architecture that assumes a mature platform team, round-the-clock monitoring and automated deployment pipelines will fail in an organisation that has two infrastructure engineers and a managed service contract that ends in eighteen months. The operating model is part of the design, whether it appears on the page or not.
And what was considered and rejected? This is the part most often missing, and arguably the most valuable. Knowing that a team evaluated a fully managed SaaS option and rejected it because of a data residency constraint saves the next team from relitigating the same debate when a new vendor arrives with a compelling demo.
The decisions should be written down
The most practical tool for making architecture visible is unglamorous: a short, structured record for each significant decision. Many teams call these architecture decision records. Each one captures the context, the options considered, the choice made, the reasons, and the consequences the organisation is accepting as a result.
A decision record does not need to be long. Half a page is often enough. What matters is that it exists, that it is dated, that it names who made the call, and that it is stored somewhere the delivery team and future maintainers will actually find it. A folder of twenty well-written decision records will tell a new architect more about a system than the most polished diagram ever drawn.
This discipline also changes the quality of governance conversations. When an executive asks why the project needs a second availability zone, the answer is no longer "best practice" or "the vendor recommended it". It is a specific record explaining the outage risk, the cost of mitigation and the business impact of downtime, which leadership can either accept or challenge on its merits. That is a far healthier conversation than one where the architect defends a picture.
For public sector and state-owned entities, decision records carry an additional benefit. They create an audit trail that survives changes in leadership, service providers and political priorities. When an Auditor-General finding asks why a particular platform was chosen, or when a new administration inherits a half-built system, documented reasoning protects the officials who made sound decisions and exposes the ones that were never properly made.
Where this goes wrong in procurement
South African procurement processes unintentionally reward diagram-first architecture. Tender evaluation criteria often score the presence of a solution architecture, sometimes the number of pages, but rarely the quality of the reasoning. A bidder who submits an impressive set of layered diagrams will often outscore one who submits fewer visuals but a rigorous explanation of trade-offs, risks and assumptions.
The consequence is predictable. Suppliers optimise for what is scored, contracts are awarded on the strength of the picture, and the real architecture work is either deferred to a "detailed design phase" that eats into delivery time or quietly absorbed by the delivery team without adequate budget. B-BBEE-compliant SMMEs bidding into these processes are particularly exposed, because they often lack the margin to absorb unpriced design work that larger firms can cover from overhead.
Buyers can correct this without making tenders more onerous. Asking bidders to identify the five most significant architectural decisions in their proposal, the alternatives they rejected and the risks they are carrying is a better test of competence than requesting a target-state diagram. It also gives evaluation committees something concrete to compare across bids, and it reveals early which suppliers have genuinely understood the problem.
There is an honest limitation here. Not every tender evaluator has the technical depth to assess the quality of a decision record, and that is a capability gap that procurement reform alone will not close. Where the buyer lacks internal architecture capacity, an independent technical reviewer during evaluation is usually money well spent relative to the cost of a failed implementation.
What to ask of your architects
If you are a business leader commissioning architecture work, whether from an internal team, a consultancy or a vendor, a few questions will quickly reveal whether you are receiving an architecture or only its illustration.
Ask which decisions have been made and which are still open. A credible architect will be able to list both, and will be comfortable admitting uncertainty where it exists. Ask what the design assumes about your organisation's skills, budget and operating capacity, and whether those assumptions are true. Ask what it will cost to run in its third year, not only to build. Ask how the design handles a power or connectivity failure in your actual environment, rather than in a generic one. Ask where personal information flows and who has confirmed that this is compliant. And ask what the team considered and decided against.
None of these questions require technical expertise to pose. They require only a willingness to look past the picture. The answers, or the absence of answers, will tell you more about the likely success of the programme than the diagram ever could.
Keep the diagram, change what it represents
This is not an argument for abandoning diagrams. They remain essential for communication, onboarding and alignment. The shift is in how they are treated: as views onto a body of documented decisions, rather than as the decisions themselves. A diagram should be traceable back to the reasoning that produced it. When the reasoning changes, the diagram should change with it, and the record should show why.
Organisations that make this shift tend to see fewer surprises in delivery, more productive conversations with vendors, and systems that are easier to hand over, support and evolve. They also tend to spend less, because the expensive mistakes in technology programmes are rarely made in code. They are made in decisions that nobody realised they were making.
How CloudNala can help
CloudNala works with South African enterprises, public sector bodies and growing businesses to turn architecture diagrams into documented, defensible decisions that delivery teams can build and operate. If your next programme needs an architecture that will survive contact with reality, get in touch.
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