# ADR-XXXX: [Decision Title]

**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]

## Related Decisions

### 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
