The AdPriority Blueprint

Automated Google Ads Priority Scoring for Shopify Merchants

Version: 1.0.0 Created: February 2026 Target Platform: /volume1/docker/adpriority/

+===============================================================================+
|                                                                               |
|           _    ____  ____  ____  ___ ___  ____  ___ _____ __   __             |
|          / \  |  _ \|  _ \|  _ \|_ _/ _ \|  _ \|_ _|_   _|\ \ / /            |
|         / _ \ | | | | |_) | |_) || | | | | |_) || |  | |   \ V /             |
|        / ___ \| |_| |  __/|  _ < | | |_| |  _ < | |  | |    | |              |
|       /_/   \_\____/|_|   |_| \_\___\___/|_| \_\___| |_|    |_|              |
|                                                                               |
|       ____  _     _   _ _____ ____  ____  ___ _   _ _____                    |
|      | __ )| |   | | | | ____|  _ \|  _ \|_ _| \ | |_   _|                   |
|      |  _ \| |   | | | |  _| | |_) | |_) || ||  \| | | |                     |
|      | |_) | |___| |_| | |___|  __/|  _ < | || |\  | | |                     |
|      |____/|_____|\___/|_____|_|   |_| \_\___|_| \_| |_|                     |
|                                                                               |
|              Automated Google Ads Priority Scoring                             |
|                   for Shopify Merchants                                        |
|                                                                               |
|         Priority Scores (0-5) --> GMC Custom Labels --> PMAX Campaigns        |
|                                                                               |
+===============================================================================+

How to Use This Book

This Blueprint is a self-contained guide for building a production-grade Shopify app that automates Google Ads product priority scoring. Every architecture diagram, API specification, scoring algorithm, and deployment procedure is included directly in these pages.

Reading Order

Key Concepts

Throughout this book, the following terms appear frequently:

+----------------------------------------------------------------------+
|  TERM              |  MEANING                                        |
+----------------------------------------------------------------------+
|  Priority Score    |  0-5 integer rating controlling ad spend         |
|  Custom Label      |  GMC product attribute for campaign segmentation |
|  Supplemental Feed |  Secondary GMC feed that adds/overrides labels   |
|  PMAX              |  Google Performance Max campaign type             |
|  Scoring Engine    |  Service that calculates product priorities       |
|  Rules Engine      |  IF-THEN conditions for automatic scoring        |
|  Seasonal Calendar |  Time-based priority rotation system              |
+----------------------------------------------------------------------+

Table of Contents

Front Matter

• 00-BOOK-INDEX.md – You are here
• 01-PREFACE.md – Why this book exists

Part I: Foundation

Understanding the problem, the requirements, and the opportunity

• Chapter 01: Vision & Goals
• Chapter 02: Product Requirements
• Chapter 03: User Stories & Personas
• Chapter 04: Market Analysis
• Chapter 05: Success Criteria

Part II: Architecture

System design and key technical decisions

• Chapter 06: System Architecture
• Chapter 07: Data Flow & Pipeline
• Chapter 08: Multi-Tenant Design
• Chapter 09: Architecture Decision Records

Part III: Integrations

External API specifications and data flows

• Chapter 10: Shopify Integration
• Chapter 11: Google Merchant Center
• Chapter 12: Google Ads Integration
• Chapter 13: Google Sheets API

Part IV: Backend

Server-side implementation details

• Chapter 14: Database Schema
• Chapter 15: API Design
• Chapter 16: Priority Scoring Engine
• Chapter 17: Seasonal Automation

Part V: Frontend

Shopify embedded app interface

• Chapter 18: Shopify Polaris UI
• Chapter 19: Dashboard & Analytics

Part VI: Implementation Guide

Step-by-step building instructions

• Chapter 20: Phase 0 - Nexus MVP
• Chapter 21: Phase 1 - SaaS Foundation
• Chapter 22: Phase 2 - Full Product
• Chapter 23: Phase 3 - App Store Launch

Part VII: Operations

Deployment, monitoring, and compliance

• Chapter 24: Deployment
• Chapter 25: Monitoring & Alerts
• Chapter 26: App Store Compliance

Appendices

• Appendix A: Nexus Product Catalog
• Appendix B: GMC Custom Label Reference
• Appendix C: Category Mapping Rules
• Appendix D: Sample Supplemental Feed
• Appendix E: Competitor Analysis

Book Statistics

How to Build This Book

Build the mdBook Site

# Navigate to mdbook source
cd /volume1/docker/planning/24-adpriority-saas/blueprint/mdbook-src

# Build the static site
mdbook build

# Output is in: ./book/

Deploy to Cloudflare Pages

# From the mdbook-src directory after building
wrangler pages deploy book --project-name=adpriority-blueprint

Local Preview

# Serve locally with hot-reload
mdbook serve --open

# Default: http://localhost:3000

Print to PDF (Pandoc)

cd /volume1/docker/planning/24-adpriority-saas/blueprint/mdbook-src/src

