There is a diagram that appears in a great many technical proposals. It fills a whole page. It has forty cloud service icons, arrows running in every direction and labels too small to read when printed. It is meant to show that the bidder has thought of everything.
What it usually shows is that nobody decided who the diagram was for.
A chief financial officer looking at that page cannot find the outcome. A security officer cannot find where customer data crosses a boundary. An operations manager cannot find who gets called at 2am. Each of them needed a different picture, and none of them got one.
This part of the series is about building an architecture pack instead: a small set of views, each designed to answer one question for one audience. We continue with Ridgeline Digital’s bid for Rivermark Water’s customer self-service and case management platform. Both organisations are fictional, and all figures are illustrative.
Why one diagram is never enough
Think about the drawings for a house. The buyer wants a floor plan: where the rooms are and how you move between them. The electrician needs the wiring layout. The plumber needs the pipe runs. The municipality needs the site plan and elevations. Nobody expects one drawing to serve all of them, and a drawing that tried would be useless to everyone.
Architecture is the same. A useful architecture pack contains several views, and each one is built for a particular decision and audience. One warning matters: repeating the same boxes at different zoom levels does not create several views. A true second view answers a different question, not the same question in more detail.
The layers of an architecture
Before choosing views, it helps to know what an architecture is made of. It helps to think in nine layers. Here they are with the question each one answers, and what that question looks like at Rivermark.
| Layer | Question | At Rivermark |
|---|---|---|
| Motivation and strategy | Why is change required and what outcomes or principles govern it? | Faster fault handling and self-service before the 1 July tariff change |
| Business | Which capabilities, actors, journeys, processes and decisions change? | Fault reporting, billing queries, complaints and the agent’s working day |
| Information and data | What information exists, who owns it and how does it move or change? | Customer accounts stay owned by billing; cases are owned by the new platform |
| Application | Which application responsibilities deliver the capabilities? | Case management, portal, agent console, notifications |
| Integration | How do systems exchange requests, events, files and data? | Read-only billing views, the field job app’s API, WhatsApp and SMS |
| Technology and platform | Which runtime, network, storage, data and platform services support the applications? | A public cloud region in South Africa, across two availability zones |
| Security and trust | Where are identities, trust boundaries, threats, controls and evidence? | Customer sign-in by account number and one-time PIN; staff sign-in through the existing identity platform |
| Operations | Who owns, observes, supports, changes and recovers the service? | Ridgeline runs the managed service; Rivermark owns business policy and priorities |
| Delivery and transition | How does the organisation move through safe intermediate states? | Three stages that retire the old tools one at a time |
The layers are separate for clarity, but they are not independent. A single constraint can travel through several of them. At Rivermark, the RFP’s requirement to host in South Africa affects the technology layer (which region), the integration layer (where the WhatsApp provider processes messages), operations (where support staff access data from), recovery (no failover to another continent) and, in the end, price. A good pack shows that ripple instead of hiding it in one layer.
A purposeful set of views
A purposeful pack draws from a set of nine views, each with a clear purpose and a primary audience.
| View | Purpose | Primary audience |
|---|---|---|
| Executive reference | Outcome, actors, solution responsibilities and value on one page | Executives and procurement |
| Business process or journey | Changed work, decisions, exceptions and human steps | Business owners and users |
| System context | Solution boundary, users and external dependencies | All evaluators |
| Solution overview | Major functional components and responsibilities | Business and technical evaluators |
| Integration and data flow | Interfaces, direction, pattern and important data | Integration, data and security |
| Production deployment | Regions, zones, networks, runtimes, stores and services | Technical and operations |
| Security and trust | Identities, boundaries, control points and sensitive flows | Security, risk and privacy |
| Operating model | Ownership, support, monitoring, escalation and change | Operations and service owners |
| Transition roadmap | As-is, bridge states, dependencies and target sequence | Sponsors, architects and delivery |
A system context view, which is the one view almost every bid needs, simply draws a line around the solution and shows who and what sits outside it: customers, agents, field teams, the billing system, the field job app, the messaging providers. It is often the most useful diagram in the whole document, precisely because it is simple.
Ridgeline’s pack for Rivermark uses all nine, but not all in the same place. The evaluation panel described in the briefing session was mostly business, operations and procurement people, with one IT manager and one security officer. So the detailed production deployment view went to an appendix, where the technical evaluator could find it, and the main body led with the views that the majority of scorers needed.
What to emphasise for different kinds of client
The same view set is weighted differently depending on who is buying. The pattern looks like this.
| Client | Emphasise | Avoid |
|---|---|---|
| Startup or product company | User flow, system context, MVP, scaling path, delivery and cash burn | Enterprise governance theatre |
| SME modernisation | Current pain, pragmatic target, migration, support and predictable cost | A target requiring skills the client lacks |
| Government | Traceability, accessibility, security, data, governance and skills transfer | Unverified savings and vague innovation |
| Bank or regulated entity | Accountability, lineage, trust, resilience, segregation, audit and third-party risk | Treating a provider’s certification as the client’s compliance |
| Healthcare | Patient or member journey, privacy, consent, human decisions and availability | Hiding safety decisions inside a technical flow |
| Data and AI | Use-case value, data readiness, evaluation, human oversight, operations and cost | One accuracy percentage or a model catalogue |
| Legacy transformation | Dependencies, seams, coexistence, migration waves, reconciliation and retirement | A big-bang target without bridge states |
Rivermark sits across two rows. As a public-facing utility it cares about traceability, accessibility and skills transfer, much like a government client. As a legacy transformation it needs coexistence with the billing system and a credible retirement plan for the old ticketing tool. Ridgeline’s emphasis follows both.
One entry deserves a plain explanation. When a cloud provider holds a security certification, that certifies the provider’s own controls. It does not mean the client’s service, configured and operated by a bidder, is compliant. Regulated clients notice immediately when a proposal blurs the two.
Progressive disclosure: build understanding in order
Progressive disclosure means revealing detail in the order a reader can absorb it. Start with the outcome and context, then who does what, then how work and data flow, then how it runs in production, and only then the implementation detail.
The test is simple: the first view should make the fifth easier to understand. If an evaluator meets the deployment diagram before they understand what a fault report is, the deployment diagram means nothing.
This also explains a comment Ridgeline heard at Rivermark’s briefing session, covered in Part 2: a previous bidder’s proposal had been “too technical”. That rarely means the solution needed less substance. It usually means the document opened with a wall of cloud icons, used the provider’s product names instead of the client’s words, or skipped the business context. The fix is order, not dilution.
Diagram discipline
A view is only useful if it can be read. These habits separate a readable architecture diagram from decoration, and each is worth applying literally:
- Give each diagram a question-shaped title. “How does a fault report reach a field team?” tells the reader what to look for. “Solution architecture v3” does not.
- State scope, environment and status. Is this production or test? Proposed or existing? Confirmed or provisional?
- Use client language for business capabilities. Rivermark says “fault”, “query” and “complaint”, so the diagrams do too.
- Separate existing, proposed, mandatory, optional and future elements. Ridgeline shades the existing billing system differently from the new platform, and marks the duplicate-matching feature and the chatbot as optional, each with its own price.
- Give arrows a defined meaning. Does an arrow mean “sends data to”, “calls”, or “depends on”? Say so in a legend.
- Show ownership and trust boundaries. Draw the line where Rivermark’s responsibility ends and a provider’s begins.
- Keep line crossings low and text readable when exported. Many evaluators print the document or read it on a laptop at normal zoom.
- Put detailed configuration in tables or designs, not tiny labels. Port numbers and service tiers do not belong on an executive view.
- Record unresolved decisions beside the view. “WhatsApp provider data location to be confirmed” next to the diagram is honest and helpful.
Choosing which artefacts a bid needs
Not every bid needs every artefact. This selection guide makes the choice practical.
| Artefact | Use when |
|---|---|
| Executive reference architecture | Almost every material solution bid |
| Capability map | Scope spans business functions or ownership |
| Journey or business flow | Process or experience drives value |
| System context | Almost every solution bid |
| As-is view | Existing constraints change delivery |
| Target solution | Responsibilities require explanation |
| Integration view | Several systems or partners exchange information |
| Data lifecycle or lineage | Data is sensitive, analytical or decision-critical |
| Security and trust view | Identity, data or external access matters |
| Deployment view | Runtime, region, resilience or networking matters |
| Operating model | Production, AI, platform or multi-party support |
| Transition roadmap | Legacy, phased funding or coexistence |
| Well-architected assessment | Production workload quality needs review |
| Cloud adoption plan | Adoption requires platform and organisation change |
| TOGAF-style roadmap | Change spans capabilities, domains and states |
For Rivermark, Ridgeline left out a full capability map, because the scope was one bounded service rather than a set of business functions, and kept a data lifecycle view because customer personal information moves between channels, the case platform and messaging providers. Part 6 covers the last three rows in more depth.
What to take from this part
Every view should answer one question for one audience. More detail on the same boxes is not a new view.
Layers are connected. One constraint, like hosting in South Africa, can change technology, integration, operations, recovery and price.
Weight the pack to the evaluation panel. Put what most scorers need in the main body and move deep technical detail to an appendix.
Disclose progressively. The first view should make every later view easier to read.
Next in the series: Components do not prove it works: flows, ownership and operations.
How CloudNala can help
We build architecture packs for bids and business cases: deciding which views a particular evaluation panel needs, drawing them in the client’s own language, and checking that each diagram has a clear question, a legend and a status. For teams that already have diagrams, a short review usually finds the views that are repeating each other and the question nobody has answered yet.
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.
Book a Bid Review or write to us at consult@cloudnala.co.za