Why Your Solution Architecture Document Keeps Getting Sent Back

We see a lot of solution architecture documents (SADs) rejected at the Architecture Review Board (ARB) because the reviewers can't tell what they are being asked to decide.

The board is asking a different question

A SAD is usually written to answer one question: what did we design? The ARB is asking another: should we let this happen?

That gap explains most of the pain. The author spends weeks making the description complete. The reviewers, who are senior, time-poor and reading many of these, are hunting for something else. They want to know what is being decided, what it costs, what could go wrong, and whether the design sits inside the organisation's standards. When the document can't answer those quickly, it gets sent back with comments that feel pedantic, and the author spends another fortnight polishing a document that was never going to pass.

The formal frameworks are clear about the purpose of a review. The TOGAF compliance process exists to catch errors early, when they are cheap to fix, and to test a project against the enterprise's standards. It also expects the review to surface places where the standards themselves need to change. That is a risk-and-fit exercise, not a proofreading exercise. The review ends with findings presented and signed off by the board and the customer. Your document has to make that sign-off easy.

Six ways a SAD fails review

These patterns come up repeatedly, and they tend to travel together.

1. It describes the design but never asks for a decision. The reader reaches page 30 and still doesn't know whether the board is being asked to approve a direction, accept a risk, grant an exception or simply note progress. A SAD should say what it needs on the first page.

2. Length is standing in for rigour. Authors worry that a thin document looks careless, so they add. One solution architect has described a design document that went through review three times without approval, growing each round until it was finally rejected for being too long and wordy. Practitioners who write about why TOGAF fails in organisations describe the same instinct at larger scale: architecture descriptions of a hundred pages that are out of date before anyone finishes them. A long document gives reviewers more places to disagree, and fewer reasons to trust that you know which parts matter.

3. It is written after the design is locked. If the SAD is a record of decisions already made and funded, the board has nothing left to influence. Reviewers sense this and push back on process instead, because the substance is out of reach. A SAD that arrives while options are still open gets better questions.

4. Only the chosen option appears. Reviewers will invent the alternatives in the meeting if you don't show them. Then you are defending a design against options you have never costed, in real time, in front of the people who sign off.

5. The non-functional requirements are adjectives. "Highly available", "scalable" and "secure" cannot be tested, so they cannot be approved. A board can approve a recovery time objective, a peak load and a data classification. It cannot approve a mood.

6. Risks, assumptions and dependencies are generic or ownerless. A risk register with "resource constraints" at the top and no names beside any item tells the board nothing about where the plan is fragile. The first question in the room will be the one the register should have answered.

There is also a structural cause that no document can fully fix. Boards that meet monthly, attract too many opinions and focus on ceremony rather than real technical and business risk push teams to design for the board instead of for users. If your reviews feel adversarial, check the process before you rewrite the template.

What a decision-grade SAD contains

A decision-grade SAD opens with the decision, not the design. Everything after the first page exists to let a sceptical reader check that decision.

The easiest way to structure it is to take the questions a board will ask and make sure each one has a home. If a question has no home, it will be asked live.

Two practical points sit behind that table.

First, put the detail in appendices and keep the body short enough to read in one sitting. The aim is not a thin document. It is a document where the reader can stop after the summary and still know what they are approving, then go deeper only where they doubt you.

Second, match the depth of review to the size of the change. Writers on TOGAF adoption suggest reserving full board review for significant changes that cut across several domains. Smaller, lower-risk changes can go through asynchronous review with required comments, with live sessions saved for high-risk work and run from a clear pre-read. If every SAD gets the same treatment, the board becomes the bottleneck and teams start routing around it.

Keep the diagrams few and the decisions visible

Two habits make the biggest difference to how a SAD reads: a small, consistent set of diagrams, and decisions recorded as decisions rather than buried in prose.

Diagrams. The C4 model, created by Simon Brown, gives you four zoom levels: system context, containers, components and code. Boards rarely need more than the first two. A context diagram shows your system, its users and the other systems it touches. A container diagram shows the separately deployable pieces and the major technology choices.