pandoc \
  00-BOOK-INDEX.md \
  01-PREFACE.md \
  Part-I-Foundation/*.md \
  Part-II-Architecture/*.md \
  Part-III-Integrations/*.md \
  Part-IV-Backend/*.md \
  Part-V-Frontend/*.md \
  Part-VI-Implementation/*.md \
  Part-VII-Operations/*.md \
  Appendices/*.md \
  -o AdPriority-Blueprint.pdf \
  --toc \
  --toc-depth=3 \
  --pdf-engine=xelatex \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V mainfont="DejaVu Sans" \
  -V monofont="DejaVu Sans Mono"

Estimated Print Size

Blueprint Maintenance

How to Update This Blueprint

CRITICAL: When adding or removing chapters/appendices, you MUST update:

1. This file (00-BOOK-INDEX.md)
2. SUMMARY.md (mdBook table of contents)

Version History

Contributors

Quick Reference: The Priority Scoring Model

+-------+-------------+-------------------------------------------+
| Score | Name        | Campaign Behavior                         |
+-------+-------------+-------------------------------------------+
|   5   | Push Hard   | Maximum budget, aggressive bidding        |
|   4   | Strong      | High budget, balanced approach            |
|   3   | Moderate    | Standard budget, conservative bidding     |
|   2   | Light       | Minimal budget, strict ROAS targets       |
|   1   | Minimal     | Very low budget, highest ROAS only        |
|   0   | Exclude     | No advertising spend                      |
+-------+-------------+-------------------------------------------+

                    THE ADPRIORITY DATA FLOW

  +-----------+      +-----------+      +-----------+      +----------+
  |  Shopify  | ---> | AdPriority| ---> |   Google  | ---> |  Google  |
  |  Product  |      |  Scoring  |      |  Merchant |      |   Ads    |
  |  Catalog  |      |  Engine   |      |  Center   |      |   PMAX   |
  +-----------+      +-----------+      +-----------+      +----------+
    5,582 SKUs        Rules +            Custom             Campaign
    (Nexus)           Seasons +          Labels             Segments
                      Manual             0-4                by Priority

“Score it. Label it. Let PMAX do the rest.”

Preface

Why This Book Exists

Every retailer running Google Ads faces the same quiet problem: not all products deserve the same advertising budget, but managing priorities manually is a losing battle.

Consider a clothing retailer with 5,000 products. Shorts should get maximum ad spend in June and minimum in December. Jackets are the opposite. New arrivals need a visibility boost. Clearance items should not eat budget at all. Bestsellers should always get strong spend. Slow movers should barely appear.

A marketing manager who gets this right can double their return on ad spend. A marketing manager who gets this wrong – or, more commonly, who never gets around to managing it at all – bleeds budget into irrelevant products every single day.

This Blueprint documents a complete system for solving that problem: AdPriority, a Shopify app that automates Google Ads product priority scoring using a 0-5 scale with seasonal automation.

The Problem in Detail

Google Performance Max (PMAX) campaigns are powerful but opaque. Google’s algorithm decides which products to show, when, and to whom. Merchants have one primary lever for influencing product-level spend: campaign segmentation using Google Merchant Center custom labels.

The workflow looks like this:

+-----------------------------------------------------------------+
|                                                                   |
|   1. Assign custom labels to products in GMC                     |
|   2. Create separate PMAX campaigns (or asset groups)            |
|      segmented by those labels                                    |
|   3. Set different budgets and ROAS targets per segment           |
|   4. Google optimizes within each segment independently          |
|                                                                   |
+-----------------------------------------------------------------+

The problem is step 1. Assigning and maintaining custom labels across thousands of products is:

• Time-consuming: Manual updates for every seasonal change, every new arrival, every clearance event
• Error-prone: Forgetting to update labels means budget flowing to the wrong products for days or weeks
• Difficult to scale: What works for 100 products breaks at 1,000 and collapses at 10,000
• Knowledge-dependent: When the person who manages labels leaves, institutional knowledge walks out the door

Most merchants either ignore custom labels entirely (leaving PMAX fully automated with no guardrails) or set them once and never update them (which is almost as bad).

The Solution Approach

AdPriority introduces a simple but powerful abstraction: the Priority Score.

+=========================================================================+
|                                                                           |
|   PRIORITY SCORING MODEL                                                 |
|                                                                           |
|   Score   Name          Ad Spend Behavior                                |
|   -----   -----------   ------------------------------------------------ |
|     5     Push Hard     Maximum budget, aggressive bidding               |
|     4     Strong        High budget, balanced approach                   |
|     3     Moderate      Standard budget, conservative bidding            |
|     2     Light         Minimal budget, strict ROAS targets              |
|     1     Minimal       Very low budget, only highest-ROAS clicks        |
|     0     Exclude       No advertising -- product is suppressed          |
|                                                                           |
+=========================================================================+

The scoring engine determines each product’s priority through a clear hierarchy:

                    SCORE OVERRIDE HIERARCHY

            +----------------------------------+
            |    1. Manual Override             |   <-- Highest priority
            +----------------------------------+
                          |
            +----------------------------------+
            |    2. Seasonal Calendar           |
            +----------------------------------+
                          |
            +----------------------------------+
            |    3. New Arrival Boost           |
            +----------------------------------+
                          |
            +----------------------------------+
            |    4. Category-Based Rule         |
            +----------------------------------+
                          |
            +----------------------------------+
            |    5. Default Score               |   <-- Lowest priority
            +----------------------------------+

Priority scores flow through a pipeline that ends at Google Ads:

  +----------+     +----------+     +-----------+     +---------+     +--------+
  | Shopify  |     |          |     | Supple-   |     | Google  |     | Google |
  | Products |---->| Scoring  |---->| mental    |---->| Merchant|---->| Ads    |
  | (source) |     | Engine   |     | Feed      |     | Center  |     | PMAX   |
  +----------+     +----------+     +-----------+     +---------+     +--------+
                        |
               +--------+--------+
               |        |        |
            Rules   Seasons   Manual
            Engine  Calendar  Overrides

The Three-Phase Approach

We adopted a deliberate phased approach, starting with a real-world validation before writing a single line of SaaS code:

+=========================================================================+
|                                                                           |
|   PHASE 0: NEXUS MVP                    STATUS: VALIDATED                |
|   ------------------                    -------------------------        |
|   Google Sheets supplemental feed       10/10 products matched           |
|   Manual priority assignment            Zero GMC errors                  |
|   Nexus Clothing as test store          Pipeline proven end-to-end       |
|   Document everything                   124,060 GMC products analyzed    |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 1: SAAS FOUNDATION              STATUS: PLANNED                 |
|   -------------------------              -------------------------        |
|   Shopify app (OAuth + App Bridge)      Database schema designed         |
|   PostgreSQL database                    API endpoints specified         |
|   Core API (products, rules, sync)      Polaris UI wireframed           |
|   Basic Polaris admin UI                                                 |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 2: FULL PRODUCT                 STATUS: PLANNED                 |
|   ----------------------                 -------------------------        |
|   Seasonal calendar engine              Category x Season matrix         |
|   Rules engine (IF-THEN)                New arrival auto-boost           |
|   Content API direct sync               Bulk operations                  |
|   Google Ads performance data           ROAS recommendations             |
|                                                                           |
|                            |                                             |
|                            v                                             |
|                                                                           |
|   PHASE 3: APP STORE LAUNCH             STATUS: PLANNED                 |
|   --------------------------             -------------------------        |
|   Shopify App Store listing             Billing integration              |
|   Multi-tenant production               Usage-based tier limits          |
|   Documentation + onboarding            Marketing + landing page         |
|                                                                           |
+=========================================================================+

The critical insight: Phase 0 is not a prototype. It is a real, working pipeline that validates the entire concept with actual GMC data before any engineering investment in the SaaS product. The supplemental feed approach was tested on 2026-02-10 with 10 Nexus products – all 10 matched in GMC with zero issues.

What Makes This Blueprint Different

1. Built on Real Data

This is not a theoretical product specification. The research behind this Blueprint includes:

2. Validated Pipeline

The most risky part of any GMC integration is the product ID matching between Shopify and Merchant Center. We validated this before writing the Blueprint:

    SUPPLEMENTAL FEED VALIDATION RESULTS (2026-02-10)

    +-----------------------------+----------+
    | Metric                      | Result   |
    +-----------------------------+----------+
    | Products submitted          | 10       |
    | Products matched in GMC     | 10       |
    | Match rate                  | 100%     |
    | Label propagation errors    | 0        |
    | Time to reflect in GMC      | < 1 hour |
    | Custom label conflicts      | 0        |
    +-----------------------------+----------+

    Verdict: Pipeline is PROVEN. Build with confidence.

3. Existing Infrastructure

AdPriority does not start from scratch. It builds on proven Shopify app infrastructure:

• Existing Shopify app template with OAuth flow (/volume1/docker/sales-page-app/)
• Shared PostgreSQL 16 instance (postgres16 container, production-grade)
• Docker deployment pipeline with Cloudflare Tunnel for external access
• Established development workflow on Synology NAS

4. Clear Market Gap

Market research identified a specific gap: no Shopify-native, affordable solution exists that is specifically focused on priority scoring for Google Ads. Competitors offer custom labels as a secondary feature within general-purpose feed management tools. AdPriority makes priority scoring the primary product.

Who Should Read This Book

The Technology Stack

+=========================================================================+
|                         TECHNOLOGY STACK                                  |
|                                                                           |
|   BACKEND                              FRONTEND                          |
|   -------                              --------                          |
|   Node.js 20 LTS                       React 18                         |
|   Express.js                           Vite (build tool)                 |
|   TypeScript                           Shopify Polaris v13               |
|   Prisma ORM                           React Query (server state)        |
|   Bull + Redis (job queue)             Chart.js (analytics)              |
|                                                                           |
|   DATABASE                             INTEGRATIONS                      |
|   --------                             ------------                      |
|   PostgreSQL 16                        Shopify Admin API (GraphQL)       |
|   (shared postgres16 container)        Google Sheets API v4              |
|   Redis 7 (cache + queue)             GMC Content API for Shopping       |
|                                        Google Ads API v17                |
|   INFRASTRUCTURE                                                         |
|   --------------                                                         |
|   Docker + Docker Compose              AUTHENTICATION                    |
|   Cloudflare Tunnel                    ---------------                   |
|   GitHub Actions (CI/CD)               Shopify OAuth (App Bridge)        |
|   Synology NAS (host)                  Google OAuth 2.0                  |
|                                        JWT session tokens                |
|                                                                           |
+=========================================================================+

Why This Stack

Business Model

Pricing rationale: Positioned between budget tools (Simprosys at $4.99) and enterprise solutions (Feedonomics at $1,000+). The $29 entry point is accessible for small Shopify merchants. The $79 tier captures the core value proposition of seasonal automation. The $199 tier targets performance-focused marketers who want data-driven decisions.

Conventions Used in This Book

Code Samples

// TypeScript code appears in blocks like this
async function calculatePriority(productId: string): Promise<number> {
  // Scoring engine implementation
}

SQL Statements

-- SQL code appears in blocks like this
CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    store_id UUID NOT NULL REFERENCES stores(id),
    priority_score INTEGER DEFAULT 3 CHECK (priority_score BETWEEN 0 AND 5)
);

API Examples

# HTTP requests appear like this
curl -X PATCH /api/products/abc123 \
  -H "Authorization: Bearer <token>" \
  -d '{"priority_score": 5}'

Important Notes

Note: Important information appears in blockquotes like this.

Warning: Critical warnings that could cause data issues or deployment failures.

ASCII Diagrams

Architecture and flow diagrams use ASCII art for portability:

+----------+     +----------+     +----------+
|  Client  |---->|   API    |---->| Database |
+----------+     +----------+     +----------+

Priority Score Indicators

When priority scores appear inline, they follow this convention:

• P5 = Push Hard (highest)
• P4 = Strong
• P3 = Moderate
• P2 = Light
• P1 = Minimal
• P0 = Exclude (no ads)

Acknowledgments

This Blueprint was created through collaboration between:

• Nexus Clothing – the real-world test store whose 5,582 products and 124,060 GMC listings validated the entire approach
• Google Merchant Center documentation – for making the supplemental feed specification clear enough to validate in one session
• The Shopify developer ecosystem – for excellent App Bridge and Polaris documentation
• Claude Code agents – who helped research, design, implement, and review every chapter

Let’s Build

The supplemental feed works. The product IDs match. The custom labels are available. The market gap is real. The infrastructure is ready.

This Blueprint contains everything needed to go from a validated Google Sheets prototype to a production Shopify app on the App Store.

Turn the page and let’s begin.

February 2026

Document Information

Chapter 1: Vision & Goals

The Problem: Retailers Waste Ad Spend on the Wrong Products

Every day, thousands of Shopify merchants pour money into Google Ads without a strategy for which products deserve the most budget. The result is predictable and costly: winter jackets get the same ad spend as shorts in January, dead stock competes with bestsellers for clicks, and new arrivals languish in obscurity while clearance items drain the budget.

The root cause is straightforward. Google Ads Performance Max (PMAX) campaigns treat all products equally unless the merchant manually segments them using custom labels in Google Merchant Center. But managing those labels is a manual, error-prone process that most merchants either skip entirely or configure once and never update.

The Scale of the Problem

Consider a retailer like Nexus Clothing with 5,582 products across 90 product types and 175 vendors. In winter, puffer jackets and hoodies should receive maximum ad spend while shorts and sandals should be excluded entirely. When spring arrives, the priorities must reverse. Multiply this by seasonal transitions four times per year, new product arrivals weekly, and clearance cycles monthly, and the manual management burden becomes untenable.

THE WASTED AD SPEND CYCLE
=========================

  Merchant sets up PMAX campaign
           |
           v
  All products treated equally
           |
           v
  Budget spread across entire catalog
           |
           +---> Shorts get clicks in January (wasted)
           |
           +---> Dead stock gets impressions (wasted)
           |
           +---> New arrivals buried under old products (missed opportunity)
           |
           +---> Seasonal items out of sync (wrong timing)
           |
           v
  Poor ROAS  -->  Merchant blames Google Ads  -->  Reduces budget
           |
           v
  Fewer sales  -->  Competitor with better segmentation wins

Why Manual Management Fails

The Solution: AdPriority

AdPriority automates product priority scoring with a simple, opinionated 0-5 scale. Instead of forcing merchants to build complex feed rules from scratch, AdPriority provides a purpose-built scoring system that maps directly to Google Ads budget allocation through Google Merchant Center custom labels.

The 0-5 Priority Scale

The scoring system is deliberately simple. Every product gets a single number from 0 to 5 that directly controls how aggressively it is advertised.

PRIORITY SCALE
==============

  5  |  PUSH HARD     Maximum budget, aggressive bidding
     |                 Seasonal bestsellers, hot new arrivals, peak demand
     |
  4  |  STRONG         High budget, balanced approach
     |                 Strong performers, seasonal relevance, name brands
     |
  3  |  NORMAL         Standard budget, conservative bidding
     |                 Average products, year-round staples
     |
  2  |  LOW            Minimal budget, strict ROAS targets
     |                 Declining season, overstocked, low margin
     |
  1  |  MINIMAL        Very low budget, highest ROAS threshold only
     |                 End of season, slow movers, clearance
     |
  0  |  EXCLUDE        No advertising spend
     |                 Dead stock, archived, out of stock, non-ad products

Priority Score Definitions

How Priority Scores Are Assigned

AdPriority calculates scores automatically using a layered rules engine. The merchant configures high-level rules (category mappings, seasonal calendars, tag modifiers), and the engine handles the per-product calculations.

Rule Hierarchy (highest priority wins):

1. Manual override – Merchant locks a specific score
2. Exclusion tags – archived, DEAD50 force score to 0
3. Inventory warnings – warning_inv_1 reduces score by 1
4. New arrival boost – Products created within 14 days get score 5
5. Tag modifiers – in-stock adds +1, NAME BRAND adds +1, Sale subtracts -1
6. Seasonal calendar – Category-specific seasonal adjustments
7. Category default – Base score from product type mapping

Real-World Example: Nexus Clothing in Winter

Product: "Rebel Minds Puffer Jacket" (active, Winter)
  Category group: Outerwear - Heavy --> seasonal Winter score: 5
  Tags: none relevant
  Final priority: 5 (PUSH HARD)

Product: "Jordan Craig Stacked Jeans" (active, Winter)
  Category group: Jeans & Pants --> seasonal Winter score: 4
  Tags: NAME BRAND --> +1
  Final priority: 5 (PUSH HARD)

Product: "New Era Yankees 59FIFTY" (active, Winter)
  Category group: Headwear - Caps --> seasonal Winter score: 3
  Tags: NAME BRAND --> +1
  Final priority: 4 (STRONG)

Product: "Generic Mesh Shorts" (active, Winter)
  Category group: Shorts --> seasonal Winter score: 0
  Tags: none relevant
  Final priority: 0 (EXCLUDE)

Product: "Old Season Hoodie" (archived, DEAD50)
  Exclusion tag override: archived --> 0
  Final priority: 0 (EXCLUDE)

How It Works: End-to-End Data Flow

AdPriority connects three systems: Shopify (product catalog), Google Merchant Center (product feed), and Google Ads (campaign bidding). The data flows in one direction, from product data to ad spend allocation.

END-TO-END DATA FLOW
=====================

+-------------------+     +------------------------+     +-------------------+
|                   |     |                        |     |                   |
|   SHOPIFY STORE   |     |   AdPriority ENGINE    |     |  GOOGLE MERCHANT  |
|                   |     |                        |     |     CENTER        |
|  - 5,582 products |---->|  1. Fetch products     |---->|                   |
|  - 90 types       |     |  2. Apply category     |     |  Supplemental     |
|  - 175 vendors    |     |     rules              |     |  Feed (Google     |
|  - 2,522 tags     |     |  3. Apply seasonal     |     |  Sheets)          |
|  - Webhooks for   |     |     calendar           |     |                   |
|    product changes|     |  4. Apply tag          |     |  custom_label_0:  |
|                   |     |     modifiers           |     |    priority-5     |
+-------------------+     |  5. Calculate final    |     |  custom_label_1:  |
                          |     priority (0-5)      |     |    winter         |
                          |  6. Generate custom    |     |  custom_label_2:  |
                          |     labels              |     |    outerwear      |
                          |  7. Write to Google    |     |  custom_label_3:  |
                          |     Sheet               |     |    in-stock       |
                          |                        |     |  custom_label_4:  |
                          +------------------------+     |    name-brand     |
                                                         |                   |
                                                         +--------+----------+
                                                                  |
                                                                  | GMC fetches
                                                                  | daily (auto)
                                                                  v
                                                         +-------------------+
                                                         |                   |
                                                         |   GOOGLE ADS      |
                                                         |   PERFORMANCE MAX |
                                                         |                   |
                                                         |  Campaign 1:      |
                                                         |    Priority 5     |
                                                         |    (max budget)   |
                                                         |                   |
                                                         |  Campaign 2:      |
                                                         |    Priority 3-4   |
                                                         |    (normal budget) |
                                                         |                   |
                                                         |  Campaign 3:      |
                                                         |    Priority 1-2   |
                                                         |    (min budget)   |
                                                         |                   |
                                                         |  [Priority 0:     |
                                                         |   excluded]       |
                                                         |                   |
                                                         +-------------------+

Custom Label Schema

AdPriority uses all five available GMC custom label slots to provide rich segmentation data to Google Ads campaigns.

This schema stays well within GMC’s limit of 1,000 unique values per label.

The Sync Pipeline

For the MVP and Starter tier, AdPriority uses a Google Sheets supplemental feed as the transport mechanism. This approach requires zero GMC API authentication from the merchant and auto-syncs daily.

SYNC PIPELINE (Google Sheets MVP)
==================================

  AdPriority App
       |
       |  Google Sheets API
       v
  +---------------------------+
  | Google Sheet              |
  |                           |
  | id                        | custom_label_0 | custom_label_1 | ...
  | shopify_US_8779..._4605.. | priority-5     | winter         | ...
  | shopify_US_9128..._4726.. | priority-4     | winter         | ...
  | shopify_US_9057..._4700.. | priority-0     | winter         | ...
  |                           |
  | (one row per variant)     |
  | (~15,000-20,000 rows)     |
  +---------------------------+
       |
       |  GMC auto-fetches daily
       v
  Google Merchant Center
       |
       |  Labels applied to matching products
       v
  Google Ads PMAX Campaigns
       |
       |  Product groups segmented by custom labels
       v
  SMART BUDGET ALLOCATION

For the Pro and Enterprise tiers, AdPriority uses the Content API for Shopping directly, enabling near-real-time updates (within GMC’s 2x/day per-product update limit).

Target Market

Primary Audience

AdPriority is built for Shopify merchants who are already running Google Ads but not getting the most out of their budget. The ideal customer has enough products that manual management is painful but not so many that they need an enterprise feed management platform.

Ideal Customer Profile

IDEAL CUSTOMER
==============

  Store Revenue:       $100K - $5M annually
  Product Count:       100 - 50,000 SKUs
  Google Ads Spend:    $1,000 - $50,000/month
  Team Size:           1-10 people
  Pain Point:          "We know we should segment our products in
                        Google Ads but we don't have time to manage it"
  Current Solution:    Manual CSV uploads (quarterly at best) or
                        no custom labels at all
  Decision Maker:      Store owner or marketing manager
  Platform:            Shopify (required)

Why These Customers

Revenue Model

AdPriority follows a SaaS subscription model with four tiers designed to capture merchants at every stage of growth.

Pricing Tiers

PRICING STRUCTURE
=================

  STARTER         GROWTH           PRO              ENTERPRISE
  $29/mo          $79/mo           $199/mo          Custom
  -----------     -----------      -----------      -----------
  500 products    Unlimited        Unlimited        Unlimited
  Manual scores   Seasonal auto    Google Ads API   Multi-store
  GMC sync        Rules engine     AI suggestions   White-label
  Basic labels    Tag modifiers    ROAS tracking    API access
                  New arrival      Performance      Dedicated
                  boost            dashboard        support
  -----------     -----------      -----------      -----------
  Entry point     Sweet spot       Power users      Agencies

Detailed Tier Comparison

Revenue Projections

Assumptions: Average revenue per customer of $60/mo (mix of Starter and Growth tiers), 5% monthly churn, 15% month-over-month growth after launch.

Project Goals

AdPriority development follows a phased approach, starting with a real-world validation using Nexus Clothing (the developer’s own store) before building the SaaS platform.

Goal 1: Validate with Nexus Clothing (Phase 0)

Objective: Prove the concept works with a real store, real products, and real Google Ads campaigns.

• Use Nexus Clothing as the test case (5,582 products, 90 product types, 175 vendors)
• Build the supplemental feed pipeline (Google Sheets to GMC)
• Restructure PMAX campaigns around priority-based product groups
• Measure ROAS improvement over 30 days
• Document the process for replication

Why this matters: Building a SaaS product without first validating the approach on a real store risks building something that sounds good in theory but fails in practice. Nexus Clothing provides a complex, representative test case.

Goal 2: Build the SaaS Platform (Phase 1)

Objective: Transform the validated approach into an installable Shopify app.

• Shopify app with OAuth authentication
• Database storing priority rules and product mappings per merchant
• Automated Google Sheets generation via Sheets API
• Basic Polaris UI for managing priorities
• Onboard 5 beta testers

Goal 3: Launch on Shopify App Store (Phase 2-3)

Objective: Make AdPriority available to the 200,000+ Shopify merchants running Google Ads.

• Complete the seasonal automation engine
• Build the configurable rules engine UI
• Pass Shopify App Store review
• Achieve 100+ installs in the first 90 days
• Maintain less than 5% monthly churn
• Accumulate positive reviews

Goal 4: Scale to 100+ Merchants (Phase 3+)

Objective: Reach product-market fit and sustainable growth.

• 100+ paying customers
• $10,000+ MRR
• Proven ROAS improvement metrics from customer data
• Google Ads API integration (Pro tier)
• AI-powered recommendations based on aggregate performance data

Phase Timeline

DEVELOPMENT TIMELINE
====================

  Phase 0: Nexus MVP                Phase 1: SaaS Foundation
  Week 1-2                          Week 3-4
  +-----------------------------+   +-----------------------------+
  | - Supplemental feed setup   |   | - Shopify app scaffold      |
  | - Category mapping applied  |   | - OAuth authentication      |
  | - PMAX restructured         |   | - Database schema           |
  | - Monitoring & measurement  |   | - Core API endpoints        |
  | - Process documented        |   | - Basic priority UI         |
  +-----------------------------+   +-----------------------------+
          |                                    |
          v                                    v
  Phase 2: Full Product             Phase 3: App Store Launch
  Week 5-8                          Week 9-12
  +-----------------------------+   +-----------------------------+
  | - Seasonal automation       |   | - App Store submission      |
  | - Rules engine UI           |   | - Marketing materials       |
  | - Tag modifiers             |   | - Onboarding flow           |
  | - New arrival boost         |   | - Billing integration       |
  | - Beta testing (5 stores)   |   | - Scale to 100+ merchants   |
  +-----------------------------+   +-----------------------------+

Summary

AdPriority solves a specific, measurable problem: retailers waste ad spend because they cannot efficiently manage which products deserve the most advertising budget. The solution is a purpose-built priority scoring system that automates the assignment of 0-5 scores based on category, season, product status, and brand, then syncs those scores to Google Merchant Center custom labels where Google Ads campaigns can use them for intelligent budget allocation.

The approach is validated first with a real store (Nexus Clothing, 5,582 products), then productized as a Shopify app, and finally scaled through the Shopify App Store. The revenue model targets $29-199/month per merchant, positioning AdPriority below enterprise feed management tools but above basic feed generators, in a market gap where no competitor offers dedicated priority scoring with seasonal automation.

Chapter 2: Product Requirements Document

2.1 Document Overview

Purpose

This Product Requirements Document (PRD) defines the complete functional, non-functional, integration, and user experience requirements for AdPriority. It serves as the authoritative reference for what the product must do, how it must perform, and what constraints it must operate within.

Every feature described in this document traces back to the core problem statement from Chapter 1: retailers waste ad spend because they cannot efficiently manage which products deserve the most advertising budget. Requirements that do not serve this purpose are out of scope.

Scope

This PRD covers AdPriority version 1.0 through version 2.0, spanning four development phases:

Requirements marked with a phase tag indicate the earliest phase in which they must be implemented.

Audience

Version History

Requirement ID Conventions

All requirements use a prefix that indicates their category:

2.2 Product Description

What AdPriority Is

AdPriority is a Shopify embedded application that automates product priority scoring for Google Ads Performance Max (PMAX) campaigns. It assigns a 0-5 priority score to every product in a merchant’s catalog, then syncs those scores as custom labels to Google Merchant Center (GMC). Merchants use these labels to segment PMAX campaigns so that high-priority products receive more ad budget and low-priority products receive less or none.

Core Value Proposition

BEFORE AdPriority                    AFTER AdPriority
================                     ================

All products treated equally         Products scored 0-5 automatically
  |                                    |
  v                                    v
Budget spread evenly                 Budget allocated by priority
  |                                    |
  v                                    v
Shorts get ads in winter             Shorts excluded in winter (score 0)
Dead stock gets impressions          Dead stock excluded always (score 0)
New arrivals buried                  New arrivals boosted (score 5)
  |                                    |
  v                                    v
Poor ROAS                            15-30% ROAS improvement
Hours of manual label management     Automated, zero-maintenance

Product Boundaries

What AdPriority IS:

• A priority scoring system with a 0-5 scale
• A rules engine that calculates scores from product attributes, categories, seasons, and tags
• A sync pipeline that writes scores as custom labels to Google Merchant Center
• A seasonal automation engine that adjusts priorities on season boundaries
• A Shopify embedded app built with Polaris components

What AdPriority IS NOT:

• Not a bid management tool (it does not set bids or budgets in Google Ads)
• Not a feed management platform (it only writes custom labels, not full product feeds)
• Not an analytics dashboard (Pro tier adds read-only performance data, but it is not a reporting tool)
• Not a campaign builder (merchants still structure their PMAX campaigns manually)
• Not a multi-channel tool (v1.0 targets Google Ads only, not Facebook or Bing)

2.3 Functional Requirements

2.3.1 Priority Scoring System

FR-01: Priority Score Definition

Phase: 0 | Priority: P0

Every product receives a single integer score from 0 to 5 that directly controls how aggressively it is advertised in Google Ads.

Constraints:

• Score must be an integer between 0 and 5 inclusive
• Every active product must have a score (no null scores)
• Default score for unclassified products is 2 (Low)
• Score is stored at the product level; variants inherit the product score unless individually overridden (future feature)

Acceptance Criteria:

• Every product in the database has a priority_score column with a CHECK (priority_score BETWEEN 0 AND 5) constraint
• Products without matching rules receive default score of 2
• Score values map to GMC label values using the format priority-{score}

FR-02: Score Assignment Methods

Phase: 0 (manual), 1 (bulk, rules), 2 (seasonal, performance) | Priority: P0

AdPriority supports five methods of assigning priority scores, each appropriate for different use cases:

Acceptance Criteria:

• Manual scoring updates a single product and marks it as priority_source = 'manual'
• Bulk scoring updates up to 1,000 products in a single operation
• Rules-based scoring recalculates on product import and webhook events
• Seasonal scoring triggers automatically on season transition dates
• Performance recommendations are read-only suggestions, not automatic changes

FR-03: Score Override Hierarchy

Phase: 1 | Priority: P0

When multiple scoring methods apply to the same product, the highest-priority method wins. The hierarchy is evaluated top-to-bottom; the first matching rule determines the score.

SCORE OVERRIDE HIERARCHY (highest priority wins)
=================================================

  1. Manual override          -- Merchant locks a specific score
     |                           (priority_locked = true)
     v
  2. Exclusion tags           -- "archived" or "DEAD50" force score to 0
     |                           (hard override, cannot be raised)
     v
  3. Inventory warnings       -- "warning_inv_1" reduces score by 1
     |                           (applied as modifier, not override)
     v
  4. New arrival boost        -- Products created within 14 days get score 5
     |                           (configurable duration and target score)
     v
  5. Tag modifiers            -- "in-stock" adds +1, "NAME BRAND" adds +1,
     |                           "Sale" subtracts -1
     v
  6. Seasonal calendar        -- Category-specific seasonal adjustment
     |                           (from the season x category matrix)
     v
  7. Category default         -- Base score from product type group mapping
     |
     v
  8. Global default           -- Score 2 if no rules match

Modifier Stacking Rules:

• Tag modifiers stack additively (e.g., in-stock +1 and NAME BRAND +1 = +2 total)
• Final score is clamped to the 0-5 range: Math.min(5, Math.max(0, score))
• Override tags (archived, DEAD50) short-circuit all other rules and return 0 immediately
• Manual overrides are respected until the merchant unlocks the product

Real-World Example with Nexus Clothing Data:

Product: "Jordan Craig Stacked Jeans" (active, Winter season)
  Step 1: Manual override?  No (priority_locked = false)
  Step 2: Exclusion tags?   No
  Step 3: Inventory warning? No
  Step 4: New arrival?      No (created > 14 days ago)
  Step 5: Tag modifiers:    NAME BRAND = +1 (store later)
  Step 6: Seasonal calendar: Jeans & Pants, Winter = 4
  Step 7: Category default:  Jeans & Pants = 4 (not needed, seasonal applied)
  Apply modifiers: 4 + 1 (NAME BRAND) = 5
  Final priority: 5 (PUSH HARD)

Product: "Generic Mesh Shorts" (active, Winter season)
  Step 1: Manual override?  No
  Step 2: Exclusion tags?   No
  Step 3: Inventory warning? No
  Step 4: New arrival?      No
  Step 5: Tag modifiers:    None relevant
  Step 6: Seasonal calendar: Shorts, Winter = 0
  Final priority: 0 (EXCLUDE)

Product: "Old Season Hoodie" (archived, DEAD50 tag)
  Step 1: Manual override?  No
  Step 2: Exclusion tags?   Yes -- "archived" found
  Final priority: 0 (EXCLUDE) -- short-circuit, no further processing

Acceptance Criteria:

• Override hierarchy is enforced in the exact order specified
• Manual overrides persist until explicitly unlocked by merchant
• Exclusion tags short-circuit all subsequent rules
• Tag modifiers stack additively and result is clamped to 0-5
• priority_source column records which method determined the final score

2.3.2 Category Mapping

FR-10: Category Rules

Phase: 1 | Priority: P0

The category mapping system translates Shopify product types into priority scores. Because product type names can be long and hierarchical (Nexus uses a {Gender}-{Department}-{SubCategory}-{Detail} convention with 90 unique types), AdPriority groups them into manageable category groups.

Rule Capabilities:

Category Group Structure:

AdPriority organizes 90+ Nexus product types into 20 manageable groups. Each group maps multiple product types to a single set of priority rules.

Acceptance Criteria:

• Merchant can create category groups that map multiple product types to a single priority
• Rules support AND/OR logic for combining conditions
• Unmapped product types receive the global default score (2)
• Category groups are stored per-store (multi-tenant safe)
• Changing a category rule triggers recalculation for all affected products

FR-11: Rule Examples with Nexus Data

Phase: 1 | Priority: P1

The rules engine must support the following patterns, all validated against real Nexus Clothing data:

# Seasonal category rules
IF product_type CONTAINS "Shorts" AND season = "Summer"
  THEN priority = 5

IF product_type CONTAINS "Shorts" AND season = "Winter"
  THEN priority = 0

IF product_type CONTAINS "Hoodies" AND season = "Winter"
  THEN priority = 5

IF product_type CONTAINS "Puffer" AND season = "Summer"
  THEN priority = 0

# Collection-based rules
IF collection = "New Arrivals"
  THEN priority = 5 FOR 14 days

# Tag-based rules (overrides)
IF tag = "archived" OR tag = "DEAD50"
  THEN priority = 0 (override)

IF tag = "clearance"
  THEN priority = 1

# Tag-based rules (modifiers)
IF tag = "NAME BRAND"
  THEN priority + 1

IF tag = "in-stock"
  THEN priority + 1

IF tag = "Sale"
  THEN priority - 1

IF tag = "warning_inv_1"
  THEN priority - 1

# Vendor-based rules (future)
IF vendor = "Nexus Clothing"
  THEN priority + 1 (store brand boost)

Acceptance Criteria:

• All rule patterns above can be expressed in the rules engine
• Rules can be tested with a “preview” mode that shows affected products without applying changes
• Rules are evaluated in priority order (see FR-03 hierarchy)

2.3.3 Product Mapping

FR-20: Product Identification

Phase: 0 | Priority: P0

AdPriority must correctly map Shopify product and variant identifiers to Google Merchant Center product IDs. The mapping is the foundation of the supplemental feed pipeline – an incorrect ID means the custom label will not be applied.

GMC Product ID Format (verified from live GMC export, 124,060 products):

Format:    shopify_US_{productId}_{variantId}
Example:   shopify_US_8779355160808_46050142748904

Components:
  shopify    -- Constant prefix (identifies source platform)
  US         -- Country code (ISO 3166-1 alpha-2)
  8779355160808      -- Shopify product ID (13 digits)
  46050142748904     -- Shopify variant ID (14 digits)

Item Group ID (parent product, used for variant grouping in GMC):

Format:    {productId}
Example:   8779355160808

Verified Real Examples from Nexus GMC Export:

Storage Strategy: Hybrid approach (recommended)

Metafield Schema:

{
  "namespace": "adpriority",
  "key": "config",
  "type": "json",
  "value": {
    "priority": 4,
    "priority_source": "seasonal",
    "priority_locked": false,
    "last_synced_at": "2026-02-10T10:00:00Z",
    "custom_labels": {
      "label_0": "priority-4",
      "label_1": "winter",
      "label_2": "jeans-pants",
      "label_3": "in-stock",
      "label_4": "name-brand"
    }
  }
}

Acceptance Criteria:

• GMC product IDs are generated using the format shopify_US_{productId}_{variantId}
• All variant-level IDs are stored (GMC uses variant-level IDs exclusively)
• Product mapping table has a computed gmc_product_id column
• Mapping handles product ID changes gracefully (e.g., product delete + recreate)

FR-21: Custom Label Structure

Phase: 0 | Priority: P0

AdPriority uses all five Google Merchant Center custom label slots to provide rich segmentation data for Google Ads campaigns. The label schema was designed to stay well within GMC’s limits while providing maximum campaign segmentation flexibility.

Total unique values across all labels: ~38 (well within the 5,000 total limit)

Status Determination Logic:

Brand Tier Determination Logic:

Acceptance Criteria:

• All five custom labels are populated for every active variant in the supplemental feed
• Label values use lowercase with hyphens (e.g., jeans-pants, not Jeans & Pants)
• Label values are within the 100-character maximum per value
• Total unique values per label do not exceed 1,000

2.3.4 Seasonal Calendar

FR-30: Season Definitions

Phase: 2 | Priority: P1

AdPriority uses a four-season calendar with configurable start/end dates. The default configuration follows the Northern Hemisphere retail calendar.

ANNUAL SEASON TIMELINE
=======================

JAN | FEB | MAR | APR | MAY | JUN | JUL | AUG | SEP | OCT | NOV | DEC
|___WINTER____|______SPRING______|______SUMMER______|______FALL______|WIN
       ^              ^                  ^                 ^
     Feb 28         May 31             Aug 31           Nov 30

Configuration Options:

Acceptance Criteria:

• Season detection correctly identifies the current season based on date and timezone
• Season transitions trigger automatic priority recalculation
• Merchants can preview the impact of an upcoming season change before it takes effect
• Manual season override allows merchants to trigger early or late transitions

FR-31: Seasonal Rules

Phase: 2 | Priority: P1

Each category group has a configurable priority score per season. This forms the Category x Season matrix, which is the core of the seasonal automation engine.

Full Seasonal Priority Matrix (Nexus Clothing default configuration):

Holiday Modifiers:

In addition to the seasonal matrix, specific shopping events can temporarily boost priorities:

Holiday Modifier Rules:

• Holiday modifiers are additive on top of the seasonal base score
• Final score is clamped to 0-5 after applying holiday modifiers
• Holiday modifiers do not override manual locks or exclusion tags
• Merchants can enable/disable individual holidays
• Custom holiday events can be created (Growth+ tier)

Acceptance Criteria:

• Seasonal priorities auto-apply on season transition dates
• Category x Season matrix is editable per merchant
• Holiday modifiers apply and expire on the configured dates
• Preview shows exact products and scores that will change on next transition
• Manual season trigger overrides the date-based automatic transition

2.3.5 New Arrival Automation

FR-40: New Arrival Boost

Phase: 2 | Priority: P1

New products added to the store automatically receive a high priority score for a configurable period, ensuring they get advertising visibility during their launch window.

Configuration Parameters:

Behavior:

WITHOUT DECAY (default):
  Day 0-14:   Priority 5 (Push Hard)
  Day 15+:    Falls back to category/seasonal score

WITH DECAY ENABLED:
  Day 0-7:    Priority 5 (Push Hard)
  Day 8-14:   Priority 4 (Strong)
  Day 15-21:  Priority 3 (Normal)
  Day 22+:    Falls back to category/seasonal score

Interaction with Override Hierarchy:

• New arrival boost sits at position 4 in the hierarchy (see FR-03)
• Manual overrides take precedence over new arrival boost
• Exclusion tags (archived, DEAD50) take precedence over new arrival boost
• Inventory warnings take precedence over new arrival boost
• New arrival boost takes precedence over tag modifiers, seasonal rules, and category defaults

Detection Method:

• Shopify created_at timestamp compared against current date
• Products detected via products/create webhook for real-time processing
• Daily reconciliation job catches any missed webhook events

Acceptance Criteria:

• Products created within days_threshold days automatically receive boost_priority score
• Boost expires silently after the threshold period, reverting to standard scoring
• Decay schedule (when enabled) reduces score on the configured interval
• Configuration is per-store, not global
• Manual overrides are not affected by new arrival boost

2.3.6 Google Merchant Center Sync

FR-50: Sync Methods

Phase: 0 (Sheets), 2 (Content API), 1 (CSV) | Priority: P0

AdPriority supports three methods of syncing custom labels to Google Merchant Center, available at different subscription tiers:

Google Sheets Pipeline (MVP and primary method):

AdPriority Database
       |
       |  Google Sheets API (googleapis/sheets/v4)
       v
Google Sheet (shared publicly, Viewer access)
  +----------------------------------------------------------------+
  | id                                    | custom_label_0 | ...    |
  | shopify_US_8779355160808_46050142748904 | priority-5   | ...    |
  | shopify_US_9128994570472_47260097118440 | priority-4   | ...    |
  +----------------------------------------------------------------+
       |
       |  GMC auto-fetches daily (or on manual trigger)
       v
Google Merchant Center
       |
       |  Labels applied to matching products
       v
Google Ads PMAX Campaigns

Feed Size Estimates for Nexus:

Acceptance Criteria:

• Google Sheets supplemental feed is generated with correct column names (id, custom_label_0 through custom_label_4)
• Product IDs in the Sheet exactly match GMC primary feed IDs (case-sensitive)
• Sheet is shared with “Anyone with the link” at Viewer access
• CSV export produces a downloadable file with the same structure
• Content API integration (Pro tier) uses products.custombatch for efficiency

FR-51: Sync Schedule

Phase: 1 | Priority: P0

Sync Status Dashboard:

The UI must display:

• Last sync timestamp
• Number of products pending sync
• Number of products successfully synced
• Number of sync errors
• “Sync Now” button for manual trigger

Acceptance Criteria:

• Scheduled sync runs at merchant-configured intervals (minimum: daily)
• Manual sync trigger writes to Sheet within 60 seconds
• Sync status is visible on the dashboard
• Products with needs_sync = true are included in the next scheduled sync
• After successful sync, needs_sync is set to false and last_synced_at is updated

FR-52: Error Handling

Phase: 1 | Priority: P1

Retry Configuration:

Max retries:          3
Initial delay:        1,000 ms
Backoff multiplier:   2
Maximum delay:        30,000 ms

Acceptance Criteria:

• All sync errors are logged with timestamp, error type, and affected product IDs
• Retry logic uses exponential backoff for transient failures
• Persistent failures (3+ consecutive) trigger a merchant notification
• Manual CSV export is always available as a fallback when automated sync fails
• Error count is displayed on the sync status dashboard

2.3.7 Google Ads Integration (Pro Tier)

FR-60: Performance Data

Phase: 3 | Priority: P2

Pro tier merchants can connect their Google Ads account to view performance metrics segmented by priority tier.

GAQL Query Example:

SELECT
  segments.product_custom_attribute0,  -- priority score label
  metrics.impressions,
  metrics.clicks,
  metrics.cost_micros,
  metrics.conversions,
  metrics.conversions_value
FROM shopping_performance_view
WHERE segments.date DURING LAST_30_DAYS

Acceptance Criteria:

• Performance data is fetched daily and stored in the database
• Dashboard displays ROAS, spend, and conversion data grouped by priority tier
• Historical trend charts show 30, 60, and 90-day windows
• Data is read-only (AdPriority does not modify Google Ads settings)

FR-61: Recommendations

Phase: 3 | Priority: P3

Based on performance data, AdPriority generates actionable recommendations for priority score adjustments.

Acceptance Criteria:

• Recommendations are displayed as dismissible cards in the dashboard
• Each recommendation shows the current score, suggested score, and supporting data
• Merchant can accept (applies change) or dismiss (hides recommendation)
• Dismissed recommendations do not reappear for the same product within 30 days

2.4 Non-Functional Requirements

2.4.1 Performance Requirements

2.4.2 Scalability Requirements

Infrastructure Scaling Approach:

2.4.3 Security Requirements

2.4.4 Availability Requirements

2.5 Integration Requirements

2.5.1 Shopify Integration

IR-01: App Installation

Phase: 1 | Priority: P0

Session Token Claims:

IR-02: Data Access

Phase: 1 | Priority: P0

Required API Scopes:

Data Retrieved from Shopify:

IR-03: Webhooks

Phase: 1 | Priority: P0

Mandatory GDPR Webhooks (required for App Store approval – app will be rejected without these):

App Lifecycle Webhooks:

Product Webhooks:

Webhook Security:

All webhooks must verify the X-Shopify-Hmac-Sha256 header using HMAC-SHA256 with the app’s client secret. Unverified webhooks must be rejected with 401 Unauthorized.

2.5.2 Google Merchant Center

IR-10: Authentication

Phase: 0 (Sheets only, no auth), 2 (Content API) | Priority: P0 (Sheets), P2 (API)

IR-11: API Operations

Phase: 2 (Content API) | Priority: P2

Rate Limits:

2.5.3 Google Ads API (Pro Tier)

IR-20: Authentication

Phase: 3 | Priority: P2

IR-21: API Operations

Phase: 3 | Priority: P2

2.6 UI/UX Requirements

UIR-01: Dashboard

Phase: 1 | Priority: P0

The dashboard is the landing page of the app, providing an at-a-glance view of the store’s priority scoring status.

UIR-02: Product Management

Phase: 1 | Priority: P0

UIR-03: Rules Engine

Phase: 2 | Priority: P1

UIR-04: Seasonal Calendar

Phase: 2 | Priority: P1

UIR-05: Settings

Phase: 1 | Priority: P0

2.7 Data Requirements

DR-01: Nexus Catalog Baseline

The following data has been verified from live Shopify Admin API and GMC product exports:

DR-02: GMC Custom Label Availability

DR-03: GMC Custom Label Constraints

DR-04: Google Sheets Constraints

DR-05: Product ID Format Verification

2.8 Acceptance Criteria

MVP (Phase 0: Nexus Implementation)

Beta Release (Phase 1)

Production Release (Phase 2-3)

2.9 Constraints and Assumptions

Technical Constraints

Platform Constraints

Assumptions

2.10 Out of Scope (v1.0)

The following features are explicitly excluded from version 1.0 and may be considered for future releases:

2.11 Open Questions and Risks

Open Questions

Risks

2.12 Requirement Traceability Matrix

This matrix maps each functional requirement to its implementation phase, source document, and related acceptance criteria.

Summary

This Product Requirements Document defines 21 functional requirements, 24 non-functional requirements, 11 integration requirements, and 5 UI/UX requirement areas for AdPriority. Every requirement traces back to the core problem: retailers waste ad spend by treating all products equally in Google Ads.

The requirements are organized by priority and phase:

• Phase 0 (Week 1-2): Core scoring system (FR-01, FR-20, FR-21, FR-50) validated with Nexus Clothing
• Phase 1 (Week 3-4): SaaS foundation (FR-02, FR-03, FR-10, FR-51, FR-52, IR-01 through IR-03) with 5 beta testers
• Phase 2 (Week 5-8): Full product (FR-11, FR-30, FR-31, FR-40) with seasonal automation and rules engine
• Phase 3 (Week 9-12): App Store launch (FR-60, FR-61, IR-20, IR-21) with billing and scale

Key technical decisions validated during the research phase:

1. GMC product ID format: shopify_US_{productId}_{variantId} – confirmed from 124,060 product export
2. All 5 custom labels available: Only 7 products use label_0 (0.006%), labels 1-4 are empty
3. Supplemental feed pipeline works: 10/10 test products matched in GMC with zero errors
4. Google Sheets capacity is sufficient: ~120,000 cells for Nexus (1.2% of 10M limit)

The next step is to use these requirements as the implementation guide for Phase 0 (Chapter 18) and the architectural foundation for the system design (Chapter 4).

Chapter 3: User Stories & Personas

3.1 Overview

This chapter defines the people who will use AdPriority, what they need from it, and how every requirement traces back to a real problem experienced by a real user type. The user stories documented here serve as the contract between design and implementation: every feature built must satisfy at least one story, and every story must have acceptance criteria that can be verified in a demo or automated test.

Story Format

All stories follow the standard format:

As a [role],
I want to [capability],
So that [benefit].

Each story includes:

• Acceptance criteria – specific, testable conditions that must be true for the story to be considered complete
• Priority – using the MoSCoW framework mapped to P0-P3
• Effort – estimated implementation complexity (Low, Medium, High)
• Phase – which development phase delivers this story
• Dependencies – other stories or infrastructure that must exist first

Priority Definitions

Story ID Conventions

3.2 User Personas

Each persona represents a distinct user type with different goals, constraints, and technical comfort levels. These are not hypothetical archetypes; they are composites of real Shopify merchants drawn from market research and, in one case, the actual store that will validate the MVP.

3.2.1 Persona: Small Store Owner (“Sarah”)

PERSONA PROFILE: SARAH
=======================

  Role:           Store owner and sole operator
  Store size:     200 - 1,000 products
  Monthly revenue: $15,000 - $80,000
  Google Ads spend: $500 - $3,000/month
  Team size:      1 (herself)
  Tech comfort:   Moderate -- comfortable with Shopify admin, intimidated by feed tools
  AdPriority tier: Starter ($29/mo)

Background: Sarah runs a women’s fashion boutique on Shopify. She launched Google Ads six months ago and is spending $1,500/month on a Performance Max campaign. She knows the ads are working – she can see the sales attribution in Shopify – but she suspects she is wasting money advertising products that are out of season or overstocked. She tried DataFeedWatch during a free trial but abandoned it after 30 minutes because the interface was overwhelming.

Pain Points:

Goals:

1. Automate ad spend allocation so she can focus on buying and customer service
2. Stop advertising out-of-season products without manual intervention
3. Give new arrivals a promotional boost automatically
4. Improve ROAS enough to justify increasing her Google Ads budget

How Sarah Uses AdPriority:

• Installs the app and connects her Google account in under 5 minutes
• Reviews the auto-suggested category mappings and makes minor adjustments
• Sets up the seasonal calendar (defaults work for her climate zone)
• Checks the dashboard weekly to see priority distribution
• Occasionally overrides a priority for a product she wants to promote or suppress

Key Stories: US-01, US-02, US-05, US-06, US-30, US-31, US-34

3.2.2 Persona: Growing Brand Manager (“Marcus”)

PERSONA PROFILE: MARCUS
========================

  Role:           E-commerce manager at a growing streetwear brand
  Store size:     1,000 - 10,000 products
  Monthly revenue: $100,000 - $500,000
  Google Ads spend: $5,000 - $20,000/month
  Team size:      3-5 (marketing, warehouse, customer service)
  Tech comfort:   High -- uses Shopify APIs, comfortable with spreadsheets and automation
  AdPriority tier: Growth ($79/mo)

Background: Marcus manages the online store for a mid-sized streetwear brand with 4,200 active products. He runs three PMAX campaigns segmented by product category, but his custom labels are six months out of date because updating them requires exporting a CSV from their product database, manually adding label columns, and uploading it to Google Merchant Center. The process takes him a full day each time he does it, so it only happens when performance drops noticeably.

Pain Points:

Goals:

1. Systematic, repeatable approach to product prioritization that the whole team can follow
2. Seasonal automation that eliminates the quarterly manual update grind
3. Confidence that new arrivals are automatically promoted on day one
4. Ability to bulk-edit priorities when running promotions or clearance events
5. Preview mode so he can verify changes before they sync to GMC

How Marcus Uses AdPriority:

• Spends 30 minutes on initial setup: category mappings, seasonal calendar, tag rules
• Relies on seasonal automation to handle the quarterly transitions
• Uses bulk edit for clearance events and promotional pushes
• Checks the preview before each sync to catch mistakes
• Delegates day-to-day monitoring to a junior team member via the dashboard

Key Stories: US-01, US-02, US-03, US-04, US-06, US-07, US-08, US-32, US-36

3.2.3 Persona: Agency Account Manager (“Diana”)

PERSONA PROFILE: DIANA
=======================

  Role:           Senior account manager at a digital marketing agency
  Stores managed: 12 Shopify stores across 8 clients
  Combined catalog: 30,000+ products
  Combined ad spend: $80,000+/month
  Team size:      4 (herself + 3 account executives)
  Tech comfort:   Expert -- uses APIs, scripts, and automation daily
  AdPriority tier: Pro/Enterprise ($199+/mo)

Background: Diana manages Google Ads for 8 retail clients, all on Shopify. Each client has unique product categories, seasonal patterns, and brand priorities. She currently maintains a master spreadsheet that tracks which custom labels each client should have, but the spreadsheet is always behind reality. Her account executives spend 6-8 hours per client per quarter updating labels manually. She has pitched the idea of a centralized tool to her director, who approved a $200-300/month budget for any tool that can cut this work in half.

Pain Points:

Goals:

1. Manage all client stores from a single dashboard
2. Clone proven rule sets from one store to another to accelerate onboarding
3. Generate per-client usage and performance reports for billing justification
4. Demonstrate measurable ROAS improvement to retain and upsell clients
5. Reduce per-client management time from 6-8 hours to under 1 hour per quarter

How Diana Uses AdPriority:

• Sets up each client store once with category mappings and seasonal rules
• Clones her “fashion retail” rule template to new fashion clients
• Checks the multi-store dashboard daily for sync failures or alerts
• Generates monthly per-store performance reports for client meetings
• Uses ROAS tracking to demonstrate the value of the service

Key Stories: US-20, US-21, US-22, US-37, US-10, US-12

3.2.4 Persona: Nexus Clothing Owner (“Will”) – Validation User

PERSONA PROFILE: WILL
======================

  Role:           Owner and operator of Nexus Clothing
  Store:          nexus-clothes.myshopify.com
  Store size:     5,582 products (2,425 active), 90 product types, 175 vendors
  GMC catalog:    124,060 variants
  Google Ads spend: Active PMAX campaigns
  Team size:      1 for digital operations
  Tech comfort:   High -- runs Docker infrastructure, builds custom tools
  AdPriority tier: Phase 0 (MVP validation)

Background: Will is the developer building AdPriority and the owner of the first store that will use it. Nexus Clothing is a multi-location streetwear retailer with a complex product catalog spanning t-shirts, jeans, outerwear, headwear, footwear, and accessories. The store runs Google Ads Performance Max campaigns but has only 7 out of 124,060 GMC variants with any custom label set (0.006% coverage). This means Google’s AI is treating every product equally, regardless of season, margin, or demand.

Pain Points:

Goals:

1. Validate the AdPriority concept with real data before investing in SaaS development
2. Score all 2,425 active products with appropriate priorities
3. Deploy a supplemental feed covering all ~15,000-20,000 active variants
4. Restructure PMAX campaigns around priority-based asset groups
5. Measure a 15%+ ROAS improvement within 30 days
6. Document the entire process for replication in the SaaS product

How Will Uses AdPriority:

• Phase 0 is a semi-automated process: category mapping spreadsheet, Python scripts, Google Sheets API
• Validates the 20 category groups against real product data
• Tests the seasonal matrix with winter priorities first
• Monitors ROAS daily during the 30-day measurement window
• Documents every decision and outcome for the blueprint book

Key Stories: US-01, US-02, US-05, US-03, US-31, US-33, US-34

Why This Persona Matters: Will is not a future hypothetical user. He is the first user, and his store provides the real-world complexity (5,582 products, 90 types, 124K GMC variants) that validates whether AdPriority’s approach works at scale. Every design decision in Phase 0 is tested against Nexus Clothing data.

3.3 Epic: Product Priority Management

This epic covers the core functionality that makes AdPriority useful: assigning, managing, and automating priority scores on products.

Story US-01: Assign Priority Scores

As a store owner, I want to assign priority scores (0-5) to my products, So that I can control how much ad budget is allocated to each product.

Acceptance Criteria:

• User can view a paginated product list showing product name, image thumbnail, product type, current priority score, and sync status
• Each priority score displays with a color-coded badge (0=gray, 1=red, 2=orange, 3=yellow, 4=blue, 5=green)
• User can click on a product row to open a detail panel showing all product attributes and priority history
• User can change a product’s priority score via a dropdown or slider in the detail panel
• Priority change is saved to the database immediately on selection (no separate save button)
• Saving a priority change creates an audit trail entry recording the old score, new score, user, timestamp, and source (“manual”)
• Saving a priority change adds a GMC sync queue entry for the next sync cycle
• A toast notification confirms the priority change was saved
• If the save fails, the UI reverts to the previous score and shows an error message
• Score labels are visible alongside the numeric value (“5 - Push Hard”, “0 - Exclude”)

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: Product import from Shopify (database must have products to score)

Nexus Validation: In Phase 0, this is done via the category mapping spreadsheet and Python scripts. The SaaS version replaces that manual process with the UI described above.

Story US-02: Category-Based Rules

As a store owner, I want to set category-based rules so new products automatically inherit priority scores, So that I do not have to manually score every new product that arrives in my catalog.

Acceptance Criteria:

• User can view a list of all Shopify product types found in their catalog, grouped by AdPriority category groups
• User can assign a default priority score (0-5) to each category group
• When a new product is created in Shopify (via webhook), the system looks up its product type, matches it to a category group, and assigns the default priority
• When a product’s product type changes in Shopify (via webhook), the system re-evaluates its category-based priority
• Category rules are lower priority than manual overrides (a manually-set score is not overwritten by a category rule)
• User can create custom category groups by combining multiple Shopify product types
• User can edit the name and default priority of any category group
• User can see how many products are in each category group
• A “Preview” button shows which products would be affected by a rule change before it is applied
• Changes to category rules trigger a bulk recalculation of affected product priorities

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-01 (priority scoring must exist), product import (product types must be available)

Nexus Validation: The 20 category groups designed during research (t-shirts, jeans-pants, outerwear-heavy, headwear-caps, etc.) were derived from grouping Nexus Clothing’s 90 product types. Phase 0 validates these groupings against real inventory.

Story US-06: Manual Override

As a store owner, I want to manually override any automatic priority assignment, So that I maintain final control over which products are advertised and at what level.

Acceptance Criteria:

• User can set a priority score on any individual product that overrides all automatic rules (category, seasonal, new arrival)
• A manual override is visually indicated on the product list (e.g., a lock icon or “Override” badge next to the score)
• The override persists across seasonal transitions and rule recalculations
• User can remove the override to return the product to automatic rule-based scoring
• Removing an override immediately recalculates the product’s priority based on current active rules
• The audit trail records override creation and removal as distinct events
• Override reason is optionally recordable (free text field, e.g., “CEO wants this promoted for store event”)
• Bulk override is supported: user can select multiple products and apply a manual override to all of them
• A filter option allows viewing only products with active overrides
• Override count is displayed on the dashboard summary

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: US-01 (priority scoring), US-02 (category rules must exist for override to be meaningful)

Design Note: The override hierarchy is fundamental to the scoring engine. The precedence order is: (1) manual override, (2) exclusion tags, (3) inventory warnings, (4) new arrival boost, (5) tag modifiers, (6) seasonal calendar, (7) category default. Manual override sits at the top because the store owner must always have the final word.

Story US-07: Bulk Edit Priorities

As a store owner, I want to bulk-edit priorities for multiple products at once, So that I can efficiently manage large catalog changes like clearance events or seasonal promotions.

Acceptance Criteria:

• User can select multiple products via checkboxes in the product list
• A “Select All” option selects all products on the current page; a “Select All Matching” option selects all products matching the current filter (even across pages)
• With products selected, a bulk action toolbar appears showing the count of selected products
• Bulk action: “Set Priority” – assigns a chosen score (0-5) to all selected products as manual overrides
• Bulk action: “Remove Override” – removes manual overrides from all selected products, returning them to rule-based scoring
• Bulk action: “Apply Rule” – recalculates priorities for selected products based on current rules
• A confirmation dialog shows the number of products affected and the action to be taken before execution
• Bulk operations process at 1,000+ products per minute
• Progress indicator displays during bulk operations that take longer than 2 seconds
• Bulk operations create individual audit trail entries for each affected product
• Bulk operations add affected products to the GMC sync queue

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-06 (manual override)

Example Use Cases:

3.4 Epic: Seasonal Automation

This epic covers the features that differentiate AdPriority from manual label management: automatic priority adjustments based on a configurable seasonal calendar.

Story US-03: Seasonal Priority Adjustment

As a store owner, I want seasonal automation so my priorities adjust automatically throughout the year, So that I do not have to remember to update labels four times per year and my ad spend always matches the current season.

Acceptance Criteria:

• User can define season boundaries (default: Winter Dec 1 - Feb 28, Spring Mar 1 - May 31, Summer Jun 1 - Aug 31, Fall Sep 1 - Nov 30)
• User can customize season start and end dates to match their business cycle
• User can configure a Category x Season priority matrix defining the base score for each category in each season
• The matrix displays as an editable table with categories as rows and seasons as columns
• When the current date crosses a season boundary, the system automatically recalculates priorities for all products affected by seasonal rules
• Seasonal recalculation respects the override hierarchy (manual overrides are not changed)
• User can manually trigger a season change early or late (e.g., “Switch to Summer now” if the weather turns early)
• A preview panel shows what will change at the next season boundary, including product counts per category and the old vs. new scores
• Seasonal transitions are logged in the audit trail with the trigger source (“automatic” or “manual”)
• A notification is sent to the user when a seasonal transition completes, summarizing the number of products affected

Priority: P1 (Should Have) Effort: High Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules provide the category groups)

Seasonal Matrix Example (from Nexus Clothing research):

CATEGORY x SEASON PRIORITY MATRIX
===================================

                          Winter   Spring   Summer   Fall
                          ------   ------   ------   ----
  T-Shirts                  2        4        5       3
  Shorts                    0        3        5       1
  Jeans & Pants             4        3        3       4
  Hoodies & Sweatshirts     5        3        1       5
  Outerwear - Heavy         5        1        0       4
  Outerwear - Light         3        4        3       4
  Headwear - Caps           3        3        3       3
  Headwear - Cold Weather   5        1        0       4
  Footwear - Sneakers       3        3        4       3
  Footwear - Sandals        0        3        5       1
  Underwear & Basics        2        2        2       2
  Accessories               3        3        3       3
  Jerseys & Sports          2        3        4       3
  Sets & Matching           3        3        4       3
  Suits & Formal            3        3        3       3
  Swimwear                  0        3        5       0
  Bags & Luggage            3        3        3       3
  Jewelry                   3        3        3       3
  Sleepwear                 3        2        2       3
  Kids                      3        3        3       3

Design Note: The matrix is the heart of seasonal automation. A store owner fills this in once (or accepts the defaults for their industry), and the system handles every transition automatically. This single feature eliminates the most common reason merchants let their custom labels go stale.

Story US-04: New Arrival Boost

As a store owner, I want new arrivals to automatically get high priority for a configurable period, So that new products get immediate advertising exposure during their critical launch window.

Acceptance Criteria:

• User can enable or disable the new arrival boost feature
• User can configure the boost duration (default: 14 days, range: 1-90 days)
• User can configure the boost priority score (default: 5, range: 1-5)
• When a new product is created in Shopify (detected via webhook or import), the system assigns the configured boost priority
• The boost is applied only if the resulting score is higher than the score from other rules (boost does not reduce a score)
• User can enable gradual decay: the priority decreases by 1 level at configurable intervals during the boost period
• Example decay: Day 1-5 = priority 5, Day 6-10 = priority 4, Day 11-14 = priority 3, then reverts to rule-based score
• Products with active boosts are visually indicated in the product list (e.g., “New Arrival” badge with countdown)
• User can manually end a boost early on any individual product
• Manual overrides take precedence over new arrival boosts
• When the boost expires, the product’s priority reverts to its rule-calculated score (seasonal + category)
• Boost expiration triggers a recalculation and GMC sync queue entry

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), Shopify webhook for products/create

Gradual Decay Configuration Example:

NEW ARRIVAL BOOST: GRADUAL DECAY
=================================

  Boost Duration: 14 days
  Starting Score: 5 (Push Hard)
  Decay Interval: Every 5 days

  Timeline:
  Day  1 -----> Day  5:  Priority 5  (Push Hard)
  Day  6 -----> Day 10:  Priority 4  (Strong)
  Day 11 -----> Day 14:  Priority 3  (Normal)
  Day 15 onwards:        Reverts to rule-based score

  Product Example: "New Jordan Craig Stacked Jeans"
  - Created: Feb 1
  - Category default: 4 (Jeans & Pants, Winter)
  - Boost: Feb 1-5 = 5, Feb 6-10 = 4, Feb 11-14 = 3*
  - Feb 15 onwards: 4 (category rule takes over)

  * Note: Day 11-14 the decay score (3) is LOWER than the
    category score (4), so category score wins. Boost only
    elevates, never reduces.

3.5 Epic: GMC Synchronization

This epic covers the connection between AdPriority and Google Merchant Center – the mechanism that makes priority scores actionable in Google Ads campaigns.

Story US-05: Sync Status Visibility

As a store owner, I want to see which products are synced to GMC and their current custom labels, So that I can verify my priority settings are actually reaching Google Ads.

Acceptance Criteria:

• The product list includes a “Sync Status” column showing one of: Synced, Pending, Error, Not in GMC
• “Synced” means the product’s current priority score matches what was last written to the supplemental feed
• “Pending” means the priority score has changed since the last sync and is queued for the next sync cycle
• “Error” means the last sync attempt for this product failed (with a tooltip showing the error message)
• “Not in GMC” means the product could not be matched to a GMC product ID
• A sync summary panel on the dashboard shows: total synced, total pending, total errors, last sync timestamp, next scheduled sync
• User can click “Sync Now” to trigger an immediate sync cycle for all pending products
• User can click on an individual product to see its sync history (last 10 sync events with timestamps and statuses)
• Filtering the product list by sync status is supported (e.g., show only “Error” products)
• A warning banner appears if more than 5% of products are in Error status
• The dashboard shows the custom label values currently written to GMC for each synced product

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-01 (products must have scores to sync), Google Sheets API integration, GMC supplemental feed connection

Sync Status Flow:

SYNC STATUS LIFECYCLE
======================

  Product priority changed (manual, rule, or seasonal)
       |
       v
  Status: PENDING
  (queued for next sync cycle)
       |
       |  Sync cycle runs (scheduled or manual)
       v
  Write to Google Sheet
       |
       +---> Success --> Status: SYNCED
       |                 (timestamp updated)
       |
       +---> Failure --> Status: ERROR
                         (error message recorded, retry queued)

Story US-08: Preview Before Sync

As a store owner, I want to preview priority changes before they sync to GMC, So that I can verify changes are correct and avoid pushing wrong labels to my live ads.

Acceptance Criteria:

• Before any sync cycle executes, a preview screen shows all products with pending changes
• The preview displays: product name, current GMC label value, proposed new label value, and the reason for the change (manual, rule, seasonal)
• User can approve the sync to proceed or cancel to hold the changes
• User can remove individual products from the pending sync while keeping others
• For automatic syncs (scheduled), the preview is recorded in a sync log that the user can review after the fact
• For rule changes and seasonal transitions that affect many products, a summary view shows affected product counts per category and per score change direction (increases vs. decreases)
• A diff view highlights products whose score is changing by more than 2 levels (potential large impact)
• The preview includes a “Download CSV” option to export the pending changes for offline review
• Preview data refreshes in real-time as the user makes changes on other pages

Priority: P2 (Nice to Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-05 (sync pipeline must exist for preview to be meaningful)

Why This Matters: Marcus (the growing brand manager persona) has pushed wrong labels to GMC twice due to errors in CSV exports. A preview step prevents this class of error entirely. For Sarah (small store owner), the preview provides reassurance that the system is doing the right thing.

3.6 Epic: Performance Analytics

This epic covers the analytics features available in the Pro tier that connect priority scoring to actual advertising performance. These features require Google Ads API integration.

Story US-10: Priority Tier Metrics

As a marketing manager, I want to see performance metrics by priority tier, So that I can understand whether my priority scoring strategy is actually improving ad performance.

Acceptance Criteria:

• A performance dashboard displays key metrics broken down by priority tier (0-5)
• Metrics shown per tier: impressions, clicks, cost, conversions, revenue, ROAS, CPC, conversion rate
• Data is pulled from Google Ads API and aggregated by the priority score assigned in AdPriority
• Metrics are available for configurable date ranges (last 7 days, 30 days, 90 days, custom)
• A bar chart shows spend distribution across priority tiers
• A table shows the top 10 performing products within each priority tier
• Data refreshes at least once daily (with timestamp of last refresh)
• A summary card highlights the ROAS for priority 5 products vs. the overall catalog ROAS
• Export to CSV is available for all metrics tables
• If Google Ads is not connected, the dashboard shows a clear prompt to connect with an explanation of what metrics will become available

Priority: P2 (Nice to Have) Effort: High Phase: Phase 2-3 Dependencies: Google Ads API integration, US-01 (products must have scores to aggregate against)

Example Dashboard Output:

PERFORMANCE BY PRIORITY TIER (Last 30 Days)
=============================================

  Tier  | Products | Impressions |  Clicks  |   Cost   | Revenue  |  ROAS
  ------+----------+-------------+----------+----------+----------+-------
    5   |      312 |    142,000  |   4,260  |  $8,520  | $34,080  |  4.0x
    4   |      589 |     98,000  |   2,450  |  $3,675  | $12,862  |  3.5x
    3   |      724 |     56,000  |   1,120  |  $1,344  |  $3,628  |  2.7x
    2   |      398 |     12,000  |     240  |    $192  |    $384  |  2.0x
    1   |      201 |      3,000  |      45  |     $27  |     $40  |  1.5x
    0   |      201 |          0  |       0  |      $0  |      $0  |   --
  ------+----------+-------------+----------+----------+----------+-------
  Total |    2,425 |    311,000  |   8,115  | $13,758  | $50,994  |  3.7x

  Insight: Priority 5 products generate 67% of revenue with 62% of spend.
           Priority 0-1 products correctly excluded from budget waste.

Story US-11: ROAS-Based Recommendations

As a marketing manager, I want recommendations for priority adjustments based on ROAS data, So that I can continuously optimize my scoring strategy with data-driven decisions instead of guesswork.

Acceptance Criteria:

• The system analyzes Google Ads performance data and identifies products whose priority score does not match their actual performance
• Recommendations fall into three categories: “Increase Priority” (high ROAS, low priority), “Decrease Priority” (low ROAS, high priority), “Review” (anomalous patterns)
• Each recommendation shows: product name, current priority, suggested priority, reason, supporting metrics (ROAS, spend, revenue)
• Recommendations require a minimum data threshold (e.g., 100+ impressions, 14+ days of data) to avoid noise
• User can accept a recommendation with one click, which applies the suggested priority as a manual override
• User can dismiss a recommendation, which hides it for 30 days
• A recommendation quality score tracks how often accepted recommendations lead to improved ROAS
• Recommendations are refreshed weekly (not real-time, to allow for statistical significance)
• A notification badge shows the count of new recommendations since last review

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-10 (performance metrics must exist first), sufficient data history (minimum 30 days)

Example Recommendations:

Story US-12: Before/After Comparison

As a marketing manager, I want to compare performance before and after priority changes, So that I can measure the impact of my optimization decisions and report results to stakeholders.

Acceptance Criteria:

• When a priority change is deployed, the system records a “change event” with the date and affected products
• A comparison report shows key metrics for a configurable period before the change vs. after the change
• Metrics compared: ROAS, total spend, total revenue, CPC, conversion rate, impressions
• The comparison isolates the products that were affected by the change (not the entire catalog)
• A chart overlays before and after trendlines for visual comparison
• Statistical confidence indicator shows whether the improvement is statistically significant or within normal variance
• Comparison reports can be exported as PDF for sharing with stakeholders
• Historical comparisons are stored and accessible from a “Change History” view
• The system auto-generates a comparison report 30 days after any major change event (10+ products affected)

Priority: P2 (Nice to Have) Effort: High Phase: Phase 2-3 Dependencies: US-10 (performance metrics), US-01 (change events recorded in audit trail)

3.7 Epic: Multi-Store Management

This epic covers the Enterprise tier features that allow agencies and multi-brand operators to manage multiple Shopify stores from a single AdPriority account.

Story US-20: Multi-Store Dashboard

As an agency user, I want to manage multiple stores from one dashboard, So that I can efficiently oversee all my clients’ priority scoring without logging in and out of separate accounts.

Acceptance Criteria:

• User can link multiple Shopify stores to a single AdPriority account
• A store switcher in the navigation allows instant switching between stores
• An aggregate dashboard shows key metrics across all stores: total products scored, total pending syncs, total errors, total stores active
• Each store card on the aggregate dashboard shows: store name, product count, last sync status, overall ROAS (if Google Ads connected)
• Clicking a store card navigates to that store’s individual dashboard (identical to single-store experience)
• User can assign team members to specific stores with role-based access (viewer, editor, admin)
• Store-specific settings (seasons, rules, overrides) are independent between stores
• Adding a new store follows the same OAuth flow as initial setup
• Removing a store requires confirmation and offers a data export option before deletion
• The aggregate dashboard highlights stores with issues (sync errors, stale rules, no recent activity)

Priority: P3 (Future) Effort: Very High Phase: Phase 3+ Dependencies: Complete single-store feature set (US-01 through US-08), multi-tenant database architecture

Story US-21: Rule Cloning Between Stores

As an agency user, I want to clone rules between stores, So that I can quickly onboard new clients by reusing proven configurations from similar stores.

Acceptance Criteria:

• User can select a source store and export its rule configuration as a “rule template”
• Rule templates include: category group definitions, category-to-priority mappings, seasonal matrix, tag modifier rules, new arrival boost settings
• Rule templates do NOT include: product-specific overrides, sync settings, Google account credentials
• User can apply a rule template to a destination store
• When applying a template, the system shows a preview of what will change in the destination store
• The system identifies unmappable categories (product types in the destination store that do not exist in the template) and prompts the user to map them manually
• User can save named templates for reuse (e.g., “Fashion Retail - US” or “Sporting Goods - Seasonal”)
• Templates are versioned; updating a template does not retroactively change stores that previously applied it
• A template library shows all saved templates with descriptions, creation dates, and the number of stores using each

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-20 (multi-store management), US-02 (category rules), US-03 (seasonal rules)

Story US-22: Per-Store Usage Reports

As an agency user, I want per-store usage reports for billing, So that I can accurately bill clients for the management services I provide using AdPriority.

Acceptance Criteria:

• A reporting page shows per-store usage metrics for a configurable date range
• Metrics include: number of priority changes made, number of sync cycles completed, number of products managed, rule changes applied, overrides set
• Reports can be filtered by date range (monthly is the default for billing cycles)
• Reports can be exported as CSV or PDF
• Each report includes the store name, AdPriority plan tier, and billing period
• An optional notes field allows the agency to add client-facing context to each report
• Automated monthly report generation can be scheduled with email delivery
• Reports include a visual summary chart suitable for inclusion in client presentations

Priority: P3 (Future) Effort: Medium Phase: Phase 3+ Dependencies: US-20 (multi-store management), audit trail data

3.8 Discovered Stories

During research, requirements analysis, and persona development, the following stories emerged as necessary for a complete product experience. These stories fill gaps between the explicit requirements and the actual user workflows.

Story US-30: Google Account Connection

As a store owner, I want to connect my Google account so that my custom labels sync automatically, So that I do not have to manually export and upload data to Google Merchant Center.

Acceptance Criteria:

• A settings page provides a “Connect Google Account” button that initiates Google OAuth 2.0
• OAuth requests only the scopes needed: Google Sheets API (for supplemental feed), and optionally Google Ads API (for Pro tier)
• After successful authentication, the system displays the connected Google account email
• The system automatically creates a Google Sheet in the user’s Google Drive for the supplemental feed
• The Sheet is pre-formatted with the correct columns (id, custom_label_0 through custom_label_4)
• Setup instructions guide the user to add the Sheet URL as a supplemental feed in GMC
• A “Test Connection” button verifies the Sheet is accessible and writable
• User can disconnect the Google account at any time (with warning about sync implications)
• Token refresh is handled automatically; the user does not need to re-authenticate unless they revoke access
• If the token expires or is revoked, a prominent warning appears on the dashboard

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: None (this is a foundational integration)

Story US-31: Dashboard Overview

As a store owner, I want to see a dashboard overview so I can quickly understand my priority distribution, So that I know at a glance whether my catalog is well-optimized and if anything needs attention.

Acceptance Criteria:

• The dashboard is the default landing page when the app opens
• A priority distribution chart (bar or pie) shows the count of products at each priority level (0-5)
• A sync status summary shows: synced count, pending count, error count, last sync time
• An upcoming changes panel lists the next seasonal transition with date and affected product count
• Quick stats cards show: total products, products with overrides, new arrivals with active boost, products excluded (priority 0)
• A recent activity feed shows the last 10 priority changes with timestamps and sources
• If the user has not completed initial setup, the dashboard shows an onboarding checklist instead of metrics
• Dashboard data loads in under 2 seconds

Priority: P0 (Must Have) Effort: Medium Phase: Phase 1 Dependencies: US-01 (products must have scores to display)

Story US-32: CSV Import/Export

As a store owner, I want to import and export priorities via CSV, So that I can make bulk changes offline or integrate with other tools in my workflow.

Acceptance Criteria:

• An “Export” button downloads a CSV file with columns: product_id, product_title, product_type, current_priority, override_status, sync_status
• Export respects current filters (if the user has filtered the product list, only filtered products are exported)
• An “Import” button accepts a CSV file with at minimum: product_id and priority columns
• Import validates the file before applying: checks for valid product IDs, valid priority values (0-5), and correct column headers
• Import shows a preview of changes before applying, including: products found, products not found (invalid IDs), and score changes
• User confirms the import after reviewing the preview
• Import applies all changes as manual overrides
• Import creates audit trail entries for each changed product
• Import adds all changed products to the sync queue
• Error rows are reported in a downloadable error file with reasons

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-06 (manual override)

Story US-33: Sync Failure Alerts

As a store owner, I want to receive alerts when sync fails, So that I can take action before my ads run with stale or incorrect labels.

Acceptance Criteria:

• When a sync cycle fails (Google Sheets API error, authentication issue, or Sheet access revoked), the system sends an email notification to the store owner
• The email includes: error type, number of products affected, last successful sync timestamp, and a link to the app’s sync status page
• An in-app banner appears on the dashboard when the last sync attempt failed
• If sync has been failing for more than 24 hours, the banner escalates to a persistent warning
• User can configure notification preferences: email, in-app only, or both
• A webhook URL option allows integration with Slack or other notification tools (Pro tier)
• Alert frequency is rate-limited (maximum one email per hour for the same error type)
• When the sync recovers, a resolution notification is sent

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-05 (sync pipeline must exist)

Story US-34: Quick Setup (Under 5 Minutes)

As a store owner, I want to set up my store in under 5 minutes, So that I can start optimizing my ad spend immediately without a lengthy configuration process.

Acceptance Criteria:

• After app installation, a guided onboarding flow walks the user through setup in 4 steps or fewer
• Step 1: Connect Google account (OAuth popup, < 30 seconds)
• Step 2: Review auto-detected category groups (system groups product types automatically, user confirms or adjusts)
• Step 3: Choose a scoring template (e.g., “Fashion - Seasonal”, “General Retail”, “Custom”) which pre-fills the seasonal matrix and default priorities
• Step 4: Confirm and trigger first sync
• The entire flow is completable in under 5 minutes for a store with 500+ products
• Progress indicators show which steps are complete
• Users can skip steps and complete them later (dashboard shows incomplete setup items)
• A “Quick Start” video or walkthrough is available at each step
• If the user abandons setup mid-flow, they can resume where they left off
• Time to first sync is tracked as a product metric

Priority: P0 (Must Have) Effort: High Phase: Phase 1 Dependencies: US-30 (Google account connection), US-02 (category rules), product import

Story US-35: Unscored Product Detection

As a marketing manager, I want to see which products have no priority assigned, So that nothing falls through the cracks and every product has a deliberate priority decision.

Acceptance Criteria:

• A filter option shows products with no priority score (null or unassigned, distinct from priority 0 which is a deliberate exclusion)
• The dashboard shows a count of unscored products prominently if the count is greater than zero
• New products that arrive via webhook and do not match any category rule are flagged as “Unscored”
• An optional setting auto-assigns unscored products a default score (configurable, default: 3)
• A periodic check (daily) identifies any products that slipped through without scoring and flags them
• The unscored product list includes the product type, so the user can quickly create a category rule to cover the gap

Priority: P1 (Should Have) Effort: Low Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules)

Story US-36: Tag-Based Priority Rules

As a store owner, I want tag-based rules (e.g., “clearance” = priority 0) so that existing Shopify tags drive priorities, So that I can leverage the tagging I already do in Shopify without duplicating effort in AdPriority.

Acceptance Criteria:

• User can create rules that map Shopify product tags to priority modifiers or overrides
• Two rule types supported: “Set to” (absolute, e.g., tag “DEAD50” sets priority to 0) and “Adjust by” (relative, e.g., tag “NAME BRAND” adds +1)
• “Set to” rules function as overrides at the exclusion/tag level in the hierarchy
• “Adjust by” rules are additive modifiers that apply after category and seasonal scores
• User can set the priority order of tag rules (which tag rule wins if a product has multiple matching tags)
• Tag rules are applied automatically when products are imported or updated
• User can preview which products match a tag rule before activating it
• Common tag rules are suggested during onboarding based on detected tags in the catalog (e.g., if the system finds an “archived” tag on 3,000+ products, it suggests a rule to set those to priority 0)
• Tag rules respect the overall override hierarchy (manual overrides still win)

Priority: P1 (Should Have) Effort: Medium Phase: Phase 2 Dependencies: US-01 (priority scoring), US-02 (category rules), product import (tags must be available)

Nexus Clothing Tag Examples:

Story US-37: Agency Client Performance Dashboards

As an agency user, I want per-client performance dashboards, So that I can report ROI to clients and justify the value of priority management services.

Acceptance Criteria:

• Each store in a multi-store account has its own performance dashboard (separate from the agency aggregate view)
• Dashboards can be shared via a read-only link that does not require an AdPriority login
• Shared links are branded with the agency’s name (or white-labeled on Enterprise tier)
• Dashboard includes: priority distribution, ROAS by tier, before/after comparisons, and key metrics
• Data on shared dashboards updates automatically (no manual refresh needed)
• Shared links can be deactivated at any time
• Dashboard includes a “Powered by AdPriority” footer (removable on white-label plans)

Priority: P3 (Future) Effort: High Phase: Phase 3+ Dependencies: US-20 (multi-store), US-10 (performance metrics), US-12 (before/after comparison)

Story US-38: Undo Priority Change

As a store owner, I want to undo a priority change, So that I can quickly revert mistakes without having to remember the previous value.

Acceptance Criteria:

• After changing a product’s priority, an “Undo” action is available for 30 seconds (toast notification with undo button)
• Clicking “Undo” reverts the product to its previous priority score
• The undo action is also recorded in the audit trail
• For bulk changes, the undo reverts the entire bulk operation (all affected products)
• Beyond the 30-second undo window, the user can view the audit trail and manually revert by clicking on a previous score entry
• The audit trail’s “Revert to this” action works for any historical score, not just the most recent

Priority: P2 (Nice to Have) Effort: Low Phase: Phase 2 Dependencies: US-01 (priority scoring), audit trail

Story US-39: Inventory-Aware Priority Adjustment

As a store owner, I want priorities to automatically adjust when inventory is critically low, So that I do not waste ad spend driving traffic to products that will sell out before the ads stop running.

Acceptance Criteria:

• User can enable inventory-aware priority adjustments
• User can set a low-inventory threshold (default: 3 units across all locations)
• When a product’s total inventory drops below the threshold, the system reduces its priority by a configurable amount (default: -2)
• When a product reaches zero inventory, the system sets its priority to 0 (Exclude)
• When inventory is restocked above the threshold, the system restores the product’s rule-based priority
• Inventory checks run at a configurable interval (default: every 6 hours, using Shopify inventory API)
• Inventory-based adjustments respect manual overrides (if the user has overridden a product, low inventory does not change it unless the user opts in)
• A dashboard indicator shows how many products have reduced priorities due to low inventory

Priority: P2 (Nice to Have) Effort: Medium Phase: Phase 2-3 Dependencies: US-01 (priority scoring), Shopify inventory API access (read_inventory scope)

3.9 Story Map

The story map organizes all stories by user activity (rows) and delivery phase (columns), showing the progressive expansion of functionality from MVP to full product.

STORY MAP: ACTIVITIES x PHASES
================================

                    Phase 0          Phase 1              Phase 2                Phase 3+
                    (Nexus MVP)      (SaaS Foundation)    (Full Product)         (Scale)
                    ============     ================     ================       ================

  SETUP &           Manual           US-30 Google         US-32 CSV              US-20 Multi-Store
  ONBOARDING        spreadsheet      US-34 Quick Setup    Import/Export          US-21 Rule Cloning
                    & scripts        US-31 Dashboard                             US-37 Client
                                                                                 Dashboards

  DAILY             Manual           US-01 Assign         US-07 Bulk Edit        US-11 ROAS
  PRIORITY          scoring          US-06 Manual         US-36 Tag Rules        Recommendations
  MANAGEMENT        via scripts      Override             US-35 Unscored
                                     US-38 Undo           Detection
                                                          US-39 Inventory-Aware

  RULES &           Category         US-02 Category       US-03 Seasonal         US-21 Rule Cloning
  AUTOMATION        mapping          Rules                US-04 New Arrival      (cross-store)
                    document                              Boost

  SYNC &            Manual Sheet     US-05 Sync Status    US-08 Preview          US-22 Per-Store
  MONITORING        creation         US-30 Google         US-33 Sync Alerts      Reports
                                     Connection

  ANALYTICS &       Manual ROAS      (basic sync stats    US-10 Tier Metrics     US-11 ROAS
  REPORTING         measurement      in dashboard)        US-12 Before/After     Recommendations
                    in Google Ads                                                US-37 Client
                                                                                 Dashboards

Reading the Story Map

• Left to right: Each column represents increasing product maturity. Phase 0 is a manual validation; Phase 3+ is a fully automated, multi-tenant SaaS product.
• Top to bottom: Each row represents a distinct user activity. The most critical activities (Setup, Daily Management) are at the top.
• Phase 1 stories are the minimum viable product for the SaaS launch. Without these, the app cannot function.
• Phase 2 stories are the differentiators that justify the Growth tier pricing and set AdPriority apart from manual CSV workflows.
• Phase 3+ stories are the scale features that justify Pro/Enterprise pricing and agency adoption.

3.10 Priority Matrix

By Priority Level

By Effort Level

Priority vs. Effort Matrix

PRIORITY vs. EFFORT MATRIX
============================

              Low Effort          Medium Effort           High Effort
              ===========         =============           ===========

  P0          --                  US-01 Assign            US-02 Category Rules
  (Must)                          US-06 Override          US-05 Sync Status
                                  US-31 Dashboard         US-30 Google Connect
                                                          US-34 Quick Setup

  P1          US-35 Unscored     US-07 Bulk Edit         US-03 Seasonal Auto
  (Should)                        US-04 New Arrival
                                  US-32 CSV Import
                                  US-33 Sync Alerts
                                  US-36 Tag Rules

  P2          US-38 Undo         US-08 Preview           US-10 Tier Metrics
  (Nice)                          US-39 Inventory         US-12 Before/After

  P3          --                  US-22 Reports           US-11 Recommendations
  (Future)                                                US-20 Multi-Store
                                                          US-21 Rule Cloning
                                                          US-37 Client Dashboards

Strategic Insight: The P0 stories are a mix of medium and high effort, which is expected for foundational features. The two low-effort stories (US-35, US-38) are quick wins that can be added to any sprint without significant schedule impact. The P3 stories are predominantly high-effort, which aligns with their “future” classification – they require the mature platform that earlier phases build.

3.11 Story Dependencies

Dependency Graph

STORY DEPENDENCY GRAPH
=======================

  [Product Import from Shopify]  <-- Infrastructure prerequisite (not a story)
         |
         v
  US-01 Assign Priority Scores
         |
         +----------+-----------+-----------+
         |          |           |           |
         v          v           v           v
  US-02 Category   US-06      US-05       US-31
  Rules            Override    Sync        Dashboard
         |          |          Status
         |          |           |
         +----+-----+           +----+
         |    |                 |    |
         v    v                 v    v
  US-03 Seasonal    US-07      US-08     US-33
  Automation        Bulk Edit  Preview   Sync Alerts
         |
         v
  US-04 New Arrival Boost


  [Google OAuth]  <-- Infrastructure prerequisite
         |
         v
  US-30 Google Account Connection
         |
         v
  US-34 Quick Setup (Onboarding)


  [Google Ads API]  <-- Infrastructure prerequisite
         |
         v
  US-10 Priority Tier Metrics
         |
         +----------+
         |          |
         v          v
  US-11 ROAS       US-12 Before/After
  Recommendations  Comparison


  US-20 Multi-Store Dashboard
         |
         +----------+-----------+
         |          |           |
         v          v           v
  US-21 Rule       US-22       US-37
  Cloning          Reports     Client Dashboards

Critical Path

The critical path for the Phase 1 launch follows this sequence:

CRITICAL PATH (Phase 1)
========================

  Product Import --> US-01 --> US-02 --> US-05 --> US-30 --> US-34 --> US-31
                     Assign    Category   Sync      Google    Quick     Dashboard
                     Scores    Rules      Status    Connect   Setup

  Estimated Duration: 4-6 weeks (parallel work possible on US-30)

Parallel Tracks: US-30 (Google account connection) can be developed in parallel with US-01 and US-02 because it depends on infrastructure (OAuth), not on the scoring features. US-06 (manual override) can be built alongside US-02. US-31 (dashboard) can be started once US-01 provides data to display.

Dependency Rules

1. No story can be deployed without US-01 – priority scoring is the foundation of every other feature
2. No sync feature can work without US-30 – Google account connection is required for the supplemental feed pipeline
3. No analytics feature can work without US-10 – performance tier metrics require Google Ads API data
4. No multi-store feature can work without US-20 – the multi-store dashboard is the prerequisite for all agency features
5. Seasonal automation (US-03) requires category rules (US-02) – seasonal scores are applied per category group

3.12 Validation with Nexus Clothing

Phase 0 uses Nexus Clothing as a live test case to validate the core stories before investing in SaaS infrastructure. Not all stories are validated in Phase 0 – only those that prove the fundamental value proposition.

Stories Validated in Phase 0

Stories Deferred to Phase 1+

Nexus-Specific Validation Criteria

Success Metrics Per Story

PHASE 0 STORY VALIDATION TARGETS
==================================

  US-01 (Assign Priorities)
  -------------------------
  Target: Every active product has a score between 0 and 5
  Measurement: COUNT(*) WHERE priority IS NOT NULL = 2,425
  Validation: Distribution looks reasonable (not all products at one score)

  Expected Distribution:
    Priority 5: ~300 products  (12%)  -- Seasonal peaks, new arrivals
    Priority 4: ~500 products  (21%)  -- Strong performers, brand names
    Priority 3: ~800 products  (33%)  -- Year-round staples
    Priority 2: ~400 products  (16%)  -- Low-season, low-margin
    Priority 1: ~200 products  (8%)   -- End of season, slow movers
    Priority 0: ~225 products  (10%)  -- Out of stock, discontinued (active only)
    Note: 3,121 archived + 36 draft products also get priority 0 but are separate

  US-02 (Category Rules)
  ----------------------
  Target: 20 category groups cover all 90 product types with zero unmapped types
  Measurement: Every product_type in the catalog maps to exactly one category group
  Validation: Store owner reviews each group and confirms the mapping

  US-05 (Sync Status)
  -------------------
  Target: 100% of active variants appear in supplemental feed
  Measurement: Row count in Google Sheet matches active variant count
  Validation: GMC processing report shows matched products = total rows, errors = 0

Summary

This chapter defined four user personas, 24 user stories, and the relationships between them.

Personas: Sarah (small store owner, Starter tier), Marcus (growing brand manager, Growth tier), Diana (agency account manager, Pro/Enterprise tier), and Will (Nexus Clothing owner, Phase 0 validation). Each persona has distinct pain points and uses AdPriority differently, but all share the same core need: automating the assignment of Google Ads product priorities.

Stories: 7 P0 stories form the minimum viable product (Phase 1). 7 P1 stories deliver the seasonal automation and rules engine that differentiate AdPriority (Phase 2). 5 P2 stories add analytics and quality-of-life features (Phase 2-3). 5 P3 stories enable multi-store agency management (Phase 3+). An additional 10 discovered stories (US-30 through US-39) fill gaps in onboarding, monitoring, and workflow efficiency.

Critical Path: Product import feeds US-01 (assign priorities), which feeds US-02 (category rules), which feeds US-05 (sync status). In parallel, US-30 (Google account connection) enables the sync pipeline. Together, these form the minimum viable product that Phase 1 must deliver.

Validation: Phase 0 validates the five most critical stories (US-01, US-02, US-03, US-05, US-36) using Nexus Clothing as a live test case with 5,582 products, 90 product types, and 124,060 GMC variants. Success is defined as 100% product scoring, accurate category mapping, and a 15%+ ROAS improvement within 30 days.

Chapter 4: Market Analysis

Market Size and Opportunity

The addressable market for AdPriority sits at the intersection of two large ecosystems: Shopify merchants and Google Ads advertisers. Understanding the size and dynamics of this intersection is essential for validating the business opportunity.

Market Funnel

MARKET SIZING FUNNEL
=====================

  Total Shopify Stores Worldwide
  ~4,000,000+ stores
         |
         |  ~25% have meaningful product catalogs
         v
  Stores with 50+ Products
  ~1,000,000 stores
         |
         |  ~20% run Google Ads
         v
  Shopify Stores Using Google Ads
  ~200,000 stores
         |
         |  ~50% use Performance Max
         v
  Shopify Stores Using PMAX
  ~100,000 stores
         |
         |  ~50% have seasonal products or 100+ SKUs
         v
  ADDRESSABLE MARKET
  ~50,000 stores
         |
         |  Realistic capture rate: 0.2-1.0% in Year 1
         v
  YEAR 1 TARGET: 100-500 customers

Market Segments

Why Now

Three market forces make this the right time for AdPriority:

1. PMAX adoption is accelerating. Google is actively migrating advertisers from legacy Shopping campaigns to Performance Max. PMAX relies on custom labels for product segmentation, creating a new and growing need for label management tools.

2. Shopify’s ecosystem is maturing. The Shopify App Store has become the primary distribution channel for e-commerce tools, and merchants increasingly expect embedded, native app experiences rather than external platforms.

3. Feed management is overpriced. Existing solutions start at $64/month for basic functionality and quickly escalate to $200-500/month. There is a clear pricing gap for a focused tool that does one thing well at a lower price point.

Competitor Analysis

The competitive landscape consists of two categories: enterprise feed management platforms (Feedonomics, DataFeedWatch, Channable) and Shopify-native feed apps (AdNabu, Simprosys, GoDataFeed). None are purpose-built for priority scoring.

Detailed Competitor Profiles

Feedonomics

DataFeedWatch

GoDataFeed

Channable

Shopify-Native Competitors

Competitive Comparison Matrix

FEATURE COMPARISON
==================

                          AdPriority  Feedonomics  DataFeedWatch  GoDataFeed  Channable  AdNabu
                          ----------  -----------  -------------  ----------  ---------  ------
Priority scoring (0-5)    AUTO        manual       manual         manual      manual     none
Seasonal automation       BUILT-IN    manual       manual         manual      manual     none
New arrival boost         AUTO        manual       manual         manual      manual     none
Category rules            yes         yes          yes            yes         yes        basic
GMC custom labels         yes         yes          yes            yes         yes        yes
PMAX optimization         PURPOSE     generic      generic        generic     generic    generic
Shopify native app        YES         no           no             partial     no         yes
Multi-channel feeds       no (v1)     60+          2,000+         200+        2,500+     multi
Managed service           no          yes          setup          $299        no         no
Starting price            $29/mo      ~$1,000/mo   $64/mo         $39/mo      $119/mo    free
Free trial                14 days     no           yes            yes         yes        yes

The Market Gap

What Competitors Are

Every competitor in this space is fundamentally a feed management tool. Their core value proposition is taking product data from one platform and formatting it for another: Shopify to Google, Shopify to Facebook, Shopify to Amazon, and so on. Custom labels are a secondary feature, one of dozens of attributes they can manipulate.

What AdPriority Is

AdPriority is a priority optimization tool. Its core value proposition is determining which products deserve the most ad spend and automatically communicating that decision to Google Ads through custom labels. Feed management is not the goal; intelligent budget allocation is.

MARKET POSITIONING
==================

  FEED MANAGEMENT TOOLS              PRIORITY OPTIMIZATION (AdPriority)
  -------------------------          ----------------------------------
  "Get your products to              "Get the RIGHT products the
   Google correctly"                  RIGHT amount of ad spend"

  Focus: Data formatting             Focus: Budget allocation
  Scope: Multi-channel               Scope: Google Ads PMAX
  Labels: One feature of many        Labels: The entire product
  Rules: Build from scratch          Rules: Pre-built scoring system
  Seasonal: Manual                   Seasonal: Automated calendar
  Audience: Feed managers            Audience: Store owners & marketers

Five Gaps AdPriority Fills

Gap 1: No Dedicated Priority Scoring Tool Exists

All competitors treat custom labels as one feature among many. Merchants must figure out their own scoring logic, build their own rules, and maintain them manually. AdPriority provides an opinionated, pre-built scoring system (0-5) that works out of the box.

Gap 2: Seasonal Automation Is Missing Everywhere

Not a single competitor offers a built-in seasonal calendar that automatically adjusts product priorities. Every existing tool requires the merchant to manually update rules when seasons change. AdPriority includes a seasonal calendar engine that transitions priorities automatically based on configurable season dates.

Gap 3: The Price Point Gap for Shopify SMBs

The market has a clear pricing gap:

PRICE POSITIONING
=================

  $1,000+/mo  |  Feedonomics (enterprise, managed service)
              |
  $500/mo     |
              |
  $200-300/mo |  DataFeedWatch Agency ($239)
              |  GoDataFeed Pro ($199)              <-- AdPriority Pro ($199)
              |                                          Undercuts with focused features
  $100-200/mo |  Channable ($119+)
              |  DataFeedWatch Merchant ($84)        <-- AdPriority Growth ($79)
              |                                          Better value for priority use case
  $50-100/mo  |  DataFeedWatch Shop ($64)
              |
  $25-50/mo   |  GoDataFeed Lite ($39)              <-- AdPriority Starter ($29)
              |                                          Lowest entry point with real features
  $0-25/mo    |  Simprosys ($4.99)
              |  AdNabu (free tier)
              |

Budget tools ($5-40/mo) offer basic feed generation with no intelligent features. Mid-tier tools ($64-239/mo) are powerful but complex and not Shopify-optimized. Enterprise tools ($1,000+/mo) are overkill for most Shopify stores. AdPriority fills the $29-199/mo range with Shopify-native, purpose-built priority intelligence.

Gap 4: PMAX-Specific Optimization

Existing tools were built for legacy Google Shopping campaigns and adapted for Performance Max. Their custom label support is generic. AdPriority is designed from the ground up for PMAX, where custom labels are the primary mechanism for product grouping and bid strategy segmentation.

Gap 5: Simplicity vs. Complexity

DataFeedWatch and Channable offer powerful rule builders, but they require significant learning curves and hours of manual configuration. A store owner who wants to “boost winter jackets and exclude summer shorts” should not need to learn a rule syntax. AdPriority provides opinionated defaults that work immediately, with customization available for those who want it.

AdPriority Differentiation

Five Competitive Advantages

Unique Value Proposition

AdPriority is the only Shopify app that automatically scores your products for Google Ads priority, turning complex feed optimization into a one-click solution.

Supporting value propositions:

• Profit-first scoring: Prioritize high-margin products without writing manual rules
• PMAX-optimized: Custom labels designed specifically for Performance Max campaign success
• Shopify-native: Seamless integration that feels like part of the Shopify admin
• Accessible pricing: Enterprise-grade scoring intelligence at SMB prices ($29-199/month)

Positioning Statement

For Shopify merchants running Google Ads Performance Max campaigns who struggle to prioritize products for maximum profitability, AdPriority is an intelligent product scoring app that automatically calculates and applies priority scores to Google Shopping custom labels. Unlike general feed management tools that require manual rule configuration, AdPriority uses a proven scoring algorithm with seasonal automation to optimize custom labels for Performance Max success.

Google Ads Performance Max Context

Understanding how PMAX campaigns use custom labels is essential to understanding why AdPriority exists.

What Performance Max Is

Performance Max (PMAX) is Google’s AI-driven campaign type that serves ads across all Google inventory: Search, Display, YouTube, Discover, Gmail, and Maps. For e-commerce, PMAX replaces legacy Smart Shopping campaigns and is now Google’s recommended campaign type for product advertising.

How PMAX Uses Custom Labels

In a PMAX campaign, the merchant creates asset groups that contain collections of products. Products are assigned to asset groups using listing group filters, which can filter on:

• Product category (Google taxonomy)
• Brand
• Item ID
• Condition
• Custom labels (0-4)

Custom labels are the most flexible segmentation mechanism because the merchant controls what values they contain. This is where AdPriority creates value.

PMAX CAMPAIGN STRUCTURE WITH AdPriority LABELS
===============================================

  PMAX Campaign: "All Products"
  |
  +-- Asset Group: "Priority 5 - Push Hard"
  |   Filter: custom_label_0 = "priority-5"
  |   Budget: $100/day (maximum)
  |   Products: Winter jackets, trending hoodies, new arrivals
  |
  +-- Asset Group: "Priority 4 - Strong Performers"
  |   Filter: custom_label_0 = "priority-4"
  |   Budget: $60/day (high)
  |   Products: Core jeans, name-brand caps, seasonal staples
  |
  +-- Asset Group: "Priority 3 - Standard"
  |   Filter: custom_label_0 = "priority-3"
  |   Budget: $30/day (normal)
  |   Products: Year-round basics, mid-tier items
  |
  +-- Asset Group: "Priority 1-2 - Low/Minimal"
  |   Filter: custom_label_0 IN ("priority-1", "priority-2")
  |   Budget: $10/day (minimum)
  |   Products: Off-season items, low margin, slow movers
  |
  +-- [Priority 0 products EXCLUDED from all asset groups]
      Products: Dead stock, archived, out of stock

The Custom Label Advantage

Without custom labels, all products compete equally for budget within a PMAX campaign. Google’s AI optimizes for conversions, but it has no concept of seasonality, margin, or strategic priority. A pair of shorts might get clicked in January (because someone in Florida is searching), consuming budget that would generate higher returns on a winter jacket.

Custom labels give the merchant control over budget allocation without micromanaging individual products. By grouping products into priority tiers, the merchant tells Google’s AI: “Spend most of your budget on these products, some on these, and none on those.”

Why This Matters for AdPriority

The effectiveness of PMAX campaigns is directly tied to the quality of product segmentation. AdPriority automates the most impactful segmentation decision – which products should get the most budget – and delivers it through the mechanism PMAX is designed to use: custom labels.

WITHOUT AdPriority                  WITH AdPriority
==================                  ===============

  All products in one group           Products segmented by priority
  Equal budget allocation             Budget weighted to best performers
  Seasonal items get wrong budget     Seasonal priorities auto-adjust
  Dead stock wastes impressions       Dead stock excluded automatically
  New arrivals buried                 New arrivals boosted for 14 days
  Manual updates (if any)             Automated daily sync

  Result: Average ROAS                Result: Improved ROAS

Go-to-Market Strategy

Primary Distribution Channel: Shopify App Store

The Shopify App Store is the primary acquisition channel. Competitors underinvest in this channel because they are multi-platform tools. As a Shopify-native app, AdPriority has a natural advantage.

Messaging Themes

1. “Stop guessing which products to promote”
2. “Automatic product scoring for Google Ads”
3. “One-click PMAX optimization”
4. “Built for Shopify, optimized for profit”

Launch Sequence

LAUNCH SEQUENCE
===============

  Month 1-2: Nexus MVP
  - Validate on own store
  - Document results (ROAS improvement)
  - Build case study

  Month 3: Beta Launch
  - 5 beta testers (free)
  - Collect feedback
  - Iterate on UI and rules

  Month 4: Paid Launch
  - App Store submission
  - Starter + Growth tiers
  - Content marketing begins

  Month 6: Growth Phase
  - Pro tier with Google Ads integration
  - First case studies published
  - Partner outreach begins

  Month 12: Scale
  - 100+ customers target
  - Enterprise tier
  - Agency partnerships

Summary

The market for Google Ads product priority optimization is large (~50,000 addressable Shopify stores), growing (PMAX adoption accelerating), and underserved (no competitor offers purpose-built priority scoring with seasonal automation). Existing competitors are feed management tools priced for enterprises or basic feed generators without intelligent features.

AdPriority occupies a clear market gap: a Shopify-native, affordable ($29-199/month) priority scoring tool designed specifically for Performance Max campaign optimization. The competitive advantages – automated scoring, seasonal calendars, simple 0-5 scale, and native Shopify integration – address real pain points that no existing product solves.

Chapter 5: Success Criteria

Overview

Success criteria define the measurable outcomes that determine whether each phase of AdPriority development has achieved its objectives. These criteria are structured around four phases, each building on the validated results of the previous one.

This chapter also documents validation milestones that have already been achieved during the research phase, providing a foundation of confirmed technical feasibility.

Phase 0 Success: Nexus MVP

Phase 0 validates the core concept using Nexus Clothing as a live test case. The goal is to prove that priority-based custom labels measurably improve Google Ads ROAS before investing in SaaS infrastructure.

Success Criteria

Phase 0 Definition of Done

PHASE 0 CHECKLIST
=================

  TECHNICAL
  [x] Google Sheets supplemental feed connected to GMC
  [x] Product ID format verified (shopify_US_{productId}_{variantId})
  [x] Custom labels recognized by GMC (10/10 test products matched)
  [ ] Full catalog scored (2,425 active products, ~15K-20K variants)
  [ ] Supplemental feed processing without errors

  CAMPAIGN STRUCTURE
  [ ] PMAX campaigns restructured with priority-based asset groups
  [ ] Budget allocation aligned to priority tiers
  [ ] Priority 0 products excluded from all campaigns

  MEASUREMENT
  [ ] Baseline ROAS captured (30-day pre-change period)
  [ ] Post-change ROAS captured (30-day post-change period)
  [ ] Comparison report generated

  DOCUMENTATION
  [ ] Category mapping validated with store owner
  [ ] Seasonal calendar confirmed
  [ ] Tag modifier rules confirmed
  [ ] End-to-end process documented for SaaS replication

Expected Outcomes

Phase 1 Success: SaaS Foundation

Phase 1 transforms the validated Nexus MVP into an installable Shopify app that other merchants can use. The focus is on core infrastructure: authentication, data storage, and automated feed generation.

Success Criteria

Phase 1 Definition of Done

PHASE 1 CHECKLIST
=================

  AUTHENTICATION
  [ ] Shopify OAuth 2.0 flow working
  [ ] Session tokens stored securely
  [ ] App installs and uninstalls cleanly
  [ ] GDPR webhooks implemented (mandatory for App Store)

  DATA LAYER
  [ ] PostgreSQL database provisioned (postgres16 container)
  [ ] Prisma schema deployed (stores, rules, products, sync_logs)
  [ ] Product import pipeline (paginated Shopify API fetch)
  [ ] Webhook handlers (products/create, products/update, products/delete)

  RULES ENGINE
  [ ] Category-to-priority mapping configurable
  [ ] Tag modifier rules configurable
  [ ] Manual override per product
  [ ] Score calculation pipeline (hierarchy: manual > tag > seasonal > category)

  SYNC PIPELINE
  [ ] Google Sheets API integration
  [ ] Automated Sheet generation with correct column structure
  [ ] Sheet sharing (public viewer access)
  [ ] Sync status tracking in database

  USER INTERFACE
  [ ] Dashboard: priority distribution, sync status, recent activity
  [ ] Product list: sortable, filterable, inline priority editing
  [ ] Rules page: category mapping, tag modifiers
  [ ] Settings: Google account connection, sync preferences

  QUALITY
  [ ] 5 beta testers actively using the app
  [ ] Zero critical bugs in production
  [ ] < 2 second page load times
  [ ] Error logging and alerting functional

Technical Targets

Phase 2 Success: Full Product

Phase 2 adds the features that differentiate AdPriority from manual feed management: seasonal automation, a configurable rules engine UI, and the new arrival boost system. This phase also expands from beta to paid customers.

Success Criteria

Phase 2 Feature Matrix

PHASE 2 FEATURES
=================

  SEASONAL AUTOMATION
  +-----------------------------------------------+
  | Season Calendar                                |
  |                                                |
  | Winter: Dec 1 - Feb 28    Spring: Mar 1 - May 31
  | Summer: Jun 1 - Aug 31    Fall:   Sep 1 - Nov 30
  |                                                |
  | Category x Season Priority Matrix:             |
  |                                                |
  |              Winter  Spring  Summer  Fall       |
  | T-Shirts       2       4       5      3        |
  | Shorts          0       3       5      1        |
  | Hoodies        5       3       1      5        |
  | Outerwear      5       1       0      4        |
  | Headwear-Caps  3       3       3      3        |
  | Beanies        5       1       0      3        |
  |                                                |
  | [Auto-transitions on season boundaries]        |
  +-----------------------------------------------+

  RULES ENGINE
  +-----------------------------------------------+
  | Rule Builder                                   |
  |                                                |
  | IF product_type CONTAINS "Shorts"              |
  |    AND current_season = "Summer"               |
  | THEN priority = 5                              |
  |                                                |
  | IF tag INCLUDES "DEAD50"                       |
  | THEN priority = 0 (override)                   |
  |                                                |
  | IF tag INCLUDES "NAME BRAND"                   |
  | THEN priority + 1 (modifier)                   |
  |                                                |
  | IF created_at > 14 days ago                    |
  | THEN priority = 5 (new arrival boost)          |
  +-----------------------------------------------+

  NEW ARRIVAL BOOST
  +-----------------------------------------------+
  | Configuration                                  |
  |                                                |
  | Boost duration:  14 days (configurable)        |
  | Boost priority:  5 (configurable)              |
  | Decay option:    5 -> 4 -> 3 over time         |
  | Override manual: No (manual always wins)        |
  +-----------------------------------------------+

Phase 3 Success: App Store Launch

Phase 3 takes AdPriority from a working product to a publicly available Shopify app. Success at this stage is defined by App Store approval, install velocity, and sustainable growth metrics.

Success Criteria

App Store Requirements Checklist

Shopify has specific requirements for app approval. Meeting these is a hard gate for Phase 3 success.

SHOPIFY APP STORE REQUIREMENTS
===============================

  MANDATORY (will not approve without these)
  [ ] OAuth 2.0 authentication (no API keys)
  [ ] GDPR webhooks: customers/data_request, customers/redact, shop/redact
  [ ] App uninstall webhook handled (cleanup user data)
  [ ] Embedded app experience (App Bridge + Polaris)
  [ ] Session token authentication (not cookie-based)
  [ ] HTTPS everywhere
  [ ] Privacy policy URL
  [ ] Clear value proposition in listing

  QUALITY REQUIREMENTS
  [ ] No broken links or dead pages
  [ ] Responsive design (works on all screen sizes)
  [ ] Loading states for async operations
  [ ] Error handling with user-friendly messages
  [ ] Onboarding flow for new installs

  LISTING REQUIREMENTS
  [ ] App name (AdPriority)
  [ ] Tagline (< 80 characters)
  [ ] Detailed description
  [ ] Screenshots (minimum 3)
  [ ] Demo video (recommended)
  [ ] Pricing displayed clearly
  [ ] Support contact information
  [ ] Category selection

Key Metrics Dashboard

These are the ongoing metrics that define AdPriority’s health and growth trajectory across all phases.

Business Metrics

Product Metrics

Customer Impact Metrics

Validation Milestones Already Achieved

Before any code was written for the SaaS platform, the research phase validated several critical technical assumptions. These milestones de-risk the implementation by confirming that the core pipeline works with real data.

Milestone 1: GMC Product ID Format Verified

Date: 2026-02-10 Status: ACHIEVED

The Shopify-to-GMC product ID format was confirmed by analyzing a live GMC export of 124,060 products from the Nexus Clothing account.

VERIFIED ID FORMAT
==================

  Format:   shopify_US_{productId}_{variantId}
  Example:  shopify_US_8779355160808_46050142748904

  Components:
  - Prefix:      "shopify_US_" (constant for all US Shopify stores)
  - Product ID:  13-digit Shopify product ID
  - Separator:   "_"
  - Variant ID:  14-digit Shopify variant ID

  Verification:
  - Source: GMC TSV export (124,060 rows)
  - All IDs follow this format consistently
  - All IDs are variant-level (no product-only IDs found)
  - Country code is "US" for all Nexus products

Why this matters: The supplemental feed must use IDs that exactly match GMC’s primary feed. An incorrect format would cause zero products to match. This was the single highest-risk technical assumption.

Milestone 2: All 5 Custom Labels Available

Date: 2026-02-10 Status: ACHIEVED

Analysis of the GMC product export confirmed that all five custom label slots are effectively available for AdPriority use.

Why this matters: If custom labels were already in use for other purposes (e.g., another app or manual feed rules), AdPriority would need to share or negotiate label slots. Having all 5 available means the full label schema can be implemented without conflict.

Milestone 3: Supplemental Feed Pipeline Confirmed

Date: 2026-02-10 Status: ACHIEVED

A test supplemental feed of 10 real Nexus products was created as a Google Sheet, connected to GMC, and processed successfully.

SUPPLEMENTAL FEED TEST RESULTS
===============================

  Test Parameters:
  - Feed type:     Google Sheets
  - Format:        6 columns (id + 5 custom labels)
  - Sample size:   10 active Nexus products
  - Data sources:  Content API - US, Content API - Local, Local Feed Partnership

  Results:
  +----------------------------------+-----------+
  | Metric                           | Result    |
  +----------------------------------+-----------+
  | Total products in feed           | 10        |
  | Products matched in GMC          | 10 (100%) |
  | Attribute names recognized       | All       |
  | Processing errors                | None      |
  | Time to process                  | < 1 hour  |
  | Feed accepted by GMC             | Immediate |
  +----------------------------------+-----------+

  Sample Products Tested:
  +-----------------------------------+----------+--------+----------------------+
  | Product                           | Priority | Season | Category             |
  +-----------------------------------+----------+--------+----------------------+
  | New Era Colts Knit 2015           | 4        | winter | headwear-cold-weather |
  | New Era Yankees 59FIFTY           | 4        | winter | headwear-caps        |
  | G3 Patriots Hoodie                | 0        | winter | hoodies-sweatshirts  |
  | Rebel Minds Puffer Jacket         | 5        | winter | outerwear-heavy      |
  +-----------------------------------+----------+--------+----------------------+

  Conclusion: Pipeline is PRODUCTION-READY for MVP deployment.

Why this matters: This test confirmed the entire data flow from Google Sheet to GMC custom labels. The 100% match rate with zero errors validates that the ID format, column naming, and sheet sharing approach all work correctly.

Milestone 4: Nexus Catalog Analyzed

Date: 2026-02-10 Status: ACHIEVED

The complete Nexus Clothing catalog was pulled from the live Shopify Admin API, providing the data needed to design the category mapping and rules engine.

NEXUS CATALOG ANALYSIS
======================

  Overall:
  - Total products:        5,582
  - Active products:       2,425
  - Archived products:     3,121
  - Draft products:        36
  - GMC variants:          124,060

  Product Types:
  - Unique types:          90
  - Grouped into:          20 category groups
  - Top type:              Men-Tops-T-Shirts (1,101 products, 19.7%)
  - Naming convention:     {Gender}-{Department}-{SubCategory}-{Detail}

  Vendors:
  - Unique vendors:        175
  - Top vendor:            New Era (576 products)
  - Name brands:           2,328 products tagged "NAME BRAND"

  Tags:
  - Unique tags:           2,522
  - Key priority tags:     archived (3,130), DEAD50 (615),
                           NAME BRAND (2,328), Sale (1,471),
                           in-stock (930), warning_inv_1 (3,619)

  Seasonal Distribution:
  - Year-round products:   ~60% (jeans, headwear-caps, underwear, accessories)
  - Seasonal products:     ~40% (shorts, outerwear, hoodies, beanies, sandals)

Why this matters: The catalog analysis informed the design of the 20 category groups, the seasonal priority matrix, and the tag modifier rules. These are the building blocks of the rules engine and have been designed from real data rather than theoretical assumptions.

Milestone 5: GMC Specifications Documented

Date: 2026-02-10 Status: ACHIEVED

All GMC custom label specifications and constraints were researched and documented.

Risk Mitigation

Each phase has identified risks with planned mitigations.

Phase 0 Risks

Phase 1 Risks

Phase 2 Risks

Phase 3 Risks

Summary

Success for AdPriority is defined in concrete, measurable terms at each phase:

• Phase 0 proves the concept works with a real store and real Google Ads campaigns. The supplemental feed pipeline is already validated (10/10 products matched). Remaining work is full catalog deployment, PMAX restructuring, and ROAS measurement.

• Phase 1 proves the concept can be delivered as a self-service Shopify app. Success means 5 beta testers are using the app with working OAuth, product import, rules engine, and automated Google Sheets sync.

• Phase 2 proves the product differentiators work at scale. Seasonal automation, the rules engine UI, and new arrival boost must function reliably with 50+ paying customers and less than 8% monthly churn.

• Phase 3 proves the product can grow through the Shopify App Store. 100+ installs in 90 days, a 4.5+ star rating, less than 5% churn, and $5,000+ MRR define a successful launch.

The research phase has already de-risked the three highest-uncertainty technical questions: the GMC product ID format works, all 5 custom labels are available, and the supplemental feed pipeline processes correctly. The remaining work is execution.

Chapter 6: System Architecture

This chapter defines the high-level architecture of AdPriority, covering component decomposition, deployment topology, security boundaries, and communication patterns. Every design decision maps back to the constraints established in Part I: a single-developer build targeting the Shopify App Store, deployed on existing Synology NAS infrastructure.

4.1 High-Level Architecture

The system is composed of five primary subsystems connected by REST APIs, webhooks, and scheduled jobs. The following diagram traces the complete path from a merchant’s Shopify store through to a live Google Ads campaign.

                           MERCHANT BROWSER
                          (Shopify Admin iFrame)
                                  |
                                  | App Bridge 4.x
                                  | Session Token
                                  v
 +-----------------------------------------------------------------+
 |                      AdPriority Application                     |
 |                                                                 |
 |  +---------------------+        +----------------------------+ |
 |  |   Frontend (SPA)    |  REST  |      Backend API           | |
 |  |                     | -----> |                            | |
 |  |  React 18 + Vite    |  JSON  |  Express.js + TypeScript   | |
 |  |  Polaris v13        |        |  Prisma ORM                | |
 |  |  React Query        |        |  Zod Validation            | |
 |  +---------------------+        +---+--------+--------+------+ |
 |                                     |        |        |        |
 |                              +------+   +----+----+   |        |
 |                              |          |         |   |        |
 |                              v          v         v   v        |
 |                      +----------+ +----------+ +----------+   |
 |                      |PostgreSQL| |  Worker  | |Scheduler |   |
 |                      |    16    | | (inline) | |  (cron)  |   |
 |                      |adpriority| |          | |          |   |
 |                      |   _db    | +----+-----+ +----+-----+   |
 |                      +----------+      |            |          |
 +-----------------------------------------------------------------+
        |              |                  |            |
        |              |                  |            |
        v              v                  v            v
 +-----------+  +-----------+  +------------------+  +----------+
 |  Shopify  |  |  Shopify  |  | Google Sheets    |  |  Google  |
 |  Admin    |  | Webhooks  |  | API (v4)         |  |   Ads    |
 |  API      |  |           |  |                  |  |   API    |
 | (GraphQL) |  | products/ |  | Writes priority  |  | (future) |
 |           |  | update    |  | data to Sheet    |  |          |
 +-----------+  | app/      |  +--------+---------+  +----------+
                | uninstall |           |
                +-----------+           v
                              +------------------+
                              | Google Merchant  |
                              | Center           |
                              |                  |
                              | Fetches Sheet    |
                              | daily as         |
                              | supplemental     |
                              | feed             |
                              +--------+---------+
                                       |
                                       v
                              +------------------+
                              | Custom Labels    |
                              | Applied to       |
                              | Product Listings |
                              |                  |
                              | label_0: priority|
                              | label_1: season  |
                              | label_2: type    |
                              | label_3: status  |
                              | label_4: brand   |
                              +--------+---------+
                                       |
                                       v
                              +------------------+
                              | PMAX Campaigns   |
                              | Listing Groups   |
                              | filtered by      |
                              | custom_label_0   |
                              +------------------+

End-to-end latency budget: A priority change made in the AdPriority UI reaches a live Google Ads campaign within 24 hours (bounded by GMC’s daily supplemental feed fetch cycle).

4.2 Component Breakdown

4.2.1 Shopify Embedded App (Frontend)

The frontend runs as an embedded iFrame inside the Shopify Admin, using App Bridge 4.x for authentication and navigation.

Key pages:

The frontend makes no direct calls to Google APIs. All external integrations are mediated by the backend.

4.2.2 Backend API (Express.js + TypeScript)

The backend serves three roles: API server for the frontend, webhook receiver for Shopify, and host for the inline worker and scheduler.

Route groups:

/auth/shopify/*          Shopify OAuth install + callback
/auth/google/*           Google OAuth connect + callback
/api/v1/products/*       Product CRUD, bulk ops, import
/api/v1/rules/*          Rule CRUD, reorder, test, apply
/api/v1/seasons/*        Season CRUD, preview, transition
/api/v1/sync/*           Trigger, status, history, export
/api/v1/settings/*       Store config, label config
/api/v1/dashboard/*      Stats, activity feed
/webhooks/shopify/*      products/create, update, delete, app/uninstalled
/health                  Liveness probe

4.2.3 Database (PostgreSQL 16)

AdPriority uses the shared postgres16 container already running on the Synology NAS. A dedicated database and user provide logical isolation.

Core tables (9 total):

stores              Tenant registry (one row per Shopify shop)
products            Product priority scores and GMC mapping
rules               Priority rule definitions
rule_conditions     AND/OR conditions per rule
seasons             Season date ranges per store
season_rules        Category x Season priority matrix
sync_logs           GMC sync audit trail
subscriptions       Shopify billing records
audit_logs          Change tracking for compliance

See Chapter 12 for the complete schema definition and Prisma model.

4.2.4 Worker (Inline Background Jobs)

For the MVP, background jobs run inline within the Express process using node-cron for scheduling and a simple in-memory queue for webhook-triggered work. This eliminates the need for Redis and Bull in Phase 0-2, reducing infrastructure complexity.

Future (Phase 3+): When scaling to multi-tenant SaaS, the worker will be extracted into a separate process backed by Bull + Redis for reliable job queuing, retry semantics, and concurrency control.

4.2.5 External Integrations

+---------------------+---------------------------+---------------------------+
| Integration         | MVP (Phase 0-2)           | SaaS (Phase 3+)           |
+---------------------+---------------------------+---------------------------+
| Shopify Admin API   | GraphQL for product fetch | Same                      |
| Shopify Webhooks    | products/*, app/*         | Same + orders/* (Pro)     |
| Google Sheets API   | Write priority data       | Same (Starter tier)       |
| GMC Content API     | Not used                  | Direct label updates      |
| Google Ads API      | Not used                  | Performance data (Pro)    |
| Shopify Billing API | Not used (Nexus only)     | Subscription management   |
+---------------------+---------------------------+---------------------------+

4.3 Deployment Architecture

4.3.1 Infrastructure Topology

AdPriority deploys as Docker containers on a Synology DS920+ NAS (192.168.1.26), joining the existing postgres_default network for database access. Cloudflare Tunnel provides a secure HTTPS endpoint for Shopify to reach the application without port forwarding or a static IP.

                    INTERNET
                       |
             +-------------------+
             | Cloudflare Edge   |
             | TLS termination   |
             | DDoS protection   |
             +--------+----------+
                      |
             Cloudflare Tunnel
             (encrypted tunnel)
                      |
  +-------------------------------------------------+
  |            Synology NAS (192.168.1.26)          |
  |                                                 |
  |  +-------------------------------------------+ |
  |  |        Docker Engine                       | |
  |  |                                            | |
  |  |  +----------------+   +----------------+  | |
  |  |  | adpriority     |   | postgres16     |  | |
  |  |  | (backend +     |   | (PostgreSQL 16)|  | |
  |  |  |  frontend +    |   |                |  | |
  |  |  |  worker)       |   | adpriority_db  |  | |
  |  |  |                |   | salessight_db  |  | |
  |  |  | Port: 3010     |   | shopsyncflow_db|  | |
  |  |  +-------+--------+   | stanly_db      |  | |
  |  |          |             | taskmanager_db |  | |
  |  |          |             +-------+--------+  | |
  |  |          |                     |           | |
  |  |          +----------+----------+           | |
  |  |                     |                      | |
  |  |            postgres_default                | |
  |  |            (bridge network)                | |
  |  |                                            | |
  |  |  +----------------+                       | |
  |  |  | cloudflared    |                       | |
  |  |  | (tunnel agent) |                       | |
  |  |  | Routes:        |                       | |
  |  |  | app.adpriority |                       | |
  |  |  |  .com -> :3010 |                       | |
  |  |  +----------------+                       | |
  |  +-------------------------------------------+ |
  +-------------------------------------------------+

4.3.2 Container Configuration

Development (docker-compose.yml):

services:
  adpriority:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "3010:3010"
    volumes:
      - ./backend/src:/app/backend/src
      - ./admin-ui/src:/app/admin-ui/src
    environment:
      NODE_ENV: development
      DATABASE_URL: postgresql://adpriority_user:AdPrioritySecure2026@postgres16:5432/adpriority_db
      SHOPIFY_API_KEY: ${SHOPIFY_API_KEY}
      SHOPIFY_API_SECRET: ${SHOPIFY_API_SECRET}
      GOOGLE_CLIENT_ID: ${GOOGLE_CLIENT_ID}
      GOOGLE_CLIENT_SECRET: ${GOOGLE_CLIENT_SECRET}
    networks:
      - postgres_default

networks:
  postgres_default:
    external: true

Production (docker-compose.prod.yml):

services:
  adpriority:
    image: adpriority:${VERSION:-latest}
    restart: always
    environment:
      NODE_ENV: production
      DATABASE_URL: ${DATABASE_URL}
      ENCRYPTION_KEY: ${ENCRYPTION_KEY}
    networks:
      - postgres_default
      - adpriority_internal
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3010/health"]
      interval: 30s
      timeout: 5s
      retries: 3

networks:
  postgres_default:
    external: true
  adpriority_internal:
    driver: bridge

4.3.3 Single-Container Strategy

For the MVP, the backend serves the compiled frontend as static files from a single Express process. This simplifies deployment, networking, and resource usage:

adpriority container (Node.js 20)
|
+-- Express server (:3010)
|   +-- /api/v1/*          --> API routes
|   +-- /auth/*            --> OAuth routes
|   +-- /webhooks/*        --> Shopify webhooks
|   +-- /health            --> Liveness probe
|   +-- /*                 --> Static files (React build)
|
+-- Inline worker
|   +-- node-cron jobs
|   +-- Webhook event queue
|
+-- Prisma Client
    +-- postgres16:5432/adpriority_db

This mirrors the architecture of the existing sales-page-app reference implementation at /volume1/docker/sales-page-app/, which also serves a React + Polaris frontend from a single backend process.

4.4 Security Architecture

4.4.1 Authentication Layers

+---------------------+-------------------+-------------------------------+
| Layer               | Mechanism         | Implementation                |
+---------------------+-------------------+-------------------------------+
| Shopify Merchant    | App Bridge        | Session token verification    |
| (embedded app)      | Session Token     | via Shopify library           |
+---------------------+-------------------+-------------------------------+
| Shopify API         | OAuth 2.0         | Access token stored           |
| (product data)      | Access Token      | encrypted in stores table     |
+---------------------+-------------------+-------------------------------+
| Google APIs         | OAuth 2.0         | Refresh token stored          |
| (Sheets, GMC, Ads)  | Refresh Token     | encrypted in stores table     |
+---------------------+-------------------+-------------------------------+
| Shopify Webhooks    | HMAC-SHA256       | Signature in                  |
| (event ingestion)   | Signature         | X-Shopify-Hmac-SHA256 header  |
+---------------------+-------------------+-------------------------------+
| Cloudflare Tunnel   | Tunnel Token      | Only Cloudflare can reach     |
| (network)           |                   | the backend; no open ports    |
+---------------------+-------------------+-------------------------------+

4.4.2 Credential Storage

All sensitive credentials are encrypted at rest using AES-256-GCM with a master key stored in an environment variable (ENCRYPTION_KEY), never in the database or code repository.

4.4.3 Data Protection

4.4.4 Rate Limiting

+--------------------------+----------+---------+
| Endpoint Group           | Limit    | Window  |
+--------------------------+----------+---------+
| API (authenticated)      | 100 req  | 1 min   |
| Sync trigger             | 10 req   | 1 min   |
| Bulk operations          | 5 req    | 1 min   |
| Export / download        | 5 req    | 1 min   |
| Webhooks (Shopify-signed)| No limit | --      |
+--------------------------+----------+---------+

4.5 Communication Patterns

4.5.1 Frontend to Backend (REST API)

The React frontend communicates with the Express backend via JSON REST APIs. Authentication is handled by Shopify App Bridge session tokens, which are attached as Bearer tokens to every request.

Browser (iFrame)
    |
    |  GET /api/v1/products?priority=5&page=1
    |  Authorization: Bearer <session-token>
    |
    v
Express API
    |
    |  1. Verify session token (Shopify library)
    |  2. Extract store_id from token
    |  3. Query database (scoped by store_id)
    |  4. Return JSON response
    |
    v
Browser renders Polaris components

4.5.2 Shopify to AdPriority (Webhooks)

Shopify delivers event payloads over HTTPS to registered webhook endpoints. Cloudflare Tunnel ensures the backend is reachable from Shopify’s servers.

Shopify Platform
    |
    |  POST /webhooks/shopify/products/update
    |  X-Shopify-Hmac-SHA256: <signature>
    |  Content-Type: application/json
    |
    v
Express Webhook Handler
    |
    |  1. Verify HMAC signature
    |  2. Parse product payload
    |  3. Queue for processing (inline worker)
    |  4. Return 200 OK immediately
    |
    v
Inline Worker
    |
    |  1. Look up product in database
    |  2. Check for type/tag changes
    |  3. Recalculate priority (if not locked)
    |  4. Mark product as needs_sync
    |
    v
Database updated (async Sheet sync on next hourly batch)

Registered webhooks:

4.5.3 AdPriority to Google Sheets (Scheduled Sync)

The hourly sync job collects all products with pending changes and writes them to the tenant’s Google Sheet via the Sheets API (v4).

Scheduler (node-cron, hourly)
    |
    |  1. Query: SELECT * FROM products WHERE needs_sync = true
    |  2. Group by store_id
    |
    v
For each tenant:
    |
    |  3. Build row data: [gmc_id, label_0, label_1, label_2, label_3, label_4]
    |  4. Authenticate with tenant's Google OAuth refresh token
    |  5. Call sheets.spreadsheets.values.update()
    |     - Clear existing data
    |     - Write header + all product rows
    |  6. Mark products as synced in database
    |  7. Create sync_log entry
    |
    v
Google Sheet updated
    |
    |  GMC fetches automatically (daily schedule)
    |
    v
Custom labels applied to GMC products within 24 hours

4.5.4 Google Sheets to GMC (Supplemental Feed)

This is a passive integration. Once a Google Sheet is registered as a supplemental feed in GMC, Google fetches it automatically on a daily schedule. AdPriority does not interact with GMC directly in the MVP.

+------------------+        +-------------------+        +------------------+
| Google Sheet     |  PULL  | Google Merchant   |  AUTO  | Google Ads       |
| (AdPriority-     | -----> | Center            | -----> | (PMAX Campaigns) |
|  managed)        | daily  |                   |        |                  |
|                  |        | Matches id column |        | Listing groups   |
| Rows:            |        | to primary feed   |        | filter by        |
|  id              |        | products          |        | custom_label_0   |
|  custom_label_0  |        |                   |        |                  |
|  custom_label_1  |        | Applies labels    |        | Budget allocated |
|  custom_label_2  |        |                   |        | by priority tier |
|  custom_label_3  |        |                   |        |                  |
|  custom_label_4  |        |                   |        |                  |
+------------------+        +-------------------+        +------------------+

4.5.5 Cron Job Schedule

All scheduled jobs run within the backend process via node-cron.

MINUTE  HOUR  DAY  DESCRIPTION
------  ----  ---  ----------------------------------------
  0      *     *   Hourly: Sync pending products to Google Sheet
  0      0     *   Daily:  Check for season transition
  0      1     *   Daily:  Expire new arrival boosts
  0      3     *   Daily:  Reconcile Shopify products
  0      4     0   Weekly: Clean up old sync_logs (> 90 days)

4.6 Technology Stack Summary

+-------------------+---------------------+------------------------------------+
| Layer             | Technology          | Rationale                          |
+-------------------+---------------------+------------------------------------+
| Frontend          | React 18 + Vite     | Industry standard, fast builds     |
| UI Components     | Shopify Polaris v13  | Native Shopify look and feel       |
| Server State      | React Query v5       | Caching, refetching, pagination    |
| Backend           | Express.js 4.x      | Simple, mature, Shopify ecosystem  |
| Language          | TypeScript 5.x      | Type safety across full stack      |
| ORM               | Prisma 5.x          | Type-safe queries, migrations      |
| Validation        | Zod                 | Schema-first, TypeScript-native    |
| Database          | PostgreSQL 16       | Shared instance, proven, JSONB     |
| Scheduling        | node-cron           | Lightweight, no Redis dependency   |
| Logging           | Pino                | Structured JSON, fast              |
| Deployment        | Docker              | Consistent builds, easy rollback   |
| Ingress           | Cloudflare Tunnel   | Existing infra, TLS, DDoS shield   |
| Version Control   | Git + GitHub        | Standard workflow                  |
+-------------------+---------------------+------------------------------------+

4.7 Scaling Considerations

The MVP architecture is designed for a single-tenant Nexus deployment and early multi-tenant usage (up to approximately 50 tenants). The following table maps growth milestones to architectural changes.

+---------------+--------+----------------------------------------------+
| Tenants       | Phase  | Architecture Change                          |
+---------------+--------+----------------------------------------------+
| 1 (Nexus)     | 0      | Single container, inline worker, node-cron   |
+---------------+--------+----------------------------------------------+
| 2-50          | 1-2    | Same architecture, monitor DB query times    |
+---------------+--------+----------------------------------------------+
| 50-200        | 3      | Extract worker to separate container          |
|               |        | Add Redis for job queue (Bull)                |
|               |        | Add connection pooling (PgBouncer)            |
+---------------+--------+----------------------------------------------+
| 200-1000      | 4+     | Move to managed PostgreSQL (RDS/Supabase)     |
|               |        | Horizontal scaling with load balancer         |
|               |        | Content API replaces Sheets for Pro/Ent tiers |
+---------------+--------+----------------------------------------------+
| 1000+         | Future | Multi-region deployment                       |
|               |        | Database read replicas                        |
|               |        | CDN for static assets                         |
+---------------+--------+----------------------------------------------+

The key insight is that complexity is deferred, not designed away. Every scaling change listed above is additive – the core application code does not need rewriting, only the infrastructure around it.

4.8 Chapter Summary

Chapter 7: Data Flow & Pipeline

This chapter traces the complete lifecycle of product data as it moves through the AdPriority system – from Shopify catalog, through priority scoring, into Google Merchant Center, and ultimately into Google Ads campaign targeting. Each pipeline stage is documented with its trigger, latency, and failure mode.

5.1 End-to-End Data Flow

The following diagram shows the full pipeline from product creation in Shopify to budget allocation in Google Ads.

+-------------+     +--------------+     +--------------+     +---------------+
|   Shopify   |     |  AdPriority  |     |   Priority   |     |    Google     |
|   Store     | --> |   Database   | --> |   Scoring    | --> |    Sheet      |
|             |     |              |     |   Engine     |     |               |
| 5,582 prods |     | products     |     | Rules +      |     | id +          |
| 124k GMC    |     | rules        |     | Seasons +    |     | custom_label_ |
| variants    |     | seasons      |     | Overrides    |     | 0 through 4   |
+------+------+     +------+-------+     +------+-------+     +-------+-------+
       |                   |                    |                      |
       |  Webhook/         |  On product        |  Hourly              |  Daily
       |  Import           |  change            |  batch               |  fetch
       v                   v                    v                      v
+-------------+     +--------------+     +--------------+     +---------------+
|  Product    |     |  Store in    |     |  Write to    |     |    GMC        |
|  payload    |     |  database    |     |  Google      |     | Supplemental  |
|  received   |     |  with rules  |     |  Sheet via   |     |    Feed       |
|             |     |  applied     |     |  Sheets API  |     |               |
+-------------+     +--------------+     +--------------+     +-------+-------+
                                                                      |
                                                              Custom labels
                                                              applied to
                                                              GMC products
                                                                      |
                                                                      v
                                                              +---------------+
                                                              |  Google Ads   |
                                                              |  PMAX         |
                                                              |  Campaigns    |
                                                              |               |
                                                              | Listing group |
                                                              | filters by    |
                                                              | custom_label_0|
                                                              +---------------+

Total pipeline latency (worst case): ~25 hours

• Webhook delivery: seconds
• Priority calculation: < 1 second
• Sheet update: up to 1 hour (next hourly batch)
• GMC fetch: up to 24 hours (daily schedule)
• Google Ads applies labels: near-instant after GMC update

Total pipeline latency (best case): ~1 hour

• Manual sync trigger writes to Sheet immediately
• GMC manual fetch or recently-scheduled fetch picks up changes

5.2 MVP Flow: Google Sheets Pipeline

The MVP uses Google Sheets as the transport layer between AdPriority and GMC. This approach was validated with a 10-product test batch (10/10 matched, zero issues). See ADR-001 in Chapter 7 for the rationale.

                        AdPriority Backend
                               |
                    +----------+----------+
                    |                     |
            Priority Engine        Sheets Writer
                    |                     |
                    v                     v
            +-------------+      +----------------+
            |  products   |      | Google Sheets  |
            |  table      | ---> | API v4         |
            |             |      |                |
            | priority: 4 |      | sheets.values  |
            | needs_sync  |      | .update()      |
            +-------------+      +-------+--------+
                                         |
                    +--------------------+
                    |
                    v
            +----------------+
            | Google Sheet   |
            |                |
            | Row format:    |
            | id             | = shopify_US_{prodId}_{varId}
            | custom_label_0 | = priority-{0-5}
            | custom_label_1 | = {season}
            | custom_label_2 | = {category_group}
            | custom_label_3 | = {product_status}
            | custom_label_4 | = {brand_tier}
            +-------+--------+
                    |
                    | GMC fetches daily (pull model)
                    v
            +----------------+
            | Google         |
            | Merchant       |
            | Center         |
            |                |
            | Matches rows   |
            | by id column   |
            | to primary     |
            | feed products  |
            +----------------+

Sheet sizing for Nexus:

The Sheet comfortably handles the Nexus catalog. Even at full 124,060 variants, usage would be only 7.4% of the limit.

5.3 Future Flow: Content API Pipeline

For the SaaS product (Growth tier and above), a direct Content API integration removes the 24-hour GMC fetch delay and eliminates the Google Sheet dependency.

                        AdPriority Backend
                               |
                    +----------+----------+
                    |                     |
            Priority Engine        Content API Writer
                    |                     |
                    v                     v
            +-------------+      +---------------------+
            |  products   |      | GMC Content API     |
            |  table      | ---> | v2.1                |
            |             |      |                     |
            | priority: 4 |      | products.update()   |
            | needs_sync  |      | or custombatch()    |
            +-------------+      +----------+----------+
                                            |
                                  Direct API call
                                  (near real-time)
                                            |
                                            v
                                 +---------------------+
                                 | Google Merchant     |
                                 | Center              |
                                 |                     |
                                 | Labels applied      |
                                 | within minutes      |
                                 +---------------------+

Content API constraints:

Hybrid approach (recommended for production SaaS):

• Google Sheets for Starter tier (simpler setup, daily sync)
• Content API for Growth/Pro/Enterprise tiers (faster updates)

5.4 Product Sync Pipeline

5.4.1 Initial Import (App Install)

When a merchant installs AdPriority, all active products are imported from Shopify and scored.

App Install
    |
    v
1. Create tenant record in stores table
    |
    v
2. Fetch products from Shopify GraphQL API
   (paginated, 250 per page)
   Nexus: 5,582 products = ~23 pages
    |
    v
3. For each product + variant:
   +--------------------------------------------------+
   | a. Generate GMC ID:                               |
   |    shopify_US_{productId}_{variantId}              |
   |                                                    |
   | b. Determine product type mapping                  |
   |    (from category-mapping rules)                   |
   |                                                    |
   | c. Calculate initial priority:                     |
   |    - Check manual override          (priority: 1)  |
   |    - Check seasonal calendar        (priority: 2)  |
   |    - Check new arrival status       (priority: 3)  |
   |    - Check category rules           (priority: 4)  |
   |    - Apply store default            (priority: 5)  |
   |                                                    |
   | d. Determine custom labels:                        |
   |    label_0 = priority-{score}                      |
   |    label_1 = {current_season}                      |
   |    label_2 = {category_group}                      |
   |    label_3 = {product_status}                      |
   |    label_4 = {brand_tier}                          |
   |                                                    |
   | e. Insert into products table                      |
   |    (needs_sync = true)                             |
   +--------------------------------------------------+
    |
    v
4. Trigger immediate Sheet sync
   (write all products to Google Sheet)
    |
    v
5. Create sync_log entry
   (products_total, products_success, products_failed)
    |
    v
6. Return import summary to UI

Estimated import time for Nexus: 2-5 minutes (network-bound by Shopify API pagination rate limits).

5.4.2 Webhook-Driven Updates

After initial import, Shopify webhooks keep the database current.

Shopify Platform                      AdPriority Backend
      |                                      |
      |  products/create                     |
      | -----------------------------------> |
      |                                      |  1. Verify HMAC
      |                                      |  2. Parse product payload
      |                                      |  3. Generate GMC IDs for all variants
      |                                      |  4. Apply rules -> calculate priority
      |                                      |  5. INSERT into products table
      |                                      |  6. Mark needs_sync = true
      |                                      |  7. Return 200 OK
      |                                      |
      |  products/update                     |
      | -----------------------------------> |
      |                                      |  1. Verify HMAC
      |                                      |  2. Parse product payload
      |                                      |  3. Check: is priority_locked?
      |                                      |     YES -> skip recalculation
      |                                      |     NO  -> continue
      |                                      |  4. Check: did product_type change?
      |                                      |     YES -> recalculate priority
      |                                      |  5. Check: did tags change?
      |                                      |     YES -> recalculate status label
      |                                      |  6. Check: did inventory change?
      |                                      |     YES -> check for out-of-stock (priority 0)
      |                                      |  7. UPDATE products table
      |                                      |  8. Mark needs_sync = true (if changed)
      |                                      |  9. Return 200 OK
      |                                      |
      |  products/delete                     |
      | -----------------------------------> |
      |                                      |  1. Verify HMAC
      |                                      |  2. Soft-delete from products table
      |                                      |  3. Remove from next Sheet sync
      |                                      |  4. Return 200 OK
      |                                      |
      |  app/uninstalled                     |
      | -----------------------------------> |
      |                                      |  1. Verify HMAC
      |                                      |  2. Mark store as inactive
      |                                      |  3. Retain data for 30 days
      |                                      |  4. Schedule cleanup job
      |                                      |  5. Return 200 OK

5.5 Priority Recalculation Triggers

Priority scores are not static. The following events trigger a recalculation for affected products.

+---------------------------+-------------------+---------------------------+
| Trigger                   | Scope             | Mechanism                 |
+---------------------------+-------------------+---------------------------+
| Manual override           | Single product    | API call from UI          |
|                           |                   | Sets priority_locked=true |
+---------------------------+-------------------+---------------------------+
| Bulk priority update      | Selected products | API call from UI          |
|                           |                   | Batch UPDATE              |
+---------------------------+-------------------+---------------------------+
| Rule created/modified     | All matching      | Rule engine evaluates     |
|                           | products          | all products against      |
|                           |                   | new/changed rule          |
+---------------------------+-------------------+---------------------------+
| Rule deleted              | Previously        | Fallback to next          |
|                           | matched products  | applicable rule or        |
|                           |                   | store default             |
+---------------------------+-------------------+---------------------------+
| Season transition         | All products with | Cron job (daily check)    |
| (calendar date reached)   | season_rules for  | or manual trigger from UI |
|                           | that category     |                           |
+---------------------------+-------------------+---------------------------+
| New product arrives       | New product       | Webhook: products/create  |
| (Shopify webhook)         |                   | Apply new arrival boost   |
+---------------------------+-------------------+---------------------------+
| Product type/tag change   | Changed product   | Webhook: products/update  |
| (Shopify webhook)         |                   | Re-evaluate rules         |
+---------------------------+-------------------+---------------------------+
| New arrival expires       | Products past     | Cron job (daily)          |
| (boost duration ended)    | boost duration    | Revert to rule/default    |
+---------------------------+-------------------+---------------------------+
| Inventory hits zero       | Out-of-stock      | Webhook: products/update  |
|                           | product           | Set priority to 0         |
+---------------------------+-------------------+---------------------------+

5.5.1 Priority Resolution Order

When multiple sources assign a priority, the following hierarchy determines which value wins.

Priority 1 (Highest):  Manual override (priority_locked = true)
    |
    v
Priority 2:            Seasonal calendar rule
    |                  (category x current season)
    v
Priority 3:            New arrival boost
    |                  (product created within N days)
    v
Priority 4:            Category-based rule
    |                  (first matching rule by order_index)
    v
Priority 5 (Lowest):   Store default
                       (stores.default_priority, typically 3)

Resolution algorithm:

function calculatePriority(product, store, currentSeason):
    // 1. Manual override always wins
    if product.priority_locked:
        return { score: product.priority, source: "manual" }

    // 2. Check seasonal calendar
    seasonRule = findSeasonRule(product.product_type, currentSeason, store.id)
    if seasonRule exists:
        return { score: seasonRule.priority, source: "seasonal" }

    // 3. Check new arrival boost
    daysSinceCreation = daysBetween(product.created_at, now())
    if daysSinceCreation <= store.new_arrival_days:
        return { score: store.new_arrival_priority, source: "new_arrival" }

    // 4. Check category-based rules (ordered by order_index)
    matchingRule = evaluateRules(product, store.rules)
    if matchingRule exists:
        return { score: matchingRule.priority, source: "rule" }

    // 5. Fall back to store default
    return { score: store.default_priority, source: "default" }

5.6 Data Freshness Requirements

Each stage of the pipeline has different latency expectations. The table below defines the target and maximum acceptable delay for each.

+----------------------------+-----------+-------------+--------------------+
| Pipeline Stage             | Target    | Max         | Bottleneck         |
+----------------------------+-----------+-------------+--------------------+
| Shopify webhook delivery   | < 5 sec   | < 60 sec    | Shopify platform   |
+----------------------------+-----------+-------------+--------------------+
| AdPriority DB update       | < 1 sec   | < 5 sec     | Database query     |
+----------------------------+-----------+-------------+--------------------+
| Priority recalculation     | < 1 sec   | < 10 sec    | Rule engine eval   |
+----------------------------+-----------+-------------+--------------------+
| Google Sheet update        | < 1 hour  | < 2 hours   | Hourly batch job   |
| (hourly batch)             |           |             |                    |
+----------------------------+-----------+-------------+--------------------+
| GMC supplemental feed      | < 24 hrs  | < 48 hrs    | GMC daily fetch    |
| fetch (daily)              |           |             | schedule           |
+----------------------------+-----------+-------------+--------------------+
| Google Ads label impact    | < 1 hour  | < 4 hours   | Google Ads sync    |
| (after GMC update)         |           |             | with GMC           |
+----------------------------+-----------+-------------+--------------------+

Implication: Priority changes are not real-time in Google Ads. The system is designed for strategic decisions (seasonal shifts, new arrivals, rule changes) where a 24-hour propagation window is acceptable. This is consistent with how merchants manage their advertising – priorities change weekly or seasonally, not minute-by-minute.

5.7 Batch Sync Process (Detailed)

The hourly batch sync is the primary mechanism for moving data from AdPriority to Google Sheets. This section describes the process in detail.

Hourly Cron Job Fires (minute 0 of each hour)
    |
    v
1. Query pending products
   SELECT p.*, s.google_refresh_token, s.sheet_id
   FROM products p
   JOIN stores s ON p.store_id = s.id
   WHERE p.needs_sync = true
   AND s.is_active = true
   ORDER BY s.id, p.updated_at
    |
    v
2. Group by store_id
   { store_abc: [product1, product2, ...],
     store_def: [product3, product4, ...] }
    |
    v
3. For each store (sequential to respect rate limits):
   |
   +-- a. Authenticate with Google
   |      (use store's refresh token -> access token)
   |
   +-- b. Fetch ALL products for store (not just pending)
   |      (full sheet rewrite for consistency)
   |
   +-- c. Build sheet data
   |      Header: [id, custom_label_0, ..., custom_label_4]
   |      Rows:   one per active variant
   |
   +-- d. Write to Google Sheet
   |      sheets.spreadsheets.values.clear()   // clear old data
   |      sheets.spreadsheets.values.update()  // write new data
   |
   +-- e. Update database
   |      UPDATE products SET needs_sync=false, sync_status='synced',
   |                         last_synced_at=now()
   |      WHERE store_id = ? AND needs_sync = true
   |
   +-- f. Create sync_log entry
          INSERT INTO sync_logs (store_id, sync_type, status,
                                 products_total, products_success, ...)
    |
    v
4. Log summary
   "Sync complete: 3 stores, 15,234 products, 2 errors"

Error handling during sync:

5.8 Reconciliation Pipeline

A daily reconciliation job ensures the AdPriority database stays in sync with the Shopify catalog, catching any missed webhooks or data drift.

Daily Reconciliation (03:00 UTC)
    |
    v
1. For each active store:
   |
   +-- a. Fetch all active products from Shopify
   |      (paginated GraphQL query)
   |
   +-- b. Fetch all products from AdPriority database
   |
   +-- c. Compare:
   |      +--------------------------------------------------+
   |      | In Shopify, NOT in DB  -> New product             |
   |      |   Action: Insert, apply rules, mark needs_sync   |
   |      +--------------------------------------------------+
   |      | In DB, NOT in Shopify  -> Deleted product         |
   |      |   Action: Soft-delete, remove from next Sheet     |
   |      +--------------------------------------------------+
   |      | In both, type changed  -> Product updated         |
   |      |   Action: Recalculate priority, mark needs_sync   |
   |      +--------------------------------------------------+
   |      | In both, no changes    -> No action               |
   |      +--------------------------------------------------+
   |
   +-- d. Generate reconciliation report
   |      { new: 5, deleted: 2, updated: 8, unchanged: 2410 }
   |
   +-- e. Alert if discrepancy > 5% of catalog
          (unusual, may indicate missed webhooks)
    |
    v
2. Log reconciliation results in sync_logs

5.9 Season Transition Flow

When the calendar date crosses a season boundary, the system automatically recalculates priorities for all affected products.

Season Transition Check (daily at 00:00 UTC)
    |
    v
1. Determine current date
    |
    v
2. For each active store:
   |
   +-- a. Load store's season definitions
   |      (seasons table: name, start_month, start_day, end_month, end_day)
   |
   +-- b. Determine current season from today's date
   |
   +-- c. Compare with last known season
   |      (stored in store settings or derived from last transition log)
   |
   +-- d. If season changed:
          |
          +-- i.   Load season_rules for new season
          |        (category x priority mappings)
          |
          +-- ii.  For each product (not priority_locked):
          |        - Find matching season_rule by product_type
          |        - Update priority and priority_source='seasonal'
          |        - Mark needs_sync = true
          |
          +-- iii. Create audit_log entries for all changes
          |
          +-- iv.  Create sync_log entry:
          |        "Season transition: Winter -> Spring, 1,847 products updated"
          |
          +-- v.   Trigger immediate Sheet sync (don't wait for hourly)
          |
          +-- vi.  Send notification to merchant:
                   "Season changed to Spring. 1,847 products updated."

Example transition (Nexus, Winter to Spring on March 1):

Product Type     | Winter Priority | Spring Priority | Products Affected
-----------------+-----------------+-----------------+------------------
Jackets          |       5         |       3         |      ~120
Hoodies          |       5         |       3         |      ~85
Sweaters         |       5         |       2         |      ~40
Shorts           |       0         |       2         |      ~150
Tank Tops        |       0         |       2         |      ~60
T-Shirts         |       2         |       3         |      ~350
Jeans            |       4         |       4         |      ~200 (no change)

5.10 Data Flow Diagram: Label Values

This section documents exactly what values flow into each custom label slot.

+------------------+--------------------+------------------------------------+
| Label            | Source Function     | Possible Values                   |
+------------------+--------------------+------------------------------------+
| custom_label_0   | Priority engine     | priority-0                        |
| (Priority Score) |                     | priority-1                        |
|                  |                     | priority-2                        |
|                  |                     | priority-3                        |
|                  |                     | priority-4                        |
|                  |                     | priority-5                        |
+------------------+--------------------+------------------------------------+
| custom_label_1   | Season calendar     | winter                            |
| (Season)         |                     | spring                            |
|                  |                     | summer                            |
|                  |                     | fall                              |
+------------------+--------------------+------------------------------------+
| custom_label_2   | Category mapping    | t-shirts                          |
| (Category Group) | from product_type   | jeans-pants                       |
|                  |                     | shorts                            |
|                  |                     | outerwear-heavy                   |
|                  |                     | outerwear-light                   |
|                  |                     | hoodies-sweatshirts               |
|                  |                     | headwear-caps                     |
|                  |                     | headwear-cold-weather             |
|                  |                     | accessories                       |
|                  |                     | footwear                          |
|                  |                     | (store-configurable)              |
+------------------+--------------------+------------------------------------+
| custom_label_3   | Tags + age logic    | new-arrival                       |
| (Product Status) |                     | in-stock                          |
|                  |                     | low-inventory                     |
|                  |                     | clearance                         |
|                  |                     | dead-stock                        |
+------------------+--------------------+------------------------------------+
| custom_label_4   | Vendor + tags       | name-brand                        |
| (Brand Tier)     |                     | store-brand                       |
|                  |                     | off-brand                         |
+------------------+--------------------+------------------------------------+

GMC constraint: Each label supports a maximum of 1,000 unique values. All label schemas above are well within this limit (6 values for label_0, 4 for label_1, ~10-20 for label_2, 5 for label_3, 3 for label_4).

5.11 Chapter Summary

The pipeline is designed around the principle that priority changes are strategic, not tactical. A 24-hour propagation window is acceptable because merchants adjust priorities on a weekly or seasonal basis, not in response to minute-by-minute market conditions. This constraint allows the MVP to use the simple, validated Google Sheets pipeline rather than the more complex Content API integration.

Chapter 8: Multi-Tenant Design

AdPriority is a Shopify app. Every Shopify app is inherently multi-tenant: each merchant who installs the app operates within their own isolated data context. This chapter defines how AdPriority implements tenant isolation, provisioning, lifecycle management, and tier-based feature gating – all within a single shared PostgreSQL database.

6.1 Isolation Model

6.1.1 Strategy: Shared Database, Tenant-Scoped Tables

AdPriority uses a single adpriority_db database on the shared postgres16 container. Every table that stores tenant data includes a store_id column referencing the stores table. There are no per-tenant databases or schemas.

+-----------------------------------------------------------------------+
|                        adpriority_db                                  |
|                                                                       |
|  stores (tenant registry)                                             |
|  +----+----------------------------+----------+-----+                 |
|  | id | shopify_shop               | plan_tier| ... |                 |
|  +----+----------------------------+----------+-----+                 |
|  | A  | nexus-clothes.myshopify.com| growth   | ... |                 |
|  | B  | acme-store.myshopify.com   | starter  | ... |                 |
|  | C  | brand-co.myshopify.com     | pro      | ... |                 |
|  +----+----------------------------+----------+-----+                 |
|                                                                       |
|  products (all tenants, scoped by store_id)                           |
|  +----+----------+----------------------+----------+--------+         |
|  | id | store_id | shopify_product_id   | priority | ...    |         |
|  +----+----------+----------------------+----------+--------+         |
|  | 1  | A        | 8779355160808        | 4        | ...    |         |
|  | 2  | A        | 9128994570472        | 5        | ...    |         |
|  | 3  | B        | 7712345678901        | 3        | ...    |         |
|  | 4  | C        | 8834567890123        | 2        | ...    |         |
|  +----+----------+----------------------+----------+--------+         |
|                                                                       |
|  rules, seasons, sync_logs, audit_logs, subscriptions ...             |
|  (all follow same store_id scoping pattern)                           |
+-----------------------------------------------------------------------+

Why shared database, not per-tenant databases?

For a single-developer project targeting up to 1,000 tenants in Year 1, the shared database approach provides the best trade-off between simplicity and isolation. The store_id column is indexed on every table, and Prisma middleware enforces automatic scoping.

6.1.2 Tables with Tenant Scope

Every table that stores tenant-specific data includes a store_id foreign key. The only exception is the stores table itself, which serves as the tenant registry.

+---------------------+----------+------------------------------------------+
| Table               | store_id | Description                              |
+---------------------+----------+------------------------------------------+
| stores              | (is PK)  | Tenant registry (one row per shop)       |
| products            | FK       | Product priority scores and GMC mapping  |
| rules               | FK       | Priority rule definitions                |
| rule_conditions     | via rule | Conditions (joined through rules.id)     |
| seasons             | FK       | Season date ranges                       |
| season_rules        | via season| Category x season mappings               |
| sync_logs           | FK       | Sync audit trail                         |
| subscriptions       | FK (1:1) | Billing records                          |
| audit_logs          | FK       | Change tracking                          |
+---------------------+----------+------------------------------------------+

6.1.3 Query Scoping with Prisma Middleware

All database queries are automatically scoped to the authenticated tenant using Prisma client extensions. This prevents accidental cross-tenant data access.

// database/client.ts

import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

/**
 * Creates a tenant-scoped Prisma client.
 * All queries through this client are automatically filtered by store_id.
 */
