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

# Rooflights Shopify Variant Feed Export (V1)

## Context
A new `feed-manager` project is being created to manage ecommerce product feeds before they are submitted to Google Merchant Center (GMC).

The first deliverable is a single-client proof of concept for `rooflights`: pull product/variant data from Shopify and generate a valid XML product feed file on local disk. This phase explicitly focuses on raw extraction and XML generation, without transformation pipelines, DB persistence, or incremental syncing.

## Requirements
- REQ-1: Create a new standalone PHP project scaffold under `feed-manager/` with reusable shared code and a client-specific area at `feed-manager/clients/rooflights/`.
- REQ-2: Implement Shopify integration in shared code (not client-locked) using Shopify Admin API credentials from environment/config.
- REQ-3: Export feed entries at variant level (one XML item per sellable variant).
- REQ-4: Generate a Google Merchant-compatible XML feed file at a local path for `rooflights`.
- REQ-5: Include core GMC attributes for each variant item: `id`, `title`, `description`, `link`, `image_link`, `availability`, `price`, `brand`, `condition`, and `gtin`/`mpn` when available.
- REQ-6: When both GTIN and MPN are missing, set `identifier_exists` appropriately to remain GMC-compliant.
- REQ-7: Do not persist Shopify product data to MySQL in this phase.
- REQ-8: Provide one command entrypoint to run export on demand for `rooflights`.

## Constraints
- PHP is the implementation language for this project.
- MySQL is planned for the wider system, but this spec forbids DB persistence in V1.
- Keep reusable integration logic in shared `feed-manager` code; keep client configuration/output in `feed-manager/clients/rooflights/`.
- Use Shopify authentication that scales for multiple stores (token-based Admin API credentials in config/env per client).
- Emit XML in Google’s RSS 2.0 structure with the `g:` namespace for attributes.
- Generate a full feed snapshot per run (no delta/incremental behavior).

## Acceptance Criteria
- [ ] AC-1: Running the export command for `rooflights` produces an XML file at a deterministic local output path.
- [ ] AC-2: The output file is well-formed XML and uses RSS 2.0 + Google namespace (`http://base.google.com/ns/1.0`).
- [ ] AC-3: The export contains one `<item>` per eligible Shopify variant from the source catalog.
- [ ] AC-4: Every item contains GMC-required core fields in valid format (`g:id`, `g:title`, `g:description`, `g:link`, `g:image_link`, `g:availability`, `g:price`, `g:brand`, `g:condition`; plus `g:gtin`/`g:mpn` when present).
- [ ] AC-5: Items missing both GTIN and MPN are emitted with compliant identifier signaling (for example `g:identifier_exists`), not silently dropped.
- [ ] AC-6: No MySQL tables are written to or read from during export.
- [ ] AC-7: Failures in Shopify retrieval (auth/network/API errors) exit with a non-zero status and a clear error message.

## Out of Scope
- Transformation/enrichment rules (title rewriting, category mapping, custom labels, pricing logic).
- Incremental syncs, change detection, and scheduling.
- Google Merchant Center API submission.
- Multi-client onboarding beyond `rooflights`.
- Deployment to AWS.

## Affected Areas
- `feed-manager/` (new project root and PHP runtime/dependency setup)
- `feed-manager/src/Integrations/Shopify/` (shared Shopify API client/service)
- `feed-manager/src/Feeds/GoogleMerchant/` (XML feed builder/writer)
- `feed-manager/src/Application/` (export use case orchestration)
- `feed-manager/bin/` (CLI command entrypoint)
- `feed-manager/clients/rooflights/` (client config and output location)
- `feed-manager/tests/` (export integration/contract tests)

## Notes
- Google Merchant Center supports text/XML feeds using RSS 2.0 or Atom 1.0; this spec standardizes on RSS 2.0 for V1 output compatibility.
- Core product data specification references for validation:
  - https://support.google.com/merchants/answer/7052112
  - https://support.google.com/merchants/answer/14987622
- Shopify Admin API should be implemented in a reusable way so additional client folders can be added later without rewriting integration code.