Epic: Author detailed ADRs (platform and per-feature) — Phase 0 &ZeroWidthSpace;

ADO reference content — historical. This file captured the draft description, scope, and acceptance criteria for the Phase 0 architecture/ADR Epic. The authoritative item is ADO Epic AB#3154, now CLOSED (2026-06-18). Retained as a record of what Phase 0 covered.

Epic overview — CLOSED (2026-06-18); addendum 2026-06-21 &ZeroWidthSpace;

All architectural decisions resolved. ADRs 0001–0028 all Accepted. Phase 1 (Build Platform, AB#3074) is unblocked. No ADR remains Proposed; the decision layer is locked.

ADRs 0025–0029 added 2026-06-21 (infrastructure, domain, design tooling, subdomain model, CI/CD auth):

ADR 0025 — infrastructure location, naming, and hosting
ADR 0026 — production domain (heritageva.app), amended by ADR 0028
ADR 0027 — Claude Design + @hch/ui; resolves background token to #F5F6F8
ADR 0028 — per-portal subdomains + Cloudflare Universal SSL (free wildcard); amends 0026 + 0008
ADR 0029 — CI/CD Azure authentication: user-assigned managed identity + OIDC (no stored secrets)

Core decisions locked:

Monorepo + three-layer structure → ADR 0001
Mobile: React Native + Expo → ADR 0002
Auth: Clerk (Apple + Google social login, no Entra for end users) → ADR 0003
CI/CD: GitHub Actions; Web app hosting: Azure SWA Free — apex heritageva.app (HTTPS-only) + per-portal subdomains via Cloudflare Universal SSL free wildcard; installable PWA; no public/marketing site → ADR 0004, ADR 0028
Compute: Azure Container Apps; Database: PostgreSQL (portable) → ADR 0024 (supersedes ADR 0004's Azure Functions + Azure SQL)
Observability: App Insights + Log Analytics + Azure Monitor + auth-provider logs → ADR 0005
RBAC: Two planes; six canonical roles; server-side enforcement → ADR 0006 + ADR 0023
Account model: Single Users table, nullable email, parent-managed child credentials, FamilyGroups, Announcements → ADR 0007
SMS: Twilio (provider-neutral adapter); email: SendGrid → ADR 0013
Platform composition + per-feature + admin/portal ADRs → ADRs 0008-0022.

MVP scope: resolved — the platform, delivered fully, first (Epic AB#3074); every other Epic is a client of it.

Scope (as delivered) &ZeroWidthSpace;

ADRs authored (one ADO Feature per ADR; all Accepted):

ADR 0001-0007 — structure, mobile, auth, cloud/hosting stack, observability, two-plane RBAC, account & family-group identity.
ADR 0008 — platform composition.
ADR 0009-0020 — per-feature, in delivery-priority order: iOS, Sermons & Music Hub, Calendar, Announcements, Messaging & Notifications, Android, Homeschool (two tiers), Marketplace, Small Groups, Pony Express, Ride Share, Sister Community.
ADR 0021-0024 — Admin & Ministry Portal, Family Portal, Communications authoring & approval (6th RBAC role comms_author), Cloud portability & provider abstraction (Postgres + Container Apps).

Schema reconciliation (completed):

Aligned database/schema.sql to the six Main-Hub RBAC roles in docs/internal/overview/ministry-leadership-overview.md.
Nullable Users.Email (children have no email); required Users.Phone (adults).
Added Announcements table (one-way broadcast, no replies).
Extended ApprovalWorkflow to gate spouse-add and content submission.

Security gaps designed (HIGH items from CAF/WAF audit):

S1: Data protection and COPPA — classification, encryption-at-rest, TLS, retention/deletion, verifiable-parental-consent flow (docs/internal/design/security-high-items-design.md).
S2: Trust and physical safety — Pony Express/Ride Share/in-person events model documented; deep design deferred to those phases.
S3: Content moderation — collapsed into the approval workflow (no user replies → no unmoderated user content).
S4: CLOSED — notifications providers decided (Twilio SMS + SendGrid email).

De-risk on paper (before Phase 1):

Integration risks for the chosen stack (auth → account/family → calendar) were surfaced and resolved in the ADRs and design notes — documentary de-risking, no throwaway proof-of-concept code.

Acceptance criteria (met) &ZeroWidthSpace;

Every architectural decision has a merged, Accepted ADR in docs/internal/adr/ before Phase 1 work begins. ✅
database/schema.sql reflects the reconciled six-role RBAC model, nullable email, required phone, Announcements table, and extended ApprovalWorkflow. ✅
Integration risks for the chosen stack are documented and resolved in ADRs/design notes (no POC code). ✅
Security items S1-S4 have design documents or ADR sections addressing them. ✅
The pmo/platform-strategy.md decisions section reflects each decision as Accepted. ✅

Priority and timing &ZeroWidthSpace;

ADO Priority: 2 (blocked all Phase 1 and later work)
Phase: 0 — COMPLETE
ADO Epic: AB#3154 — Closed (2026-06-18)

Out of scope (was, and remains) &ZeroWidthSpace;

Implementing any production infrastructure (Phase 1, AB#3074).
Building any user-facing features (Phase 2+).

"Unless the Lord builds the house, the builders labor in vain." — Psalm 127:1