Architecture Decision Records

This folder holds one file per significant architectural decision, in MADR format. ADRs capture why the system is built the way it is — the context, the options weighed, and the consequences — so a future reader (human or AI agent) does not have to reverse-engineer intent from the code.

Rules

• Append-only & immutable. Never rewrite an accepted ADR. If a decision changes, write a new ADR and set the old one’s status to Superseded by NNNN.
• One decision per file. Filename: NNNN-kebab-case-slug.md (zero-padded).
• Link, don’t duplicate. Reference code as path:line and link sibling ADRs with relative links. The canonical fact lives in exactly one place.

Index

ADR	Title	Status
0001	Long-polling over webhook for update intake	Accepted
0002	Fat services return (text, keyboard); thin handlers	Accepted
0003	lazy="raise" on large / unmigrated relationships	Accepted
0004	Preserve TS bot behaviour bug-for-bug across cutover	Accepted
0005	Outbound sender: bounded concurrency + 429 retry + per-message isolation	Accepted
0006	Shared DB schema owned by backend; reflection test, not migrations	Accepted
0007	Keep DB TLS verification ON (no rejectUnauthorized:false)	Accepted

Template (copy for a new ADR)

# NNNN. <short decision title>

- **Status:** Proposed | Accepted | Superseded by [NNNN](NNNN-...md)
- **Date:** YYYY-MM-DD
- **Deciders:** <names / roles>

## Context and problem statement

<What forces are at play? What problem are we solving? 2–4 sentences.>

## Considered options

1. **<Option A>** — <one line>
2. **<Option B>** — <one line>

## Decision outcome

Chosen: **<Option>**, because <justification>.

### Consequences

- ✅ <positive>
- ⚠️ <trade-off / negative>

## More information

<Links to code (`path:line`), related ADRs, external references.>