Skip to content

Architecture Decision Records (ADRs)

This directory contains Architecture Decision Records (ADRs) that document important architectural decisions made for the LBS Foundry platform.

What are ADRs?

Architecture Decision Records (ADRs) are short text documents that capture important architectural decisions made along with their context and consequences. They help:

  • Document reasoning behind architectural choices
  • Preserve context for future developers
  • Track evolution of architectural thinking
  • Facilitate discussions about design decisions

ADR Index

ADR Title Status Date
ADR-007 Multi-Language SDK Auto-Generation Accepted 2025-01
ADR-008 OpenAPI 3.0 Specification Generation Proposed 2025-01
ADR-009 Sports Content Query Service Validation Proposed 2026-05
Real-Time Notification System Real-Time Notification System Implemented 2026-04

Note: ADR-001 through ADR-006 documented a Strapi/CMS content platform that was never built; they were removed on 2026-06-20 (recoverable from git history), which is why the numbering begins at ADR-007.

Reading ADRs

Each ADR follows a standard format:

Title

Brief description of the decision

Status

  • Proposed - Under consideration
  • Accepted - Decision made and implemented
  • Rejected - Decision considered but not adopted
  • Deprecated - Previously accepted but now superseded

Context

The situation that led to the need for a decision

Decision

The architectural decision that was made

Consequences

The positive and negative consequences of the decision

How to Use ADRs

For New Developers

  1. Start with core platform ADRs to understand fundamental decisions
  2. Read integration ADRs relevant to your work area
  3. Refer back when questions arise about "why we did it this way"

For Architects

  1. Review all ADRs to understand the current architectural landscape
  2. Consider impact on existing decisions when proposing changes
  3. Create new ADRs for significant architectural decisions

For Product Teams

  1. Understand constraints documented in ADRs
  2. Reference decisions when planning new features
  3. Raise questions if requirements conflict with existing decisions

Creating New ADRs

When you need to make a significant architectural decision:

1. Use the ADR Template

# ADR-XXX: [Title]

## Status
Proposed / Accepted / Rejected / Deprecated

## Context
[Describe the problem and context]

## Decision
[Describe the decision and rationale]

## Consequences
### Positive
- [List positive consequences]

### Negative
- [List negative consequences]

### Risks
- [List potential risks]

## Implementation
- [Implementation notes if applicable]

## References
- [Related ADRs, documents, or external resources]

2. ADR Numbering

  • Use sequential numbering: ADR-001, ADR-002, etc.
  • Check existing ADRs to find the next available number
  • Update this index when adding new ADRs

3. Review Process

  1. Create draft ADR with status "Proposed"
  2. Share with team for review and discussion
  3. Update based on feedback
  4. Mark as "Accepted" when consensus is reached
  5. Update this index with the new ADR

ADR Categories

Platform Architecture

  • Event sourcing decisions
  • CQRS implementation choices
  • Database and storage decisions
  • Authentication and authorization

Integration Architecture

  • External API integrations
  • Data ingestion patterns
  • Third-party service decisions
  • Webhook implementations

Development Process

  • Code organization decisions
  • Testing strategies
  • Deployment approaches
  • Development tooling choices

Business Domain

  • Domain modeling decisions
  • Aggregate boundary definitions
  • Event design choices
  • Business rule implementations

Architecture Guides

Development Guides

External Resources

ADR Lifecycle

Creating

  • Identify need for architectural decision
  • Research options and gather context
  • Write initial ADR with "Proposed" status
  • Share for team review

Reviewing

  • Gather feedback from stakeholders
  • Discuss trade-offs and alternatives
  • Refine decision based on input
  • Reach consensus on approach

Accepting

  • Update status to "Accepted"
  • Implement the decision
  • Monitor consequences and outcomes
  • Update documentation as needed

Evolving

  • Revisit decisions as context changes
  • Create new ADRs that supersede old ones
  • Mark outdated ADRs as "Deprecated"
  • Maintain historical record

Tips for Writing Good ADRs

Keep it Concise

  • Focus on the essential information
  • Avoid unnecessary technical details
  • Use clear, simple language

Provide Context

  • Explain why the decision was needed
  • Describe alternatives considered
  • Include relevant constraints

Document Consequences

  • Be honest about trade-offs
  • Include both positive and negative impacts
  • Consider long-term implications

Stay Relevant

  • Keep ADRs up to date
  • Remove or deprecate outdated decisions
  • Reference related decisions

Benefits of ADRs

For Teams

  • Shared Understanding of architectural decisions
  • Faster Onboarding for new team members
  • Better Collaboration through documented reasoning
  • Consistent Decisions across the platform

For Projects

  • Reduced Technical Debt through thoughtful decisions
  • Easier Maintenance with documented rationale
  • Better Planning with understood constraints
  • Improved Quality through deliberate architecture

For Organizations

  • Knowledge Preservation beyond individual developers
  • Improved Communication between teams
  • Better Risk Management through documented trade-offs
  • Informed Evolution of architecture over time

Need to create a new ADR? Use the template above and follow our review process. Questions? Ask in the development channel!