# Brand Reviews External Sync Debt TODO

Date: 2026-06-20

Status: deferred technical debt. Do not implement external sync until the source, API access, moderation workflow, and legal/privacy constraints are explicitly chosen.

Scope: plan future ingestion of brand-level testimonials from Google Business Profile and/or Facebook Page into the local Payload `brandReviews` collection. Storefront rendering must continue reading from the local database, not from third-party APIs at request time.

## Current Implementation

- Brand reviews are stored locally in the `brandReviews` collection.
- Homepage rendering uses the `BrandReviews` page-builder block.
- Public frontend only reads published local reviews.
- Admin can create manual brand reviews now.
- Fields already reserved for future sync:
- `source`
- `sourceUrl`
- `externalReviewId`
- `syncedAt`
- `status`

## Locked Decisions

- Reviews in this subsystem are brand/company reviews, not product reviews.
- Do not merge this with product `ratingSummary`.
- Do not fetch Google Business or Facebook reviews directly during homepage render.
- The local Payload database remains the storefront source of truth.
- External reviews must be synced into local records first.
- Admin moderation must happen before synced reviews become public.
- Homepage should only render `status = published`.

## No-Touch Zones

- Do not alter product review/rating logic.
- Do not alter product detail pages.
- Do not add third-party API calls to React Server Components.
- Do not make the homepage depend on Google/Facebook uptime.
- Do not publish imported reviews automatically without a moderation policy.
- Do not store more personal data than required for public testimonial display.

## Required Future Decisions

- Source priority: Google Business Profile, Facebook Page, or both.
- API access model and provider credentials.
- Sync interval.
- Whether imported records default to `draft` or `hidden`.
- Duplicate matching policy using `source + externalReviewId`.
- Whether source links should be shown publicly.
- Whether reviewer avatar images may be stored locally or only referenced.
- Data retention policy for removed/edited external reviews.
- Admin workflow for approve, hide, or edit imported reviews.

## Recommended Future Flow

1. Scheduled job fetches reviews from selected provider.
2. Job normalizes provider response into the local `brandReviews` shape.
3. Existing records are matched by `source + externalReviewId`.
4. New imported records are saved as `draft` or `hidden`.
5. Admin reviews imported content in Payload.
6. Admin publishes approved reviews.
7. Homepage renders only local published reviews.

## Suggested Future Schema Additions

Do not add these yet. They are candidates only.

- `providerRating`
- `providerReviewUpdatedAt`
- `importStatus`
- `moderationNotes`
- `approvedBy`
- `approvedAt`
- `lastSyncError`
- `rawProviderPayload` for admin-only debugging, if legally acceptable

## Verification Needed Later

- Provider API credential smoke.
- Sync idempotency test.
- Duplicate prevention test.
- Admin access test.
- Public API must not expose hidden/draft reviews.
- Homepage must render local published records when provider is offline.
- Build and TypeScript.

## Recommended Next Action

Do not implement sync now.

Next real action should be provider research:

- Google Business Profile API feasibility and terms.
- Facebook Page reviews/recommendations API feasibility and terms.
- Moderation and privacy policy decision.