# Persona Buyer Extract Dashboard — Business Case and Workflow

**Prepared by:** OneLine engineering / Max using GStack product + engineering review  
**Date:** 2026-05-09  
**Status:** proposed second-layer product capability  
**Related production app:** https://oneline-ten.vercel.app

---

## 1. One-Line Product Case

OneLine should add a **Persona Buyer Extract Dashboard** as the second intelligence layer above raw channel integrations. The first layer connects Meta, Google Ads, Shopify, Pinterest, and TikTok. The second layer turns that collected data into buyer personas, locations, channel affinity, purchase intent, and ready-to-use targeting recipes.

This changes OneLine from “a dashboard that connects platforms” into “the system that tells the brand who is buying, where they are, which channel created them, and exactly how to target more people like them.”

---

## 2. Business Case

### 2.1 Customer Pain

Ecommerce operators and agencies can see channel dashboards, but they still struggle to answer operational questions:

- Who is actually buying, not just clicking?
- Which buyer types come from Meta vs Google vs TikTok vs Pinterest?
- Where are the highest-value buyers located?
- Which products map to which buyer groups?
- What targeting parameters should the team use next week?
- Which channel deserves more spend for each persona?

Each platform gives a partial view. Shopify knows the order. Meta knows the ad/audience. Google knows intent and keywords. TikTok and Pinterest know creative and discovery behavior. The missing product is the cross-channel buyer layer.

### 2.2 Buyer Value

The dashboard should produce practical outputs, not just charts:

1. **Persona cards**: named buyer segments with revenue, order count, AOV, LTV, products, locations, and channel source mix.
2. **Where they are**: city/region heatmap and ranked location table per persona.
3. **Who is buying**: buyer traits inferred from order history, ad interaction, campaign/adset metadata, search terms, creative theme, device, and customer geography.
4. **How to target them**: channel-specific targeting recipe for Meta, Google Ads, TikTok, Pinterest, and retargeting.
5. **What to do next**: budget shift, creative angle, keyword list, lookalike seed, exclusion list, and retargeting window.

### 2.3 Why It Fits OneLine

OneLine already has the hard parts started:

- OAuth/connectors for Shopify, Google Ads, Meta, TikTok, and Pinterest.
- Attio-backed tenant records and encrypted token storage.
- Shopify order sync into `shopify_orders`.
- Persona and audience APIs at `/api/personas`, `/api/client/personas`, and `/api/audiences`.
- Dashboard routes for `/personas`, `/reports`, `/meta-ads`, `/google-ads`, `/tiktok`, `/pinterest`, and `/shopify`.
- MiniMax integration for AI-generated persona narratives.

The gap is not the concept. The gap is a formal extraction workflow, normalized cross-channel schema, confidence scoring, and a UI built around buyer personas as the main operating unit.

### 2.4 Commercial Upside

This can be a clear paid feature for Growth/Scale plans because it directly improves marketing spend allocation:

- Agencies can use it to generate client-ready monthly insights.
- Founders can use it to decide where to spend next.
- Media buyers can copy targeting recipes into ad platforms.
- AI agents can call the extracted persona API and automate reports or campaign drafts.

Recommended packaging:

| Plan | Capability |
|------|------------|
| Starter | Basic Shopify-only personas, limited refresh |
| Growth | Cross-channel persona extract, channel mix, targeting recipes |
| Scale | Multi-store/multi-client persona library, exports, webhooks, agent API, custom attribution windows |

---

## 3. Product Workflow

### Layer 1 — Data Collection

Each connected channel sends raw facts into OneLine.

| Source | Data to collect | Why it matters |
|--------|-----------------|----------------|
| Shopify | orders, customer email/hash, city, province, country, product titles/SKUs, order value, discount, refund, UTM/referrer, created date | Identifies real buyers, revenue, geography, products, and repeat purchase behavior |
| Meta | campaigns, ad sets, ads, spend, impressions, clicks, conversions, breakdowns by age/gender/region/device, audience names, creative names, pixel/CAPI events | Shows social audience fit and creative-to-buyer signal |
| Google Ads | campaigns, ad groups, keywords/search terms, location, device, conversion value, spend, click path | Shows intent, keyword demand, and high-converting geography |
| TikTok | advertiser, campaign/ad group/ad metrics, creative performance, interests, age/gender/location/device if available | Shows discovery-led buyer segments and creative hooks |
| Pinterest | campaigns, ad groups, pins, boards/interests, saves, outbound clicks, conversions if available | Shows planning/research buyer behavior and visual categories |