Component diagrams are worth including only where a particular container is hard to understand, and code-level diagrams are usually better generated from the code than drawn by hand. One point trips up newcomers: in C4 a container is anything that holds code or data and can be deployed, not a Docker container.

Whatever notation you use, add a legend and make sure each diagram has a stated audience. A diagram that works for engineers and confuses the board is not doing its job in a SAD.

Decisions. Michael Nygard popularised architecture decision records in 2011 as short documents that capture one significant decision, with its context and consequences. He defined an architecturally significant decision as one affecting "the structure, non-functional characteristics, dependencies, interfaces, or construction techniques" of the system.

His template is deliberately small: a title, a status, the context, the decision and the consequences, usually within a page or two. Variants such as the Markdown-based MADR add fields for options considered, and the Y-statement compresses a decision into a single sentence of context, concern, choice, quality sought and downside accepted.

The format matters less than the habit. For a SAD, summarise each key decision in the options section and link to its full record. That gives the board a short path to the reasoning, and it gives the delivery team a trail they can still read after the project has moved on. The status field earns its keep here: a decision marked as superseded tells later readers the design has moved, which is exactly the failure that makes old architecture documents untrustworthy.

If you work in Australian government

Public sector reviews add a second audience. The Digital Transformation Agency maintains the Australian Government Architecture, a body of strategies, policies, standards and designs meant to encourage reuse and consistent investment across agencies.

It is built into the Digital and ICT Investment Oversight Framework, the six-stage framework the government uses to manage digital investments across their lifecycle, and the DTA positions it as a decision-making aid for those investments. The DTA also advises agencies preparing new proposals to contact it early.

The practical consequence for a SAD is that alignment cannot be left for the reviewer to infer. If your solution goes to an agency board or supports an investment proposal, show which Australian Government Architecture guidance applies, where you comply, where you reuse an existing platform and where you deviate. A deviation with a reason is a discussion. A deviation the reviewer discovers is a finding.

The same logic holds in any regulated Australian sector: map the design to the obligations that govern it in a table the reviewer can tick through, rather than scattering references across forty pages.

Before you submit

Run the document past this list. If you can't tick an item, you have found the question the board will ask first.

• ☐ The first page states what decision is needed, by when, and who makes it.
• ☐ A reader can stop after page one and still know what they are approving.
• ☐ The document reaches the board while options are still open, not after the design is locked and funded.
• ☐ Two or three options are shown, with the criteria used and the reasons for rejection.
• ☐ Every non-functional requirement has a number and a way to verify it.
• ☐ Every principle or standard is marked comply or deviate, and each deviation is an explicit exception request.
• ☐ Every risk, assumption and dependency has a named owner.
• ☐ Each diagram has a legend and a stated audience.
• ☐ Key decisions link to short records with a status.
• ☐ Cutover and rollback are described, with go/no-go criteria.
• ☐ The body can be read in one sitting; detail sits in appendices.

A SAD that passes review is not the longest or the most polished one. It is the one that makes a sound decision easy to take and a poor one hard to hide. Write for the person who has to sign it, and the document usually takes care of the rest.

Sources

• TOGAF Standard: Architecture Compliance, The Open Group
• No more Architecture Review Boards, please?, Bo Vincent Thomsen
• Why TOGAF fails in organizations (and how to fix it), NILUS
• Why most architecture review boards suck, Trilogy AI
• How to run effective architecture reviews, Ledwith
• The Art and Science of Architectural Decision-Making, Tech World With Milan
• Lightweight Architecture Documentation with ADRs, production-ready.de
• ADR templates, adr.github.io
• The C4 model, Simon Brown
• The C4 Model for Software Architecture, InfoQ
• Australian Government Architecture, Digital Transformation Agency
• About the AGA, Digital Transformation Agency
• AGA and new investments, Digital Transformation Agency