machi

systems/machi.md · Systems

unverified: no trust signals recorded yet

Machi — the marketing brain

What: the single strategist every outbound marketing touch flows through. She reads the observed world, decides WHO needs a postcard, picks the MESSAGE most likely to convert them, has the AI postcard engine paint a gated card, and learns from what actually happened (scans / visits / claims / Doozer+ conversions). Winning angles get sent more; losers fade. Named for a strategist who "smells success in the wind." Shipped v2.2.380.

Engine — includes/machi.php

• machiScoreBusiness($biz) → 0-100. NEED (weak/no own website), FIT

(machiNicheTier — trades/health/auto/legal/realtor = tier 3, active marketers food/beauty/fitness = tier 2), PROOF + ability to pay (review volume, rating, price_level). Returns score + segment + reasons.

• machiRankTargets($opts) → the "these need a postcard" list. SQL preconditions:

active domain (a real screenshot exists), OPERATIONAL, not claimed (admin_email empty), not already converted; default view = untouched, or follow_up for businesses past cooldown (≤3 touches). Scored + sorted in PHP.

• machiPickVariant($businessId,$seg,$peek,$exclude) → the angle. Weighted-random

by machiVariantScore (Bayesian-smoothed conversion value + scan/claim signal) × segment affinity, EXCLUDING angles already SENT to this business (follow-ups differ) and any explicit exclude (a rerun's current angle).

• machiGenerateForTarget($businessId,$opts) → pick angle → postcardAiRun with

campaign='machi', message=chosen copy, variant_id. NO touch yet (previews and reruns must not inflate the sequence); the angle is stored on the design.

• machiFullSend($designId,$opts['live']) → postcardAiSend live, then creates the

machi_touches row (the send is the real event), touch_no = prior sent + 1, then machiSyncOutcomes.

• machiSyncOutcomes() → for each SENT touch pull postcardAiTracking + claim +

machiBusinessConverted (premium owner by email match), recompute each variant's rolling stats from machi_touches (idempotent).

• machiPerformance() (funnel + variant leaderboard + spend from

ai_generation_history content_type postcard_ai + thanksio sends + revenue = conversions × machi_conversion_value default 99 + ROI). machiMarketScan() = which segments pay back.

Tables (self-creating): machi_variants (8 seeded angles: ready / leads / found / free / proof / local / pens / ahead; each with rolling times_sent/scans/visits/claims/conversions) and machi_touches (per-business send history + learning signal). postcard_designs gained variant_id + angle.

Dashboard — includes/admin-machi.php (Story → Machi, route machi): funnel + spend + revenue + ROI; ranked target cards (score / why / segment / lead angle) → Generate → gated preview appears in-card → Full send (live=mail) / Rerun (fresh angle) / Reject; "Winning messages" leaderboard + "Market scan"; filters by segment / state / min score / follow-ups-due / untouched-only.

Creative uses the operator's Image Generation config now: postcardAiGenerate routes through aiImageProviderDefault() — OpenAI GPT Image via /images/edits (screenshot + logo as real reference images) OR Gemini generateContent — so no separate key is needed when OpenAI is set, and cost lands in Analytics & Costs at the configured per-image price. See [[ai-postcards]], [[claim-codes]], [[thanksio]], [[the-observed-world]].

Dev API: dz machi — rank / gen b= / send id= live=1 confirm=1 / sync / perf / market / seed.

Verified live v2.2.380: seed + rank return sensible targets (established high-review businesses first, angles varied, trades score tier-3). Real sends + learning accrue once postcards mail. NEXT: scheduled auto-drafting of top targets into the review queue (traffic-driven, like the job runner); agent-authored new angles into machi_variants (source='agent'); market/geo selection surfacing high-ad-spend metros.