Skip to content

Template 01

[ADR Number]: [Short Title of Decision]

Status: Proposed / Accepted / Deprecated / Superseded

Context and Problem Statement

[ Context]{ .md-color--blue }

\[Clearly and concisely describe the context and background of the decision. What is the issue or problem that needs to be addressed? What are the relevant facts and circumstances? Avoid jargon and be specific. This should be understandable to someone unfamiliar with the project, but familiar with the domain. Use diagrams if they help explain the context. Focus on *why* a decision is needed, not *what* the decision is.\]

[ Problem Statement]{ .md-color--blue }

[A concise statement of the problem. This should be a single sentence or a very short paragraph. It should be clear what problem this ADR is trying to solve.]

Drivers

[ Drivers]{ .md-color--blue }

\[List the key drivers influencing this decision. Categorize them as *Technical* or *Business*. Use bullet points for clarity. These are the "forces" at play.\]
  • Technical:
    • [Technical Driver 1: e.g., Scalability requirements]
    • [Technical Driver 2: e.g., Performance targets]
    • [Technical Driver 3: e.g., Existing technology stack]
  • Business:
    • [Business Driver 1: e.g., Time-to-market constraints]
    • [Business Driver 2: e.g., Budget limitations]
    • [Business Driver 3: e.g., Regulatory compliance]

Constraints

[ Constraints]{ .md-color--blue }

[List any constraints that limit the possible solutions. These are non-negotiable limitations. Use bullet points.]

  • [Constraint 1: e.g., Must use existing database]
  • [Constraint 2: e.g., Must be deployable on platform X]
  • [Constraint 3: e.g., Must integrate with service Y]

Objectives

[ Objectives]{ .md-color--blue }

[List the specific, measurable, achievable, relevant, and time-bound (SMART) objectives that the chosen solution should achieve. Use bullet points.]

  • [Objective 1: e.g., Reduce latency to under 200ms]
  • [Objective 2: e.g., Achieve 99.99% uptime]
  • [Objective 3: e.g., Support 10,000 concurrent users]

Considered Solutions

[ Considered Solutions]{ .md-color--blue }

[Describe each considered solution in detail. For each solution, include:]

Solution [Number]: [Solution Name]

[Detailed description of the solution. Include diagrams, code snippets, or other relevant artifacts as needed. Be thorough and clear.]

Pros

[ Pros]{ .md-color--green }

[List the advantages of this solution. Use bullet points.]

  • [Pro 1]
  • [Pro 2]
  • [Pro 3]

Cons

[ Cons]{ .md-color--red }

[List the disadvantages of this solution. Use bullet points.]

  • [Con 1]
  • [Con 2]
  • [Con 3]

Mitigation Strategies

[ Mitigation Strategies]{ .md-color--orange }

[For each significant con, describe how the risk can be mitigated. Use bullet points.]

  • [Con]: [Mitigation Strategy]
  • [Con]: [Mitigation Strategy]

Consequences

[ Consequences]{ .md-color--orange }

[Describe the potential consequences (both positive and negative) of adopting this solution. Consider long-term impacts.]

  • [Consequence 1]
  • [Consequence 2]

(Repeat the above "Solution [Number]" section for each considered solution)

Trade-off Analysis

[ Trade-off Analysis]{ .md-color--blue }

[Provide a comparative analysis of the considered solutions. Use a table to summarize the pros, cons, and other relevant factors. This helps visualize the trade-offs.]

Technical Trade-offs

Feature/Criteria Solution 1 Solution 2 Solution 3 ...
[Criteria 1] [Value] [Value] [Value] ...
[Criteria 2] [Value] [Value] [Value] ...
[Criteria 3] [Value] [Value] [Value] ...
... ... ... ... ...

Business Trade-offs

Feature/Criteria Solution 1 Solution 2 Solution 3 ...
[Criteria 1] [Value] [Value] [Value] ...
[Criteria 2] [Value] [Value] [Value] ...
[Criteria 3] [Value] [Value] [Value] ...
... ... ... ... ...

Decision

[ Decision]{ .md-color--green }

Chosen Solution: [Solution Number] - [Solution Name]

[Clearly state the chosen solution.]

Justification

[ Justification]{ .md-color--blue }

[Provide a detailed justification for the chosen solution. Explain why this solution was selected over the alternatives. Address both technical and business considerations. Refer back to the drivers, constraints, objectives, and trade-off analysis.]

Technical Justification

[Explain the technical reasons for choosing this solution. Be specific and reference the trade-off analysis.]

Business Justification

[Explain the business reasons for choosing this solution. Be specific and reference the trade-off analysis.]

Consequences

[ Consequences (Revisited)]{ .md-color--orange }

[Reiterate and expand upon the consequences of the chosen solution. This section should provide a final, comprehensive overview of the expected impacts.]

  • [Consequence 1]
  • [Consequence 2]
  • ...

Notes (Optional)

[ Notes]{ .md-color--blue }

[Include any additional notes, comments, or considerations that are relevant to the decision but don't fit elsewhere.]