Eve library

Architecture Decision Records (ADRs)

ADR

Revision 1

On this page

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

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