Architecture Decision Records (ADR)

ADRs capture why we made important decisions, so future changes don’t repeat old mistakes.

When to write an ADR

• Data model decisions (multi-tenancy, RLS strategy)
• Security boundaries (service role usage, admin privileges)
• Payment model decisions (Stripe as source of truth, webhook handling)
• Major tech choices (hosting, auth approach, background jobs)

ADR format (simple)

• Title, date, status
• Context
• Decision
• Consequences
• Alternatives considered

Example: - 0001: Multi-tenancy + Owner RLS Bypass