---
project: feed-manager
author: mattbeswick
date: 2026-02-24
status: approved
---

# Feed Persistence and Approval Workflow (V1)

## Context
`feed-manager` currently exports a valid Shopify variant feed for `rooflights` directly to XML.

The next phase must preserve feed optimizations across Shopify updates while still allowing selected fields (for example pricing and stock status) to flow through automatically. Content-sensitive fields (for example titles/descriptions/categories) must be reviewed before publication.

This requires moving from direct source->feed export to a persisted, policy-driven enrichment and approval workflow with a minimal multi-user web UI and scheduled sync operations.

## Requirements
- REQ-1: Implement a local MySQL-backed persistence model for:
  - raw Shopify variant snapshots
  - field-level diffs per sync run
  - pending approvals
  - approved enriched values used for export
  - audit logs
- REQ-2: Add field-level policy routing with default matrix:
  - auto-pass-through: `price`, `availability`, `sale_price`, `sale_price_effective_date`
  - approval-required: all other mapped feed fields
- REQ-3: Implement sync run processing that:
  - pulls Shopify source data
  - computes field-level changes against persisted state
  - auto-applies pass-through fields
  - queues approval-required fields
  - records run metadata and outcomes
- REQ-4: Export feed XML from persisted enriched state (not raw source payload), maintaining existing XML validity and GMC compatibility.
- REQ-5: Build V1 authenticated web UI with pages:
  - `Login`
  - `Sync Runs`
  - `Pending Approvals` (default review surface)
  - `Product Detail` with optional field-level drill-down
  - `Audit Log`
- REQ-6: Default reviewer workflow is product/batch accept actions from pending lists; users can drill into field-level review when needed.
- REQ-7: Implement auth/role pattern aligned with `prism` framework conventions (same auth framework), but using a separate feed-manager database.
- REQ-8: Add scheduled sync capability via cron with script-level frequency control.
- REQ-9: Capture immutable audit records for auto-policy actions and user decisions (who, when, what, before/after, reason/source).
- REQ-10: Keep reusable logic in shared `feed-manager` code and retain client-specific configuration under `clients/<client>/`.

## Constraints
- PHP remains the implementation language.
- Use local MySQL for V1 persistence; no production hosting concerns in this spec.
- `feed-manager` must remain standalone from `prism` data stores (separate DB), while reusing auth framework patterns.
- Scheduled syncs must be operable using cron and script-level frequency controls.
- V1 scope includes a minimal approval UI, not full admin suite.

## Acceptance Criteria
- [ ] AC-1: `feed-manager` has a local MySQL-backed persistence layer for raw Shopify snapshots, field-level diffs, approvals, and final enriched values.
- [ ] AC-2: Field policy matrix is configurable and active with defaults: `price`, `availability`, `sale_price`, `sale_price_effective_date` = auto-pass-through; all other mapped fields = approval-required.
- [ ] AC-3: Running a sync creates a traceable sync run record, computes field-level diffs vs current persisted state, and applies policy routing (auto-applied vs pending approval).
- [ ] AC-4: Approval UI supports batch/product-level accept as default workflow, with optional field-level drill-down per product.
- [ ] AC-5: Approved values persist across subsequent Shopify syncs unless superseded by policy-allowed auto-pass-through fields or explicit reviewer action.
- [ ] AC-6: Exported XML is generated from persisted enriched state (not direct raw Shopify payload) and remains valid RSS 2.0 + Google namespace.
- [ ] AC-7: V1 web app includes authenticated pages: `Login`, `Sync Runs`, `Pending Approvals`, `Product Detail` (field-level review), and `Audit Log`.
- [ ] AC-8: Authentication/authorization uses the same framework/pattern as Prism (delight-im/auth style), implemented against a separate feed-manager DB.
- [ ] AC-9: Scheduled sync execution is supported via cron with script-level frequency control and run logging.
- [ ] AC-10: Every approval/rejection/change action is audit-logged with user, timestamp, entity, field, old/new values, and decision source (auto-policy vs user).

## Out of Scope
- Full admin suite (user management, role configuration, system settings UI) in this spec.
- Advanced optimization transforms (category intelligence, custom-label scoring, rewrite rules).
- Multi-client rollout beyond `rooflights`.
- AWS deployment and production hardening.

## Affected Areas
- `feed-manager/src/Integrations/Shopify/` (sync ingestion updates)
- `feed-manager/src/Application/` (diffing, policy routing, approval orchestration, export state assembly)
- `feed-manager/src/Repositories/` (new MySQL repository layer)
- `feed-manager/src/Auth/` or equivalent auth bootstrap layer aligned to Prism framework pattern
- `feed-manager/src/Web/` or page/controller layer for approval UI
- `feed-manager/bin/` (sync/export/review/scheduler scripts)
- `feed-manager/clients/rooflights/` (client policy/config defaults)
- `feed-manager/migrations/` (new schema)
- `feed-manager/tests/` (unit + integration coverage for diffing/policies/approval persistence)

## Notes
- Default reviewer UX is optimized for speed (product/batch accept), with field-level controls available per product.
- Full admin suite is planned immediately after this spec as the next milestone.
- Suggested near-term follow-on specs:
  - attribute expansion (`google_product_category`, `product_type`, `item_group_id`, `custom_label_*`)
  - priority scoring/labeling