Architecture decisions


Use this template to write better architecture decisions. The help text can be deleted of course.

Documenting architecture is crucial for improving speed of acceptance, understanding and maintenance of your architecture deliverable. Architecture decisions are NO principles or requirements. Most of the time architecture decision arise when principles and/or requirements are conflicting. Also architecture decisions can be needed due to a specific context constrains as speed of delivery ( project deadline) or cost.

By documenting architecture decisions in a structured way relevant stakeholders are able to better review, discuss and give input to the architecture document. Also by keeping an architecture decision log direct input can be given to solve architecture debt in future.

Architecture decisions SHOULD outline all decisions that have significant impact on the final solution in terms of flexibility, cost, speed of delivery, operations and always mention decisions that are rise by conflicting principles or requirements.

The architecture decision SHOULD be a very brief summary. Extensive discussion regarding one specific architecture decision SHOULD be worked out in a workshop and documented in an separate architecture deliverable (e.g. separate memo). An architecture decision COULD consist of the following minimal items:

  • Summary of decision

  • Context which describes the problem where this decision is needed for

  • Alternatives evaluated

  • Consequences




Decision made

Clear statement of the decision


Identification of the problem.

Alternatives evaluated

Brief summary of alternatives considered.


Consequence of this decision