Keep the reasoning behind an architecture decision

A document-conversion product chooses a hosted processing service. Six months later, an engineer proposes bringing conversion in-house. The original decision says “use the vendor,” but nobody can find the document restrictions, expected workload or exit costs that made that choice reasonable.

Architecture decision records are useful when they preserve enough context for a later team to reassess the choice. The record should let someone challenge the reasoning without having to reconstruct it from meeting invitations.

Record the constraint that made the choice difficult

In this fictional product, customers upload documents and receive a converted file. A hosted service reduces the amount of conversion software the team must operate. In-house processing offers different control over the execution environment but gives the team responsibility for capacity, maintenance and failure handling. Neither description proves that one option is cheaper or safer.

The decision needs evidence about the actual product. Which documents may leave the organisation's environment? Where can they be processed? What load and file sizes does the proposed design cover? Who can investigate a failed conversion? What happens to retained files and logs?

Write the answer as a dated assumption or an evidenced constraint, not as a timeless advantage of “build” or “buy.”

A compact record for a consequential choice

AWS's ADR process guidance describes recording context, the decision and its consequences. Accepted records remain available; a later decision can supersede one, and rejected alternatives retain their reasons. That preserves the history needed to understand a change.

For the conversion product, I would use a record with the following entries:

This is an author-proposed structure. Filling every cell does not validate the architecture. If the cost estimate excludes support work or the trial omits the largest supported file, the decision still rests on incomplete evidence.

Preserve the rejected option fairly

A weak record makes the losing option look foolish. A useful one explains when it might become preferable.

Suppose the team rejects in-house conversion because it has not established operating capacity for the proposed launch. The record should say that. “In-house does not scale” would be a much broader claim, unsupported by that finding. If capacity and staffing later change, the next team can reconsider the option without overturning a false universal rule.

Use the same workload boundary for both estimates. Identify whether pricing is a quote, a projection or measured usage. Keep commercial details in an appropriately restricted source, with a usable reference in the decision record.

Revisit the choice without rewriting its history

When the proposed document scope changes, assess whether the existing decision still applies. A new record should name the old one, the changed evidence, the alternatives now feasible and the authorized technical decision. Retain the former reasoning even when its conclusion is superseded.

Then connect the accepted change to implementation. Update affected interfaces, operational instructions and development handoff evidence. A new ADR marked accepted is not proof that production uses the new architecture.

This technical record answers why a particular design was chosen. It complements the product's boundaries and non-goals but does not replace programme spending authority or customer policy. The future engineer should be able to find the assumption that changed, not just the name of the person who approved the old option.