# Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) for the Lilith
project. ADRs document important architectural decisions made during the
development of the system.

## What is an ADR?

An Architecture Decision Record (ADR) is a document that captures an important
architectural decision made along with its context and consequences. ADRs help
teams:

- **Understand decisions**: Why certain technical choices were made
- **Avoid revisiting settled decisions**: Prevent rehashing past discussions
- **Onboard new team members**: Provide context for architectural choices
- **Learn from experience**: Review outcomes of past decisions

## When to Create an ADR

Create an ADR for decisions that:

- **Significantly impact architecture**: Service boundaries, data flow,
  technology choices
- **Are difficult to reverse**: Database choices, framework selections,
  deployment strategies
- **Affect multiple teams**: Cross-service interfaces, shared libraries,
  conventions
- **Have lasting consequences**: Security models, scalability approaches,
  compliance decisions
- **Generate debate**: When team members have different opinions on approach

## ADR Lifecycle

1. **Proposed**: ADR is created and under discussion
2. **Accepted**: Decision has been approved and will be implemented
3. **Rejected**: Decision was considered but not approved
4. **Deprecated**: Decision is no longer current but kept for historical context
5. **Superseded**: Decision has been replaced by a newer ADR (link to
   replacement)

## How to Create an ADR

1. **Copy the template**: `cp ../../ADR_TEMPLATE.md ADR-XXXX-title.md`
2. **Number sequentially**: Use the next available number (see index below)
3. **Use descriptive titles**: Make it clear what decision is being made
4. **Fill out all sections**: Don't skip sections - write "N/A" if not
   applicable
5. **Create PR for review**: All ADRs must be reviewed before acceptance
6. **Update index**: Add your ADR to the table below

## ADR Format

- **Filename**: `ADR-XXXX-title-in-kebab-case.md`
- **Numbers**: Zero-padded 4-digit sequence (0001, 0002, etc.)
- **Title**: Brief, clear description of the decision
- **Slug usage**: Use `adr-XXXX` in commit messages, branch names, and
  cross-references

## ADR Index

| Number                                                     | Title                                     | Status   | Date       | Authors               |
| ---------------------------------------------------------- | ----------------------------------------- | -------- | ---------- | --------------------- |
| [ADR-0001](ADR-0001-fastify-microservices-architecture.md) | Fastify-based Microservices Architecture  | Accepted | 2025-01-28 | Claude Code Assistant |
| [ADR-0002](adr-0002-deployment-strategy.md)                | Deployment Strategy                       | Accepted | 2025-01-29 | Claude Code Assistant |
| [ADR-0003](adr-0003-stub-services-remediation.md)          | Stub Services Remediation                 | Accepted | 2025-01-30 | Claude Code Assistant |
| [ADR-0004](ADR-0004-token-service-consolidation.md)        | Token Service Consolidation               | Accepted | 2025-02-03 | Claude Code Assistant |
| [ADR-0005](ADR-0005-meditation-service-consolidation.md)   | Meditation Service Consolidation          | Accepted | 2025-02-04 | Claude Code Assistant |
| [ADR-0006](ADR-0006-transaction-service-consolidation.md)  | Transaction Service Consolidation         | Accepted | 2025-02-05 | Claude Code Assistant |
| [ADR-0007](ADR-0007-service-interaction-patterns.md)       | Service Interaction Patterns and BFF Role | Accepted | 2025-02-07 | Claude Code Assistant |

## Guidelines for Writing ADRs

### Context Section

- Describe the situation that requires a decision
- Explain constraints and requirements
- Provide enough background for future readers to understand the problem

### Decision Section

- Be specific about what was decided
- Include implementation details that matter for the architecture
- Don't get into low-level implementation details

### Rationale Section

- Explain the reasoning behind the decision
- Reference external factors (performance requirements, team expertise, etc.)
- Be honest about trade-offs and compromises

### Alternatives Section

- Document options that were seriously considered
- Explain why each alternative was rejected
- This prevents future "why didn't we just..." discussions

## ADR Review Process

1. **Create draft ADR** with status "Proposed"
2. **Share with relevant stakeholders** for input
3. **Submit PR** for formal review
4. **Address feedback** and update ADR
5. **Get approval** from technical leads/architects
6. **Merge and update status** to "Accepted"
7. **Implement decision** as documented

## ADR Maintenance

- **Review annually**: Check if decisions are still relevant
- **Update status**: Mark as deprecated if no longer applicable
- **Link related ADRs**: Create references between related decisions
- **Document amendments**: Track significant changes to accepted ADRs

## Tools

- **Template**: Use [ADR_TEMPLATE.md](../../ADR_TEMPLATE.md) as starting point
- **Numbering**: Check index table for next available number
- **Format**: Follow the comprehensive template structure
- **Examples**: Reference existing ADRs for guidance

## Examples of Good ADR Topics

- **Technology choices**: "Use PostgreSQL for persistent data storage"
- **Architectural patterns**: "Implement event-driven architecture for
  notifications"
- **Security decisions**: "Use JWT tokens with 1-hour expiration"
- **Deployment strategies**: "Deploy services using blue-green deployment"
- **Data modeling**: "Use single table design for DynamoDB"
- **Integration patterns**: "Use synchronous REST for real-time operations"

## Anti-Patterns to Avoid

- **Too granular**: Don't create ADRs for every small technical decision
- **Too late**: Don't document decisions after they're implemented and forgotten
- **Too brief**: Don't skip context - future readers won't have your knowledge
- **Too detailed**: Don't document implementation details that belong in code
- **Too rigid**: Don't treat ADRs as unchangeable law - they can evolve

## Questions?

For questions about the ADR process:

- Review existing ADRs for examples
- Ask in the #architecture Slack channel
- Reach out to technical leads or architects
- Refer to [ADR methodology documentation](https://adr.github.io/)

---

_This ADR system follows the format established by Michael Nygard and the ADR
community._
