Architecture Decision Records

Explanation — why we chose X over Y. Numbered, immutable, append-only.

Every load-bearing technical choice gets an ADR. Format: MADR v3 lite.

Why ADRs

Immutable: once accepted, an ADR is never rewritten. Superseded by a new ADR that links back.
Searchable: grep for a tech name and find the decision + alternatives.
AI-friendly: agents read ADRs to stop re-litigating settled decisions.
Audit trail: new devs see the reasoning, not just the outcome.

Format

# ADR <N>: <title>

- Status: Accepted | Superseded by ADR-<M> | Deprecated
- Date: YYYY-MM-DD
- Deciders: Ideony team

## Context
Why this needed to be decided. 1-3 sentences.

## Decision
What was chosen. 1-2 sentences.

## Consequences
+ positive outcomes
− negative trade-offs
3-5 bullets, concrete.

## Alternatives considered
- Name — why rejected
- Name — why rejected

When to write a new ADR

Picking a new library, framework, or external service
Changing an architecture pattern (auth, deployment, data layer)
Establishing a code-level convention with broad impact (e.g. central fonts registry, rebase-over-merge)
Superseding a previous ADR — write a new one with Status: Accepted, mark the old one Status: Superseded by ADR-<N>.

Do not ADR-ify:

Bug fixes or routine refactors
UI copy changes
Config tweaks that don’t shape the system

Numbering

Sequential, zero-padded to 4 digits. Never reuse a number.

Current highest: see file list. Next ADR = highest + 1.

Index

ADRs are self-indexing — ls shows all, filenames encode title + chronological order. For a quick scan, run:

grep -h "^# ADR" decisions/*.md

Sub-topic index (by area):

Monorepo & tooling

Mobile app

Backend

External services

AI / agentic

0011 — LangGraph + Gemini 2.5 Flash

Infra & deploy

Product / UX

Testing

0026 — E2E strategy — full-stack web + iOS + Android, 4 envs, 3 cadences

Supersession chain

None yet. If you supersede an ADR, add the link here.