Architecture & API Integration

Status Draft v1.0

Owner Product, in partnership with Engineering

Series

Ad Copilot Portfolio Doc

Written as the artifact a PM brings into an engineering design review — enough system detail for a real tradeoff conversation, not a substitute for engineering’s own design doc. Open questions for engineering are flagged rather than dictated.

1. System overview

┌─────────────────────┐ │ Ad Platforms │ │ (Meta Ads, Google │ │ Ads APIs) │ └──────────┬───────────┘ │ OAuth + REST ▼ ┌─────────────────────┐ │ Ingestion Service │ │ (hourly pull, │ │ rate-limit aware) │ └──────────┬───────────┘ ▼ ┌─────────────────────┐ │ Performance Data │ │ Store (time-series) │ └──────────┬───────────┘ ▼ ┌─────────────────────┐ │ Drift Detection & │ │ Recommendation Svc │ └──────────┬───────────┘ ┌─────────────────┼─────────────────┐ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Creative Generation │ │ Confidence Scoring │ │ Service (LLM calls) │◄──────────────┤ & Lane Assignment │ └──────────┬───────────┘ └──────────┬───────────┘ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ Brand-Safety Filter │──────────────►│ Review Queue │ └──────────────────────┘ └──────────┬───────────┘ ▼ ┌─────────────────────┐ │ Action Executor │ │ (writes to APIs) │ └──────────┬───────────┘ ▼ ┌─────────────────────┐ │ Audit Log & Rollback│ └──────────────────────┘

2. Core components

Component	Responsibility
Ingestion Service	Hourly pulls from Meta/Google; OAuth refresh, rate-limit backoff, pagination
Performance Data Store	Time-series spend/conversions/ROAS/CPA/CPC/CTR for drift windows
Drift Detection & Recommendation	Compares live metrics to targets; emits recommendation objects
Creative Generation Service	Tiered LLM calls, caching, per-account cap enforcement
Confidence Scoring & Lane Assignment	Composite confidence → Auto-apply / Suggest / Escalate
Brand-Safety Filter	Deterministic check before anything enters the review queue
Review Queue (UI + API)	Approve/edit/reject surface; system-of-record for human feedback
Action Executor	Only component with write access to live campaigns
Audit Log & Rollback	Immutable log of every AI action; 5-minute Auto-apply rollback (NFR-2)

3. Key API integrations

3.1 Meta Marketing API

Auth: OAuth 2.0; long-lived system-user tokens where available; refresh in Ingestion Service.
Reads: Campaign/Ad Set/Ad structure; Insights for spend, conversions, CTR, CPC, purchase value.
Writes: Budget/bid via Ad Set update; new copy via Ad Creative — Action Executor only.
Constraint: Insights can be provisional ~72h — tagged final vs provisional and propagated into recommendation reasoning.
Rate limits: exponential backoff + request queue; stale gracefully into the data-freshness UI indicator.

3.2 Google Ads API

Auth: OAuth 2.0 + developer token (approval lead time is a launch-timeline dependency).
Reads: GAQL against campaign/ad group/ad performance tables.
Writes: Budget/bid mutates; Google enforces stricter change-rate limits than Meta — may warrant tighter default blast radius (open question §6).

3.3 LLM Provider API

Structured-output (JSON schema) for generation and reasoning.
Tiered routing lives in Creative Generation Service.
Every call logged with tokens, model tier, prompt version (NFR-4).
Circuit breaker on error/latency spikes → “generation delayed.”

4. Data model notes

Account — platform connections, trust tier, thresholds, plan tier/cost cap.
Campaign/AdSet — target metric type/value, lane-eligibility state.
Recommendation — signal, action, confidence breakdown, lane, status, model/prompt version.
GeneratedCreative — variant text, confidence, brand-safety result, cache key.
AuditEvent — append-only state changes, timestamped, acting entity (system vs user).

5. Security & compliance

OAuth tokens encrypted at rest; minimum required scopes.
Action Executor isolation — generation/scoring bugs cannot mutate live campaigns without lane assignment (+ human approval where required).
Audit log append-only — record of truth for trust and disputes.

6. Open questions for engineering

Should Google Ads get a stricter default blast-radius cap than Meta given tighter mutate limits?
What’s the right retention window for the Performance Data Store?
Does the LLM provider’s structured-output mode give hard schema guarantees, or do we need our own validation/retry layer?
Confirm Google Ads developer token lead time against the Phase 2 schedule in the Release Plan.