Appearance
Architecture Decision Records
This log exists to answer one question raised across the Templates, Subscriptions, and Ad Manager screen reviews: the Claude Designs prototype has, in places, designed further ahead than the real backend has decided. CONTRACTS.md (Track B of the approved plan) already specifies a tenant model; Templates.dc.html already implements a real entitlement + lifecycle + widget-security model; Subscriptions.dc.html already designs proration/dunning/refund UI. None of that is wrong to have designed — but before any of it becomes real schema, Edge Functions, or RPCs, the underlying architecture questions need an explicit decision, not an implicit one inherited from whatever the prototype happened to draw.
Why ADRs, not just tracker entries: a QRS-### tracker row is for a bounded bug/debt/risk item. These questions are wider — each has multiple real options, cross-cutting consequences, and a recommendation that needs product sign-off before any migration or Edge Function work starts. That's what an ADR is for. Each ADR below still cross-links the QRS-### rows that triggered it.
Status lifecycle
| Status | Meaning |
|---|---|
| 🟡 Proposed | Drafted with a recommendation; awaiting product/engineering sign-off |
| 🟢 Accepted | Signed off; the recommendation is the plan of record |
| 🔵 Superseded | Replaced by a later ADR (linked) |
| ⚫ Rejected | Considered and explicitly not adopted (reasoning kept for history) |
Log
| # | Title | Status | Depends on |
|---|---|---|---|
| ADR-0001 | Tenancy & identity model (Organization above Workspace) | 🟡 Proposed | — |
| ADR-0002 | Subscription & billing system of record (PSP vs in-house) | 🟢 Accepted — Razorpay confirmed 2026-07-20 | ADR-0001 |
| ADR-0003 | Template system scalability (rendering engine, import contract, ad-slot schema) | 🟡 Proposed | — |
| ADR-0004 | Advertising & sponsored placements platform scope | 🟡 Proposed | ADR-0003 |
| ADR-0005 | Affiliate, referral & growth rewards program (cash commission + viral/gamified growth) | 🟡 Proposed, revised 2026-07-19 | ADR-0001, ADR-0002 |
| ADR-0006 | RBAC & authorization model (platform role vs tenant role, capabilities-as-code) | 🟢 Accepted (D1–D3 signed off 2026-07-19) | ADR-0001, ADR-0003 |
| ADR-0007 | Feature entitlements & subscription gating (freemium; domain × tier × feature command center) | 🟡 Proposed, revised 2026-07-20 | ADR-0002, ADR-0006 |
| ADR-0008 | Email & notifications (ZeptoMail transactional + Zoho Campaigns promotional) | 🟢 Accepted (OTP = email; split confirmed 2026-07-20) | — |
| ADR-0009 | Business-vertical archetype platform (metadata-driven verticals; new vertical = config, not code) | 🟡 Proposed (direction endorsed 2026-07-20) | ADR-0001, ADR-0007 |
| ADR-0010 | Analytics & reporting data architecture (command-center read model; canonical metrics + rollups) | 🟡 Proposed (direction endorsed 2026-07-20) | ADR-0009, ADR-0007 |
| ADR-0011 | Frontend platform architecture (surface-matched: web-DOM for public+admin, universal Expo/RN for the merchant app) | 🟢 Accepted (hybrid signed off 2026-07-20; SEO uncompromised) | ADR-0009 |
| ADR-0012 | Monorepo structure, package boundaries & documentation standard (npm workspaces; bounded packages; README-everywhere) | 🟢 Accepted (greenfield rebuild; finalized 2026-07-20) | ADR-0011, ADR-0009, ADR-0007 |
| ADR-0014 | Public data exposure & least-privilege grants (RLS filters rows not columns → column-level grants for anon; every policy names its TO audience) | 🟢 Accepted (adopted 2026-07-25 after a live production exposure) | ADR-0006, ADR-0001 |
| ADR-0015 | Design governance & drift reconciliation (asymmetric: tokens/primitives design-first, screens code-first; record at divergence, sync at the release boundary) | 🟢 Accepted (adopted 2026-07-26) | ADR-0011, ADR-0012 |
| ADR-0016 | Reminders domain model (rule + sparse exception rows, occurrences computed not stored; legacy tables archived not dropped after the pre-flight found 11 rows on Prod; the iOS 64-pending cap shapes the model) | 🟢 Accepted (adopted 2026-07-27) | ADR-0007, ADR-0009, ADR-0012, ADR-0014 |
| ADR-0017 | Cross-platform parity automation (layered by what each layer can observe: hooks + static gate shipped, native probe specified; a green layer is never reported as parity) | 🟡 Accepted, phased (layers 0–1 adopted 2026-07-27) | ADR-0011, ADR-0015 |