Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for Heritage Community Hub. Every significant architectural or tool choice must be captured in an ADR before code depends on it — this is the "Decide before building" gate from the platform strategy.

What is an ADR?

An ADR is a short document that records a single architectural decision: what was decided, why, what alternatives were considered, and what the consequences are. Once accepted, an ADR is immutable — superseding it requires a new ADR that references the old one.

File naming

NNNN-kebab-case-slug.md

Where NNNN is a zero-padded four-digit sequence number. Use the next available number when creating a new ADR.

ADR lifecycle

Status	Meaning
Proposed	Under discussion; not yet decided
Accepted	Decision locked; code may depend on it
Superseded	Replaced by a later ADR (link to it)
Deprecated	No longer relevant

Template

Use 0000-adr-template.md as the starting point for every new ADR.

Index

ADR	Title	Status
0000	ADR template	Reference
0001	Monorepo with three-layer structure	Accepted
0002	Mobile: React Native + Expo	Accepted
0003	Authentication: Clerk + Apple/Google, no Entra for end users	Accepted (Android Google Sign-In path needs Phase 4 verification)
0004	Cloud/hosting stack, CI/CD, and free-tier path	Accepted (compute + DB superseded by 0024)
0005	Observability model	Accepted (tooling TBD; stack resolved by ADR 0024 — Container Apps + Postgres)
0006	Two-plane RBAC with reconciled role model	Accepted (extended by 0023 — 6th role comms_author)
0007	Account and Family-Group identity + approval workflow	Accepted (schema changes in Phase 2)
0008	Platform composition — how the core pieces fit together	Accepted
0009	iOS app delivery	Accepted
0010	Sermons & Music Hub	Accepted
0011	Community Calendar	Accepted
0012	Announcements (one-way broadcast)	Accepted
0013	Notification transport (channels)	Accepted (SMS = Twilio, provider-neutral behind SmsProvider adapter)
0014	Android app delivery	Accepted
0015	Homeschool Education Portal	Accepted
0016	Community Marketplace	Accepted
0017	Small Groups & Ministries management	Accepted
0018	Pony Express Delivery Network	Accepted
0019	Community Ride Share & Travel	Accepted
0020	Sister Community Integration	Accepted
0021	Admin & Ministry Portal	Accepted
0022	Family Portal	Accepted
0023	Communications authoring & approval workflow (adds 6th RBAC role comms_author)	Accepted
0024	Cloud portability & provider abstraction (DB = Postgres; compute = container)	Accepted
0025	Infrastructure location, naming, and hosting	Accepted
0026	Production domain and DNS strategy (heritageva.app)	Accepted (amended by ADR 0028)
0027	Web frontend & design-system tooling (Claude Design + @hch/ui)	Accepted (amended by ADR 0031)
0028	Per-portal subdomain addressing & TLS (Cloudflare Universal SSL)	Accepted
0029	CI/CD Azure authentication: managed identity + OIDC	Accepted
0030	Progressive feature enablement (feature registry — dark until onboarded)	Accepted
0031	Code-first design workflow and cross-platform delivery (amends ADR 0027)	Accepted (amended by ADR 0033 — responsive values ratified)
0032	Member Directory: field visibility and role-based access	Accepted (revised 2026-06-22 — corrected to Manage-button + kid-birthday-only model)
0033	Platform foundation UI & view inventory (ratifies responsive layout; amends ADR 0031)	Accepted

Process

1. Copy 0000-adr-template.md to NNNN-slug.md.
2. Fill in all sections. Status = Proposed.
3. Open a PR; link it to the relevant ADO work item (AB#<id>).
4. After team review and decision, update status to Accepted and merge.
5. If a decision changes later, create a new ADR with status Accepted and mark the old one Superseded, linking to the new ADR.

ADR authoring status (2026-06-22)

Phase-0 research workstream completed. ADRs 0001–0007 are filled in and accepted — all Phase-0 decisions are locked, and Phase-1 infrastructure scaffolding is unblocked.

Beyond Phase 0 — the full ADR set is authored (0008–0031, every entry in the index above).

• ADR 0008 (platform composition, AB#3155) records how the platform core pieces fit together.
• Per-feature ADRs 0009–0020 cover every delivery feature in delivery-priority order — iOS, Sermons & Music Hub (AB#3156), Calendar, Announcements, Messaging & Notifications, Android, Homeschool, Marketplace, Small Groups, and the three Signature features.
• Admin/portal & portability ADRs 0021–0024 — Admin & Ministry Portal, Family Portal, Communications authoring & approval, and Cloud portability & provider abstraction.
• Infrastructure & toolchain ADRs 0025–0029 — Infrastructure location, naming, and hosting (0025, AB#3675), production domain and DNS (0026, AB#3675), web frontend design-system tooling / Claude Design (0027, AB#3237), per-portal subdomains and Cloudflare Universal SSL (0028, AB#3079), and CI/CD Azure authentication via managed identity + OIDC (0029, AB#3082).
• Platform UX & workflow ADRs 0030–0031 — Progressive feature enablement via feature registry (0030, AB#3692) and code-first design workflow + cross-platform delivery (0031, AB#3237, amends 0027).

Owner acceptance complete (2026-06-22): ADRs 0001–0033 are all Accepted. The full decision layer is locked; code may depend on any ADR. Key decisions and their forward-looking effects:

• 0025 — heritageva CAF/WAF resource naming; HCS-tenant hosting; -eus region suffix.
• 0026 — heritageva.app as production domain; Cloudflare DNS + email routing.
• 0027 — Claude Design is the sole UI tool; @hch/ui is the only import path for design tokens and presentational components in every surface; background = #F5F6F8. Amended by 0031.
• 0028 — per-portal subdomains (*.heritageva.app) routed via Cloudflare Universal SSL (free wildcard) to one SWA; amends ADR 0026 and ADR 0008.
• 0029 — managed identity (OIDC) for CI/CD; no long-lived secrets in GitHub.
• 0030 — feature registry drives UI visibility; un-onboarded features show nothing across web, iOS, and Android; core nav shell (bottom tab bar) always present; AB#3692.
• 0031 — real code (packages/ui/src/) is the source of truth; Claude Design receives mirrored @dsCard HTML mockups, not the other way around; web/PWA is the verified cross-platform path; React Native fidelity through the Claude Design pipeline is deferred to the iOS phase. Amends 0027. Amended by 0033 — responsive layout values (1024 / sidebar 220px / 860px) ratified.
• 0032 — member directory: single detail screen for all roles; adult fields (birthday, anniversary, address, phone, email); kid = birthday only; admin and minister get a "Manage" button → separate management screen. Revised from inline-tier model 2026-06-22.
• 0033 — platform foundation view inventory (~35 views); DesignSync card naming convention; feature ADR "Views: TBA" convention; ratifies responsive layout values. Amends ADR 0031.

Tracked under Epic AB#3154 (ADR authoring) and Epic AB#3074 (Platform build).

See pmo/platform-strategy.md for the full platform roadmap.