How architecture decisions actually get made

What architecture principles are (and aren't)

How to tell a principle from a rule, a goal, or a technology decision dressed up in fancier clothes.

Most teams have something they call principles. Half the time those are actually rules ("all data must be encrypted at rest"), goals ("reduce processing time by 50%"), or technology choices ("we use AWS"). None of those help you choose between two architectures when you're sat in a workshop on a Wednesday afternoon. A real principle points in a direction without specifying the destination. "Prefer open standards over proprietary protocols" tells you something useful. "Be excellent in everything we do" tells you nothing. The honest test isn't whether the principle sounds noble. It's whether you've ever used it to make a decision you wouldn't otherwise have made. If the answer is no, what you have is wallpaper.

A principle that never rules anything out isn't a principle. It's a slogan.

The Technology Code of Practice as architecture principles

How to use the TCoP as a working tool, not just something to satisfy at service assessment.

Architects usually meet the TCoP twice in their careers. Once when they join the civil service and somebody hands them the link. Once at service assessment, when the panel asks how their design aligns with it. Both encounters miss the point. The TCoP earns its keep when you apply it during decisions, not after them. The principles will sometimes be inconvenient. Cloud first can pull hard against an existing on premises estate. Share and reuse sounds great until you find that the existing component does eighty percent of what you need, and the remaining twenty percent would cost more to retrofit than it would to build fresh. Those tensions are the point of having principles in the first place. They force you to make a conscious choice rather than drifting into one.

The TCoP is most useful before assessment day, not on it.

Creating project level principles

Where the TCoP and departmental strategy stop, and your project's own design rules begin.

The TCoP and your departmental strategy give you the wide guardrails. They don't tell you whether to use serverless or containers, whether reference data should live in code or in configuration, or how to handle the legacy integration that nobody on the team wants to touch. That's what project principles are for. The mistake most teams make is writing them like a corporate values poster: seven or eight worthy statements, none of them specific enough to actually use. A good set of project principles answers questions that will come up during delivery, and each one rules something out. If your principles don't make at least a couple of plausible options harder to justify, they're decorative.

Good project principles answer questions that will come up during delivery. If they don't rule anything out, they're decorative.

Frameworks for making architecture decisions

Practical methods for getting from 'we should probably decide this' to a documented choice.

The framework you reach for says something about the decision you're facing. Weighted scoring is useful when you have several real options and need to defend the choice to people who weren't in the room. Cost, benefit and risk is the language programme boards already speak, so it's the right format when the audience holds the budget. The reversibility test is the most underused of the lot, because architects tend to apply the same depth of analysis to every decision regardless of how much it actually matters. Three days spent picking a logging library is wasted work. Three hours choosing your data persistence strategy probably isn't enough. Match the depth of analysis to the cost of being wrong.

Reversible decisions deserve quick judgement. Irreversible ones deserve careful thought. The skill is knowing which is which before you start.

Architecture Decision Records

A simple format for capturing why a decision was made, while the reasoning is still fresh.

Architects often start writing ADRs with enthusiasm and stop after the third one. The pattern is almost always the same. They start writing them retrospectively, the writing feels like homework, and then they stop. The fix is to write the ADR at the point of decision, while the alternatives are still live in your head and you can still remember why you ruled them out. The "alternatives considered" section is where the real value sits. It shows the decision was made consciously, and it gives whoever inherits the system a path back if circumstances change. The decision itself is often the least interesting part of the document. The thinking behind it is what matters.

The decision itself is often the least interesting part of an ADR. The thinking behind it is what matters.

Documenting decisions in government context

Why decision documentation in government has a slightly different job to do.

In a private sector team, decision documents mostly serve the people writing the code. In government, they also serve service assessors, the National Audit Office, departmental finance teams, and on occasion a select committee. That sounds like it raises the bar. In practice it lowers it. The audiences outside your delivery team don't want elegance or depth. They want clarity, honesty, and a clean line from principle to decision. A short ADR written in plain English will satisfy a service assessor faster than a solution design document that runs to a hundred pages and that nobody actually reads. Write for the person who joined the team last week and needs to understand why you did what you did.

If a programme board member can't follow your decision document, the document isn't finished.

When principles conflict

How to handle a tradeoff honestly when two good principles pull in different directions.

This is the part of the job that no training course really prepares you for. Principles in tension is the normal case. The situations where every principle points the same way are the easy ones, and they're rare. What makes a conflict feel difficult is usually the pressure to pretend it doesn't exist. A team will quietly compromise on simplicity to chase reusability, or quietly trade off security to ship faster, and nobody says so out loud. The fix is to name the tension. State which principles are pulling against each other, decide which one carries more weight in this particular situation, and write down why. The act of naming the conflict is what turns a quiet compromise into a defensible choice.

A documented tradeoff is a decision. An undocumented one is just a problem nobody noticed yet.

Building a culture around decisions

How individual good decisions become consistent good decisions across a team and a delivery.

One architect making good decisions matters less than a team where good decisions are the default. Most of what goes wrong in architecture practice isn't a single bad call. It's a slow accumulation of small decisions that nobody quite owned, nobody quite documented, and nobody can now explain. The cultural failures look mundane. Decisions get delayed because nobody wants to be wrong on the record. Defaults set in because the absence of a decision becomes the decision. Challenge gets read as criticism, so the people who notice problems stop raising them. An architect's job runs beyond making the right calls. You also have to set the tempo, make documentation routine, and make it safe for people to disagree out loud.

A strong culture around decisions is what makes good architecture survive a change of team.