GA
Application Overview

What is Google Ads Agent?

Google Ads Agent is an internal AI-powered platform for automating Google Ads campaign management across all Color Ecommerce accounts. It combines Google Ads API integration, Claude AI analysis, and a human-in-the-loop approval workflow to continuously monitor, analyze, and optimize campaigns.

Purpose

  • Reduce manual optimization time by 60%
  • Improve ROAS by 15% through continuous AI analysis
  • Detect performance anomalies within 1 hour
  • Analyze 100% of managed accounts daily

Core Capabilities

  • Continuous monitoring of all managed accounts
  • AI-driven analysis identifying opportunities and risks
  • Automated recommendations with reasoning and projected impact
  • Full audit trail of every change proposed and executed

How It Works

1

Sync

Fetches account structure, metrics, and search terms via Google Ads API

2

Analyze

Claude AI identifies anomalies, trends, and optimization opportunities

3

Propose

Generates change proposals with impact projections and confidence scores

4

Execute

Approved changes are applied via API with full audit logging

API Features Used

Google Ads API Integration

Detailed breakdown of every Google Ads API service, method, and query pattern used by the application. All mutations are gated behind the human-in-the-loop approval workflow — no changes are made without explicit approval.

Account Management

ServiceMethodPurposeFrequency
CustomerServiceListAccessibleCustomersDiscover MCC hierarchy and client accountsOn OAuth connect
GoogleAdsServiceSearchStreamFetch account-level settings and statusDaily sync

Campaign Data

ServiceMethodPurposeFrequency
GoogleAdsServiceSearchStreamQuery campaigns, ad groups, keywords, ads structureDaily (6 AM)
GoogleAdsServiceSearchStreamFetch daily performance metrics (clicks, impressions, cost, conversions)Hourly / Daily
GoogleAdsServiceSearchStreamSearch term report data for keyword miningDaily (8 AM)

Optimization Mutations

ServiceMethodPurposeFrequency
GoogleAdsServiceMutateCampaign budget adjustmentsOn approval
GoogleAdsServiceMutateKeyword bid adjustments and match type changesOn approval
GoogleAdsServiceMutateAdd/remove negative keywordsOn approval
GoogleAdsServiceMutateAd copy create/update (RSA assets)On approval
GoogleAdsServiceMutateCampaign/ad group status changes (pause/enable)On approval

Recommendations

ServiceMethodPurposeFrequency
RecommendationServiceSearchStreamFetch Google's optimization recommendationsDaily (7 AM)
RecommendationServiceApplyRecommendationApply approved Google recommendationsOn approval
RecommendationServiceDismissRecommendationDismiss irrelevant recommendationsOn approval

Change History

ServiceMethodPurposeFrequency
GoogleAdsServiceSearchStreamAudit external changes made outside our platformEvery 12 hours

GAQL Queries

All data is queried using Google Ads Query Language (GAQL). Below are the primary query patterns:

Campaign structure sync

SELECT campaign.id, campaign.name, campaign.status, campaign.budget FROM campaign

Ad group structure sync

SELECT ad_group.id, ad_group.name, ad_group.status FROM ad_group

Keyword data

SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type FROM ad_group_criterion WHERE ...

Performance metrics

SELECT metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date DURING ...

Search term mining

SELECT search_term_view.search_term, metrics.impressions, metrics.clicks, metrics.conversions FROM search_term_view WHERE ...

Recommendations

SELECT recommendation.type, recommendation.impact, recommendation.campaign_budget_recommendation FROM recommendation WHERE ...

External change detection

SELECT change_event.change_date_time, change_event.user_email, change_event.changed_resource FROM change_event WHERE ...
Privacy & Compliance

Data Handling & GDPR

We take data protection seriously. All personal data is encrypted, retained only as long as necessary, and processed in compliance with GDPR and Google's API Terms of Service.

Data Inventory

CategoryData ElementsRetentionEncryption
User AuthenticationOAuth tokens, JWT sessions, IP addressesUntil revoked + 30 daysAES-256-GCM (tokens), TLS (transit)
User IdentityEmail, display nameAccount lifetime + 30 daysDatabase encryption at rest
Account DataCustomer IDs, MCC hierarchy, account namesActive lifetime + 90 daysDatabase encryption at rest
Advertising DataCampaign names, keywords, metrics, search termsRolling 24 monthsDatabase encryption at rest
Change HistoryProposals, approvals, execution results36 monthsDatabase encryption at rest
Operational LogsRequest IDs, IPs, user agents90 daysTLS in transit

Security Measures

Encryption

  • TLS 1.2+ for all data in transit
  • AES-256-GCM for OAuth refresh tokens
  • Database-level encryption at rest
  • Redis TLS + encrypted volumes

Access Control

  • Google OAuth 2.0 authentication
  • JWT-based sessions (1h expiry)
  • Rate limiting (100 req/min per IP)
  • CORS restricted to allowed origins

Data Minimization

  • Only necessary Google Ads data fetched
  • User profile limited to email & name
  • Logs exclude request/response bodies
  • Metrics aggregated where possible

Data Subject Rights (GDPR)

Right of Access (Art. 15)

Export all personal data in JSON format within 30 days of request.

Right to Erasure (Art. 17)

Delete all records and anonymize associated logs upon verified request.

