From ecbb9e94aaa2a1ce966f25a43213aab1f1588fe8 Mon Sep 17 00:00:00 2001 From: implementer Date: Mon, 31 Aug 2026 00:52:47 +0000 Subject: [PATCH] docs(adr): add repository ADR index mirroring the wiki ADR-Index page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds docs/adr/README.md as the in-repo copy of the ADR index (§70 of the wiki ADR-Index page), including the "ADR-006 | Kysely contained inside DB adapter" entry, the §46 six-sections mandate, the §71 architectural fitness tests and the §68 architecture review gates. Committed ADRs in docs/adr/ must record a decision that matches their §70 row; the wiki page remains the canonical index. --- docs/adr/README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 docs/adr/README.md diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..82259bb --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,65 @@ +# ADR index (§70) + +Repository copy of the ADR index from the wiki ADR-Index page (§70): the +canonical list of architectural decisions, committed or planned. Every ADR +committed to `docs/adr/` must record a decision that matches its row in +section 70; the wiki page remains the canonical index. + +| ADR | Decision | +|---|---| +| ADR-001 | Modular monolith | +| ADR-002 | Node.js 24 LTS runtime | +| ADR-003 | TypeScript 6.0.3 pending TS7.1 ecosystem review | +| ADR-004 | Fastify 5 HTTP runtime | +| ADR-005 | PostgreSQL 18 sole canonical DB | +| ADR-006 | Kysely contained inside DB adapter | +| ADR-007 | React SSR for public rendering | +| ADR-008 | React/Vite admin | +| ADR-009 | Zero-JS public baseline | +| ADR-010 | Client-island model for optional public interactivity | +| ADR-011 | JSON Schema + TypeBox + Ajv validation | +| ADR-012 | EPPP Extension API hides framework internals | +| ADR-013 | Node/Amber is a theme extension | +| ADR-014 | Blog is a first-party content extension | +| ADR-015 | Versioned block documents | +| ADR-016 | Versioned page composition | +| ADR-017 | Extension-owned migrations/tables | +| ADR-018 | Docker Compose primary installation | +| ADR-019 | Opaque DB-backed admin sessions | +| ADR-020 | Separate anonymous preference identity | +| ADR-021 | Local media storage through storage port | +| ADR-022 | PostgreSQL jobs before external broker | +| ADR-023 | No Redis initially | +| ADR-024 | No microservices initially | +| ADR-025 | Trusted build-time executable extensions in v1 | +| ADR-026 | Exact dependency pinning + controlled upgrade lanes | +| ADR-027 (v1.1) | `core.markdown` block restores Markdown authoring inside the block model | +| ADR-028 (v1.1) | Hardened outbound fetch as a core service; extensions never fetch directly | +| ADR-029 (v1.1) | Embed provider allowlist enforced in renderer and generated CSP | +| ADR-030 (v1.1) | Native server-side SVG charts and diagrams with an accessibility contract | +| ADR-031 (v1.1) | Theme renaming replaces trademark references | +| ADR-032 (v1.1) | Day-one byte budgets; latency targets from measurement | + +Every ADR contains: Context, Decision, Alternatives, Consequences, Operational +impact, Revisit trigger (§46 E01-S01). + +## Architectural fitness tests (§71) + +- **Add Ledger/Paper:** create `theme-paper` extension → register + manifest/tokens/assets → optionally override renderer slots → tests → + include in build. Failure = editing Home/Post domain, core DB, auth, or + `if (theme === "paper")` in core. +- **Add Reading:** create `org.eppp.reading` → migrations → public route → + admin contribution → Home section → settings → job(s) → content/block + contributions. Failure = core learning seam/half-life/bookmark/link-health + semantics. + +## Architecture review gates (§68) + +Gate A (end Sprint 1): publish a real post without core becoming +blog/Amber-specific. Gate B (end Sprint 3): add a Home feature as an extension +with no core edits. Gate C (end Sprint 4): a radically different theme runs +without changing content/business logic. Gate D (end Sprint 5): visitor +preference persists without coupling to auth or theme storage. Gate E (before +public SDK): Extension API v1 proven enough to maintain. Gate F (Reading): +Reading owns its whole domain without `if (readingEnabled)` in core.