# Growth & Sales Engine (revenue-first)

The first seven docs make a platform that **manages** the business. This doc makes it **sell,
retain, and scale** — the revenue engine. It reframes the whole system around **revenue
outcomes**, not just marketing output, and adds the India-specific selling channels
(**WhatsApp-first**, Instagram, YouTube) that actually convert.

**Two decisions locked with the owner:**
1. **WhatsApp = full WhatsApp Business Cloud API** (automated broadcasts, abandoned-cart
   recovery, order updates, catalog sync, broadcast-to-buy). Credential-gated: Meta Business
   onboarding + a dedicated number + message-template approval.
2. **Agent runs = campaign-driven & coordinated** — a **Campaign Coordinator** runs only the
   agents serving the active goal; always-on becomes opt-in. Builds on the existing
   **Festive 2026** plan (`plans/festive-2026-action-plan.md`).

Everything here rides the hardened core from `07-architecture-hardening.md` (event bus,
workflow engine, channel manager, A/B module) — so most of it is **configuration of existing
seams, not new foundations.**

---

## 1. Revenue-first: KPI hierarchy + Business KPI dashboard

The platform leads with a **simple business dashboard**, above all the agent activity:

```text
NORTH STAR: Revenue
 ├─ Traffic           (sessions by channel)
 ├─ Conversion rate   (sessions → orders)
 ├─ AOV               (avg order value)  ← bundles, upsells
 ├─ Repeat rate       (returning customers)  ← retention engine
 ├─ Cart recovery     (abandoned → recovered)  ← WhatsApp
 ├─ Channel ROI / CAC (spend vs revenue per channel)  ← attribution
 └─ LTV               (lifetime value per segment)
```

This is the **festive "5-number report"** (`plans/festive-2026-action-plan.md` Phase 4)
formalized into a live dashboard. Every agent and feature is judged by its effect on these
numbers — see the agent revenue-classification in §10.

## 2. Customer Journey map

Features and agents map to journey **stages**, so we manage the *whole* path, not isolated tasks:

```mermaid
flowchart LR
    D["Discovery<br/>IG Reels · YouTube · SEO · Pinterest"] --> C["Consideration<br/>PDP trust layer · AI search · WhatsApp Q&A"]
    C --> P["Purchase<br/>checkout · Razorpay · bundles · cart recovery"]
    P --> R["Retention<br/>post-purchase journeys · reorder · reviews · VIP"]
    R --> A["Advocacy<br/>UGC · referrals · influencer codes"]
    A -.loops back.-> D
```

## 3. Customer segmentation

The unit the sales engine targets. Built on Medusa `CustomerGroup` + a `customer_segment`
module: **new vs repeat**, **VIP** (top RFM), **festival buyers**, **at-risk/churned**,
**wholesale/B2B**, **gifting buyers**. Segments drive broadcasts, journeys, pricing, and which
campaign a customer enters.

## 4. The selling channels (Channel Manager)

All channels implement the one **Channel Manager** interface (`07 §12`). Priority order
reflects what converts in India.

### 4a. WhatsApp-first selling (full Cloud API) — the primary conversion channel

```mermaid
flowchart TB
    CAT["Catalog sync → WhatsApp catalog"]
    SEG["Segment → segmented broadcast"]
    AC["Cart abandoned → recovery message"]
    OU["Order placed/shipped → order updates"]
    B2B["Broadcast-to-buy (festival drop) → checkout link"]
    CAT --> WA["WhatsApp Business Cloud API"]
    SEG --> WA
    AC --> WA
    OU --> WA
    B2B --> WA
    WA --> CONV["Conversion + attribution event"]
```

- Driven by the **workflow engine** (`event → message`) + the `whatsapp_subscriber`/`template`
  data (§ data model). Opt-in compliant; uses approved message templates.
- **Onboarding (credential-gated):** Meta Business verification, a dedicated WhatsApp number,
  and template approval. Flagged as a setup prerequisite, not a code blocker.

### 4b. Instagram commerce

Reels → **product tag** → site; **UGC** collection (repost rights), **influencer link
tracking** (referral codes §9), and **product-drop** campaigns for impulse buying. Uses the
Meta catalog + the Instagram graph (Meta MCP tools available in this env).

### 4c. YouTube funnel

"How to choose / how to style / how to care" videos + short cuts with product links — video
builds trust for premium handloom. Reuses the existing **`youtube-seo` agent**; ties to the
Festive plan's YouTube launch (Phase 3).

## 5. Retention engine (repeat revenue)

Acquisition alone means re-buying the same customer forever. Built on the **workflow engine +
segments + WhatsApp/email**:
- **Post-purchase journeys** (thank-you → care guide → review request → reorder nudge).
- **Reorder nudges** timed to product life (e.g. seasonal razai, gifting cycles).
- **Review requests** (feeds the review-reputation agent + PDP social proof).
- **VIP segments** (early access to drops, perks).
- **Festival comeback** campaigns to last year's festive buyers.

## 6. Smart bundles (AOV)

