Dossier
    Shopify AI Product OptimizerUpdated Jul 13, 2026

    Project Intake - Shopify AI Product Optimizer

    Markdown file

    Imported markdown

    Project Intake - Shopify AI Product Optimizer

    1) Executive Summary

    Shopify AI Product Optimizer was a killed Shopify app experiment that tried to make product-catalog optimization measurable, reviewable, and reversible. The source app combined deterministic SEO checks with merchant-contextual AI suggestions, Shopify product updates, background jobs, audit logs, and one-click revert behavior.

    The public value is not a claim that the product worked in market. The final handoff left the real embedded UI -> queue -> worker -> result -> apply -> revert loop unvalidated, and the repository stopped after a five-day implementation window. This intake preserves the interaction model, safety boundaries, data model, operational ambition, and the evidence that the experiment ended before proving its core loop.

    2) Project Type and Domain

    • Project type: experiment.
    • Status: killed.
    • Domain: Shopify app, ecommerce operations, product-catalog SEO, AI-assisted content generation, reversible automation.
    • Trail: eCommerce (ecommerce).
    • Map trail group: shopify-app-experiments.
    • Intended user: a Shopify merchant or catalog operator responsible for product quality and search visibility.
    • Lifecycle authority: Maggie's explicit July 13, 2026 classification. The source repository itself does not record a kill decision.

    3) Repository and Live URLs

    • Source repository: maggielerman/shopify-ai-product-optimizer
    • Former Render deployment: shopify-ai-product-optimizer-web-p446.onrender.com
    • Source baseline: main / origin/main at 012073a1b3041a5dd0e70e39a476ff8f8794d626 (continuing work, 2026-02-06 14:08 EST).
    • Current live state: the former Render endpoint did not return an HTTP response during a 60-second check on 2026-07-13. No current public deployment was found.
    • Visual proof surface: a temporary, read-only Remix/Polaris fixture route built from the historical source and synthetic catalog data. It was not committed to the source repository.

    4) Product/User Journey Summary

    The intended merchant journey was:

    1. Install the embedded Shopify app and sync the store's product catalog.
    2. Convert failed checks into a normalized SEO score and field-specific issues.
    3. Send only the affected fields, current product context, merchant brand voice, audience, language, and explicit constraints to the configured AI model.
    4. Review a current-value -> suggested-value comparison with rationale and risk level.
    5. Apply selected suggestions, or enable bounded automation in suggest-only, safe-auto, or full-auto mode.
    6. Record the before/apply state in an audit log and preserve the product snapshot.
    7. Revert applied changes when the output is wrong or conflicts with current Shopify data.

    The app also proposed keyword campaigns and generated landing pages, but the source marks creation as moved to a separate app and leaves that surface read-only. This intake therefore centers the better-supported product-optimization loop.

    5) Architecture and Stack Summary

    • Embedded app: Remix, React 18, TypeScript, Shopify Polaris, and App Bridge.
    • Commerce boundary: Shopify GraphQL Admin API, OAuth sessions, product and bulk-operation webhooks, and privacy-compliance webhooks.
    • Analysis: deterministic weighted SEO checks produce a score, issue list, passed checks, and failed checks before any model call.
    • Generation: OpenAI chat completions generate structured field-level suggestions from product facts plus merchant brand voice, target audience, and primary language. The settings surface also modeled Anthropic as a provider option, but the inspected suggestion implementation uses OpenAI.
    • Jobs: BullMQ and Redis separate catalog sync, analysis, apply, revert, bulk-result processing, and page generation from web requests.
    • Deployment intent: Render web and worker processes with Neon Postgres and Upstash Redis.
    • Safety: suggest-only default, field risk levels, constrained safe-auto fields, billing caps, snapshots, change logs, conflict checks, and revert.

    6) Key Workflows and Operational Flows

    • Catalog analysis: fetch current Shopify product data, run deterministic checks, persist score/issues/snapshot, then generate suggestions only for fields with evidence-backed gaps.
    • Human review: expose current and proposed values, rationale, and risk; let the merchant apply a subset instead of accepting a wholesale rewrite.
    • Bounded automation: trigger on product create/update, a schedule, or manual selection; filter the catalog by status/type/vendor/tag; choose suggest-only, safe-auto, or full-auto.
    • Apply and audit: queue selected suggestion IDs, mutate Shopify, mark suggestion status, and write before/apply evidence to ChangeLog.
    • Revert: compare current Shopify state with the local snapshot, restore preserved fields, mark applied suggestions reverted, and write a revert log.
    • Operational proof loop: web and worker services must share Postgres and Redis; the staging runbook requires verifying OAuth, sync, analysis, suggestion creation, apply, audit, revert, and webhook-triggered automation end to end.
    • Killed-state boundary: these are implemented or documented historical flows, not a currently operating Shopify automation.

    7) AI Context: Prompts, Chats, Agent Workflows

    AI appears at a narrow, consequential point in the product loop:

    • Deterministic rules decide what is wrong before the model writes anything.
    • worker/services/ai-suggestions.ts constructs a system prompt from general ecommerce SEO guidance plus merchant-specific brand voice, target audience, and primary language.
    • A field-specific prompt provides current values, source product facts, failed-check messages, and explicit length/format requirements.
    • The model must return JSON with suggestion and rationale; the app assigns risk based on the target field.
    • Model output is stored as a pending Suggestion, not treated as canonical product truth.
    • Human review is the default. Optional automation is constrained by mode and field allowlists, and the database preserves what was generated, applied, rejected, failed, or reverted.
    • The final source handoff considered a future multi-agent planner/researcher/writer/critic/apply architecture and an evaluation flywheel, but those remained research goals rather than implemented product claims.

    No first-class Codex/ChatGPT transcript was discovered in the source repo. This dossier does not infer one from commit history.

    8) Supporting Docs and External Resources

    • README.md - product ambition, features, stack, and operating commands.
    • docs/ARCHITECTURE.md - web/worker/data/queue boundaries and typical data flow.
    • docs/handoff/2026-02-04.md - strongest source statement of what was implemented and what still needed real end-to-end validation.
    • docs/runbooks/staging-e2e.md - explicit OAuth, queue, analysis, apply, audit, revert, and webhook proof contract.
    • prisma/schema.prisma - first-class project data model.
    • worker/services/seo-analyzer.ts - deterministic evidence layer.
    • worker/services/ai-suggestions.ts - prompt assembly, structured response, and risk assignment.
    • worker/processors/analyze-product.ts - orchestration from Shopify snapshot through suggestion storage and bounded auto-apply.

    Hydration Source Artifacts

    Artifact (relative repo path)Canonical URLTypeWhy hydrate this into note body
    README.mdhttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/README.mdmarkdownDefines the product hypothesis, merchant-facing features, stack, and execution model.
    docs/ARCHITECTURE.mdhttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/docs/ARCHITECTURE.mdmarkdownExplains the embedded app, worker, database, queue, and typical data flow.
    docs/handoff/2026-02-04.mdhttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/docs/handoff/2026-02-04.mdmarkdownPreserves the last substantive implementation state and the unvalidated core-loop risk.
    docs/runbooks/staging-e2e.mdhttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/docs/runbooks/staging-e2e.mdmarkdownDefines the artifact/dry-run proof expected for OAuth, jobs, suggestions, apply, audit, revert, and webhook automation.
    prisma/schema.prismahttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/prisma/schema.prismatextProvides first-class evidence for the product, suggestion, automation, audit, revert, and usage model.
    worker/services/seo-analyzer.tshttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/worker/services/seo-analyzer.tstextShows deterministic checks and weighted scoring before AI generation.
    worker/services/ai-suggestions.tshttps://github.com/maggielerman/shopify-ai-product-optimizer/blob/main/worker/services/ai-suggestions.tstextShows exactly how product evidence and merchant context become field-level model requests.
    ./screenshots/03-product-review.pnghttps://github.com/maggielerman/hyphenomenon/blob/codex/shopify-ai-product-optimizer-intake/DOCS/intake/runs/projects/2026-07-13-shopify-ai-product-optimizer/screenshots/03-product-review.pngimageFresh fixture-backed visual evidence of the reviewable suggestion and risk model.

    No .pdf or .docx source artifact exists in the source repository. The source also contains no checked-in product screenshot; the image candidate is fresh, Hyphenomenon-owned intake evidence.

    9) Screenshot Gallery (with relative links + captions)

    1. Catalog health dashboard - Fixture-backed dashboard showing catalog coverage and a pending-review count; synthetic data and no connected Shopify store.
    2. Product analysis queue - Product-level SEO scores, pending suggestions, and analysis timestamps on the source app's Polaris table pattern.
    3. Field-level suggestion review - Current listing context beside low/medium-risk AI suggestions and disabled apply/reject controls.
    4. Automation safety boundary - Suggest-only, safe-auto, and full-auto modes with trigger and catalog-filter controls; suggest-only is selected.
    5. Reversible activity log - Synthetic apply, auto-apply, and revert events illustrating the intended audit trail.
    6. AI and brand settings - Provider/model selection plus merchant brand voice and target-audience context, with killed-state metadata visible.

    All six images were captured on 2026-07-13 from a temporary read-only route compiled against the historical Remix/Polaris source. The fixture was not added to the source repository, all records are synthetic, and no Shopify, database, queue, billing, or model-provider action was available.

    10) Candidate Import Nodes and Relationships

    • Project supernode:
      • ID: project-shopify-ai-product-optimizer
      • Slug: shopify-ai-product-optimizer
      • Title: Shopify AI Product Optimizer
      • Project type: experiment
      • Status: killed
      • Trail: ecommerce
      • Map trail group: shopify-app-experiments
    • Workflow:
      • workflow-shopify-ai-product-optimizer-catalog-review-loop
      • Historical catalog-analysis -> AI-suggestion -> review/apply -> audit/revert process.
    • Supporting notes:
      • Product ambition and source status.
      • Architecture and deployment boundary.
      • Final implementation handoff.
      • Staging end-to-end proof contract.
      • Prisma data model.
      • Deterministic analyzer.
      • AI suggestion generator.
    • Data models:
      • Product evidence and suggestion lifecycle.
      • Catalog-analysis and reversible-action boundary.
    • Relationships:
      • Project -> historical workflow.
      • Project -> hydrated source notes and fixture-backed screenshots.
      • Project -> data-model artifacts.
      • No direct code lineage to another Hyphenomenon project is claimed from source evidence.

    The revoked 1079 batch represented this project as a paused AI Ops/agent-orchestration experiment related to App Growth Agent. This fresh intake supersedes that classification: it is a killed ecommerce/Shopify-app experiment, and the source does not implement a multi-agent runtime.

    11) Risks, Gaps, and Unknowns

    • The operator supplied the killed lifecycle; the source contains no written kill decision or reason. Why it stopped is Unknown.
    • The final handoff left the real embedded OAuth -> job -> worker -> result -> apply -> audit -> revert loop as future validation.
    • The former Render endpoint did not respond during a 60-second request on 2026-07-13. Its exact retirement state is Unknown.
    • The repo is private, has no homepage URL in GitHub metadata, and has no checked-in screenshots, .pdf, or .docx files.
    • Fixture screenshots prove the inspected interaction and information model, not a successful Shopify install, real catalog performance, model quality, SEO impact, or merchant adoption.
    • The OpenAI implementation uses chat completions and JSON parsing rather than a modern Responses/structured-output contract; source model/config references are historical and should not be read as current recommendations.
    • Source dependencies install with 55 audit findings (1 low, 18 moderate, 35 high, 1 critical) and declare Node 20 while the capture environment uses a newer Node runtime. No source remediation was attempted because the project is killed.
    • Usage billing, scheduled automation, AI-provider switching, landing-page generation, and production-grade Prisma migrations were incomplete or explicitly deferred.
    • Applying the historical workflow will create a visible workflow object; its title, summary, tags, final state step, and project metadata must preserve that it is historical and killed rather than currently operating.

    12) Handoff Checklist for Hyphenomenon Import

    • Review Hyphenomenon and source governance/docs before intake.
    • Establish fresh source identity, current Git baseline, and historical deployment state.
    • Record experiment / killed as project metadata.
    • Inspect routes, Prisma schema, analyzer, model prompt path, background jobs, audit, and revert logic.
    • Build the historical source successfully in an isolated fixture worktree.
    • Capture and visually inspect six public-safe, fixture-backed screenshots.
    • Author a reader-facing project-page packet rather than copying dossier mechanics.
    • Author a complete historical workflow packet with proof, decision, operator-review, provenance, and killed-state steps.
    • Generate and validate the hydration payload.
    • Run project and workflow dry-runs and review their deltas.
    • Intentionally apply both packets to the non-production preview database.
    • Verify project route, workflow route, Map focus, provenance, metadata, screenshots, and drift.
    • Log the completed intake and remove IQ-0011 from the active queue.
    • Commit and push the dedicated intake branch.

    Dataset Preview

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