Software architecture: what it is and which decisions belong to it

A project is made of hundreds of decisions: what to call a function, which date library to use, where to store data, how applications talk to each other. Most of them can be revisited in an hour. A few cannot: changing the database, splitting the application into services or switching the sign-in mechanism touches all the code and all the data. Those are the decisions we call architecture.

In his column "Who Needs an Architect?" (IEEE Software, 2003), Martin Fowler discusses two definitions by Ralph Johnson. First: architecture is the shared understanding that the expert developers have of the system design. Second: it is the decisions you wish you could get right early in a project. People want to get them right early because they perceive them as hard to change — hence the working definition "things that people perceive as hard to change" and Fowler's conclusion: architecture is about the important stuff, whatever that is.

Michael Nygard gave a practical filter in his 2011 article on ADRs: architecturally significant decisions are those that affect the structure, non-functional characteristics, dependencies, interfaces or construction techniques of a system.

Functional requirements say what the system does: a client books a stylist, an admin moves a booking. Quality attributes — also called non-functional requirements — say how it does it: how reliably, securely, quickly and at what cost. Architecture mostly answers these: the same "book a slot" feature can be built a dozen ways with different properties.

A handy frame is the five pillars of Microsoft's Azure Well-Architected Framework: reliability, security, cost optimization, operational excellence and performance efficiency. It was written for the cloud, but its questions fit any system. We add a sixth attribute — changeability, i.e. how much a change costs. Fowler stresses that high internal quality speeds up feature delivery rather than slowing it down: there is less cruft getting in the way of understanding the code.

Quality attributes conflict: improving one almost always costs you another. The Well-Architected Framework has a separate trade-offs page for every pillar. A few examples from the performance section:

• A cache speeds up responses, but the longer a copy lives, the more likely it reflects a stale state: a cached authorization decision may keep letting in a user who has already been disabled
• Components added for speed — a message bus, a load balancer, a cache — enlarge the attack surface and the cost, and must be made reliable themselves
• Sharding and denormalization speed up work with large datasets but complicate consistency and routine operations such as backups
• Packing several applications densely onto one platform saves resources but widens the blast radius of a failure

That is why "this is better" sounds suspicious in architecture. The working wording is "for our load and our team we choose X for the sake of attribute A and accept cost B". That is exactly what goes into an ADR, covered below.

A module is a part of the system with one area of responsibility and an explicit public interface. A module boundary answers the question of what the outside world may use and what is internal. For the booking service, natural modules match the business language: Bookings, Schedule, Notifications, Payments.

A boundary does not have to be a network boundary. Modules can live in one application — a modular monolith — or be separate services. In his "MonolithFirst" note, Fowler writes that almost all successful microservice stories started with a monolith that grew too big and was broken up, and that even experienced architects find it hard to get boundaries right at the start. Hence the order: boundaries inside the code first, network boundaries later if there is a reason.

Inside a backend module the code is usually split into layers as well: a controller handles HTTP, a service holds business rules, a repository works with the database. That is the next zoom level, covered in the lesson on backend application layers.

You need to be able to show the architecture: to a new developer, to a client, to yourself six months later. Simon Brown's C4 model draws a system like a map with zoom levels — four levels from the big picture down to code. The model is notation- and tooling-independent: a whiteboard works as well as any diagramming tool.

c4model.com recommends system context and container diagrams for all teams. It suggests drawing component diagrams only if they add value, and generating them automatically for long-lived documentation. It does not recommend code diagrams for long-lived documentation because IDEs generate them on demand. Let us start with the context of the booking service.

The container level zooms into the online booking service: which runnable parts it consists of and how they communicate.

A diagram shows what was built but not why. A year later a new developer sees the monolith and asks why it is not microservices. Michael Nygard described two bad outcomes: blindly accepting an old decision without understanding it, or blindly changing it and breaking whatever it was made for. His answer is the Architecture Decision Record (ADR), a short record of one architectural decision and its reasons.

ADRs live in the repository next to the code, in Markdown, numbered sequentially; numbers are never reused. Length: one or two pages — in Nygard's words, nobody ever reads large documents, and large documents are never kept up to date. The format has five parts.

# ADR NNNN: Short noun phrase describing the decision

## Context

The forces at play: requirements, constraints, deadlines, team, load.
Facts only, value-neutral. Which options were considered.

## Decision

What we are doing. Full sentences in active voice: "We will…".

## Status

Proposed | Accepted | Deprecated | Superseded by ADR NNNN

## Consequences

What becomes easier and what becomes harder after the decision.
All consequences, not just the positive ones.

# ADR 0002: Modular monolith for the booking service

## Context

An online booking service for salons: a client picks a service, a stylist
and a time slot, the admin sees the schedule, and the client gets a Telegram
reminder. The team is three developers shipping once a week. The Bookings,
Schedule, Notifications and Payments modules are identified, but their
boundaries have been tested with a single salon only. A booking must not be
lost when Telegram is unavailable.

## Decision

We will deploy the backend as one Node.js application with one PostgreSQL
database; the Next.js web front end remains a separate application.
Each module lives in its own folder, owns its own tables and exposes
only a public interface to other modules. A linter rule in CI forbids imports
of another module's internal files. Reminders are sent by a background job:
the booking is saved to the database immediately, and sending is retried
when Telegram fails.

## Status

Accepted, 2026-10-11. Supersedes ADR 0001 "Separate notification service".

## Consequences

One build and one deployment: monitoring, rollback and local runs are simpler.
Creating a booking and reserving a slot stay in one database transaction.

Modules cannot be scaled or released independently: a fix in Payments
requires releasing the whole application. Boundaries rely on discipline and
import checks; without them the monolith turns into a "big ball of mud".

If a module needs its own scaling or a separate team, we will extract it into
a service and record that in a new ADR that supersedes this one.

Nygard's template is not the only one. The adr.github.io catalogue and Joel Parker Henderson's repository collect others: MADR with an explicit list of considered options and their pros and cons, Y-statements — a decision in one structured sentence, and the detailed Tyree and Akerman template. Consistency matters more than the template. You do not need an ADR for every decision: a temporary workaround, a prototype or an experiment with limited risk and cost does not need one.

Architecture is not approved once and for all. Fowler quotes an email from Johnson: there is no theoretical reason that anything is hard to change about software. Any one aspect can be made easy to change, but that makes the overall system a little more complex, and making everything easy to change makes the entire system very complex — and complexity is what makes software hard to change. So, in Fowler's view, one of an architect's most important tasks is to remove irreversibility where it is expensive — not to make everything flexible.

• Defer expensive decisions until you have enough information, but no longer: "we'll figure it out later" is a decision too, and worth recording
• Hide what is likely to change behind your own interface: the payment provider, the notification channel, file storage
• Revisit an ADR when the conditions in its Context change: the team or the load grew, a regulator added a requirement
• Update the context and container diagrams together with the code — they change rarely, so keeping them current is cheap

Next in this direction: the principles used to draw boundaries inside the code — SOLID — and then the design patterns that implement those boundaries in practice.