# b3yotch/marketing-automation architecture

> Architecture diagram of the GitHub repository b3yotch/marketing-automation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/b3yotch/marketing-automation
- Repository: https://github.com/b3yotch/marketing-automation

## Overview

This repository implements an ecommerce-ad creative workflow: a product-page URL is researched, turned into creative direction and generation prompts, used to generate images, judged to select a source frame, and optionally used to generate video. The shared pipeline runner owns the ordered stages; each agent is a LangGraph subgraph. The README documents the stages and bulk-run modes, while sampled source confirms several internal calls. Some subsystem details are documented but not sampled, so those links rely on the README rather than inferred implementation.

Main entry points: [`app/core/pipeline.py`](https://github.com/b3yotch/marketing-automation/blob/main/app/core/pipeline.py) (Stage runner), [`app/agents/creative_strategy_agent/nodes.py`](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/nodes.py) (Creative strategy), [`app/agents/video_generation/nodes.py`](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/nodes.py) (Video generation), [`app/agents/research_agent/nodes.py`](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/nodes.py) (Product research)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Workflow orchestration"]
  node_runner["Stage runner<br/>[pipeline.py]"]
end

subgraph group_research_strategy["Research and strategy"]
  node_research["Product research<br/>[nodes.py]"]
  node_scraper["Page scraper<br/>[scraper.py]"]
  node_research_contract["Research contract<br/>[schema.py]"]
  node_strategy["Creative strategy<br/>[nodes.py]"]
  node_market["Market research<br/>[market_research.py]"]
  node_strategy_contract["Strategy contract<br/>[schema.py]"]
end

subgraph group_creative_generation["Creative generation"]
  node_prompt_gen["Prompt generation<br/>[nodes.py]"]
  node_prompt_contract["Prompt contract<br/>[schema.py]"]
  node_image_gen["Image generation<br/>[nodes.py]"]
  node_image_client["Image ComfyUI client<br/>[comfyui_client.py]"]
  node_image_contract["Image results<br/>[schema.py]"]
end

subgraph group_review_video["Selection and video"]
  node_critic["Image selection<br/>[nodes.py]"]
  node_selection_contract["Selection results<br/>[schema.py]"]
  node_video_gen["Video generation<br/>[nodes.py]"]
  node_video_client["Video ComfyUI client"]
  node_video_contract["Video results<br/>[schema.py]"]
end

subgraph group_shared["Shared services"]
  node_llm["Structured LLM<br/>[llm.py]"]
end

node_brand_user(("Product URL"))
node_comfyui{{"ComfyUI"}}
node_tavily{{"Tavily search"}}

node_brand_user -->|"submits URL"| node_runner
node_runner -->|"runs first"| node_research
node_runner -->|"runs second"| node_strategy
node_runner -->|"runs third"| node_prompt_gen
node_runner -->|"runs fourth"| node_image_gen
node_runner -->|"runs fifth"| node_critic
node_runner -->|"runs sixth"| node_video_gen
node_research -->|"scrapes page"| node_scraper
node_research -->|"extracts data"| node_llm
node_research -->|"validates output"| node_research_contract
node_strategy -->|"fetches context"| node_market
node_strategy -->|"creates direction"| node_llm
node_strategy -->|"uses product data"| node_research_contract
node_strategy -->|"returns direction"| node_strategy_contract
node_market -->|"searches trends"| node_tavily
node_market -->|"searches competitors"| node_tavily
node_prompt_gen -->|"generates prompts"| node_llm
node_prompt_gen -->|"uses direction"| node_strategy_contract
node_prompt_gen -->|"validates prompts"| node_prompt_contract
node_image_gen -->|"queues workflow"| node_image_client
node_image_gen -->|"uses prompts"| node_prompt_contract
node_image_gen -->|"produces images"| node_image_contract
node_image_client -->|"queues and polls"| node_comfyui
node_critic -->|"judges candidates"| node_llm
node_critic -->|"reviews candidates"| node_image_contract
node_critic -->|"returns selection"| node_selection_contract
node_video_gen -->|"uses selected frame"| node_selection_contract
node_video_gen -->|"uses video prompt"| node_prompt_contract
node_video_gen -->|"generates video"| node_video_client
node_video_gen -->|"returns video results"| node_video_contract
node_video_client -->|"uploads and polls"| node_comfyui

click node_runner "https://github.com/b3yotch/marketing-automation/blob/main/app/core/pipeline.py"
click node_research "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/nodes.py"
click node_scraper "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/scraper.py"
click node_research_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/schema.py"
click node_strategy "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/nodes.py"
click node_market "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/market_research.py"
click node_strategy_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/schema.py"
click node_prompt_gen "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/prompt_gen_agent/nodes.py"
click node_prompt_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/prompt_gen_agent/schema.py"
click node_image_gen "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/nodes.py"
click node_image_client "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/comfyui_client.py"
click node_image_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/schema.py"
click node_critic "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_selection_agent/nodes.py"
click node_selection_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_selection_agent/schema.py"
click node_video_gen "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/nodes.py"
click node_video_client "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/video_comfyui_client.py"
click node_video_contract "https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/schema.py"
click node_llm "https://github.com/b3yotch/marketing-automation/blob/main/app/core/llm.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_comfyui toneBlue
class node_research,node_scraper,node_research_contract,node_strategy,node_market,node_strategy_contract toneAmber
class node_prompt_gen,node_prompt_contract,node_image_gen,node_image_client,node_image_contract toneMint
class node_critic,node_selection_contract,node_video_gen,node_video_client,node_video_contract toneRose
class node_llm,node_brand_user,node_tavily toneIndigo
```

## Components

### Workflow orchestration

- [Stage runner](https://github.com/b3yotch/marketing-automation/blob/main/app/core/pipeline.py): `app/core/pipeline.py`

### Research and strategy

- [Product research](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/nodes.py): `app/agents/research_agent/nodes.py`
- [Page scraper](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/scraper.py): `app/agents/research_agent/scraper.py`
- [Research contract](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/research_agent/schema.py): `app/agents/research_agent/schema.py`
- [Creative strategy](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/nodes.py): `app/agents/creative_strategy_agent/nodes.py`
- [Market research](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/market_research.py): `app/agents/creative_strategy_agent/market_research.py`
- [Strategy contract](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/creative_strategy_agent/schema.py): `app/agents/creative_strategy_agent/schema.py`

### Creative generation

- [Prompt generation](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/prompt_gen_agent/nodes.py): `app/agents/prompt_gen_agent/nodes.py`
- [Prompt contract](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/prompt_gen_agent/schema.py): `app/agents/prompt_gen_agent/schema.py`
- [Image generation](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/nodes.py): `app/agents/image_generation/nodes.py`
- [Image ComfyUI client](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/comfyui_client.py): `app/agents/image_generation/comfyui_client.py`
- [Image results](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_generation/schema.py): `app/agents/image_generation/schema.py`

### Selection and video

- [Image selection](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_selection_agent/nodes.py): `app/agents/image_selection_agent/nodes.py`
- [Selection results](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/image_selection_agent/schema.py): `app/agents/image_selection_agent/schema.py`
- [Video generation](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/nodes.py): `app/agents/video_generation/nodes.py`
- [Video ComfyUI client](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/video_comfyui_client.py): `app/agents/video_generation/video_comfyui_client.py`
- [Video results](https://github.com/b3yotch/marketing-automation/blob/main/app/agents/video_generation/schema.py): `app/agents/video_generation/schema.py`

### Shared services

- [Structured LLM](https://github.com/b3yotch/marketing-automation/blob/main/app/core/llm.py): `app/core/llm.py`

### Other components

- **Product URL**
- **ComfyUI**
- **Tavily search**

## Connections

- Product URL → Stage runner: submits URL
- Stage runner → Product research: runs first
- Stage runner → Creative strategy: runs second
- Stage runner → Prompt generation: runs third
- Stage runner → Image generation: runs fourth
- Stage runner → Image selection: runs fifth
- Stage runner → Video generation: runs sixth
- Product research → Page scraper: scrapes page (evidence: `app/agents/research_agent/nodes.py`)
- Product research → Structured LLM: extracts data (evidence: `app/agents/research_agent/nodes.py`)
- Product research → Research contract: validates output (evidence: `app/agents/research_agent/nodes.py`)
- Creative strategy → Market research: fetches context (evidence: `app/agents/creative_strategy_agent/nodes.py`)
- Creative strategy → Structured LLM: creates direction (evidence: `app/agents/creative_strategy_agent/nodes.py`)
- Creative strategy → Research contract: uses product data (evidence: `app/agents/creative_strategy_agent/nodes.py`)
- Creative strategy → Strategy contract: returns direction (evidence: `app/agents/creative_strategy_agent/nodes.py`)
- Market research → Tavily search: searches trends
- Market research → Tavily search: searches competitors
- Prompt generation → Structured LLM: generates prompts (evidence: `app/agents/prompt_gen_agent/nodes.py`)
- Prompt generation → Strategy contract: uses direction (evidence: `app/agents/prompt_gen_agent/nodes.py`)
- Prompt generation → Prompt contract: validates prompts (evidence: `app/agents/prompt_gen_agent/nodes.py`)
- Image generation → Image ComfyUI client: queues workflow (evidence: `app/agents/image_generation/nodes.py`)
- Image generation → Prompt contract: uses prompts (evidence: `app/agents/image_generation/nodes.py`)
- Image generation → Image results: produces images (evidence: `app/agents/image_generation/nodes.py`)
- Image ComfyUI client → ComfyUI: queues and polls (evidence: `app/agents/image_generation/comfyui_client.py`)
- Image selection → Structured LLM: judges candidates (evidence: `app/agents/image_selection_agent/nodes.py`)
- Image selection → Image results: reviews candidates
- Image selection → Selection results: returns selection (evidence: `app/agents/image_selection_agent/nodes.py`)
- Video generation → Selection results: uses selected frame (evidence: `app/agents/video_generation/nodes.py`)
- Video generation → Prompt contract: uses video prompt (evidence: `app/agents/video_generation/nodes.py`)
- Video generation → Video ComfyUI client: generates video (evidence: `app/agents/video_generation/nodes.py`)
- Video generation → Video results: returns video results (evidence: `app/agents/video_generation/nodes.py`)
- Video ComfyUI client → ComfyUI: uploads and polls (evidence: `app/agents/video_generation/video_comfyui_client.py`)
