📖 Concepts & jargon
A plain-English guide to how the platform fits together. Read this first if "MCP", "tactic", or "playbook" don't yet mean anything specific to you.
TL;DR — what we actually sell
- A small business buys a Plan.
- The plan unlocks a bundle of Products — what the customer sees in My products: "Campaigns", "Reputation", "Website".
- Each product is delivered by one or more Tactics — what we run internally: "Google SEM", "Meta Paid", "Review Response".
- Every tactic is executed by a specialized Agent.
- The agent talks to the ad platform through an MCP server.
- The agent's brain is the Playbook for that tactic × industry.
The layer cake — Plan → Product → Tactic → Agent → MCP → Platform
💼 Plan — what the customer pays for
↓ unlocks
📦 Product — customer-facing capability
- Plain English so the SMB owner gets it
- Campaigns · Social · Reputation · Website · Reports
- One product → many tactics under the hood
↓ delivered by
🎯 Tactic — internal unit of execution (47 of these)
- A specific channel + intent
- Google SEM · Meta Paid · GBP Posts · LSA · Review Response · Email Marketing …
- Has its own KPIs, budget cap, lifecycle (plan → launch → optimize → report → sunset)
- The live instance for one customer is an account_tactic
↓ executed by
🤖 Agent — one Python class per tactic
- Specialized for that tactic
- Reads the 4 sources → plans → calls the MCP → monitors → optimizes → reports
- GoogleSemAgent · MetaPaidAgent · ReviewResponseAgent …
- Every run is logged in agent_runs for replay & revert
↓ talks to platform via
⚙ MCP server — raw I/O to the ad platform (~12 of these)
- A thin wrapper exposing platform actions as callable tools
- google_ads · meta · tiktok · gbp · reviews · seo …
- No business logic — just create campaign, set bid, fetch metrics
- Behavior comes from the matching platform reference
↓ which calls
🔌 Platform — the actual third-party API
- Google Ads · Meta · TikTok · Trade Desk · Yelp · GBP · etc.
- Connected per account in integrations
How an agent decides what to do — the 4 sources
Every campaign the agent plans is a synthesis of 4 inputs. None of them is hardcoded — each is versioned and editable without a code deploy.
👤 Advertiser Profile
30 params · per account · DB-versioned
- Who the business is
- Industry, locations, audience
- Brand voice, budget ceiling, prohibited topics
📝 Campaign Brief
20 params · per request · immutable
- What this specific push is for
- Goal, dates, offer
- Target geo, success metric
📚 Industry Playbook
50 params · per vertical · markdown in git
- Our moat.
- What works for pizzerias vs dentists vs HVAC
- Dayparting, keywords, creative angles, do/don't
📐 Platform Reference
50 params · per platform · markdown in git
- Quirks of each ad platform
- Bid types, rate limits
- Policy gotchas, format specs
Why this isn't hardcoded: ad platforms and vertical best-practices change quarterly. Storing playbooks & platform refs as versioned markdown in git (not in Python code) means ops + creative can ship updates via PR review without an engineering deploy. Every agent run pins the exact version it consumed → fully reproducible, fully revertable.
The three agent tiers
Tier 1 · Orchestrators (7) — route, schedule, arbitrate
- StrategyOrch · OnboardingOrch · LaunchOrch · OptimizationOrch
- ReportingOrch · ComplianceOrch · LeadOrch
- Never touch a platform directly — they decide which tactic agent to call and when
↓ spawn
Tier 2 · Tactic specialists (47) — one per tactic
- Same lifecycle on every class: plan → preflight → launch → monitor → optimize → report → pause/resume → revert → sunset
- Reads its playbook + the platform ref at run time
- This is where the playbook intelligence actually lives
↓ call
Tier 3 · MCP servers (~12) — raw platform I/O
- Thin wrappers. No business logic.
google_ads.create_campaign(...),meta.fetch_insights(...)- Swappable when platform APIs change
"Recommended tactics" — what does that mean?
When a new account is created, StrategyOrchestrator proposes a tactic mix based on:
- The customer's plan (budget + included products)
- Their industry (which playbooks exist for them)
- Their advertiser profile goals + constraints
- Budget allocation across tactics
Example for Joe's Pizza on Growth: Google SEM + Meta Paid + GBP + Review Response + Email. The AM reviews on campaign plan review and approves before anything launches.
Glossary
- Plan — the SKU the customer pays for. Sets budget + included products.
- Product — customer-facing capability ("Campaigns"). Marketing language.
- Tactic — internal unit of execution ("Google SEM"). 47 in the catalog.
- Account tactic — one customer × one tactic. The live, running instance with its own budget and KPIs.
- Playbook — versioned markdown that tells the agent how to run a tactic for a specific industry. Our IP.
- Agent — a Python class. Tactic specialists do the work; orchestrators coordinate them.
- MCP server — Model Context Protocol server. A standardized wrapper that exposes platform actions as tools the agent can call.
- Platform — the third-party ad/listing service (Google, Meta, Yelp…).
- Platform reference — ~50 params per platform. Bid types, format specs, rate limits, policy gotchas. Markdown in git.
- Advertiser Profile — the 30-param record of who the business is. Versioned.
- Campaign Brief — the 20-param record of what a specific push is for. Immutable.
- Industry — the vertical (pizzeria, dental, HVAC…). Drives which playbook applies.
- Compliance gate — pre-publish check (brand safety, vertical rules, spend cap) run by ComplianceOrchestrator. Cannot be bypassed.
- Preflight — every tactic agent's "can I actually launch?" check. Returns blockers (no OAuth, no creative, no playbook, etc.).
- Revert — every agent decision is reversible. One-click rollback from the agent run page.
- Needs human — queue of items where an agent paused and is waiting on human input.
📊 Prefer pictures? See the Concepts diagram — ASCII wire charts of all of the above.