A `bundle` module + an AI **bundle generator**: auto-create **gift sets**, **festival wear**,
**office wear**, **trousseau** collections from catalog + margin + co-purchase data — lifting
average order value. Surfaced on the storefront and in WhatsApp broadcasts.

## 7. Trust layer (PDP conversion)

Handloom is a trust purchase. Storefront sections (content blocks) that make proof **visible on
product pages**: **artisan stories**, **handloom/craft proof** (Sanganeri/Bagru process),
**quality badges**, **delivery promise** ("ships before Diwali" countdown), **return policy**,
and **social proof** (reviews, UGC). Directly raises conversion rate (§1).

## 8. Conversion optimization (continuous A/B)

Extends the `ab_experiment` module (`03 §2f`) into a **continuous experimentation framework**:
test PDPs, banners, **pricing**, **bundles**, **offer wording**, and **checkout flow** — not
just content. Winners auto-promote; results feed the CRO agent. (Festive plan already runs
A/B #1–2 in Phase 2.)

## 9. Channel attribution + influencer referral

Know **what actually drives revenue**: UTM tagging + **referral/influencer codes** +
`attribution_event` on the event bus → **revenue by WhatsApp / Instagram / YouTube / SEO /
influencer**. Influencers get unique **referral codes** with conversion + **payout tracking**.
Feeds Channel ROI/CAC in the KPI dashboard.

## 10. Campaign Mode + Campaign Coordinator

A **campaign** is a first-class object: `goal`, `dates`, `target SKUs`, `KPIs`, `channels`,
`budget`. The **Campaign Coordinator** is the single owner that prevents the "25 agents doing
duplicate/overlapping work" problem:

```mermaid
flowchart TB
    CAMP["Active campaign<br/>(e.g. Diwali 2026)"] --> COORD["Campaign Coordinator"]
    COORD -->|run only relevant agents, prioritized| AG["Selected agents<br/>(content, seo, social, cro, review…)"]
    COORD -->|dedupe keywords/content| AG
    COORD -->|enforce inventory guard §11| AG
    AG --> DEL["Deliverables aligned to ONE goal"]
    DEL --> KPI["Campaign KPIs (§1)"]
    KPI -->|feedback| COORD
```

- **Replaces always-on**: agents run **campaign-driven & prioritized**; a campaign can still
  keep a small core opt-in. Cuts cost, noise, and duplicate work.
- **Agent revenue classification:** every one of the 25 agents is tagged
  **`direct-revenue`** (CRO, ecommerce-SEO, review, retention), **`awareness`** (social,
  Pinterest, YouTube, brand), or **`support`** (technical-SEO, schema, analytics) so the
  coordinator prioritizes revenue drivers first. Stored on the agent registry (`07 §13`).

## 11. Inventory-aware selling (stock-protection guard)

The "inventory lock": **agents and channels never promote what you can't sell.** A guard reads
**live stock** via the event bus and filters out **out-of-stock, dead, and low-margin SKUs**
before any agent recommends or any channel lists them:

```mermaid
flowchart LR
    INV[("Live inventory (Medusa)")] -->|inventory.low / out_of_stock event| GUARD["Inventory Guard"]
    GUARD -->|suppress / swap to in-stock alt| AG["Agents"]
    GUARD -->|block listing / hide| CH["Channels (WhatsApp/IG/web)"]
```

Protects trust and stops wasted traffic to dead links — a top-priority fix.

## 12. Monetization expansion (beyond D2C)

Structured paths to more revenue, on Medusa primitives:
- **Wholesale/B2B**: a **wholesale lead-capture page** → `wholesale_lead`; B2B buyers as a
  `CustomerGroup` with a wholesale `PriceList`.
- **Gifting & corporate orders**: bundles + bulk + gift notes (ties to the festive corporate
  Diwali pages already planned).
- **Local retail pickup**: a pickup `ShippingOption`/fulfillment for Jaipur-local buyers.

## 13. Roadmap priority (owner's highest-priority fixes first)

| Priority fix | Where it lands |
|---|---|
| **Revenue-first KPI dashboard** | MVP/v1 |
| **Inventory guard (sell only what's in stock)** | MVP |
| **WhatsApp Cloud API selling** | v1 (after store live) |
| **Retention flows (repeat sales)** | v1 |
| **Campaign mode + coordinator** | v1 |
| Instagram commerce, smart bundles, attribution, A/B framework, trust layer | v1 |
| YouTube funnel scale, influencer payouts, B2B/wholesale, loyalty | v2 |

(Reflected in `06-roadmap.md`.)

## 14. Reused vs new

- **Reused:** the 25 agents (now classified + coordinated), the Festive 2026 campaign pattern,
  the review/CRO/social/YouTube agents, Medusa customer groups + price lists + inventory +
  fulfillment, the event bus + workflow engine + channel manager + A/B module from `07`.
- **New (mostly config + thin modules):** KPI dashboard, Campaign Coordinator, inventory guard,
  WhatsApp/Instagram channels, retention journeys, bundle generator, attribution + referral,
  trust-layer sections, wholesale lead capture.