# 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 | Title | Status | Date | Category |
|-----|-------|--------|------|----------|
| [ADR-001](ADR-001-consolidate-backends.md) | Consolidate to Single Backend | Accepted | 2026-02-12 | Architecture |
| [ADR-002](ADR-002-separate-fontelepay.md) | Separate FontelePay from Drop Repository | Accepted | 2026-02-12 | Architecture |
| [ADR-003](ADR-003-psd2-pass-through.md) | Adopt PSD2 Pass-through Model (No Wallet) | Accepted | 2026-02-12 | Architecture |
| [ADR-004](ADR-004-jwt-httponly-cookies.md) | JWT Storage in httpOnly Cookies | Accepted | 2026-02-21 | Security |
| [ADR-005](ADR-005-monolith-first.md) | Monolith-First Architecture | Accepted | 2026-02-21 | Architecture |
| [ADR-006](ADR-006-sqlite-to-postgresql.md) | SQLite for Dev, PostgreSQL for Production | Superseded by ADR-014 | 2026-02-21 | Database |
| [ADR-007](ADR-007-bankid-oidc-auth.md) | BankID as Sole Authentication Provider | Accepted | 2026-02-21 | Security |
| [ADR-008](ADR-008-hono-api-framework.md) | Hono v4 for Mobile API | Accepted | 2026-02-21 | Backend |
| [ADR-009](ADR-009-feature-flag-system.md) | Custom Feature Flag System | Accepted | 2026-02-21 | Backend |
| [ADR-010](ADR-010-dual-database-driver.md) | Dual Database Driver Abstraction | Superseded by ADR-014 | 2026-02-21 | Database |
| [ADR-011](ADR-011-expo-mobile-framework.md) | Expo SDK 54 for Mobile App | Accepted | 2026-02-21 | Mobile |
| [ADR-012](ADR-012-aws-app-runner-deploy.md) | AWS App Runner for Deployment | Accepted | 2026-02-21 | Infrastructure |
| [ADR-014](ADR-014-postgresql-only.md) | PostgreSQL-Only Architecture (Drizzle ORM) | Accepted | 2026-02-26 | Database |

---

## ADR Lifecycle

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

```markdown
# 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](../../../project/architecture/architecture-document.md) -- Main architecture overview
- [System Context (C4 Level 1)](../hld/system-context.md) -- System context diagram
- [Compliance Status](../../security/COMPLIANCE.md) -- Regulatory compliance tracking