export function getTenantClient(storeId: string) {
  return prisma.$extends({
    query: {
      $allModels: {
        async findMany({ args, query }) {
          args.where = { ...args.where, storeId };
          return query(args);
        },
        async findFirst({ args, query }) {
          args.where = { ...args.where, storeId };
          return query(args);
        },
        async findUnique({ args, query }) {
          // findUnique uses unique fields; add storeId check post-query
          const result = await query(args);
          if (result && (result as any).storeId !== storeId) {
            return null; // Tenant mismatch
          }
          return result;
        },
        async create({ args, query }) {
          args.data = { ...args.data, storeId };
          return query(args);
        },
        async update({ args, query }) {
          args.where = { ...args.where, storeId } as any;
          return query(args);
        },
        async delete({ args, query }) {
          args.where = { ...args.where, storeId } as any;
          return query(args);
        },
        async updateMany({ args, query }) {
          args.where = { ...args.where, storeId };
          return query(args);
        },
        async deleteMany({ args, query }) {
          args.where = { ...args.where, storeId };
          return query(args);
        },
      },
    },
  });
}

Usage in route handlers:

// api/routes/products.ts

router.get('/products', async (req, res) => {
  const storeId = req.session.storeId; // From Shopify session token
  const db = getTenantClient(storeId);

  // This query is automatically scoped to the tenant.
  // No need to manually add WHERE store_id = ?
  const products = await db.product.findMany({
    where: { syncStatus: 'pending' },
    orderBy: { priority: 'desc' },
    take: 50,
  });

  res.json({ products });
});

