Documentation
Technical reference for operators, self-hosters, and security reviewers evaluating Adsynth and its Google Ads API usage.
Product architecture
Adsynth is a Next.js web application (chat UI, marketing site, authentication) talking to a FastAPI backend. The backend orchestrates Google Ads API calls, Meta and Bing Ads where configured, GA4 and Search Console reads, SEO intelligence (GSC×GA4, SERP APIs), ML helpers (forecasts, anomaly detection, scoring), Outcome OS playbooks, and persistence in PostgreSQL. Mutations to Google Ads are queued for human approval in the product surface unless explicitly configured otherwise for non-production environments.
Shipped capabilities (through May 2026)
- Brand training & context — upload library, email inbox → knowledge, Brand Brief synthesis,
search_brand_knowledge, AI memory across sessions. - Chat skills — workspace and org-default
/slashcommands with governed procedures stored in Postgres. - Outcome OS playbooks — scheduled cross-channel reviews, approval inbox, impact ledger (
docs/PLAYBOOKS.md). - SEO suite — GSC×GA4 decay, SERP intelligence, technical audits, article briefs, branded HTML/QBR exports via SEO specialist agent.
- Creative intelligence — ranked vision scoring, YouTube channel import to Creative hub, Veo video, inline creative cards in reports.
- Integrations — Google Ads, Meta, Bing, Apple Search Ads, GA4, GSC, Shopify, YouTube, Slack.
- Governance — RBAC, tenant HMAC isolation, POPIA/GDPR privacy suite, audit export, encrypted OAuth tokens.
Repository & source layout
Source code and markdown docs live in the open repository: https://github.com/PreboDigital/googleadsagent. High-level layout:
chat-app/— Next.js 16 app (app router), Better Auth, tenant HMAC to backend, marketing pages under/site.backend/— FastAPI service, tool registry exposed to agents, GDPR/DSAR endpoints, Paddle/Stripe billing hooks where enabled.mcp-server/— Extended Google Ads MCP server for editor and automation hosts (Cursor, etc.).docs/— Architecture, endpoints, deployment, GA4/GSC credentials, roadmap, Google Ads access application materials.
Key documents (in-repo)
- README.md — capabilities overview and quick start.
- docs/ARCHITECTURE.md — system design and data flow.
- docs/ENDPOINTS.md — agent tools / Google Ads operations catalogue.
- DEPLOYMENT.md — environment variables and hosting notes.
- docs/GA4_GSC_CREDENTIALS.md — Analytics and Search Console OAuth/ADC.
- docs/GOOGLE_ADS_RMF_COMPLIANCE.md — Google Ads API RMF alignment notes.
Google OAuth & Ads API
Users connect Google with the standard OAuth consent screen. Tokens are stored server-side and encrypted at rest. API access is limited to customers and scopes the user authorizes. See README prerequisites for developer token and Cloud project setup when self-hosting.
Privacy & data subject rights
Public policies: Privacy Policy, Terms of Use, Cookie Policy. Signed-in users can access export and erasure from Privacy & Data in the app.
Help
Commercial or security questionnaires: Contact us.