The Architecture Decision Nobody Writes Down

Six months ago, I chose Supabase over Firebase for Nexural. I had good reasons — PostgreSQL, row-level security, self-hostable. But I almost forgot those reasons. The only thing that saved me from re-evaluating the same decision (and wasting a week) was a markdown file I wrote in 15 minutes.

The Problem

Every engineering team has this conversation:

"Why do we use RabbitMQ instead of Kafka?" "I think Dave chose it. Dave left 8 months ago." "..." "Should we switch to Kafka?"

And now you're spending a sprint re-evaluating a decision that was already evaluated. The institutional knowledge walked out the door.

Architecture Decision Records (ADRs)

An ADR is a short document that captures a significant decision. Mine are dead simple:

```markdown

ADR-003: Use Supabase over Firebase for Nexural

Status

Accepted (2024-06-15)

Context

Need a database and auth solution for the Nexural trading platform. Requirements: PostgreSQL (for complex queries), row-level security, real-time subscriptions, self-hostable (for future enterprise clients).

Decision

Use Supabase.

Alternatives Considered

• Firebase: NoSQL limits complex trading queries. No RLS. Vendor lock-in with no self-host option.
• Raw PostgreSQL on RDS: No built-in auth, real-time, or admin dashboard. Would need to build all of that.
• PlanetScale: MySQL-based. No PostgreSQL features we need (materialized views, RLS, jsonb).

Consequences

• Positive: Native PostgreSQL, RLS for multi-tenancy, built-in auth
• Negative: Smaller ecosystem than Firebase, fewer tutorials
• Risk: Supabase is younger and could pivot/shut down (mitigated by PostgreSQL portability — we can migrate to raw Postgres)

Revisit When

• We need real-time collaborative editing (Firebase CRDT support is better)
• We need to serve 100K+ concurrent connections (unknown Supabase limits) ```

That took 15 minutes. It will save me hours every time I (or anyone else) questions the choice.

What Gets an ADR

Not every decision needs one. My rule: if the decision would take more than 30 minutes to reverse, write an ADR.

Things that deserve ADRs:

• Database choice
• Auth strategy
• API architecture (REST vs GraphQL)
• Hosting platform
• State management approach
• Major library choices (ORM, testing framework)
• Billing/payment provider
• CI/CD platform

Things that don't:

• Which CSS class naming convention
• Tabs vs spaces (actually, this probably does)
• Which icon library
• File naming conventions

Where I Store Them

``` docs/ adr/ 001-use-nextjs-for-frontend.md 002-use-stripe-for-billing.md 003-use-supabase-over-firebase.md 004-monolith-over-microservices.md 005-raw-sql-for-dashboards.md ```

Numbered. In the repo. Version controlled. Searchable.

When someone asks "why do we use X?" the answer is `docs/adr/`. Not "I think I remember" or "ask the person who left."

The Superpower Nobody Talks About

ADRs aren't just documentation. They're a thinking tool. The act of writing down "Alternatives Considered" forces you to actually consider alternatives. I've changed my mind mid-ADR at least three times because writing it out made me realize my original choice was wrong.

The 15 minutes you spend writing an ADR is the most undervalued engineering practice I know.