Software architecture, and the decision record

What the word actually names

Software architecture is the structure of a system's components, the externally visible properties of those components, and the relationships among them. All three phrases carry weight, and an answer that drops one of them loses marks.

Structure is how the system is divided and how the pieces are arranged — not what any one piece computes inside itself. Externally visible properties are the characteristics another component must know in order to interact: the interface offered, the data consumed and produced, the timing and failure behaviour it promises. Internal properties — the algorithm a component uses, the data structure it keeps — are deliberately not specified at this level, and that omission is the whole point: it is what keeps the architecture small enough to argue about. Relationships range from one component calling another, through a shared database access protocol, to an event channel nobody owns.

One more clause matters: an architecture is a representation, not the operational software. It stands to the running system as a floor plan stands to a building. Say this in an exam answer; "the big picture" is the phrase that marks you down.

Why it is worth doing before the code

Three reasons, and they are separable. First, the architecture is the earliest artefact that can be analysed — you can hold it against the requirements and ask whether it can possibly meet them, at a stage where changing your mind costs a conversation rather than a rewrite. Second, it highlights the decisions with the longest reach: a handful of early choices constrain every downstream design action, and naming them explicitly is how you stop them being made by accident. Third, it is a small model — small enough for one person to hold whole, which is what makes it usable as the shared language between people who otherwise share nothing.

A description is a set of views, not a diagram

Different stakeholders come to the same architecture with different concerns, so an architectural description is a set of work products, each a view answering one group's questions. A developer reads the architecture as a blueprint to build from. A project manager reads it as a set of decisions that commit people and budget. A maintainer reads it as the record of why the system is shaped this way. IEEE-Std-42010 exists to codify exactly this — viewpoints, frameworks and description languages — because one diagram cannot serve four audiences.

Agility does not exempt you. The agile answer to "where is your architecture?" is a walking skeleton: a thin end-to-end implementation that carries the highest-priority functional requirement through every layer and exercises the hardest quality attribute, built in the first iterations and grown from there.

Recording the decision, not just the diagram

A diagram shows what you chose; it never shows what you rejected or why, and six months later that is the only thing anybody needs. The architecture decision description template fixes eight fields: the design issue, the resolution, the category it falls in, the assumptions and constraints that shaped it, the alternatives considered and why they lost, the argument for the resolution, and the implications you are accepting. An agile team's lightweight architectural decision record (ADR) compresses that to a title, a context, the decision, its status and its consequences.

Worked example — BorrowBox's first architectural decision

BorrowBox is a neighbourhood tool library: members reserve a power tool in an app, collect it from a smart locker bank with a one-time code, and return it to any locker. Its first architectural decision is how does a phone open a locker door?

• Issue. The door must open within three seconds of a valid scan, on street furniture with intermittent connectivity.
• Resolution. The phone never talks to the locker. It presents a short-lived signed token; the locker controller validates the signature offline against a rotating key it already holds.
• Alternatives. Direct phone-to-locker Bluetooth pairing — rejected, because it leaves no server-side audit trail of who opened which door. Server-pushes-open — rejected, because the cabinet is offline often enough that the three-second budget would be missed.
• Implications. You have just committed to a key-distribution component and to clock discipline on every controller. Neither existed in the requirements model.

Notice what the architecture fixes and what it leaves open. It fixes that the gateway's externally visible contract is "given a signed token under ninety seconds old, open door N and answer within three seconds". It says nothing about how the gateway is built. Everything downstream — where fee logic lives, whether the app works offline, how you test a door standing on a public street — follows from that one sentence.