Heritage Community Hub — Project Roadmap

Reference document. This file summarises the delivery plan derived from the canonical pmo/platform-strategy.md. Authoritative work items live in Azure DevOps Boards. Phase 0 (Decide) is complete (2026-06-18). All architectural decisions are locked in ADRs 0001-0024, all Accepted (see docs/internal/adr/). Phase 1 (Build Platform, AB#3074) is the current phase.

---

Vision

One faith-centered community platform for Heritage Virginia, delivered on three surfaces from one codebase: a responsive web app, a native iOS app, and a native Android app. All three are clients of a single backend API. Build a feature once on the platform; it appears on every surface.

---

Architecture summary

API-first / headless platform. All logic, data, auth, and rules live behind a single backend API. Web and mobile contain only presentation and client state.

Monorepo structure (decided)

heritage-community-hub/
├── apps/
│   ├── api/       # backend — all features as API endpoints (containerized Node.js)
│   ├── web/       # React + TypeScript client
│   ├── mobile/    # React Native + Expo (iOS + Android)
│   └── landing/   # retired interim placeholder — entry point is apps/web (heritageva.app)
├── packages/
│   ├── shared-types/   # domain types / API contracts
│   ├── api-client/     # typed SDK used by web and mobile
│   ├── shared-utils/   # validation, formatting, RBAC helpers
│   ├── shared-config/  # shared config / constants
│   └── ui/             # design tokens / shared design system
├── infrastructure/     # Bicep IaC (currently empty — Phase 1)
├── database/           # schema, migrations, seeds
└── docs/               # internal (team) + member (in-app) docs, ADRs

apps/* and packages/* are skeleton placeholders, not yet populated with code. They are scaffolded in Phase 1 (AB#3074).

Decisions locked

• Monorepo, layered via workspaces (pnpm + Turborepo) — ADR 0001.
• Mobile: React Native + Expo (one TypeScript codebase → iOS + Android) — ADR 0002.
• Project management: ADO Boards is the single source of truth.
• Code and PRs on GitHub (Heritage-Virginia org); work items in ADO linked via AB#.
• End-user auth: Clerk (Apple + Google social login); no Entra for end users.
• Messaging: one-way broadcast announcements only; no user-to-user replies.
• Marketplace: member-only listings only; no transactions.
• Two-plane RBAC; application authorization enforced server-side.

Decisions locked in Phase 0 (ADRs 0001-0024 — all Accepted)

• CI/CD: GitHub Actions — ADR 0004
• Compute: Azure Container Apps (containerized Node.js API) — ADR 0024 (supersedes ADR 0004 Azure Functions)
• Database: PostgreSQL on Azure Database for PostgreSQL Flexible Server; portable to AWS RDS / GCP Cloud SQL / Supabase as a connection-string swap — ADR 0024 (supersedes ADR 0004 Azure SQL)
• Web app hosting: Azure SWA Free — custom domain heritageva.app (HTTPS-only); installable PWA; opens to sign-in/register; no public or marketing site — ADR 0004
• Infrastructure: HCS Azure tenant / subscription; dedicated resource group rg-heritageva-prod-<region>; CAF/WAF naming with workload token heritageva; DNS in Cloudflare
• Auth: Clerk (Apple + Google social login) — ADR 0003
• Observability: App Insights + Log Analytics + Azure Monitor + auth-provider logs — ADR 0005
• RBAC: Two planes; six canonical roles (member, family_admin, ministry_leader, content_approver, admin, comms_author); server-side enforcement — ADR 0006, extended by ADR 0023
• Account model: Single Users table, nullable email, parent-managed child credentials (Argon2id) — ADR 0007
• SMS provider: Twilio via provider-neutral SmsProvider adapter — ADR 0013
• Cloud portability: abstract compute/DB/storage/secrets; provider swap = config change — ADR 0024
• Per-feature & portal ADRs 0008-0022 — all Accepted (platform composition, iOS, Sermons & Music Hub, Calendar, Announcements, Messaging, Android, Homeschool, Marketplace, Small Groups, Pony Express, Ride Share, Sister Community, Admin & Ministry Portal, Family Portal, Communications authoring).

No ADR remains Proposed. The decision layer is CLOSED.

---

Delivery roadmap — priority order

Forward-looking vision — not a task list. Each delivery phase below is owned by an ADO Epic; the "deliverables" are the Features tracked under that Epic as User Stories and Tasks. No build work is performed from this document. Phases are executed later, from the ADO board.

This is the agreed delivery order (revised 2026-06-17): the platform is first and most important — get it right — and every other Epic is a client of it.

#	Phase	ADO Epic	Priority
0	Decide ✅ COMPLETE (2026-06-18) — ADRs 0001-0024 all Accepted	Author detailed ADRs — AB#3154 (Closed)	done
1	Platform — foundation + all identity, RBAC, member features, signups, family portal	Build Platform — AB#3074	2
2	Apple (iOS) app	Deliver iOS (Apple) App — AB#3077	2
3	Sermons & Music Hub — sermons/video/music, storage, web + mobile streaming, offline download	Deliver Sermons and Music Hub — AB#3137	3
4	Community Calendar & Announcements	Deliver Community Calendar and Announcements — AB#3075	3
5	Messaging & Notifications	Deliver Messaging and Notifications — AB#3138	4
6	Google (Android) app	Deliver Android (Google) App — AB#3139	4
7	Additional features — Small Groups/Ministries, Homeschool, Marketplace, member-posted media (back burner)	Deliver Additional Features — AB#3076	4
7	Signature features — Pony Express, Ride Share, Sister Community	Deliver Signature Features — AB#3078	4

Cross-cutting Epics (also in ADO): planning/docs/repo foundation AB#3150; ADRs AB#3154 (Closed); build-ready foundation documentation AB#3177; documentation accuracy & maintenance AB#3197. (AB#3157 interim landing site is superseded — no public site; retire in ADO.)

Phase 1 — Build Platform · ADO Epic AB#3074

Goal: the platform core every surface and feature depends on — not a thin foundation.

Deliverables (Features tracked in ADO):

• Bicep IaC for all free-tier Azure resources (infrastructure/); dev / test / prod environments.
• CI/CD pipeline (GitHub Actions); enforces lint + test + build + Snyk + secret scanning.
• Key Vault integration — all secrets via KV, none in repo.
• Observability baseline: Application Insights SDK in web, API, and mobile.
• Budget alerts and documented free-tier ceilings.
• Scaffold apps/api, apps/web, apps/mobile, and all packages/* workspaces. (apps/landing is a retired placeholder — not deployed.)
• Identity & access: Clerk auth (Apple/Google); member signups + minister approval workflow; sessions; server-side RBAC (six roles); the two-plane model.
• Member & family domain: Account model, Family Groups, the family portal, member profiles, parent-managed child sub-accounts, member directory.
• Core shared services: the API framework; api-client SDK; shared-types; the ui design system; notifications transport; audit logging; file/media storage primitives.
• Core web shell (apps/web): navigation, auth-gated routing, layout, account/profile screens; installable PWA (web app manifest + service worker + icons); hosted at heritageva.app. First usable client and testbed before iOS ships.

Phase 2 — Apple (iOS) app · ADO Epic AB#3077

Native iOS app via React Native + Expo, consuming api-client (shared types, zero logic duplication); push notifications (APNs); offline cache/sync; App Store publishing via EAS Build.

Phase 3 — Sermons & Music Hub · ADO Epic AB#3137

Post weekly sermons (video), videos, and music (audio); inexpensive S3-compatible/Blob storage; web streaming; mobile streaming and offline download; member-only via RBAC; all original community content. Distinct from member-posted media (back burner).

Phase 4 — Community Calendar & Announcements · ADO Epic AB#3075

Primary engagement driver. Community Calendar — events, RSVP, attendance/check-in, month/week/day views, recurring events, role/group visibility, tokenized read-only ICS subscription feed + per-event .ics. One-way Announcements — approver-authored broadcast; no replies; Announcements table.

Phase 5 — Messaging & Notifications · ADO Epic AB#3138

Leadership one-way broadcasts + the notifications service: multi-channel fan-out across SMS (Twilio) + app push + email (SendGrid). Required phone number for adults. No user-to-user chat.

Phase 6 — Google (Android) app · ADO Epic AB#3139

Native Android app from the same React Native + Expo codebase; push notifications (FCM); Google Play publishing via EAS Build.

Phase 7 — Additional features · ADO Epic AB#3076

• Small Groups & Ministries management.
• Homeschool Education Portal — two tiers: Tier 1 Resource & Support Library (all families); Tier 2 High School Program (LMS-like teacher back-end, deferred for deeper design). Parent-managed student accounts, COPPA-compliant, no student self-registration — ADR 0015.
• Community Marketplace — member-only classifieds and vendor/business listings; browse and reviews; no transactions.
• Member-posted media (back burner) — event/wedding/engagement photos, separate from the Sermons & Music Hub.

Phase 7 — Signature features · ADO Epic AB#3078

• Pony Express Delivery Network — route registration, item transport coordination, rider verification.
• Community Ride Share and Travel Coordination — ride requests, route matching, event transportation.
• Sister Community Integration — multi-community event coordination, resource sharing, directory.

Candidate additions (not yet committed): Community Learning Platform, Community Wellness & Support.

---

Feature inventory summary

Cross-cutting platform foundation

• Authentication & Identity — invitation-code registration, multi-step approval, MFA, token-based auth.
• Role-Based Access Control — six roles, per-feature visibility, enforced server-side.
• Audit logging — security and compliance trail.
• Notifications service — email (SendGrid) + SMS (Twilio) + in-app + mobile push, with priority levels.

Main Community Hub

• Sermons & Music Hub (sermons/video/music; member-only streaming + mobile offline download).
• Community Calendar System (primary engagement driver).
• Communication / Messaging — one-way broadcast announcements only.
• Small Groups & Ministries Management.
• Resource Management.
• Member-posted media (back burner).

Homeschool Education Portal — two tiers

• Tier 1 — Resource & Support Library (all families, all ages).
• Tier 2 — High School Program (dedicated; teacher back-end; LMS-like; deferred).

Community Marketplace

• Member-only listings; browse and reviews; no transactions.

Signature / future

• Pony Express Delivery Network, Community Ride Share & Travel, Sister Community Integration.

---

Security gaps to close (before build-ready)

ID	Severity	Item
S1	HIGH	Data protection and COPPA — data classification, encryption-at-rest, TLS, retention/deletion, verifiable-parental-consent flow
S2	HIGH	Trust and physical safety — Pony Express/Ride Share/in-person events: identity verification, report/block, liability/waiver
S3	HIGH	Content moderation — collapses into approval workflow (no user replies)
S4	MED — CLOSED	Notifications providers decided: Twilio (SMS) + SendGrid (email); ADR 0013 Accepted
S5	MED	Mobile client secrets — OAuth PKCE + secure storage + backend-for-frontend
S6	MED	API security baseline — OWASP: server-side validation, rate limiting, CORS, CSRF, output encoding
S7	MED	Vulnerability management — Snyk + Dependabot + CodeQL + secret scanning
S8	LOW/MED	Privacy and legal — Privacy Policy, ToS, GDPR/CCPA/COPPA rights, app-store data-safety labels

---

"For where two or three gather in my name, there am I with them." — Matthew 18:20