Skip to content

ADR Index

Ankit Upadhyay edited this page Aug 25, 2026 · 2 revisions

Architecture Decision Records

An ADR captures a single architectural decision: the context that forced it, the decision itself, and the trade-offs accepted. It exists so a new contributor can understand why the code looks the way it does without reverse-engineering it from git blame.

Canonical source: docs/adr/ in the main repo. Each ADR below mirrors its repo file for browsability; if the two differ, the repo file wins. ADRs still in an open PR link to that PR until they merge to main.

When to write one

Write an ADR when a decision is expensive to reverse, crosses app/package boundaries, or picks between two reasonable designs where the reasoning would otherwise be lost — a datastore or migration strategy, a payment/settlement model, an auth or persistence trade-off, a public API contract shape.

Skip it for anything a code review can fully capture on its own: a new utility function, a bug fix, a routine dependency bump.

Process

  1. Copy template.md to NNNN-kebab-case-title.md, where NNNN is the next number in sequence. Numbers are never reused, even if a proposed ADR is rejected.
  2. Open it as part of the PR that makes the decision, or as a standalone docs PR for retroactive documentation.
  3. Status starts at Proposed; once the PR merges, update to Accepted.
  4. If a later decision replaces this one, mark the old ADR Superseded by ADR-000X and link forward. Don't delete or rewrite history.

Index — Yosemite-Crew

# Title Status Date
0001 Postgres + Prisma as the target source of truth Accepted (migration complete - exit criteria met by #1819, 2026-07-18) 2026-06-07
0002 Stripe Standard Connect with direct charges; clinic as merchant of record Accepted 2026-06-25
0003 Provider-neutral auth boundary with SuperTokens as the first adapter Accepted (implemented via PR #1763, merged 2026-07-16) 2026-07-02
0004 Single declared region for developer tenants, with a region field for later Proposed on open PR #1788 - not yet in docs/adr/ on main or dev 2026-07-07
0005 Security model for the Tier 1 in-browser AI editing agent Proposed on open PR #1788 - not yet in docs/adr/ on main or dev 2026-07-07

Index — SuperAdmin (separate repo)

SuperAdmin keeps its own ADR log next to its own code, because it documents a different codebase.

# Title Status Date
0001 Audit log persisted in SuperTokens UserMetadata (no dedicated DB, no CAS) Accepted (PR #102) 2026-07-01

Related architecture pages

The ADRs are the decisions; the Architecture section is the current state those decisions produced. Notable pairings: ADR-0001 ↔ Data Layer, ADR-0002 ↔ Payments, ADR-0003 ↔ Auth & Identity, ADR-0004/0005 ↔ Developer Portal.

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally