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