Decision records — ADR · PDR · TDR

Purpose: the durable, append-only record of the decisions that shape the solution, so agents and humans cite a decision instead of re-deriving or re-litigating it. Every ticket that implements a decision links its record; every record links the tickets it spawned. Established 2026-07-11 as part of Wave 3 (see wave3-mvp-analysis). Status: as of 2026-07-30 — index current; the ten records below are all still Accepted, and all four Wave-3 decisions have since been executed (see the outcome column).

The three record types

The repo distinguishes decisions by what kind of question they answer, because the audiences and the “who signs off” differ. A single wave usually produces some of each.

Type	Answers	Owner (signs off)	Lives in
ADR — Architecture Decision Record	Structural/architecture choices that span repos or bind the shape of the system for a long time (data platform, auth model, deploy topology, migration strategy).	Engineering + architecture	adr
PDR — Product Decision Record	Product/scope/UX choices: what is in or out of a release, what a feature must do, which reports must exist, pricing/policy calls.	Product Owner	pdr
TDR — Technical Decision Record	Implementation-level technical choices, narrower than an ADR: how to wire a library, which test strategy, a service-internal pattern. Reversible with local blast radius.	The implementing engineer(s)	tdr

Rule of thumb: if reversing it later would force a cross-repo rewrite → ADR; if it changes what the client can do at launch → PDR; if it only changes how one repo builds something → TDR. When unsure, prefer the broader type (ADR > PDR > TDR).

Format

All three share the ADR-0001 skeleton so they read the same:

• Front-matter: Status (Proposed / Accepted / Superseded by …), Date, Deciders, Repos, Related (links).
• Context — the situation and forces.
• One ## section per decision, each with a Rationale and an ### Alternatives rejected subsection.
• Supersede, never edit history: a reversed decision gets a new record whose Status points back, and the old record’s Status becomes Superseded by <id>.

Numbering is zero-padded and per-type: adr/000N-*.md, pdr/000N-*.md, tdr/000N-*.md.

Index

ADR — Architecture

#	Title	Status	Date	Outcome (2026-07-30)
0001	Appwrite integration architecture	Accepted	2026-06-25	✅ Built — Epics A–F merged sprint 32
0002	Full Postgres→Appwrite domain migration & TypeORM decommission	Accepted	2026-07-11	✅ Executed — BetterAuth gone (#149, 07-04), frozen tables dropped (#248, 07-12); TypeORM migrations machinery deliberately retained (#180)
0003	Observability telemetry transport — Sentry (frontend) + OTel/LGTM (backend)	Accepted	2026-07-11	✅ Wired — observability-{validate,stage,prod}.yml + grafana-stage dashboards

PDR — Product

#	Title	Status	Date	Outcome (2026-07-30)
0001	MVP go-live scope — VAS + Clientes in; QR / cobro-rápido / POS-interaction / KPI-drill-down deferred	Accepted	2026-07-11	✅ In scope and built on all three clients; deferrals held
0002	MVP reports catalog	Accepted	2026-07-11	✅ All 8 built + CSV export; live verification partly blocked by the report-store-select drift
0003	VAS provider connectivity phasing (1: shared VB user · 2: per-merchant · 3: direct) & wallet visibility — VB balance never displayed	Accepted	2026-07-11	🟡 Phase 1 in progress — the shared-user model is what makes the Mantarys catalog-tenancy question open (see open questions)

TDR — Technical

#	Title	Status	Date	Outcome (2026-07-30)
0001	Wave 3 verification strategy — stories + parity audit + E2E	Accepted	2026-07-11	✅ All three legs running: story boards, parity galleries (web + mobile), mock + live Playwright suites
0002	Sentry SDK wiring — web (Next.js) + mobile (Compose)	Accepted	2026-07-11	✅ Web wired behind FEATURE_FLAG_OBSERVABILITY_SENTRY_WEB (now ON)
0003	VAS fulfillment via DBOS durable workflows + products.kind discriminator	Accepted (amended by PDR-0003)	2026-07-11	✅ Workflow, ledger, wallet debit and PIN custody built; the aggregator transport is the open half — see Mantarys
0004	Merchant wallet integrity — DBOS per-merchant serialization (Lendbit pattern) on Appwrite	Accepted	2026-07-11	✅ Serialized ops + integrity job merged (api #374/#375); wallet flags enabled on stage 2026-07-30

Standing directives without a record (yet)

Binding calls made in review sessions that have not been written up as ADR/PDR/TDR. They are listed here so they are citable; promoting them into real records is outstanding work.

Directive	Date	Type it should be	Where it currently lives
All feature flags ON for MVP — the ramp is over; nothing ships dark	2026-07-14	PDR (supersedes the flag-ramp posture)	AI_CONTEXT.md hard rule 1; production ramp ticket api #264
Sales are online-only, forever — no offline queueing of operational writes; the offline cache is non-operational reads only; DBOS owns resiliency	2026-07-06	ADR	business-rules/offline-and-idempotency.md
Mantarys Confirmation code 17 is terminal → FAILED (reverse, never poll) — fail-safe, overrides the legacy documentation	2026-07-26	TDR	mantarys-integration-plan
M6 cutover: migrations are the only DDL path; no console/psql DDL	2026-07-11	ADR	terminales-api/src/database/MIGRATIONS.md (api #180)
terminales-solution commits direct to main; code repos keep PRs	—	convention, not a decision record	AI_CONTEXT.md hard rule 7

Relationship to existing docs

• architecture-decisions — the informal rationale table that predates this system; ADR-0001/0002 formalize it. New architecture decisions go through an ADR, not that table.
• open-questions-and-todos — live deferrals and “do not fix prematurely” notes; when an open question is settled, it becomes a record here and is struck from that list.