Eve library

ADR-XXXX: [Decision Title]

Guide

Revision 1

On this page

Status: [Proposed | Accepted | Rejected | Superseded | Deprecated] Date: YYYY-MM-DD Authors: [Name(s)] Reviewers: [Name(s)] Supersedes: [ADR number if applicable] Superseded by: [ADR number if applicable]

Context and Problem Statement#

Clearly describe the architectural problem or decision that needs to be made. Include:

  • What is the issue we're trying to solve?
  • What are the constraints and requirements?
  • What is the business context?
  • What technical context led to this decision?

Example: We need to choose a data persistence strategy for user-generated content in the Lilith platform. The system must handle high-volume writes from user interactions while maintaining data consistency for critical operations like payments and user authentication.

Decision Drivers#

List the key factors that influence this decision:

  • Performance Requirements: [e.g., < 200ms read latency, 10k+ writes/sec]
  • Consistency Requirements: [e.g., Strong consistency for payments, eventual for social features]
  • Scalability Requirements: [e.g., Support 1M+ active users]
  • Operational Requirements: [e.g., 99.9% uptime, automated backups]
  • Team Constraints: [e.g., Existing expertise, learning curve]
  • Budget Constraints: [e.g., Cost per month, licensing]
  • Compliance Requirements: [e.g., GDPR, data residency]
  • Integration Requirements: [e.g., Must work with existing Auth service]

Considered Options#

Option 1: [Name]#

Description: Brief description of the option

Pros:

  • ✅ Advantage 1 with quantified impact where possible
  • ✅ Advantage 2
  • ✅ Advantage 3

Cons:

  • ❌ Disadvantage 1 with impact assessment
  • ❌ Disadvantage 2
  • ❌ Disadvantage 3

Cost: [Implementation cost, operational cost] Risk: [High/Medium/Low with explanation] Effort: [Development time, learning curve]

Option 2: [Name]#

[Same structure as Option 1]

Option 3: [Name]#

[Same structure as Option 1]

Decision Outcome#

Chosen option: Option X - [Name]

Justification: Explain why this option was selected over others. Include:

  • How it best addresses the decision drivers
  • What trade-offs were accepted
  • What risks are being mitigated
  • Expected positive consequences

Implementation Plan:

  1. Phase 1: [Timeline, deliverables, success criteria]
  2. Phase 2: [Timeline, deliverables, success criteria]
  3. Phase 3: [Timeline, deliverables, success criteria]

Success Metrics:

  • Metric 1: [Measurable criteria with target values]
  • Metric 2: [Measurable criteria with target values]
  • Metric 3: [Measurable criteria with target values]

Review Schedule: [When to review this decision]

Implementation Details#

Technical Specifications#

  • Architecture: [High-level system design]
  • Interfaces: [APIs, protocols, data formats]
  • Dependencies: [External systems, libraries, services]
  • Configuration: [Environment variables, config files]

Migration Strategy#

  • From: [Current state description]
  • To: [Target state description]
  • Steps: [Detailed migration steps]
  • Rollback Plan: [How to revert if needed]
  • Timeline: [Migration schedule]

Testing Strategy#

  • Unit Tests: [What needs unit test coverage]
  • Integration Tests: [Inter-service testing approach]
  • Load Tests: [Performance validation]
  • Security Tests: [Security validation]
  • User Acceptance: [Validation with stakeholders]

Consequences#

Positive Consequences#

  • ✅ Benefit 1: [Specific impact on system/team/users]
  • ✅ Benefit 2: [Quantified where possible]
  • ✅ Benefit 3: [Long-term advantages]

Negative Consequences#

  • ❌ Cost 1: [Technical debt, complexity]
  • ❌ Cost 2: [Operational overhead]
  • ❌ Cost 3: [Learning curve, training needs]

Risks and Mitigation#

Risk Probability Impact Mitigation Strategy
Risk 1 description High/Med/Low High/Med/Low Specific mitigation plan
Risk 2 description High/Med/Low High/Med/Low Specific mitigation plan

Compliance and Security#

Security Implications#

  • Data Protection: [How sensitive data is handled]
  • Access Control: [Authentication/authorization changes]
  • Audit Requirements: [Logging, monitoring needs]
  • Encryption: [Data at rest, in transit]

Compliance Requirements#

  • GDPR: [Data privacy implications]
  • SOC 2: [Control requirements]
  • Industry Standards: [Relevant standards compliance]

Monitoring and Observability#

Metrics to Track#

  • Performance: [Latency, throughput, error rates]
  • Business: [User engagement, conversion rates]
  • Operational: [Resource utilization, costs]

Alerting Strategy#

  • Critical Alerts: [System down, data loss]
  • Warning Alerts: [Performance degradation]
  • Info Alerts: [Capacity planning]

Dashboards#

  • Real-time: [Operations dashboard]
  • Business: [KPI tracking]
  • Technical: [System health]

Upstream Dependencies#

  • ADR-XXXX: [Related architectural decision]
  • ADR-YYYY: [Another related decision]

Downstream Impacts#

  • Service A: [How this affects other services]
  • Service B: [Integration changes needed]
  • Client Applications: [API changes, migration needed]

References#

External Resources#

  • [Technical documentation links]
  • [Industry best practices]
  • [Vendor documentation]
  • [Academic papers or research]

Internal Resources#

  • [Related ADRs]
  • [Design documents]
  • [Implementation pull requests]
  • [Meeting notes or discussions]

Revision History#

Version Date Author Changes
1.0 YYYY-MM-DD [Author] Initial version
1.1 YYYY-MM-DD [Author] Updated based on review feedback

Template Notes#

Usage Instructions:

  1. Copy this template to docs/adr/ADR-XXXX-decision-title.md
  2. Replace XXXX with the next sequential ADR number
  3. Fill in all sections with specific, concrete information
  4. Remove any sections not applicable to your decision
  5. Submit for review before marking as "Accepted"

Quality Checklist:

  • Problem statement is clear and specific
  • All viable options are considered
  • Decision rationale is well-justified
  • Implementation plan is detailed
  • Success metrics are defined
  • Risks are identified with mitigation plans
  • Compliance and security implications addressed
  • Monitoring strategy defined

ADR Numbering:

  • Start with ADR-0001
  • Increment sequentially
  • Never reuse numbers
  • Include leading zeros (ADR-0001, not ADR-1)

Status Definitions:

  • Proposed: Under consideration, not yet decided
  • Accepted: Decision made and implementation approved
  • Rejected: Considered but not selected
  • Superseded: Replaced by a newer decision
  • Deprecated: No longer relevant or applicable