Design Decisions
What Is a Design Decision in ArchRepo?
A Design Decision is a formal record of a significant choice made during solution design. Each record captures what was decided, the problem it addressed, what alternatives were considered, and the impact of the decision. Design Decisions are referenced using the prefix DD- — DD-1, DD-2, and so on.
The register is the authoritative log of why the solution is the way it is — a resource for new team members, stakeholders, and auditors who need to understand the reasoning behind how the solution was built.
Beyond Architecture: The Full Decision Register
ArchRepo’s Design Decision register extends the ADR (Architecture Decision Record) concept to cover any significant decision in the project — not just technical architecture.
Many design decisions require stakeholder sign-off that goes beyond the architecture team. Examples:
| Decision type | Example |
|---|---|
| Technical architecture | ”We will use an event-driven integration pattern rather than synchronous API calls between services” |
| Technology selection | ”PostgreSQL will be used as the primary operational database” |
| Capability endorsement | ”The solution will provide a self-service customer portal for order tracking — approved by the product owner” |
| Business process design | ”Automated approval will be applied for purchase orders under £5,000” |
| Data design | ”Customer PII will not be stored in the data warehouse — anonymised identifiers only” |
| Constraint acceptance | ”The solution will not support Internet Explorer 11 — agreed with IT steering group” |
Any decision that is significant, that cannot easily be reversed, or that requires formal stakeholder buy-in belongs in the register.
ADR Background
The Architecture Decision Record was introduced by Michael Nygard to address a common problem in software projects: teams often know what was built but not why. ADRs solve this by creating a lightweight, persistent log of significant decisions alongside the codebase.
Key industry resources:
- Documenting Architecture Decisions — Michael Nygard’s original post introducing the ADR format (Cognitect, 2011)
- Architecture Decision Record — GitHub — Joel Parker Henderson’s widely-referenced ADR template collection, covering many variations and formats
ArchRepo applies the same principle — record decisions as they are made, with enough context to make them understandable months or years later — and broadens the scope to the full set of decisions made across the project, not just those made by architects.
Decision Structure
Each Design Decision is structured around four core questions:
| Field | Question it answers |
|---|---|
| Problem and Context | What problem are we solving? What constraints or pressures apply? What is the context that makes this decision necessary? |
| Decision | What did we decide? State it clearly and unambiguously. |
| Decision Impact | What are the consequences? What trade-offs are accepted? What changes as a result? |
| Alternatives Considered | What else was evaluated? Why were those alternatives not chosen? |
A fifth field — Supporting Material — allows a link to any briefing document, presentation, or analysis that was produced to support the decision.
Approval
Design Decisions support a formal approval workflow. Once a decision is ready for sign-off, it is submitted for approval. The approver, date, and outcome are recorded, creating an auditable trail of who approved what and when.
This is particularly important for decisions that have been agreed with customers, steering groups, or external stakeholders — the record shows who authorised the decision, not just what was decided.
Action Tracker
Design Decisions include an Action Tracker for recording actions that arise from the decision — follow-up tasks, information to be confirmed, or parties to be notified. Actions are tracked with owners and due dates, separate from the main task register.
Categories
Design Decisions support categories, allowing the register to be organised into logical groups — for example, Integration, Security, Data, Infrastructure, or Business Process. The Design Decisions by Category view provides a categorised breakdown of the full register.
Traceability
Design Decisions can be linked to the requirements they support:
| Link | What it means |
|---|---|
| Supports Business Requirement | The decision was made to address or implement this requirement |
| Supports Non-Functional Requirement | The decision addresses a quality attribute or constraint |
| Supports Transition Requirement | The decision addresses how the solution transitions from current to target state |
Linking decisions to requirements creates a complete traceability chain: from the business need, through the decision, to the implemented solution.
Fields Reference
See Design Decision Fields for a description of each field and guidance on what to record.