arc42 section 9: Architecture Decisions

Important, expensive, risky decisions with rationale

• Storage choices such as partitioning and tablespaces are documented. → Physical Data Model
• Temporary transition components are identified, and a plan exists to remove them once the target is reached. → AS-IS and TO-BE View
• The business context shows the system as a black box apart from its communication partners. → Architecture Canvas
• The document covers what cannot be read from the code. → Motivation for Architecture Documentation
• Documents are built and published by a toolchain, not assembled by hand. → Self-Documentation
• Each entry in section 9 states the decision together with its rationale. → arc42 Architecture Decisions
• Decisions in section 4 are short but give reasons. → arc42 Architecture Decisions
• Business, data, and technology architecture are described as separate levels. → Common Features of Architecture Frameworks
• Topics near the peak are treated with caution, since publicity there can create unrealistic expectations. → Gartner Hype Cycle for Enterprise Architecture
• Responsibility for concerns that affect several applications is assigned between EA and the application. → Relationship between Enterprise Architecture and Application Architecture
• Reference models, if used, are named and their constraining role on design is clear. → TOGAF
• The document shows that data architecture and application architecture are developed together in Phase C. → TOGAF Architecture Development Method
• Conflicting stakeholder quality requirements, such as performance versus security, are named as a reason for the evaluation. → ATAM Application Phases
• Each documented non-risk names a quality attribute or scenario, a specific architectural decision, and a justification. → ATAM Non-Risk
• The architecture evaluation produced a written report or out-brief that lists risks and non-risks. → Advantages and Drawbacks of ATAM
• The approaches are listed without risk or trade-off findings attached; those appear in the later analysis step. → Architectural Approach Identification
• Important, expensive, large-scale or risky decisions are documented with their rationales. → Architectural Decision Records as Evaluation Prerequisite
• Risks, sensitivity points and trade-off points are listed separately for each alternative. → Comparing Architectural Alternatives with ATAM
• The document judges the style’s benefits against its challenges for the specific context. → Fitness for Purpose
• Each risk names a specific architectural decision and a specific scenario it could make fail. → Insufficient ATAM Application
• The evaluation report lists sensitivity points and states which quality attribute response each one affects. → Sensitivity Point
• The evaluation does not rely on metrics alone to judge whether quality goals are met. → Software Architecture Evaluation
• Each trade-off decision is recorded in arc42 section 9 with its rationale. → Trade-off Point
• Accepted trade-off consequences are tracked in the prioritized risk and technical debt list in section 11. → Trade-off Point
• The criteria in the ADR come from the context and requirements, not from the properties of the preferred option. → ADR Common Mistakes and Review Checklist
• The ADR lists the considered options and justifies the rejection of each alternative. → ADR Common Mistakes and Review Checklist
• The decision section explains why the option was chosen and does not just repeat the ADR title. → ADR Common Mistakes and Review Checklist
• The consequences of each constraint, such as extra cost or effort, are described. → Architectural Constraint
• Each decision states the alternatives considered and the criteria used to choose among them. → Architectural Decision
• Each decision records its rationale, answering why this option was chosen. → Architectural Decision
• The context of each decision covers technical, political, social, and project aspects. → Architectural Decision
• The record shows that the stakeholders of the decision were identified, for example in a RACI matrix. → Architectural Decision Definition of Ready
• The decision requirements and drivers are at least identified and drafted, ideally in SMART form. → Architectural Decision Definition of Ready
• An ADR template was chosen and validated before the decision was recorded. → Architectural Decision Definition of Ready
• Context and requirements are stated explicitly, so decisions can be compared with earlier projects. → Architectural Decision Making Fallacies
• Each decision record states its scope and does not mix system-wide and local arguments. → Architectural Decision Making Fallacies
• The ADR log contains only architecturally significant decisions, those affecting structure, quality characteristics or important dependencies. → Architectural Decision Management
• Each ADR logs the resolution of at least one architecturally significant requirement. → Architectural Decision Management Cycle
• Each ADR names its decision makers. → Architectural Decision Management Cycle
• Each decision lists at least two options and the criteria (decision drivers) used to compare them. → Architectural Decision Management Cycle
• The ADR title conveys both the problem solved and the solution chosen. → Architectural Decision Record
• The ADR evaluates more than one real option, not dummy alternatives. → Architectural Decision Record
• The decision is traced to requirements. → Architectural Decision Record
• The record names the problem and links it to at least one quality goal or significant requirement. → Architectural Decision Record Example
• Rejected options are listed and evaluated, not only the chosen one. → Architectural Decision Record Example
• Pros, cons and trade-offs of the chosen option are balanced, with a stated judgment. → Architectural Decision Record Example
• Each recorded decision shows at least two options that were compared. → Architectural Decision-Making Process
• Decisions state when they will be reviewed or which context changes trigger re-evaluation. → Architectural Decision-Making Process
• The document describes how the system keeps its most critical functions working when elements fail. → Architectural Decisions for Availability
• Each design issue is phrased as a concise question. → Architectural Design Issue
• Rejected options are evaluated too, not only the chosen one. → Architectural Design Issue
• The document separates constraints (which must be handled, though some are negotiable) from forces (which are weighed). → Architectural Force
• The architecture decisions section lists only important, expensive, large-scale or risky decisions, each with its rationale. → Architecturally Significant Decision
• Each ASR is linked to business value or risk, or to a key stakeholder’s concern. → Architecturally Significant Requirement
• Essential architectural decisions are recorded, for example as ADRs, using one consistent template. → Architecture Challenges at Project Start
• Each decision lists all consequences, including negative ones. → Architecture Decision Documentation and Requirements Management
• Each recorded decision names the chosen alternative and the criteria or requirement behind the choice. → Architecture Decision Rationale
• Each ADR covers exactly one decision together with its rationale. → Architecture Decision Rationale
• Consequences list all effects of the decision, not only the positive ones. → Architecture Decision Rationale
• The architecture documentation lists the important, expensive, large-scale or risky decisions together with their reasons. → Architecture as Set of Design Decisions
• Each documented decision is tied to an architecturally significant requirement. → Architecture as Set of Design Decisions
• The reasoning behind resolving concern conflicts is recorded in Architecture Decision Records. → Concern
• Decisions with many or unclear outgoing dependencies are flagged as big or early decisions. → Decision Dependencies
• The decision record shows at least two alternatives that were investigated and compared. → Definition of Done for Architectural Decisions
• The decision is captured and shared in a lean template. → Definition of Done for Architectural Decisions
• The record states who challenged the decision and that the team accepts outcome and rationale. → Definition of Done for Architectural Decisions
• AI-generated ADRs show evidence of human review before being accepted. → GenAI Support for Architectural Decision Records
• References in AI-drafted ADRs (APIs, web pages, product features) were checked to exist. → GenAI Support for Architectural Decision Records
• Pros and cons suggested by an AI were validated for incorrect or exaggerated details. → GenAI Support for Architectural Decision Records
• Each open decision states whether its most responsible moment has come. → Last Responsible Moment
• Big architectural decisions with an early most responsible moment are identified and not postponed. → Last Responsible Moment
• Architectural decisions made by teams are recorded, for example in ADRs, after seeking advice from affected parties. → Levels of Architectural Decisions
• Higher-level bodies provide guidelines or principles rather than deciding everything themselves. → Levels of Architectural Decisions
• Decision files sit in docs/decisions and follow the NNNN-title-with-dashes.md naming pattern. → Markdown Architectural Decision Records
• Each decision lists its consequences, both good and bad. → Markdown Architectural Decision Records
• Each decision says how compliance with it will be confirmed. → Markdown Architectural Decision Records
• Each architectural decision names its decision makers, consulted stakeholders and affected people. → RACI Matrix
• Each task or decision has exactly one Accountable party. → RACI Matrix
• Non-functional requirements are explicitly linked to the architectural decisions that address them. → Requirements-Decision Modeling for Cyber-Physical Systems of Systems
• Buy-versus-build decisions state their total-cost-of-ownership consequences. → Seven Types of Architectural Decisions
• The solution strategy is described as able to evolve, with iterative and incremental building. → Solution as Moving Target
• Technical limits or goal conflicts found during architecture work are recorded as feedback to the requirements. → Twin Peaks Model
• Each decision statement names its context, concern, chosen option, neglected options, desired qualities and accepted downside. → Y-Statement
• The downside clause (‘accepting that…’) states a concrete cost, not a generic remark. → Y-Statement
• The decision is written as one sentence, kept lean. → Y-Statement
• The team has recorded architectural decisions, so the structure traces back to deliberate choices. → Accidental Architecture
• Models or viewpoints are chosen to answer stated questions, such as a throughput model for a throughput concern. → Agile Architecture
• Conflicting goals are recorded together with how the relevant stakeholders resolved them. → Architectural Thinking
• For each chosen style, the document states the constraints it imposes and the trade-offs accepted. → Architecture Means
• Changes are made in small steps and integrated often, rather than in one late big-bang integration. → Keep It Working
• The architecture is described in views that address stakeholder concerns. → Role of the Software Architect
• The consequences of key trade-offs are made visible to stakeholders at several organizational levels. → Software Architect
• The canonical model is independent of any specific application. → Canonical Data Model
• Platform and protocol constraints of a chosen messaging product, such as proprietary protocols, are stated. → Integration Pattern vs. Middleware Technology
• If a shared database is used, the document explains how one schema serves all applications and how changes are controlled. → Integration Style
• The document states which AMQP version is meant, since 1.0 and 0-9-1 differ on the wire. → Messaging Protocol Support in Message Brokers
• The document states how long clients can rely on a published API version. → Patterns for API Design
• Any shared database between applications is justified, including the risk it adds when applications change. → Principles Influencing EAI Pattern Selection
• If a relay publishes outbox messages, the document states that duplicates are possible and how receivers handle them. → Transactional Client
• If models are published straight from the tool to an environment, the document names that environment. → BPMN Modeling Tool
• RPA bots run as normal process steps with shared error handling, retries, and audit. → Degrees of BPM Maturity
• Principles narrow the options instead of dictating a single answer. → Architecture Principle
• Choices such as microservices are justified by fit to context, not by trend. → Conflicting Architecture Principles
• Decisions are based on facts rather than guesses, so unused capabilities are not built. → Continuous Architecture Principles
• The document shows how user and stakeholder feedback is collected and fed back into the design. → Incrementality
• Widely deployed, hard-to-change elements, such as enterprise database schemas, are identified, with the cost of changing them noted. → Shearing Layers
• Important architecture decisions name the requirements behind them. → Traceability
• Each principle gives a rationale in business terms. → Working with Principles
• Each major decision names the quality it improves and the quality it may harm. → Quality Attribute Trade-off
• The standby type (hot, warm, or cold) is named, and the state the standby holds at takeover is described. → Quantifying Recovery and Availability Trade-offs
• Reused assets are checked as fit for purpose, or designed for reuse. → Reusability
• The document states the topology constraints of each pattern, such as what elements may know about each other. → Architectural Pattern
• The trade-offs of the chosen style or patterns are stated. → Architectural Pattern vs. Design Pattern
• The style choice is traced to business drivers and prioritized architecture characteristics, with stakeholder input. → Architecture Style
• The document explains how the serving layer combines batch views with speed-layer updates for queries. → Lambda Architecture
• Where a pattern is used, the tactics it is built from are identified. → Architectural Tactic
• The document describes which essential functions stay available in a degraded mode when components fail. → Availability Tactic
• Side effects of each tactic on other quality attributes are documented along with the trade-offs accepted. → Choosing and Applying Tactics
• Runtime overhead from added structure, such as layer crossings, is acknowledged. → Increase Cohesion
• Key modules expose an explicit interface that hides implementation details. → Modifiability Tactic
• Queue sizes and execution time per event are bounded, or the document explains why not. → Performance Tactic
• Design decisions are tied to a stated quality attribute objective. → Reasons for Architectural Tactics
• The document says how each chosen tactic is realized, for example through a pattern, framework or code. → Relationship between Tactics and Architectural Styles/Patterns
• The document records that stakeholders took part in selecting the security tactics. → Security Tactic
• The decision to split or join is based on overall complexity, not size. → Split Module
• Trade-off points and sensitivity points found in the analysis are identified. → Tactic Trade-off Balancing
• Each tactic decision is recorded as an ADR that traces back to a requirement. → Working with Tactics and Quality Attributes
• Each strategic decision is tied to the problem statement, quality goals or key constraints. → System Idea