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#
- Proposed: ADR is created and under discussion
- Accepted: Decision has been approved and will be implemented
- Rejected: Decision was considered but not approved
- Deprecated: Decision is no longer current but kept for historical context
- Superseded: Decision has been replaced by a newer ADR (link to replacement)
How to Create an ADR#
- Copy the template:
cp ../../ADR_TEMPLATE.md ADR-XXXX-title.md - Number sequentially: Use the next available number (see index below)
- Use descriptive titles: Make it clear what decision is being made
- Fill out all sections: Don't skip sections - write "N/A" if not applicable
- Create PR for review: All ADRs must be reviewed before acceptance
- 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-XXXXin commit messages, branch names, and cross-references
ADR Index#
| Number | Title | Status | Date | Authors |
|---|---|---|---|---|
| ADR-0001 | Fastify-based Microservices Architecture | Accepted | 2025-01-28 | Claude Code Assistant |
| ADR-0002 | Deployment Strategy | Accepted | 2025-01-29 | Claude Code Assistant |
| ADR-0003 | Stub Services Remediation | Accepted | 2025-01-30 | Claude Code Assistant |
| ADR-0004 | Token Service Consolidation | Accepted | 2025-02-03 | Claude Code Assistant |
| ADR-0005 | Meditation Service Consolidation | Accepted | 2025-02-04 | Claude Code Assistant |
| ADR-0006 | Transaction Service Consolidation | Accepted | 2025-02-05 | Claude Code Assistant |
| ADR-0007 | 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#
- Create draft ADR with status "Proposed"
- Share with relevant stakeholders for input
- Submit PR for formal review
- Address feedback and update ADR
- Get approval from technical leads/architects
- Merge and update status to "Accepted"
- 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 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
This ADR system follows the format established by Michael Nygard and the ADR community.