Heritage Docs

Appearance

0016 — Community Marketplace ​

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

Date: 2026-06-17

ADO work item: AB#3095

Deciders: Kristopher Turner (platform owner)

Context ​

Heritage Virginia is a closed, vetted faith community. Members already know and trust one another — they share meals, minister to each other's families, and coordinate shared life across homeschool co-ops, prayer groups, and community events. A natural extension of that existing trust is the ability for members to post items for sale or trade, and for member-operated businesses and vendors to make themselves visible to the congregation.

The platform strategy (Epic AB#3076; Feature AB#3095) calls for a Community Marketplace as a member-only classifieds and vendor-directory layer. The core design constraint is explicit: this is a listings service, not a commerce platform. There are no transactions, no payments, no checkout, no escrow, and no payment-processor integrations. The marketplace surfaces what is available and from whom; the actual exchange — money, goods, services — happens between members directly, the same way it has always happened in a close-knit community.

This constraint is a ministry choice, not merely a technical one. Introducing a payment layer would shift the tone from community connection to commercial transaction, add PCI-DSS obligations, and require ongoing payment-processor cost and liability — none of which is appropriate for a small fellowship operating on a free/cheap infrastructure budget (established across ADRs 0001–0008).

Because every member has passed through the minister-approval workflow (ADR 0007) and holds a vetted identity, the closed membership itself is the primary trust-and-safety control. There is no anonymous browsing, no unauthenticated listing creation, and no path for an outside party to place an item or contact a seller. This significantly narrows the moderation surface compared with a public marketplace.

Security audit S2 (trust & safety) applies to the Marketplace. The mitigating factor — that membership is closed — reduces S2 scope to a member-facing report/flag path and basic listing moderation by community managers. S2 re-opens at its full scope if a public marketplace (visible to non-members) is ever introduced. That question is deferred; this ADR covers the member-only model only.

The feature composes on the platform as defined in ADR 0008: listing data lives in Azure SQL, listing images in Azure Blob Storage (ADR 0004), all business logic is enforced in apps/api, and every client (web, iOS, Android) reaches the feature only through the typed api-client SDK. RBAC is enforced server-side per ADR 0006.

Decision ​

We will implement the Community Marketplace as a member-only listings service — classified items and member-business/vendor directory entries — with browse, search, category filtering, and member reviews/ratings, delivered as an apps/api feature slice behind full RBAC-gated access; no payment, checkout, or transaction capability will be included now or until a separate ADR explicitly lifts that constraint.

Listing types ​

TypeDescription
Classified itemA member offers a specific item (goods, household, homeschool materials, etc.) for sale, trade, or giveaway. Includes title, description, asking price or "make an offer / free", category, condition, photos, and member contact info visible to signed-in members only.
Member business / vendorA member or member-operated business posts a persistent directory entry: business name, description, service categories, contact information, and photos. Functions as a congregation-visible yellow-pages entry, not a storefront.

Feature capabilities ​

  • Browse & search — members can browse all active listings by type and category; full-text search across title and description; filter by category and listing type.
  • Categories — a seeded, admin-managed list (examples: Furniture & Home, Clothing & Textiles, Homeschool Materials, Tools & Equipment, Books & Media, Services, Vehicles, Free/Giveaway, Business & Vendor). Categories are a platform configuration table, not hard-coded.
  • Listing images — stored in Azure Blob Storage (ADR 0004) following the same media primitives provided by platform shared services (ADR 0008, responsibility 4). Images are served via pre-signed or CDN-backed URLs; they are never embedded as base64.
  • Member reviews & ratings — members may leave a star rating and short text review on a classified seller's record or a vendor/business entry. One review per member per target. Reviews are visible only to signed-in members. Ratings aggregate to a display score on the listing.
  • Listing lifecycle — create, edit, mark sold/closed, and delete. Expired listings (configurable TTL, default 60 days for classifieds; none for vendor directory) are archived, not hard-deleted.
  • RBAC gating — all Marketplace endpoints require an authenticated, approved member session (ADR 0006). Role minimums: any of the five canonical roles (Member, Family Manager, Community Manager, Staff, Minister) may browse and create listings. Community Manager and above may moderate (hide/remove) listings and reviews. No endpoint is accessible to unauthenticated callers.

Trust & safety (security audit S2) ​

  • Report/flag path — any member can flag a listing or review as inappropriate. Flags queue in a moderation inbox visible to Community Manager and above. This is the primary S2 control.
  • Listing moderation — Community Managers may hide or remove any listing or review without additional workflow. A reason is recorded in the AuditLog (ADR 0005, ADR 0008) for accountability.
  • Closed-membership mitigation — because every account is minister-approved and associated with a real identity (ADR 0007), the probability of bad-actor listings is low. The report/flag path is sufficient for this threat model. No AI content moderation, escrow, identity-verification overlay, or external trust-and-safety service is required at this scope.
  • S2 re-open trigger — if a future decision introduces public (non-member) listing visibility, a new ADR is required and S2 must be fully re-evaluated (anonymous abuse vectors, spam, fraudulent listings, CSAM risk all increase substantially in a public model).

API slice location ​

Per ADR 0008 composition rule, the feature is implemented as:

apps/api/src/features/marketplace/

Shared types in packages/shared-types/src/marketplace.ts. No cross-feature imports.

Alternatives considered ​

OptionProsConsWhy not chosen
Member-only listings, no transactions (chosen)Ministry-appropriate tone; no PCI or payment-processor cost/liability; closed membership is the primary trust-and-safety control; aligns with free/cheap budget constraintMembers must arrange exchange directly; no in-platform purchase convenience— chosen
Full e-commerce with payments and checkoutIn-platform purchase convenience; verifiable transaction recordsIntroduces PCI-DSS scope; requires payment-processor integration (Stripe, etc.) and ongoing fees; clashes with the "listings not transactions" ministry tone; adds liability Heritage Fellowship is not equipped to manageRejected — explicitly out of scope; contradicts ADRs 0004/0008 cost constraints and the ministry principle
Third-party classifieds or marketplace SaaS (Facebook Marketplace, etc.)Zero build cost; feature-rich out of the boxBreaks the closed-community guarantee — a third-party service cannot enforce minister-approval gating or member-only RBAC; member data leaves the platform; inconsistent UXRejected — irreconcilable with the closed-community model (ADR 0007) and data-control principle (ADR 0004)
Public (non-member) listing visibility nowBroader community reach; potential outreach toolRe-opens S2 trust & safety at full scope; creates anonymous-abuse surface; undermines the closed-community value propositionRejected for this ADR; deferred to an open future question requiring a separate ADR and full S2 re-evaluation

Consequences ​

Positive ​

  • Members can connect over goods, services, and local businesses within a trusted, vetted context — an extension of existing community relationships, not a new commercial layer.
  • No payment integration means no PCI-DSS scope, no payment-processor fees, and no checkout liability, keeping the feature within the free/cheap infrastructure budget (ADRs 0004, 0008).
  • The closed membership substantially reduces the moderation burden; a report/flag path and Community Manager role are sufficient for the current threat model.
  • Listing images route through the platform's shared Blob primitives (ADR 0008); no second storage solution is introduced.
  • RBAC gating is inherited from the platform (ADR 0006); the feature adds no novel authorization logic.
  • Vendor/business directory entries give member-operated businesses low-cost visibility inside the congregation — consistent with supporting one another's livelihoods as a community value.

Negative / trade-offs ​

  • Members must arrange payment and exchange outside the platform, which may feel incomplete for higher-value transactions. This is an accepted trade-off given the community context and the ministry tone constraint.
  • Reviews and ratings introduce a reputation layer. Even in a closed community, a negative review can be sensitive. Community Managers must be prepared to moderate disputes carefully; policy guidance (outside this ADR's scope) is advisable.
  • Listing TTL and archival policy add minor operational complexity; defaults (60-day TTL for classifieds) should be reviewed with leadership before launch.

Risks ​

  • Feature scope creep toward payments — future requests to add "pay now" or link to a payment processor should be treated as a new ADR trigger, not a minor enhancement. Mitigation: this ADR is the explicit gate; any payment capability requires a new ADR and PCI/liability review.
  • S2 trust & safety re-open — if a public visibility mode is added without a new ADR, S2 scope expands silently. Mitigation: the "public listings" alternative is formally rejected here; a new ADR is required to reconsider.
  • Review abuse — even in a closed community, reviews can be weaponized in personal disputes. Mitigation: Community Managers have moderation authority; the AuditLog records all moderation actions for accountability. Leadership should establish a light review-dispute policy.
  • Image storage cost — listing photos in Blob Storage are the primary cost vector for this feature. Mitigation: enforce per-listing image limits (e.g., max 8 images, max 5 MB each) and include marketplace Blob usage in the cost-governance budget alerts (ADR 0005).

References ​

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

Heritage Virginia · Owner: Kristopher Turner