### Layer 2 — Persona Buyer Extract

The extractor runs after data collection and produces normalized intelligence:

1. **Normalize events** into a shared shape: `tenant_id`, `platform`, `event_type`, `campaign_id`, `adset_id`, `creative_id`, `keyword`, `geo`, `device`, `customer_key`, `product_key`, `value`, `occurred_at`.
2. **Resolve buyers** by deterministic keys where possible: Shopify customer email hash, order ID, UTM parameters, platform conversion IDs, pixel/CAPI IDs, and campaign metadata.
3. **Build buyer profile features**: location, product mix, average order value, purchase cadence, channel touchpoints, campaign/keyword exposure, creative theme, discount sensitivity, repeat behavior.
4. **Cluster into personas** using rules first, ML later. MVP can use revenue bands, product categories, geography, channel source, and repeat/first-time status.
5. **Score each persona** for revenue, growth, conversion quality, data confidence, and channel fit.
6. **Generate targeting recipes** for each channel using extracted traits and platform-specific fields.
7. **Render dashboard and API output** for humans and agents.

### Layer 3 — Dashboard and Action

The UI should make the persona the primary object.

Core dashboard modules:

- **Persona overview cards**: persona name, summary, revenue, orders, AOV, LTV, confidence, primary channel, top products.
- **Where they are**: region/city table, map-ready geo data, best-performing locations by revenue and conversion.
- **Channel mix**: Meta/Google/Shopify/Pinterest/TikTok contribution by persona.
- **Targeting recipes**:
  - Meta: location, age, interests, lookalike seed, retargeting window, exclusions.
  - Google Ads: keywords, negative keywords, geo, campaign type, intent notes.
  - TikTok: interests, behaviors, creative hooks, creator/UGC angle.
  - Pinterest: interests, boards/pins themes, planning-stage keyword ideas.
- **Recommended actions**: budget move, creative idea, keyword add/remove, persona to retarget, persona to exclude.
- **Export/API**: JSON, CSV, Google Sheet, and API endpoint for AI agents.

---

## 4. Data Model Needed

### 4.1 MVP Attio Objects

Attio can support the prototype if we keep records compact and regenerate extracts on a schedule.

Proposed new objects:

| Object | Purpose | Key fields |
|--------|---------|------------|
| `channel_events` | Normalized raw/lightweight marketing and commerce events | `tenant_id`, `platform`, `event_type`, `customer_key`, `campaign_id`, `adset_id`, `creative_id`, `keyword`, `city`, `region`, `country`, `product_key`, `value`, `occurred_at`, `raw_ref` |
| `buyer_profiles` | One row per resolved buyer/customer | `tenant_id`, `buyer_key`, `email_hash`, `city`, `region`, `country`, `first_seen_at`, `last_seen_at`, `order_count`, `total_revenue`, `top_products`, `source_channels`, `traits_json` |
| `persona_extracts` | Versioned persona outputs | `tenant_id`, `persona_id`, `name`, `summary`, `confidence`, `buyer_count`, `revenue`, `aov`, `ltv`, `top_locations`, `top_products`, `primary_channel`, `traits_json`, `generated_at` |
| `persona_channel_performance` | Persona x platform metrics | `tenant_id`, `persona_id`, `platform`, `spend`, `orders`, `revenue`, `roas`, `cpa`, `conversion_rate`, `top_campaigns`, `generated_at` |
| `persona_targeting_recipes` | Ready-to-copy targeting output | `tenant_id`, `persona_id`, `platform`, `objective`, `locations`, `interests`, `keywords`, `negative_keywords`, `lookalike_seed`, `creative_angles`, `exclusions`, `recipe_json`, `generated_at` |

### 4.2 Scale Datastore

For production scale, move raw events and extracts to Postgres/Supabase/Neon with Attio as CRM/admin mirror. Persona extraction needs joins, versioned outputs, event volumes, and scheduled recomputation. Attio is fine for MVP visibility, but it is not the right long-term analytics store.

---

## 5. API and Jobs Needed

### 5.1 New or Upgraded APIs

