# End-to-End Flow: Marketing Command Center

## Complete Pipeline Flow

### 1. Setup (One-time)
- User goes to **Settings** page
- Configures API keys:
  - **Tavily** — for trend/research agents (free: 1000 searches/mo)
  - **Gemini** — for NanoBanana MCP image generation (~$0.04-0.13/image)
  - **Postiz** — URL + API key for IG/TikTok publishing
  - **Nextdoor** — API token + advertiser ID (optional)
- User fills in knowledge files:
  - `pipeline/knowledge/brand_identity.md` — brand voice, CTAs, personality
  - `pipeline/knowledge/platform_guidelines.md` — platform specs
  - `pipeline/knowledge/product_campaign.md` — product details, features

### 2. Campaign Creation
User fills out campaign form:
- **Name** — campaign identifier
- **Platforms** — Instagram, TikTok, Nextdoor (checkboxes)
- **Goal** — app downloads, brand awareness, engagement
- **Key Message** — the core value proposition
- **Social Proof** — download count, rating, press
- **Target Audience** — who we're reaching
- **Visual Direction** — clean/bold/premium/warm/tech
- **Competitor Apps** — for research context
- **Variations** — hook count per platform (default 5)
- **Use Trend Report** — incorporate latest trends

### 3. Pipeline Launch
User clicks "Launch Pipeline" → system:
1. Creates output directory: `pipeline/outputs/{name}_{date}/`
2. Creates subdirectories: `ads/`, `scripts/`, `video/`, `copy/`
3. Loads API keys from Settings DB into environment
4. Spawns 7 Claude subprocess agents sequentially
5. Streams progress via SSE to the browser

### 4. Agent Execution (7 Steps)

#### Step 1: Trend Scout (~12s)
- Reads knowledge files
- Runs 5 Tavily searches (hooks, competitors, viral formats, pain points, timely angles)
- Outputs: `trend_report.json`

#### Step 2: Marketing Research Agent (~2min)
- Reads knowledge files + trend_report.json
- Runs 5 deep Tavily research queries
- Outputs: `research_results.json`, `research_brief.md`, `interactive_report.html`

#### Step 3: Script Writer (~1.5min)
- Reads knowledge + research + trends
- Writes 5 hook variations × 3 platform styles = 15 scripts
- Hook-Body-CTA structure with timing cues for video
- Outputs: `scripts/scripts_all.json`, `scripts/scripts_summary.md`

#### Step 4: Ad Creative Designer (~3min)
- Reads knowledge + scripts + research
- For each ad variation:
  1. Calls NanoBanana MCP `generate_image` tool with campaign-aware prompt
  2. Builds HTML/CSS layout at exact dimensions with generated image + headline + CTA
  3. Launches Playwright → screenshots to PNG
- Outputs: `ads/*.png` + `ads/ad_manifest.json`
- Dimensions: IG Feed 1080x1080, IG Stories 1080x1920, ND Spotlight 1200x1200, ND Display 1200x628

#### Step 5: Video Ad Producer (~5min)
- Reads knowledge + scripts + ad manifest
- Creates scene_plan.json per video (hook/problem/solution/proof/CTA scenes)
- Creates/modifies Remotion compositions in `remotion-ad/src/`
- Renders via `npx remotion render` → MP4 files
- Outputs: `video/*.mp4` + `video/scene_plans.json`
- Styles: polished (IG), authentic (TikTok), local (Nextdoor)

#### Step 6: Copywriter Agent (~1min)
- Reads knowledge + research + scripts
- Writes platform-tuned captions: Hook → Value → CTA → Hashtags
- Outputs: `copy/instagram_captions.json`, `copy/tiktok_captions.json`, `copy/nextdoor_posts.json`, `copy/copy_matrix.json`

#### Step 7: Distribution Agent (~30s)
- Gathers all outputs
- Creates `Publish_manifest.md` with:
  - All assets with file paths
  - Recommended caption per asset
  - Recommended posting schedule
  - Review checklist
- DOES NOT publish — waits for human approval

### 5. Asset Scanning
After pipeline completes:
- Scanner reads all files in output directory
- Creates Asset records in database
- Infers: platform (from filename), dimensions, type
- Loads metadata from adjacent JSON files
- All assets start in "draft" status

### 6. Review
User goes to campaign Assets tab:
- Grid view of all generated content
- Images shown inline, videos play on hover
- Filter by: platform, type, status
- Each asset shows: platform badge, dimensions, caption preview
- User clicks Approve or Reject per asset
- Bulk select → Approve/Reject multiple

### 7. Claude Chat (Feedback Loop)
User goes to Claude Chat tab:
- Chat with Claude about the campaign
- "Make the hooks snarkier"
- "Regenerate the TikTok ad with darker colors"
- Claude has access to all pipeline files
- New/modified assets appear after re-scan

### 8. Publishing
User selects approved assets → Push to Postiz:
- Modal shows selected assets with schedule date/time picker
- Postiz uploads media, creates scheduled posts
- Assets marked as "published" with Postiz post ID

For Nextdoor:
- Separate "Push to Nextdoor" flow
- Creates campaign → ad group → creative → ad via GraphQL API

### 9. Queue
Queue page shows all published/scheduled assets with status tracking.

## Integration Requirements

| Integration | Required? | API Key Source | What It Does |
|------------|-----------|----------------|-------------|
| Tavily | Yes | Settings page | Web research for trends + market analysis |
| Google Gemini | Yes | Settings page | Powers NanoBanana MCP image generation |
| Playwright | Built-in | npm package | HTML-to-PNG rendering for static ads |
| Remotion | Built-in | npm package | React-to-MP4 video rendering |
| Postiz | For publishing | Settings page | Instagram + TikTok scheduling |
| Nextdoor | Optional | Settings page | Direct Nextdoor Ads API |
| Claude Code | Required | Max plan OAuth | Pipeline engine (subprocess spawning) |