Right to Portability (Art. 20)

Provide data in a structured, machine-readable format for transfer.

Right to Rectification (Art. 16)

Correct any inaccurate personal data upon notification.

Right to Restriction (Art. 18)

Pause processing of personal data while disputes are resolved.

Right to Object (Art. 21)

Opt out of non-essential data processing and analytics logging.

Cookie & Tracking Policy

This application uses only strictly necessary cookies: a JWT session token (HTTP-only, SameSite=Strict, 24h), a CSRF state token (10-minute expiry), and request ID headers for debugging. We do not use Google Analytics, advertising pixels, social media trackers, or any third-party tracking services.

Architecture

System Architecture

The application is a TypeScript monorepo with four services, a shared core package, and infrastructure backed by PostgreSQL, Redis, and BullMQ.

Google Ads API
Claude AI
Slack

Application Layer

API Server

Fastify + JWT Auth

Worker

BullMQ Jobs

Dashboard

Next.js 15

MCP Server

Claude Integration

Shared Packages

@core

Google Ads client, analysis, services

@shared

Types, constants, GAQL builders

@db / @queue

Drizzle ORM, BullMQ queues

Infrastructure

PostgreSQL

Accounts, metrics, proposals, audit log

Redis

Cache, rate limiting, locks

BullMQ

Job queues, scheduling

OAuth 2.0 Flow

1

Initiate

User clicks "Connect Google Ads" → redirected to Google consent screen

2

Consent

User grants access to manage Google Ads accounts

3

Callback

Authorization code returned to /api/auth/google/callback

4

Exchange

Code exchanged for access + refresh tokens. Refresh token encrypted with AES-256-GCM

5

Session

JWT issued (1h expiry). Refresh token stored encrypted in database

Queue Architecture

QueueConcurrencyPurposeSchedule
sync10Account structure & metrics syncHourly / Daily 6 AM
analysis5AI analysis pipelineDaily 7 AM
optimization3Execute approved changesOn approval
report5Report generationWeekly / Monthly
alert10Alert notificationsOn trigger
change-detection5Detect external changesEvery 12 hours
Responsible Usage

Rate Limiting & Error Handling

The application is designed for responsible API usage with multiple layers of rate limiting, intelligent retry logic, and comprehensive error handling to prevent quota exhaustion.

Token Bucket Rate Limiter

A token bucket algorithm controls request flow to the Google Ads API, preventing burst traffic from exceeding quota limits.

// Rate limiting configuration

Global: 100 requests/minute per IP

Google Ads API: Token bucket per account

Concurrent accounts: Max 5 (configurable)

BullMQ rate: 10 jobs/min per queue

Exponential Backoff Retry

All API calls use exponential backoff with jitter on transient failures, with a maximum of 3 retry attempts before failing gracefully.

// Retry strategy

Attempt 1: Immediate

Attempt 2: ~2s delay (1s * 2^1)

Attempt 3: ~4s delay (1s * 2^2)

Attempt 4: Fail with structured error

Error Handling Strategy

Error TypeResponseRetry?
RATE_LIMIT_EXCEEDED (429)Back off and retry with exponential delayYes (up to 3x)
QUOTA_EXCEEDEDLog warning, skip account, retry in next cycleNext scheduled run
AUTHENTICATION_ERRORAttempt token refresh, notify if refresh failsAfter refresh
PARTIAL_FAILURELog individual operation failures, continue with successesFailed ops only
INTERNAL_ERROR (5xx)Retry with backoff, alert after 3 failuresYes (up to 3x)
INVALID_ARGUMENTLog error details, skip operation, create alertNo (fix required)

BullMQ Queue Safeguards

  • Job deduplication via unique jobId per account/operation
  • Configurable concurrency per queue (3-10 workers)
  • Automatic retry with exponential backoff on failure
  • Dead letter queue for permanently failed jobs
  • Job retention limits (500 completed, 2000 failed)

Monitoring & Observability

  • Prometheus-compatible metrics at /api/metrics
  • Per-client rate limit tracking at /api/admin/rate-limits
  • Structured error tracking with event IDs
  • Transaction-level performance monitoring
  • Health check endpoint at /api/health
Dashboard

Application Screenshots

Interactive mockups of the key dashboard screens showing account management, proposal workflow, and reporting capabilities.

Accounts

Acme Corporation

123-456-7890

$24.5K/moROAS 4.8x

Widget Industries

234-567-8901

$18.2K/moROAS 3.1x

TechStart Inc

345-678-9012

$12.8K/moROAS 5.2x

Global Commerce

456-789-0123

$31.4K/moROAS 2.7x
Approvals

Add negative keyword "free trial" to Campaign Alpha

Negative Keyword

92%
Impact: +$420/mo saved

Increase budget for "Brand Terms" by 15%

Budget

87%
Impact: +12% conversions

Pause underperforming ad group "Generic Terms"

Status Change

78%
Impact: -$180/mo waste
Reports

Total Spend

$86.9K

Conversions

2,847

Avg CPA

$30.52

Avg ROAS

4.1x

Auto-Approval Rules

Negative Keywords

Min confidence: >85% | Zero conversions, max 20/batch

Bid Adjustments

Min confidence: >90% | Max 15% change, 30+ data points

Budget Changes

Min confidence: >95% | Max 10% increase, min 14 days data