Project Intake - Xyppy Shopify Merchant App

1) Executive Summary

Xyppy Shopify Merchant App is a Shopify embedded app for merchants and catalog operators who need to edit products and variants in controlled batches. The source repo represents the xyppy.com Bulk Product Editor / BPE app: a Remix + Shopify App Bridge + Polaris application with Prisma-backed job history, Shopify Admin GraphQL mutations, merchant help docs, billing/usage gating, and Render deployment definitions for BPE and BPE-preview.

This fresh intake does not reuse the revoked 1079 project record. It reviews the current source repo as a shipped eCommerce project candidate. The strongest public story is a serious Shopify app build around safe bulk catalog operations: filter, preview, queue, run, verify, and rollback. The operator supplied product screenshots for the Xyppy/Bulk Product Editor interface on 2026-06-04, and the local review packet now uses those real app-surface and help-center screenshots instead of docs-page screenshots.

2) Project Type and Domain

Project category: Shopify embedded app / merchant operations tooling.
Domain: eCommerce catalog operations, bulk product editing, Shopify App Store readiness.
Primary users: Shopify merchants, agencies, catalog managers, and internal app-review operators.
Public status recommendation: shipped, per operator confirmation and public product/support surfaces.
Trail recommendation: ecommerce.

3) Repository and Live URLs

Source repo: https://github.com/maggielerman/shopify-bulk-editor-app
App Store Listing: https://apps.shopify.com/bulk-product-editor-1
xyppy.com: https://www.xyppy.com/
Local source path: /Users/maggielerman/Github/shopify-bulk-editor-app
Render production service from render.yaml: BPE.
Render preview service from render.yaml: BPE-preview.
Runtime check result during intake: the preview service returned 404; the production service did not return promptly and was stopped after a long wait. Treat runtime route verification as unresolved.
Docs surface inspected from built VitePress output under docs/.vitepress/dist/.
Product screenshots supplied by the operator from the Xyppy/Bulk Product Editor interface on 2026-06-04.

4) Product/User Journey Summary

The merchant-facing help docs describe the core journey as:

Install the embedded Shopify app.
Open Bulk Edit.
Build a product or variant filter with AND/OR/NOT logic, product fields, variant fields, collections, vendors, product types, and metafields.
Preview counts, matching products, and before/after changes before running.
Run the edit as a background job that respects Shopify API limits.
Review Job History for queued/running/completed/failed state, warnings, CSV exports, duplicate actions, and rollback where supported.
Use billing/usage surfaces to understand plan limits, rollback windows, saved filters, saved templates, and job concurrency.

The current app intentionally presents a safer single-action MVP. Multi-action stacking is documented as planned future work rather than current behavior.

5) Architecture and Stack Summary

App framework: Remix on React 18, with Shopify App Bridge and Polaris.
Shopify API integration: @shopify/shopify-app-remix, Admin GraphQL, App Bridge embedded auth, mandatory privacy/uninstall webhook routes.
Data layer: Prisma with Postgres/Neon for sessions, jobs, usage, synced reference data, and retained history.
Job execution: server-side bulk job models, job queue service, Shopify mutation helpers, history retention, and rollback support for stored before-values.
AI/help layer: app/routes/app.chat.tsx and app/services/chatAssistant.server.ts provide an authenticated AI help endpoint without storing conversation history beyond the session.
Billing: Shopify managed pricing redirect, usage snapshots, tier config, plan limits, saved filters/templates, and job concurrency by tier.
Deployment: Docker-based Render services BPE and BPE-preview; env vars include Shopify credentials, scopes, API version, Neon database URLs, and job queue settings.
Verification: Vitest, Playwright, Prisma setup, dependency audit/report scripts, docs manifest/link tooling, and Partner/App Store review docs.

6) Key Workflows and Operational Flows

Bulk edit setup flow: product filter -> action selection -> optional variant targeting -> preview count/table/changes -> create task.
Background processing flow: create job -> queue/batch execution -> Shopify Admin GraphQL mutations -> per-row logs -> warnings/CSV evidence when partial failures happen.
Rollback flow: select completed job -> inspect summary -> confirm rollback -> replay stored before-values for supported actions -> surface warnings for rows Shopify rejects.
Reference-data sync flow: synced collections, vendors, product types, and metafield definitions feed dropdowns and selectors so merchants can target current catalog dimensions.
Billing/usage flow: resolve tier from Shopify, enforce monthly task/product limits, and send upgrade actions to Shopify's hosted managed pricing page.
App Store readiness flow: docs under docs/internal/listing/ track listing copy, pricing, screenshots, reviewer instructions, privacy/compliance, QA, and launch tasks.

7) AI Context: Prompts, Chats, Agent Workflows

The repo contains explicit AI/tooling traces:

