Buddy Architecture

Buddy Architecture — Cloudflare Production System

Buddy is the production deployment of the Google Ads API Agent, running on Cloudflare's edge infrastructure at googleadsagent.ai.

Stack Overview

Layer	Technology	Purpose
Frontend	Static HTML/JS on Cloudflare Pages	Tools UI, SSO, BYOK key management
API Gateway	Cloudflare Pages Functions	Rate limiting, CORS, request routing
AI Backend	brain.js (Pages Function)	Tool dispatch, ReAct loop, multi-provider AI
Google Ads	gads.js (Pages Function)	GAQL queries, mutations, OAuth
Agent Runtime	Cloudflare Workers + Durable Objects	Stateful agent, WebSocket, billing
Memory	Cloudflare Vectorize	Semantic search over conversation history
Storage	Cloudflare KV + D1 + R2	Sessions, billing, file exports
Auth	Google OAuth 2.0 + AES-256-GCM	SSO, encrypted token storage

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                        User Browser                          │
│  ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────────┐│
│  │ Buddy    │ │Keyword  │ │Ads       │ │ Other Tools      ││
│  │ Auditor  │ │Analyzer │ │Builder   │ │ (Social, Audit,  ││
│  │          │ │         │ │          │ │  Analytics, etc.) ││
│  └────┬─────┘ └────┬────┘ └────┬─────┘ └────┬─────────────┘│
└───────┼────────────┼──────────┼──────────────┼──────────────┘
        │            │          │              │
        ▼            ▼          ▼              ▼
┌─────────────────────────────────────────────────────────────┐
│              Cloudflare Pages Functions                       │
│  ┌────────────┐ ┌──────┐ ┌──────┐ ┌────────┐ ┌───────────┐│
│  │_middleware  │ │auth  │ │brain │ │gads    │ │Other APIs ││
│  │(rate limit)│ │(OAuth)│ │(AI)  │ │(GAdAPI)│ │(crux,etc) ││
│  └────────────┘ └──────┘ └──┬───┘ └──┬─────┘ └───────────┘│
└──────────────────────────────┼────────┼─────────────────────┘
                               │        │
                    ┌──────────┼────────┼──────────┐
                    ▼          ▼        ▼          ▼
           ┌──────────┐  ┌────────┐  ┌────────┐  ┌──────────┐
           │ Claude   │  │ GPT    │  │ Gemini │  │ Google   │
           │ Opus/    │  │ 5.2/   │  │ 2.5/3  │  │ Ads API  │
           │ Sonnet   │  │ 5.2Pro │  │ Flash  │  │ v22      │
           └──────────┘  └────────┘  └────────┘  └──────────┘

Buddy Agent Worker

The buddy-agent Worker runs as a Durable Object with the Cloudflare Agents SDK:

┌─────────────────────────────────────────────────┐
│          Buddy Agent (Durable Object)            │
│                                                   │
│  ┌─────────────┐  ┌──────────────────────────┐  │
│  │ WebSocket   │  │ State (SQLite)            │  │
│  │ Connection  │  │ - Conversation history    │  │
│  │             │  │ - Account context         │  │
│  └──────┬──────┘  │ - Write rollback log      │  │
│         │         │ - Task lists              │  │
│         ▼         └──────────────────────────┘  │
│  ┌─────────────┐                                 │
│  │ Agent SDK   │  ┌──────────────────────────┐  │
│  │ - onStart   │  │ Tools                     │  │
│  │ - onConnect │  │ - 21 tools same as brain  │  │
│  │ - onTask    │  │ - search_memory (extra)   │  │
│  └─────────────┘  └──────────────────────────┘  │
│                                                   │
│  ┌─────────────────────────────────────────────┐ │
│  │ Scheduled Tasks (onTask)                     │ │
│  │ - dailyHealthCheck → account monitoring      │ │
│  │ - weeklyReport → performance digest          │ │
│  │ - outcomeCheck → verify past recommendations │ │
│  └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────┘

Key Features

Feature	Implementation
Per-user state	Durable Object SQLite — survives disconnects
Semantic memory	Vectorize embeddings for past conversations
Write safety	Pre-write snapshots, rollback log, CEP protocol
Real-time	WebSocket via Agents SDK onConnect
Monitoring	onTask scheduled checks (daily, weekly)
Multi-provider	Claude, GPT, Gemini with automatic fallback
Billing	Credit system with D1 storage

AI Model Support

Provider	Models	Tool Calling
Anthropic	Claude Sonnet 4.6, Claude Opus 4.6	Yes (ReAct)
OpenAI	GPT-5.2, GPT-5.2 Pro	Yes (ReAct)
Google	Gemini 2.5 Flash, Gemini 2.5 Pro, Gemini 3 Flash Preview	Streaming only

Security Architecture

Layer	Protection
Auth	Google OAuth 2.0 with AES-256-GCM encrypted token storage
CORS	Origin allowlist (no wildcards)
Rate limiting	Per-endpoint limits in _middleware.js
CSP	Strict Content-Security-Policy headers
HSTS	Strict-Transport-Security enforced
Write safety	CEP protocol — no mutations without explicit user confirmation
Session	Server-generated session IDs (no fixation)
Redirects	Allowlist-validated return URLs (no open redirects)
SSRF	URL validation blocks private/internal addresses
XSS	HTML/SVG escaping on dynamic content

Tools Suite

Buddy powers 6 web tools, all accessible at googleadsagent.ai/tools:

Tool	Purpose
Buddy (Auditor)	Full AI conversation agent for Google Ads management
Audit Engine	250-point automated Google Ads audit
Google Ads Builder	AI-assisted campaign creation
Keyword Analyzer	Keyword research and analysis
Social Media Builder	Social media ad copy generation
Analytics Auditor	Marketing analytics tag/pixel auditing with CrUX data
Business Discovery	Business research and market analysis