6.2 Shopify as Natural Multi-Tenancy

The Shopify app model provides built-in multi-tenancy primitives that AdPriority leverages.

Shopify App Store
    |
    | Merchant clicks "Add app"
    v
+-------------------+
| Shopify OAuth     |
| Install Flow      |
|                   |
| 1. Consent screen |
| 2. Permissions    |
| 3. Callback       |
+--------+----------+
         |
         | shop = acme-store.myshopify.com
         | access_token = shpat_xxxxx
         v
+-------------------+
| AdPriority        |
| /auth/callback    |
|                   |
| UPSERT stores     |
| SET shop, token   |
+-------------------+

How Shopify enforces tenant boundaries:

AdPriority maps the Shopify shop domain (e.g., nexus-clothes.myshopify.com) to a row in the stores table. The stores.id UUID then serves as the store_id foreign key across all other tables.

6.3 Tenant Provisioning

6.3.1 Install Flow

When a merchant installs AdPriority from the Shopify App Store, the following provisioning sequence executes automatically.

Step  Action                                   Table/System
----  ---------------------------------------- -------------------
  1   Merchant clicks "Add app" in Shopify     Shopify App Store
      |
  2   Shopify redirects to /auth/shopify       AdPriority backend
      with shop domain + auth code
      |
  3   Exchange auth code for access token      Shopify OAuth API
      |
  4   UPSERT store record:                     stores table
      - shopify_shop = 'acme.myshopify.com'
      - shopify_access_token = encrypted(token)
      - plan_tier = 'starter' (default)
      - default_priority = 3
      - new_arrival_priority = 5
      - new_arrival_days = 14
      - is_active = true
      - installed_at = now()
      |
  5   Register Shopify webhooks:               Shopify Webhooks API
      - products/create
      - products/update
      - products/delete
      - app/uninstalled
      |
  6   Create default seasons:                  seasons table
      - Winter (Dec 1 - Feb 28)
      - Spring (Mar 1 - May 31)
      - Summer (Jun 1 - Aug 31)
      - Fall (Sep 1 - Nov 30)
      |
  7   Queue product import job:                Inline worker
      - Fetch all products from Shopify
      - Apply default priority (3)
      - Store in products table
      |
  8   Redirect to app dashboard:               Frontend (React)
      - Show onboarding wizard
      - Step 1: Connect Google account
      - Step 2: Configure category rules
      - Step 3: Review priorities
      - Step 4: Connect Google Sheet to GMC