AGENTS.md sets checkpoint-based repository instructions for AI agents.
CLAUDE.md and .claude/settings.json are referenced in docs as Claude Code governance/configuration surfaces.
docs/development/claude-code-setup.md documents the Claude Code setup lane.
docs/merchant/tasks/* and docs/internal/* reflect repeated AI-assisted documentation and release-readiness passes.
app/services/chatAssistant.server.ts provides an authenticated AI help assistant path for merchant support, with public-safe fallback behavior when AI help fails.

The project should be represented as AI-assisted Shopify app/product operations work, not as an autonomous agent product.

8) Supporting Docs and External Resources

README.md - Shopify Remix template baseline plus local/e2e/dependency-maintenance guidance.
AGENTS.md - repository operating contract for checkpointed AI-agent work.
render.yaml - production and preview Render service definitions.
docs/merchant/getting-started/first-edit.md - merchant workflow source of truth for the first bulk edit.
docs/merchant/tasks/job-history-rollback.md - rollback and job-history behavior source of truth.
docs/merchant/tasks/jobs-and-queue.md - background jobs, queueing, and timing source of truth.
docs/internal/filters-variants-actions-status.md - implementation status for filters, variant targeting, action conversion, Shopify query compilation, and tests.
docs/internal/listing/app-listing.md - Shopify App Store listing draft.
docs/internal/listing/checklist.md - listing/compliance/QA readiness checklist.
docs/internal/launch/production-plan.md - launch readiness workstream checklist.

Hydration Source Artifacts

Artifact (relative repo path)	Canonical URL	Type	Why hydrate this into note body
`docs/merchant/getting-started/first-edit.md`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/docs/merchant/getting-started/first-edit.md`	markdown	Core merchant journey: filter, choose action, preview, run, verify, and roll back.
`docs/merchant/tasks/job-history-rollback.md`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/docs/merchant/tasks/job-history-rollback.md`	markdown	Operational proof of job status, warnings, rollback scope, unsupported cases, and support boundaries.
`docs/internal/filters-variants-actions-status.md`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/docs/internal/filters-variants-actions-status.md`	markdown	Implementation-status record for filter DSL, variant targeting, Shopify GraphQL helpers, and test coverage.
`docs/internal/listing/app-listing.md`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/docs/internal/listing/app-listing.md`	markdown	Public listing/product positioning draft for the Shopify app.
`docs/internal/launch/production-plan.md`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/docs/internal/launch/production-plan.md`	markdown	Launch readiness and App Store submission workstream evidence.
`render.yaml`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/render.yaml`	text	Deployment service and environment contract for `BPE` and `BPE-preview`.
`assets/image-0cd6dc2f-e6df-4d3e-a834-c6adf5fb903f.png`	`https://github.com/maggielerman/shopify-bulk-editor-app/blob/main/assets/image-0cd6dc2f-e6df-4d3e-a834-c6adf5fb903f.png`	image	Existing repo image path; file is currently 0 bytes and should be treated as a visual-asset gap, not project proof.
`Unknown`	`Unknown`	pdf	No `.pdf` source artifact was found during this review.

9) Screenshot Gallery (with relative links + captions)

- Branded Xyppy/Bulk Product Editor surface showing Step 1 product inclusion filters and saved-filter capacity.
- Filter-builder detail with title, status, metafield, and tag criteria plus preview-table controls.
- Bulk action configuration for setting a product metafield, including required-value validation before execution.
- Job History table showing completed, rolled-back, and failed bulk-edit jobs with product/variant counts and quick actions.
- Usage dashboard showing plan capacity, product edits, task limits, retention, concurrency, draft tasks, and saved-filter limits.
- Public xyppy.com help center showing Shopify Bulk Editor support categories, onboarding articles, troubleshooting, search, and chat support entry points.

These screenshots replace the earlier docs-surface captures for local project-page review. The docs captures are retained in docs-reference-screenshots/ as source-review context, not as the primary project media set.

10) Candidate Import Nodes and Relationships

Project supernode:
- ID: project-shopify-bulk-editor-app
- Slug: shopify-bulk-editor-app
- Title: Xyppy Shopify Merchant App
- Status: shipped
- Trail: ecommerce
Candidate supporting notes:
- First bulk edit workflow
- Job history and rollback coverage
- Filters, variant targeting, and action implementation status
- Shopify App Store listing and launch readiness
- Render deployment service contract
Candidate workflow:
- workflow-shopify-bulk-editor-safe-bulk-edit-loop
Candidate data model:
- Bulk edit job and rollback lifecycle
Relationships:
- Project -> merchant docs and help center notes
- Project -> workflow for safe bulk-edit operations
- Project -> data model for job/rollback lifecycle
- Future project relationship to bpe-marketing-lp only after that queue item is reviewed from source.

11) Risks, Gaps, and Unknowns

IQ-0003 is already completed as Maintain iOS and is not part of this new artifact set.
The source repo has an unrelated local .DS_Store modification; source content was otherwise at main/origin/main parity.
Render route verification is unresolved: bpe-preview.onrender.com/ returned 404, and bpe.onrender.com/ did not return promptly during this intake.
Operator confirmed the project status should be shipped; the Render service status remains separate deployment evidence, not the public status source.
The only source repo PNG found under assets/ is 0 bytes, so it should not be treated as visual proof.
The README still contains substantial Shopify template text; curated docs and app code provide stronger source evidence than the root README.
The earlier Shopify App Store URL checked during this update returned a 404 from a non-authenticated command-line fetch; the corrected operator-provided App Store listing URL is represented in the local review record.

12) Handoff Checklist for Hyphenomenon Import

Dataset Preview

Raw CSV row/table content is available in the source artifact.