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

If You Want To…	Start With…
Understand the product vision	Part I: Foundation
Design the system	Part II: Architecture
Understand external APIs	Part III: Integrations
Build the backend	Part IV: Backend
Create the Shopify UI	Part V: Frontend
Start implementing	Part VI: Implementation
Deploy and operate	Part VII: Operations
Look up reference data	Appendices

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              |
+----------------------------------------------------------------------+

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

Part II: Architecture

System design and key technical decisions

Part III: Integrations

External API specifications and data flows

Part IV: Backend

Server-side implementation details

Part V: Frontend

Shopify embedded app interface

Part VI: Implementation Guide

Step-by-step building instructions

Part VII: Operations

Deployment, monitoring, and compliance

Appendices

Book Statistics

Metric	Value
Total Chapters	26
Parts	7
Appendices	5
Database Tables	8 core
API Endpoint Groups	7
Integration APIs	4 (Shopify, GMC, Google Ads, Sheets)
Priority Levels	6 (scores 0-5)
Pricing Tiers	4 (Starter, Growth, Pro, Enterprise)
Implementation Phases	4 (Phase 0-3)
Target Grade	A (Production-Ready Shopify App)

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

Format	Pages	Notes
Full Book	~250-300	All chapters and appendices
Core (Parts I-IV)	~120	Foundation through Backend
Quick Reference	~30	Appendices only

Blueprint Maintenance

How to Update This Blueprint

Task	Action
Edit content	Update markdown file in `src/`
Add chapter	Create file, update this index, update `SUMMARY.md`
Add appendix	Create file, update this index, update `SUMMARY.md`
Build site	Run `mdbook build` from `mdbook-src/`
Deploy	Run `wrangler pages deploy book`

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

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

Version History

Version	Date	Changes
1.0.0	2026-02-10	Initial AdPriority Blueprint

Contributors

Role	Contributor
Architect	Claude Code Architect Agent
Author	Claude Code Editor Agent
Reviewer	Claude Code Engineer Agent
Research	Claude Code Researcher Agent
Coordinator	Claude Code Orchestrator

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.”