AI Growth Engine¶

A data-driven marketing engine that ingests content performance (IG + TikTok), ad performance (Meta + TikTok Business), commerce data (Woo + GA4), and SEO signals (Search Console), then proposes marketing actions via a Claude-CLI-driven recommendation layer. Every action is approval-gated — no auto-publishing, no auto-spend.

Source documents: Fruitplug_Claude_CLI_Master_Plan.pdf and Fruitplug_Final_Boss_Master_Plan.pdf (both user-approved 2026-04-24).

Architecture¶

PWA (Next.js)
  ↓
WordPress / WooCommerce  ← source of truth for orders, customers, products
  ↓
fruitplug-api plugin     ← control layer, stores metrics + recommendations
  ↓
AI Marketing Engine      ← Claude CLI via Bash (stdin/stdout)
  ↓
External APIs            ← IG Graph · TikTok Business · Meta Ads · Search Console · GA4
  ↓
Analytics + Feedback     ← performance fed back into the LLM loop

The PWA stays a view layer. The plugin and CLI scripts live on A2 (or on this dev server for iteration) and never expose secrets to the browser.

Phases¶

#	Name	What ships	Weeks
1	Data aggregation	New DB tables, IG Graph ingester, TikTok Business ingester, Woo exporter, GA4 reader	3
2	LLM recommendation engine	`scripts/generate-recommendations.sh`, prompt templates, output JSON schema	2
3	Approval queue	wp-admin review UI inside `fruitplug-api`, bulk approve/reject, audit log	2
4	Publishing automation	Scheduled posting to IG + TikTok via their APIs, Meta Ads draft creation (review-required)	2
5	SEO automation	Product meta rewrites (draft-only), internal-link suggestions, schema completeness scan	2
6	Feedback loop	Metric deltas post-action tied back to recommendation IDs; confidence calibration	1

Total: ~12 weeks serial, ~8 with parallelization on phases 3 + 5.

New database tables¶

All prefixed wp_fruitplug_ so they sit alongside the existing plugin tables.

Table	Purpose
`content_assets`	Videos, captions, hooks, thumbnails; product mappings. Seeded from IG library (349 reels, 151M views)
`platform_metrics`	Time-series rows — one per (asset, platform, day). Views, likes, saves, CTR, conversions
`ai_recommendations`	One row per LLM output: action_type, reasoning, expected_impact, confidence, risk, approval_required, suggested_copy, audience, budget, rollback, status
`marketing_actions`	Resolved recommendations that got approved + their execution state
`campaigns`	Meta / TikTok campaign handles once they launch. References `marketing_actions.id`
`seo_tasks`	SEO-specific action items (meta rewrites, internal linking, schema gaps)
`llm_memory`	Prior decisions + outcomes used for few-shot priming on subsequent runs
`api_connections`	Encrypted store of long-lived tokens + refresh state (IG, TikTok, Meta, GA4)
`approval_events`	Audit log: who approved/rejected what, when, with what note

Migration to be added to wp-plugin/fruitplug-api/includes/Migrations.php when Phase 1 kicks off.

Claude CLI workflow¶

# Edit the prompt (lives in scripts/ as a plain markdown file, version-controlled)
nano scripts/ai/fruitplug-growth-engine-prompt.md

# Dry run to stdout
cat scripts/ai/fruitplug-growth-engine-prompt.md | claude -p

# Save human-readable plan
cat scripts/ai/fruitplug-growth-engine-prompt.md | claude -p > output/plan-$(date +%F).md

# Save machine-readable recommendations for the approval queue
cat scripts/ai/fruitplug-growth-engine-prompt.md \
  | claude -p --output-format json \
  > output/recommendations-$(date +%F).json

The payload fed into Claude is a JSON dump of the last 7 days of metrics + active content assets + open recommendations from ai_recommendations. Output conforms to the Recommendation schema below.

Recommendation output schema¶

Every LLM recommendation must conform to this shape. Rejected if any field is missing or if approval_required defaults to anything other than true.

{
  "action_type": "repurpose_ig_to_tiktok | launch_meta_ad | rewrite_product_meta | send_restock_email | ...",
  "title": "Short human summary",
  "reasoning": "Evidence trail: which metrics, which comparison, which pattern",
  "expected_impact": "Estimated delta + confidence interval",
  "confidence": 0.0,
  "risk": "low | medium | high",
  "approval_required": true,
  "products": ["slug-1", "slug-2"],
  "content_assets": ["ig_reel_id", "tt_video_id"],
  "suggested_copy": "Draft caption or meta description. Never published without review",
  "audience": "Description or encoded targeting payload",
  "budget": "£ amount if ad spend is involved, null otherwise",
  "rollback": "Exact steps to revert if the action underperforms"
}

Automation scripts¶

All live in scripts/ai/ and are thin shell wrappers around the plugin's REST endpoints + the Claude CLI. No business logic in Bash beyond glue.

Script	Purpose
`sync-metrics.sh`	Pull latest IG/TikTok/Meta/GA4 metrics into `platform_metrics`
`generate-recommendations.sh`	Run the LLM, write to `ai_recommendations`, notify admin
`export-growth-report.sh`	Monthly markdown report — top content, worst content, opportunities
`run-seo-audit.sh`	Scan products for meta/schema/linking gaps → `seo_tasks`
`import-content-library.sh`	One-time seed from the existing IG archive (349 reels)
`test-marketing-engine.sh`	Smoke run with canned payload — CI-friendly

Safety rules (hard-coded)¶

These are enforced at the plugin layer, not just cultural norms.

No automatic publishing — content drafts only, human approves each post.
No automatic ad-spend changes — Meta/TikTok Ads API calls always create paused campaigns in review state.
No product page overwrites — meta/description rewrites land as WordPress revisions, never direct updates.
No customer messaging without approval — email drafts to segments must be approved in approval_events before any send.

Violating any of these throws at the marketing_actions insertion layer in the plugin.

External API requirements¶

These are blockers on Phase 1 — nothing else starts until they're in place.

Provider	What's needed	Status
Instagram Graph	Long-lived Page access token, IG Business/Creator account linked to FB Page, Meta App with `instagram_graph_user_media` + `instagram_graph_user_profile` scopes	⏳ user to generate
TikTok Business	Developer app, OAuth flow, `business_account`, `content_performance` scopes	⏳ user to generate
Meta Ads	Same Meta app, `ads_management` scope	⏳ user to generate (post-Phase-3)
Search Console	OAuth2 credentials, verified site	⏳ user to generate
GA4	Service-account key JSON	⏳ user to generate

Keys live in wp_fruitplug_api_connections (encrypted with AES-256 via wp_salt('auth')), never in .env committed to disk.

Competitive stance¶

Most brands guess at what to post next. This engine turns the 349-reel archive + Woo order data into a pattern-matched, confidence-scored recommendation queue that ops approve in under 5 minutes a day. The moat is the feedback loop: every shipped recommendation's outcome gets fed back into the LLM prompt, so the system gets better the more it's used.

Why this is deferred (for now)¶

Phase 1 PWA cutover (Stripe, auth, UX) has to land first — no point optimizing a funnel that isn't yet the public funnel.
External API credentials are all pending.
The approval UI lives inside fruitplug-api, which itself is still getting its core commerce features wired.

Tracked as Phase 3 in the main roadmap.