Architecture is often presented as a diagram: boxes, arrows, services, data stores, and deployment boundaries. The diagram matters, but it is only the visible residue of earlier choices. The architecture itself is the sequence of decisions that produced those boundaries—and the constraints those decisions place on the next team.
A useful architecture practice therefore does not begin with “What is the ideal target state?” It begins with better questions: What problem are we solving now? Which qualities matter most? What evidence supports this choice? How expensive will it be to reverse? What must we observe after deployment? A decision becomes architectural when its consequences extend beyond the change that introduced it.
Preserve the reasoning, not just the result
Most repositories explain what the system does. Far fewer explain why it does it that way. Six months later, an intentional constraint can look like accidental complexity, while an old workaround can be mistaken for a permanent requirement.
An Architecture Decision Record, or ADR, is a compact way to preserve that reasoning. AWS Prescriptive Guidance recommends recording at least the context, decision, and consequences. It also treats accepted ADRs as immutable history: when evidence changes, a new record supersedes the old one instead of rewriting the past.
That distinction is important. Architecture evolves through new information. Editing an old decision until it appears universally correct destroys the evidence that helps a team understand how the system arrived at its current shape.
GitHub describes a practical version of this approach in its account of adopting ADRs in the mobile team . The records covered iOS, Android, and decisions shared by both clients. Their value was not ceremonial documentation; it was asynchronous context for current colleagues, future maintainers, and the original author returning months later.
As a team grows, preserving context becomes increasingly valuable because the number of possible direct communication paths grows much faster than headcount.
A short decision record cannot replace conversation, but it prevents every architectural question from requiring the same conversation again.
Match the process to the cost of reversal
Not every decision deserves the same ceremony. Amazon’s original description of one-way and two-way door decisions offers a useful classification.
A one-way-door decision is difficult or prohibitively expensive to reverse: publishing a contract used by external customers, selecting a data partitioning model at large scale, or committing to a regulatory boundary. These choices deserve broader consultation, stronger evidence, and explicit migration planning.
A two-way-door decision is recoverable: enabling a feature for a small cohort, choosing an internal library behind an interface, or testing a new read path while retaining the old one. These decisions should usually be made locally and quickly, provided that the team has built a real exit.
Before escalating a decision, ask:
- Can we restore the previous state without losing data?
- Can the change be isolated behind an interface, route, or feature flag?
- How quickly would we detect a bad outcome?
- Who has the authority and operational access to reverse it?
- Does another team or customer depend on the new contract?
- What is the maximum credible blast radius?
“Reversible” is not a feeling. It is an engineered property supported by compatibility, observability, controlled exposure, and a tested rollback path.
A lightweight ADR can make those properties explicit:
# ADR-014: Introduce the new pricing path
Status: Accepted
Context: The legacy implementation limits experimentation.
Decision: Route one internal cohort through the new service.
Consequences: Temporary dual operation and extra monitoring.
Evidence: Error rate, latency, and pricing-difference reports.
Rollback: Disable the route flag; no new data format is persisted.
Revisit when: The new path handles 25% of eligible traffic safely.AWS provides a more complete official ADR example , but the document should remain proportional to the decision. A concise record that the team reads is more valuable than an exhaustive template that everyone avoids.
Turn important decisions into feedback loops
A decision is incomplete if the team cannot tell whether it is working. This is where evolutionary architecture differs from unmanaged accumulation.
Martin Fowler’s introduction to Building Evolutionary Architectures describes small changes and feedback loops as central to the approach. Architectural fitness functions turn desired qualities into checks: dependency rules, latency thresholds, recovery tests, schema-compatibility checks, security policies, or cost limits.
For example, “services should be independently deployable” is an aspiration. A stronger decision defines observable evidence:
- A service can be deployed without coordinating releases with its consumers.
- Contract tests run before deployment.
- The previous version can be restored within the agreed recovery time.
- Database changes remain compatible during the rollout window.
- Failure of the new component does not silently corrupt shared state.
The goal is not to freeze the architecture. It is to detect when reality has invalidated an assumption.
Modernise through seams, not a single leap
Large replacements are often framed as one monumental architectural decision: approve the target, build it, and switch everything over. The hidden problem is that learning arrives throughout the work, while value and risk remain concentrated at the end.
Martin Fowler’s canonical explanation of the Strangler Fig approach proposes gradual displacement instead. A team identifies a seam, moves a bounded capability, observes the result, and then chooses the next boundary with better information.
The sequence may look like this:
- State the business outcome, not merely the desired technology.
- Introduce a routing, API, or event seam around one capability.
- Send a small, observable slice of work through the new path.
- Compare behaviour and operational qualities.
- Increase exposure or reverse the change.
- Remove the old capability only after the evidence supports it.
This sometimes requires temporary components. Fowler’s more detailed Transitional Architecture case describes routers, adapters, and compatibility mechanisms that allowed old and new components to coexist. In the example, traffic was progressively moved until the new path handled 100% before the legacy middleware was decommissioned.
Temporary architecture is not automatically waste. It can purchase earlier value, smaller failure domains, and safer learning. The important decision is to define its removal condition when it is introduced.
A good decision creates the next option
The strongest architecture is not the one that predicts every future requirement. It is the one that makes consequential choices deliberately, preserves their context, validates their assumptions, and leaves affordable paths forward.
For each significant decision, record five things: the present constraint, the chosen trade-off, the evidence to watch, the reversal mechanism, and the trigger for reconsideration. Then keep the decision close to the code and operations it governs.
Architecture becomes easier to lead when it stops being a periodic attempt to declare the final design. It becomes a disciplined sequence: decide, expose assumptions, deliver a small change, observe reality, and decide again.