Heritage Docs

Appearance

0020 — Sister Community Integration ​

Status: Accepted (2026-06-18 — owner accepted during ADR review)

Date: 2026-06-17

ADO work item: AB#3102

Deciders: Kristopher Turner (platform owner)

Context ​

Heritage Virginia is a single, closed congregation. Every architectural decision to date assumes exactly one community: one membership roll, one minister-approval gate, one set of RBAC roles, one data store (ADRs 0003, 0006, 0007). That model is intentional and correct for the immediate build.

The platform strategy identifies a far-future signature feature — Sister Community Integration (Epic AB#3078, Feature AB#3102) — that would allow distinct sister congregations or fellowships to interoperate selectively: sharing selected events, announcements, or directory entries across community boundaries while each congregation retains its own closed membership, its own minister-approval workflow, and its own RBAC space. This is a Phase 7 aspiration; it will not be built for many iterations.

The risk of waiting until Phase 7 to think about this is that the data model ships without any notion of community ownership, making the feature prohibitively expensive to retrofit. A narrow set of decisions must be made now:

  1. Every data record must carry a community/tenant key from the start so records can be scoped, filtered, and shared without schema surgery later.
  2. The federation mechanism, when built, must stay inside the existing API-first / api-client boundary (ADR 0008); it must not introduce direct database coupling between deployments.
  3. Identity and RBAC must remain per-community; cross-community access is a granted, scoped permission — not a shared account.

This ADR does not decide how federation will be implemented (single multi-tenant instance versus federated instances versus a broker service). That choice carries enough unknowns — community count, data residency preferences, cost profile — that it is deferred to a fuller ADR at Phase 7 build time. This ADR records the intent, the boundary constraints, and the one near-term action (the tenant key) that must be honoured during the Phase 1 platform build.

This is a planning and architecture decision. It introduces no code.

Decision ​

We will reserve a communityId tenant key on every data entity from the initial schema; treat each congregation as a fully isolated community by default; and, when Sister Community Integration is eventually built, federate it exclusively through the platform API (api-client + shared-types) with cross-community access governed by scoped, server-side RBAC grants — never by shared accounts or direct inter-deployment database access.

Architectural boundaries ​

Community isolation is the default. A member belongs to exactly one home community. A record (event, announcement, directory entry, media asset) is owned by exactly one community. Absence of an explicit sharing grant means the record is invisible to all other communities.

The communityId key is required in the data model from Phase 1. It does not need to be exercised by federation logic in early phases; it exists so that every query can be community-scoped and so that opt-in sharing can be layered on top without schema migration. The Phase 1 platform build (Epic AB#3074) must include this column on all principal tables.

Federation goes through the API, not the database. When content is shared across communities, the mechanism is an API call (authenticated, rate-limited, audited) against the owning community's platform instance — consistent with ADR 0008. No deployment exposes its database to another deployment. No feature reads directly from a remote community's data store.

Member PII does not cross community boundaries by default. Explicitly published content (an event, an announcement marked shareable) may be surfaced to a partner community. A member's profile, contact information, family-group structure, and child-account data are never exported unless that member grants explicit consent — a consent model to be designed in the Phase 7 ADR.

Identity stays per-community. A member who belongs to Heritage Virginia does not automatically receive any access to a sister community's data. Cross-community access is a named, scoped RBAC grant issued by both communities' ministers or administrators (ADR 0006). A member does not hold a super-community account; they hold a home-community account that may accumulate additional community grants.

The federation implementation is deferred. Whether the platform runs as one multi-tenant instance (shared schema, communityId partitioned), as federated single-tenant instances that call each other's APIs, or as a broker-mediated hub is not decided here. The deferred decision must be revisited before any Phase 7 implementation begins and must result in a new ADR.

Alternatives considered ​

OptionProsConsWhy not chosen
Tenant-keyed data + API-federated sharing (chosen)Preserves closed-community model; no schema retrofit needed; consistent with ADR 0008 API-first constraint; privacy boundary is clearRequires communityId discipline from Phase 1; federation design still deferred— chosen
One large shared community (all congregations, single membership)Simpler data modelDestroys the per-congregation closed membership, minister-approval, and RBAC model that defines the platform; no congregation-level autonomyRejected — contradicts the foundational closed-community guarantee
Direct database sharing between deploymentsNo API overhead for cross-community readsBreaks API-first (ADR 0008); exposes raw schema; no audit trail; coupling prevents independent deployments; privacy boundary unenforceableRejected — incompatible with ADR 0008 and privacy requirements
Full multi-tenant SaaS re-architecture nowSolves federation in one passPremature; community count and data-residency needs are unknown; re-architecting ADRs 0004, 0007, 0008 before the platform ships is unacceptable risk and costRejected — deferred; reserve the tenant key and revisit at Phase 7
No tenant key until Phase 7No extra column to manageSchema retrofit across all tables at Phase 7 is high-cost and high-risk; likely requires a data migration on a live production databaseRejected — cheap to add now, expensive to add later

Consequences ​

Positive ​

  • The single near-term action (communityId on all tables) costs almost nothing at Phase 1 and eliminates a potentially expensive schema migration at Phase 7.
  • Each congregation retains full autonomy: its own membership roll, minister approval gate, RBAC space, and data — regardless of whether federation is ever activated.
  • Sharing is always explicit and auditable; the default is no cross-community visibility, which is the correct privacy posture for a faith community.
  • The deferred federation decision remains open to the options that best fit conditions at Phase 7 (cost, community count, data residency, cloud constraints).

Negative / trade-offs ​

  • Every Phase 1 table must carry communityId even though it will be a constant (one community) for years. Minor schema overhead; justified by the retrofit cost avoided.
  • The Phase 7 ADR carries significant design weight — it will need to choose between multi-tenant instance models, federated API calls, broker patterns, and consent flows. That work is not trivial and is not funded by this ADR.
  • Developers must apply the communityId filter discipline in every query from day one or the isolation guarantee leaks silently. Lint rules or a query-builder abstraction should enforce this.

Risks ​

  • Tenant key omission — a table is added without communityId and later becomes a privacy vector. Mitigation: the Phase 1 schema review checklist must include communityId as a required column on all principal entities; the schema ADR (Phase 2) will codify this.
  • Premature federation — a Phase 3–6 feature team attempts to wire up sister-community sharing before the federation ADR exists, creating an ad-hoc and likely inconsistent implementation. Mitigation: this ADR explicitly marks Sister Community Integration as Phase 7; no feature Epic should reference AB#3078/AB#3102 as a dependency before the deferred ADR is Accepted.
  • Consent model gaps — when federation is designed, the consent and data-export model for member PII may conflict with privacy regulations (state law, COPPA for minors). Mitigation: the Phase 7 ADR must include a privacy-and-consent design section; the security audit (S1–S8) should flag cross-community PII flows as a track to revisit.
  • Identity confusion — a member with grants in multiple communities presents a complex UX and token-management challenge. Mitigation: the home-community account + additional grants model is the starting assumption; the Phase 7 ADR must design the UX and token scope explicitly.

References ​

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner