# google/pmax_best_practices_dashboard architecture

> Architecture diagram of the GitHub repository google/pmax_best_practices_dashboard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/pmax_best_practices_dashboard
- Repository: https://github.com/google/pmax_best_practices_dashboard

## Overview

##### Project Type & Purpose
- This project is a full-stack reporting/dashboard solution built to monitor and report on performance metrics for pMax campaigns. Its main deliverable is a Looker Studio dashboard that aggregates data from Google Ads (via GAQL queries) and processes information using Google Cloud Platform (GCP) services.
- The solution is designed to provide best-practice insights for campaign and asset performance using SQL queries (both BigQuery and GAQL), shell scripts for deployment/upgrades, and configuration files.

##### Analyzing the File Structure
- The top-level files and directories (such as the SQL queries folders – “bq_queries”, “google_ads_queries”, plus additional queries in the “plugins/retail” directory) indicate that the system extracts and processes data from Google Ads and uses BigQuery for analysis.
- Multiple shell scripts (build-retail.sh, no_gmc_update.sh, setup-wfs.sh, upgrade_pmaximizer.sh, and non_retail_to_retail_upgrade.sh) show the automation and deployment aspects of the solution.
- The presence of package.json and package-lock.json implies some Node.js-based tooling or dependency management that might be involved in orchestrating parts of the project.
- Configuration details (with files like answers.json and various SQL files) suggest that the project is structured to support different deployment scenarios (e.g., standard and retail versions) along with regular updates.

##### Reading the README for Architectural Guidance
- What happens during installation (automated deployment)
- Automatic deployment of components like Storage, Scheduler, Workflows, Run, and BigQuery.
- The README explains the daily pipeline, GCP authentication, and troubleshooting steps which further confirm the cloud-based design.

a. Main Components to Include:
- Frontend/Presentation Layer: Represented by the Looker Studio dashboard that displays the reporting results.
- Data Extraction Layer: Google Ads queries (GAQL queries) that retrieve data from Google Ads.
- Data Processing/ETL Layer: SQL queries in “bq_queries” and additional scripts; this is where data is processed, transformed, and stored.
- Google Cloud Infrastructure:
- Google Cloud Storage (for file storage)
- Cloud Scheduler & Workflows (for scheduling, triggering ETL pipelines)
- Cloud Run (to run containerized processing tasks)
- BigQuery (for data warehousing and analytics)
- Auxiliary Components: The shell scripts and plugins that facilitate deployments and updates, which could be annotated as supporting utilities.

b. Relationships & Interactions:
- That shell scripts (like upgrade and deployment scripts) control or trigger the automation of processes within the GCP environment.
- Separation between different deployment variants (e.g., standard vs. retail) by including the “plugins/retail” module and how these might integrate with the central pipeline.

c. Architectural Patterns/Design Principles:
- Microservices/cloud functions design: each GCP component (Storage, Scheduler, Workflows, Run, BigQuery) is modular and integrated to build an automated, scalable pipeline.
- Automation and the “push button” nature of the deployment, as the project uses several shell scripts to manage updates and deployments.
- Separation of concerns: queries and workloads for data extraction (google_ads_queries, bq_queries) are separated from the orchestration and deployment mechanisms.

d. Relevant Technologies & Tools:
- Looker Studio for visualization.
- Google Ads API with GAQL queries.
- Google Cloud services (Storage, Scheduler, Workflows, Run, BigQuery).
- SQL for data processing.
- Shell scripting for automation.
- NodeJS (implied by package.json) for dependency management or possible backend utilities.

##### Final Advice
- Double-check that each deployment script or module (as seen in the file tree) is represented where relevant within the cloud orchestration flow (especially scripts like upgrade_pmaximizer.sh and non_retail_to_retail_upgrade.sh which adjust the system’s behavior).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Extraction Layer
    subgraph "Data Extraction Layer"
        GAQ["Google Ads API Queries"]:::extraction
        RGAQ["Retail Google Ads API Queries"]:::extraction
    end

    %% ETL/Processing Layer
    subgraph "ETL/Processing Layer"
        ETL["ETL/Processing (SQL Queries)"]:::processing
        RSQL["Retail SQL Processing"]:::processing
    end

    %% GCP Cloud Services
    subgraph "GCP Cloud Services"
        CS["Cloud Scheduler"]:::cloud
        CW["Cloud Workflows"]:::cloud
        CR["Cloud Run"]:::cloud
        GS["GCP Storage"]:::cloud
        BQ["BigQuery"]:::database
    end

    %% Presentation Layer
    DS["Looker Studio Dashboard"]:::presentation

    %% Deployment & Automation Scripts
    subgraph "Deployment & Automation Scripts"
        S1["build-retail.sh"]:::automation
        S2["no_gmc_update.sh"]:::automation
        S3["setup-wfs.sh"]:::automation
        S4["upgrade_pmaximizer.sh"]:::automation
        S5["non_retail_to_retail_upgrade.sh"]:::automation
    end

    %% Configuration & Dependencies
    subgraph "Configuration & Dependencies"
        CFG["Configuration (answers.json)"]:::support
        DEP1["package.json"]:::support
        DEP2["package-lock.json"]:::support
    end

    %% Data Flow Connections
    GAQ -->|"feeds"| ETL
    RGAQ -->|"feeds"| RSQL
    ETL -->|"processes to"| BQ
    RSQL -->|"processes to"| BQ
    BQ -->|"visualized in"| DS

    %% Scheduling Trigger from Cloud Scheduler to ETL Layer
    CS -->|"trigger"| ETL
    CS -->|"trigger"| RSQL

    %% Deployment Scripts triggering Cloud Services
    S1 -->|"deploy"| CS
    S2 -->|"deploy"| CW
    S3 -->|"deploy"| CR
    S4 -->|"deploy"| CS
    S5 -->|"deploy"| CW

    %% Support links (dotted lines to indicate configuration support)
    CFG --- S1
    DEP1 --- S1
    DEP2 --- S1

    %% Styling Classes
    classDef extraction fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef processing fill:#F7D6AE,stroke:#333,stroke-width:2px;
    classDef cloud fill:#DFF7AE,stroke:#333,stroke-width:2px;
    classDef database fill:#F7AEAE,stroke:#333,stroke-width:2px;
    classDef presentation fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef automation fill:#AEF7D6,stroke:#333,stroke-width:2px;
    classDef support fill:#E0E0E0,stroke:#333,stroke-width:2px;

click GAQ "https://github.com/google/pmax_best_practices_dashboard/tree/main/google_ads_queries/"
click RGAQ "https://github.com/google/pmax_best_practices_dashboard/tree/main/plugins/retail/google_ads_queries/"
click ETL "https://github.com/google/pmax_best_practices_dashboard/tree/main/bq_queries/"
click RSQL "https://github.com/google/pmax_best_practices_dashboard/tree/main/plugins/retail/bq_queries/"
click S1 "https://github.com/google/pmax_best_practices_dashboard/blob/main/build-retail.sh"
click S2 "https://github.com/google/pmax_best_practices_dashboard/blob/main/no_gmc_update.sh"
click S3 "https://github.com/google/pmax_best_practices_dashboard/blob/main/setup-wfs.sh"
click S4 "https://github.com/google/pmax_best_practices_dashboard/blob/main/upgrade_pmaximizer.sh"
click S5 "https://github.com/google/pmax_best_practices_dashboard/blob/main/non_retail_to_retail_upgrade.sh"
click CFG "https://github.com/google/pmax_best_practices_dashboard/blob/main/answers.json"
click DEP1 "https://github.com/google/pmax_best_practices_dashboard/blob/main/package.json"
click DEP2 "https://github.com/google/pmax_best_practices_dashboard/blob/main/package-lock.json"
```
