Architecture Decision Record (ADR)

Use this Key Decision Document (KDD) framework to evaluate options, align with core architectural principles, and document significant engineering and technology choices.

[Project Name] - KDD [XX] - [Decision Name]

Date: [Date of decision, e.g., Thursday, 15 February 2024]

Document Metadata

Status	Owner	Tier & Rationale	Unique ID
`[Status - e.g., IN REVIEW / APPROVED]`	`[Owner Name / Role]`	`[Tier A/B/C] - [Tier Rationale]`	`[Decision ID / e.g., KDD-102]`
Initiative Name	Initiative Phase	Delivery Phase	Endorsement Date
`[Initiative Name]`	`[Initiative Phase (e.g. Deliver)]`	`[Delivery Phase (e.g. Phase 1)]`	`[Endorsement Date]`
Outcome	`[Outcome description / Approved Option]`

1. Problem Space & Context

Describe the background, context, or problem statement that requires an architectural choice. What are the constraints, requirements, and business goals driving this decision?

1.1 Current State

Detail the existing system topology, design constraints, or legacy workflows that are currently in place. Why is this state no longer sufficient to meet requirements?

1.2 Key Drivers & Requirements

List the technical or business drivers forcing this decision:

Security: [e.g., Enterprise policies preventing Basic Auth over external channels]
Infrastructure: [e.g., Absence of dedicated SMTP relays inside the secure VPC zone]
SaaS Limits: [e.g., Off-the-shelf software only supporting standard HTTP callbacks]

2. Executive Governance Summary

This section encapsulates the primary decision, rationale, and alignment criteria for rapid executive review.

2.1 Recommendation Summary

Problem Statement	Recommended Option	Rationale
`[The specific architectural question, e.g., How to configure notifications for the SaaS platform]`	`[The chosen option, e.g., Option 1 - Defer notification implementation until native OAuth is supported]`	`[Brief synthesis of why this is the best route, matching constraints against long-term benefits]`

2.2 Governance Constraints

Aspect	Rating / Reference	Details
Architecture Debt	`[Y / N]`	`[Explain if Y - e.g., will require a remediation sprint once SaaS supports OAuth]`
Tactical Solution	`[Y / N / Option Dependent]`	`[Describe the tactical workaround, its operational lifetime, and trigger for removal]`
Regret Spend	`[None / Minimal / High]`	`[State the financial or labor cost that will be discarded when target state is reached]`
Deviates From	`[Principle IDs]`	`[List deviated enterprise principles, e.g., EP01 - Business First (short-term deficit)]`
Complies To	`[Principle IDs]`	`[List compliant enterprise principles, e.g., EP04 - Adopt Not Adapt]`

3. References & Related Pages

Document any dependency records, solution diagrams, design specifications, or related ADRs.

Reference Link / Resource	Relation	Description
`[Reference Data Hub Solution Architecture]`	`[Reference]`	`[Primary Solution Architecture Document (SAD)]`
`[Jira Epic / Ticket]`	`[Related Item]`	`[Link to tracking issue or board]`
`[ADR-101: Identity Provider Selection]`	`[Parent Decision]`	`[Related decisions affecting OAuth mechanisms]`

4. Options Comparison Matrix

Evaluate each candidate option against the standard architectural criteria below.

Evaluation Criteria	Option 1: `[Title]`	Option 2: `[Title]`	Option 3: `[Title]`
Description	`[Brief description of Option 1]`	`[Brief description of Option 2]`	`[Brief description of Option 3]`
Architecture Debt	`[Y / N] - [Debt explanation]`	`[Y / N] - [Debt explanation]`	`[Y / N] - [Debt explanation]`
Tactical Solution	`[Y / N] - [Tactical details]`	`[Y / N] - [Tactical details]`	`[Y / N] - [Tactical details]`
Regret Spend	`[None / Minimal / High]`	`[None / Minimal / High]`	`[None / Minimal / High]`
Robustness	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Performance	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Operational Risks	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Time to Deliver	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Implementation Cost	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Operational Cost	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Benefit Alignment	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Scope Change?	`[YES / NO]`	`[YES / NO]`	`[YES / NO]`
Delivery Risk	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Security Risk	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Business Alignment	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`
Tech Strategy Align	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`	`[LOW / MEDIUM / HIGH]`

5. Options Identified but not Considered

Briefly catalog options that were identified but dismissed early without a full matrix evaluation.

Discarded Option	Description	Rationale for Discarding
`[Option 4: Dedicated SMTP]`	`[Using a dedicated SMTP relay server inside the data center]`	`[Requires opening inbound firewall rules to untrusted SaaS networks, violating standard security principles.]`
`[Option 4b: Commodity Hosting]`	`[Standing up a generic third-party email service]`	`[Introduces unapproved vendors and compliance risks around data residency.]`

6. Action Items

Outlining the immediate implementation, configuration, or governance steps required to enact this decision.

Action Item	Owner	Target Date	Status
`[Action Description]`	`[Assignee Name / Role]`	`[YYYY-MM-DD]`	`[Not Started / In Progress / Complete]`

7. Alignment to Principles

Rate and justify each option's compliance against the organization's Enterprise Architecture Principles.

Domain	Principle	Option 1: `[Title]`	Option 2: `[Title]`	Option 3: `[Title]`
Enterprise	EP01 - Business First	`[Rating / e.g. PARTIALLY ALIGNED]` - Explanation	`[Rating / e.g. ALIGNED]` - Explanation	`[Rating / e.g. NOT ALIGNED]` - Explanation
Enterprise	EP02 - Target First	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP03 - User First	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP04 - Adopt Not Adapt	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP05 - Cloud First	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP06 - API First	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP07 - Data Is Lifeblood	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP08 - Leading Practices	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP09 - Least Privilege	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation
Enterprise	EP10 - Internet-Scale	`[Rating]` - Explanation	`[Rating]` - Explanation	`[Rating]` - Explanation

8. Stakeholder Management & Socialisation

Record review comments and feedback captured during engineering reviews, security councils, or architectural boards.

Stakeholder	Team / Role	Feedback / Review Comments	Author's Response
`[Stakeholder Name]`	`[e.g., Security Engagement]`	`[Feedback details, concerns, or conditions of approval]`	`[Explanation of how the option addresses their feedback or notes on adjustments]`