6.3.2 Provisioning Timing

The merchant sees the dashboard within 6 seconds of completing OAuth. Product import runs in the background, with a progress indicator on the dashboard.

6.4 Google Integration Per Tenant

Each tenant connects their own Google account. AdPriority never shares Google credentials or Sheet access between tenants.

+------------------+     +------------------+     +------------------+
|  Tenant A        |     |  Tenant B        |     |  Tenant C        |
|  (Nexus)         |     |  (Acme)          |     |  (BrandCo)       |
+------------------+     +------------------+     +------------------+
| Google Account:  |     | Google Account:  |     | Google Account:  |
| will@nexus.com   |     | ads@acme.com     |     | team@brandco.com |
|                  |     |                  |     |                  |
| GMC Merchant ID: |     | GMC Merchant ID: |     | GMC Merchant ID: |
| 123456789        |     | 987654321        |     | 456789123        |
|                  |     |                  |     |                  |
| Google Sheet:    |     | Google Sheet:    |     | Google Sheet:    |
| (own sheet)      |     | (own sheet)      |     | (own sheet)      |
|                  |     |                  |     |                  |
| Refresh Token:   |     | Refresh Token:   |     | Refresh Token:   |
| encrypted(xxx)   |     | encrypted(yyy)   |     | encrypted(zzz)   |
+------------------+     +------------------+     +------------------+

Per-tenant Google configuration (stored in stores table):