| Endpoint | Purpose |
|----------|---------|
| `GET /api/personas/extract` | Returns cross-channel persona buyer extract for API-key clients |
| `GET /api/client/personas/extract` | Session-authenticated portal version |
| `POST /api/personas/extract/run` | Triggers extraction for a tenant, gated to admins/owners |
| `GET /api/personas/:id/targeting` | Returns per-channel targeting recipes for one persona |
| `GET /api/personas/:id/channel-performance` | Returns persona x channel performance metrics |
| `POST /api/export/personas` | Exports persona extracts to CSV/Sheets |

### 5.2 Background Jobs

Minimum job set:

1. `sync:shopify-orders` — refresh orders and customer geography.
2. `sync:ad-platform-metrics` — refresh campaign/adset/ad/keyword metrics from Meta, Google, TikTok, Pinterest.
3. `normalize:channel-events` — write common event records.
4. `extract:buyer-profiles` — resolve buyers and compute profile features.
5. `extract:personas` — build personas, scores, and targeting recipes.
6. `notify:persona-changed` — emit webhook if persona mix or targeting recommendations materially changed.

---

## 6. MVP Build Plan

### Phase 1 — Fix Current Persona Foundation

- Align `/api/personas`, `/api/client/personas`, and `/api/audiences` response shapes.
- Make dashboard/client pages call the right auth-specific endpoint.
- Add missing fields currently expected by the UI: `description`, `audience_suggestion`, `retargeting_hint`, and `median_order_value`.
- Add Pinterest to `AudienceSuggestions`, not only Meta/Google/TikTok.

### Phase 2 — Cross-Channel Extract Schema

- Add normalized event/write helpers for Shopify, Meta, Google Ads, TikTok, and Pinterest.
- Store enough source IDs to trace every recommendation back to source platform data.
- Add extractor functions under `src/services/persona-extract/`.

### Phase 3 — Dashboard UX

- Upgrade `/personas` and `/client/portal/audiences` into the Persona Buyer Extract dashboard.
- Add persona detail view with tabs: Overview, Locations, Channel Mix, Targeting Recipes, Source Data.
- Add export and copy-to-clipboard actions for targeting recipes.

### Phase 4 — AI Narrative and Agent API

- Use MiniMax to turn structured persona facts into short narratives and recommendations.
- Keep the structured data deterministic. AI should write the explanation, not invent the metrics.
- Expose the same output through API-key endpoints for external agents.

### Phase 5 — Scheduled Refresh and Webhooks

- Refresh extracts on a schedule and after material data syncs.
- Emit webhooks when a new persona appears, a region spikes, or a targeting recipe changes.

---

## 7. Acceptance Criteria

The first production-ready version is done when:

1. A connected tenant can open a Persona Buyer Extract dashboard and see at least 3 persona cards or a clear empty state.
2. Each persona shows revenue, order count, AOV, top products, top locations, primary channel, and confidence.
3. Each persona has platform-specific targeting guidance for Meta, Google Ads, TikTok, Pinterest, and Shopify/retention.
4. The data can be exported as JSON and CSV.
5. API-key clients can retrieve the same extract.
6. Recommendations are traceable to source metrics or marked as AI-generated narrative.
7. The dashboard handles missing platform data without failing.
8. The extraction job is tenant-scoped and does not leak buyer data between clients.

---

## 8. Risks and Guardrails

| Risk | Guardrail |
|------|-----------|
| Attribution is incomplete across platforms | Show confidence score and source coverage per persona |
| AI invents unsupported targeting claims | Generate structured metrics deterministically, use AI only for narrative copy |
| Attio becomes too slow for event analytics | Keep MVP extracts compact, move raw event store to Postgres before scale |
| Platform APIs expose different demographic fields | Design recipes with optional fields and platform-specific adapters |
| Privacy/compliance issues around profiling | Hash direct identifiers, tenant-scope every query, disclose usage in privacy docs, avoid selling/transferring data |
| Bad recommendations hurt ad spend | Show evidence, confidence, and last refreshed timestamp; allow manual override/export review |

---

## 9. Recommended Next Engineering Ticket

Build **Persona Buyer Extract v1** as a scoped feature:

- Fix existing persona/audience endpoint shape mismatches.
- Add cross-channel extract service with deterministic rules.
- Extend current `/personas` dashboard into the buyer extract view.
- Include Meta, Google Ads, Shopify, Pinterest, and TikTok in the output contract.
- Keep storage in Attio for MVP but design the service so the backing store can move to Postgres without changing the UI/API contract.

This is the right second layer for OneLine. The first layer collects the data. This layer turns the data into a decision: who to target, where to target them, and why.