Architecture & API Integration · v1.0
System components & data flow
Enough system detail for a real engineering tradeoff conversation — not a substitute for engineering's own design doc.
Owner Product, with Engineering · the Action Executor is the only component with write access to live campaigns.
System flow
Ad Platforms — Meta & Google APIs
Ingestion Service (hourly, rate-limit aware)
Performance Data Store (time-series)
Drift Detection & Recommendation
Creative Generation (LLM)
Confidence Scoring & Lane Assignment
Review Queue (approve / edit / reject)
Action Executor — only writer to live campaigns
Audit Log & Rollback (5-min window)
API integrations
Meta Marketing APIOAuth 2.0. Insights provisional ~72h — tagged final vs. provisional in reasoning.
Google Ads APIOAuth + developer token. Stricter change-rate limits — may need a tighter blast radius.
LLM provider APIStructured JSON output. Every call logs tokens, tier, prompt version.
Open questions for engineering
- Should Google Ads get a stricter default blast-radius cap than Meta, given tighter mutate limits?
- Does the LLM provider's structured-output mode give hard schema guarantees, or do we need our own validation layer?
- What's the right retention window for the Performance Data Store?