ADR Overview

Architecture Decision Records (ADRs)

Project: Drop -- Fintech Payment App Last updated: 2026-03-03 Maintainer: Standards Architect

What are ADRs?

Architecture Decision Records capture significant technical decisions made during Drop's development. Each ADR documents the context, the decision itself, and its consequences -- providing a historical record of why the system is built the way it is.

ADRs are immutable once accepted. If a decision is reversed, the original ADR is marked Superseded and a new ADR is created referencing it.

ADR Index

ADR Lifecycle

stateDiagram-v2
    [*] --> Proposed : Author drafts ADR
    Proposed --> Accepted : Team reviews and approves
    Proposed --> Rejected : Team rejects proposal
    Accepted --> Deprecated : No longer relevant
    Accepted --> Superseded : New ADR replaces this one
    Rejected --> [*]
    Deprecated --> [*]
    Superseded --> [*]

ADR Template

Use this template when proposing a new ADR. Save as ADR-NNN-short-title.md in this directory.

# ADR-NNN: Title

**Status:** Proposed | Accepted | Deprecated | Superseded by [ADR-XXX](ADR-XXX-title.md)
**Date:** YYYY-MM-DD
**Deciders:** [Names and roles]
**Category:** Architecture | Security | Database | Backend | Frontend | Mobile | Infrastructure

---

## Context

What is the issue that we are seeing that motivates this decision?
Include technical background, constraints, and forces at play.

## Decision

What is the change that we are proposing and/or doing?
State the decision clearly and concisely.

## Consequences

### Positive
- List benefits of this decision

### Negative
- List drawbacks and trade-offs

### Risks
- List risks and their mitigations

## References

- Link to related ADRs, documents, or external resources
- Link to implementation PRs or tasks

Guidelines for Proposing ADRs

1. When to write an ADR: Any decision that affects the system architecture, technology choices, security model, or data model and would be hard to reverse.

2. Scope: One ADR per decision. If a decision has multiple parts, consider splitting into separate ADRs.

3. Numbering: Use sequential three-digit numbers (001, 002, ...). Never reuse numbers.

4. Review process: Draft as Proposed, share with the team. Once approved by the AI Director (John) and/or CEO (Alem), change status to Accepted.

5. Superseding: When reversing a decision, create a new ADR and update the old one's status to Superseded by [ADR-XXX]. Never delete old ADRs.

6. Context matters: Future readers need to understand why the decision was made. Include constraints, alternatives considered, and the reasoning.

Cross-References

• Architecture Document -- Main architecture overview
• System Context (C4 Level 1) -- System context diagram
• Compliance Status -- Regulatory compliance tracking