Campaign Manager - Product Guide

Complete product overview - what Campaign Manager is, how campaigns are built, templates, AI features, microsites, and the Customer App

1. Overview

Campaign Manager (Velocity Engine) is a platform for building, managing, and executing marketing campaigns at scale. It combines a structured campaign pipeline - where each campaign is broken into phases, steps, and computation variables - with powerful AI/LLM content generation across multiple providers (OpenAI, Anthropic Claude, Google Gemini, Perplexity, AWS Bedrock).

Users design campaign workflows, provide inputs, and the system computes outputs using templates, scripts, and AI prompts, ultimately producing ready-to-publish assets that can be deployed to company microsites.

Two Applications, Two Audiences

Architecture Overview

graph TB
    subgraph Users
        Admin["Admin Console
(full management)"]
        Customer["Customer App
(5-step wizard)"]
    end
    subgraph Backend["Campaign Manager Backend"]
        API["REST API
55+ controllers, 200+ endpoints"]
        Compute["Computation Engine
DAG executor, multi-threaded"]
        WS["WebSocket
real-time progress"]
        Script["Scripting Engine
JavaScript functions"]
    end
    subgraph AI["AI / LLM Providers"]
        OpenAI["OpenAI (GPT-4, DALL-E)"]
        Claude["Anthropic Claude"]
        Gemini["Google Gemini"]
        Perplexity["Perplexity"]
        Bedrock["AWS Bedrock"]
    end
    subgraph Infra["Infrastructure"]
        DB[(PostgreSQL)]
        S3["S3 File Storage"]
        CF["CloudFront CDN"]
        R53["Route53 DNS"]
        Agents["External AI Agents
(A2A proxy)"]
    end
    Admin -->|REST + WebSocket| API
    Customer -->|REST + WebSocket| API
    API --> Compute
    Compute --> AI
    Compute --> Script
    API --> WS
    API --> DB
    API --> S3
    S3 --> CF
    CF --> R53
    API -->|/a2a proxy| Agents

2. How a Campaign Is Built

A campaign in Campaign Manager is not a flat document - it is a structured computation pipeline. Understanding the hierarchy is key to understanding why the system works the way it does.

What Is a Campaign?

A campaign is a project container that holds everything needed to produce marketing deliverables: strategy inputs, AI-generated content, formatted documents, and publishable assets. The system structures this work into a hierarchy so that different pieces can be worked on independently, computed selectively, and exported or imported at any level.

Why Phases Exist

Think of phases as chapters in a book. Each phase groups related work into a logical stage of the campaign process. For example, a campaign might have three phases: "Research", "Content Creation", and "Review". Phases let you:

• Organize work into meaningful stages that reflect the real-world campaign process
• Compute an entire phase at once without touching other phases
• Export or import a single phase independently
• Assign different teams to different phases

Why Steps Exist

Think of steps as pages in a chapter. Each step is an individual unit of work within a phase. A step holds the actual data (variables) and can produce a document. Steps allow you to:

• Break work into manageable pieces that can be computed independently
• Attach a document template to a step so it renders a formatted deliverable
• Clone, move, or reorder steps within a phase
• Control which steps are visible to different users

Why Variables (CC Items) Exist

Each step has variables (called CC Items - Computation Context Items) that hold values. Some variables are entered manually by users, some are computed by AI prompts, and some are calculated by JavaScript functions. Variables can depend on each other, forming a computation graph. This is what makes the system powerful: you define inputs and the system produces outputs by walking the dependency chain automatically.

Variable types include:

• String / JSON / XML - static values entered by users or other systems
• Prompt - text generated by an AI model from a prompt template
• JSON Prompt - structured JSON output from an AI model with schema validation
• Image Prompt - images generated by AI (DALL-E)
• Session Prompt - multi-turn AI conversations with memory
• Function - a JavaScript function that computes a value from other variables
• Asset - a deployable file rendered from a document template

The Campaign Hierarchy

flowchart TD
    Campaign["Campaign
'Summer Product Launch'"]
    Campaign --> P1["Phase 1
'Research'"]
    Campaign --> P2["Phase 2
'Content Creation'"]
    Campaign --> P3["Phase 3
'Review & Publish'"]

    P1 --> S1["Step: Market Analysis"]
    P1 --> S2["Step: Competitor Review"]

    P2 --> S3["Step: Blog Posts"]
    P2 --> S4["Step: Social Media"]
    P2 --> S5["Step: Landing Page"]

    P3 --> S6["Step: Final Review"]
    P3 --> S7["Step: Asset Export"]

    S3 --> V1["Var: audience_profile
(AI prompt)"]
    S3 --> V2["Var: blog_headline
(AI prompt, depends on V1)"]
    S3 --> V3["Var: blog_body
(AI prompt, depends on V1+V2)"]
    S3 --> V4["Var: word_count
(function)"]
    S3 --> V5["Var: blog_pdf
(asset - renders document)"]

    style Campaign fill:#EEEEFD,stroke:#623CEA
    style P1 fill:#F4FBFF,stroke:#22B5FF
    style P2 fill:#F4FBFF,stroke:#22B5FF
    style P3 fill:#F4FBFF,stroke:#22B5FF

The full hierarchy is: Campaign -> Phase -> Step -> Variable -> (produces) Asset

Why This Hierarchy Matters

Campaign Lifecycle: 5 Phases

Every campaign goes through the same five phases, whether in the Admin Console or Customer App:

flowchart LR
    Create["1. CREATE
Clone from template
or start from scratch"] --> Configure["2. CONFIGURE
Set env vars, phases,
steps, variables"]
    Configure --> Compute["3. COMPUTE
Execute the DAG,
AI generates content"]
    Compute --> Iterate["4. ITERATE
Review, override,
re-compute"]
    Iterate --> Compute
    Iterate --> Publish["5. PUBLISH
Deploy to microsite,
export assets"]
    Configure --> Iterate

3. Templates & Blueprints

Campaign Types

Every campaign in the system has one of three types:

The Template Concept: Design Once, Start Many

The core idea behind templates is simple: a campaign designer builds a campaign structure once (phases, steps, variables, prompts, functions, document templates), publishes it as a template, and then any number of users can start new campaigns from it. Each new campaign gets its own independent copy of everything.

stateDiagram-v2
    [*] --> DraftTemplate : create as template
    [*] --> Campaign : create or start from template
    DraftTemplate --> PublishedTemplate : publish template
    PublishedTemplate --> DraftTemplate : unpublish
    PublishedTemplate --> Campaign : "Start Campaign" (clone + activate)
    Campaign --> Campaign : compute, edit, manage
    Campaign --> Archived : archive
    Archived --> Campaign : unarchive

    note right of PublishedTemplate
        Publishing resets all env items
        and computation items
    end note

    note right of Campaign
        "Start Campaign" deep-clones
        the entire template structure
    end note

"Start Campaign" = Deep Clone

When a user starts a campaign from a published template, the system creates a complete deep clone: all phases, steps, variables, environment items, i18n labels, and assets are copied. The new campaign gets its own independent copy of everything. What gets copied:

• All phases and steps (structure and configuration)
• All CC Items (variables) with their types, dependencies, and settings
• All environment variables (prompt templates, functions, JS libraries)
• All i18n labels (translations)
• All assets (file references)
• The MCT reference is saved as a read-only link back to the source template

Template -> Campaign Relationship

flowchart TD
    Template["Published Template
(MCT)"] -->|"Start Campaign
(deep clone)"| C1["Campaign A"]
    Template -->|"Start Campaign"| C2["Campaign B"]
    Template -->|"Start Campaign"| C3["Campaign C"]

    Template -->|"Update template"| Template
    Template -.->|"NO auto-update"| C1
    Template -.->|"NO auto-update"| C2
    Template -.->|"NO auto-update"| C3

    C1 -->|"mctId link
(read-only reference)"| Template

    style Template fill:#EEEEFD,stroke:#623CEA
    style C1 fill:#F4FBFF,stroke:#22B5FF
    style C2 fill:#F4FBFF,stroke:#22B5FF
    style C3 fill:#F4FBFF,stroke:#22B5FF

• The mctId field on a campaign is a read-only reference to its source template. It is for tracking lineage only.
• To propagate template changes to a live campaign, you must re-clone or migrate.
• The migration feature can selectively copy data from a source campaign to a target using a field mapping file.

MCT (Market Campaign Template) - Git Integration

MCT is the system's approach to reusable campaign blueprints with version control. The workflow:

1. A campaign designer builds a campaign structure (phases, steps, variables, prompts)
2. They publish it as a Published Template - this is the MCT
3. Users "Start" new campaigns from this MCT - each gets an independent deep clone
4. The MCT can be versioned via Git integration - push/pull to a repository
5. When the MCT is updated, existing campaigns are NOT affected (one-way clone)
6. To propagate changes, use the Migration feature with field mapping

Git Push / Pull / Branch

flowchart LR
    MCT["Published Template
(MCT in DB)"] -->|"Git Push"| Repo["Git Repository
(directory structure)"]
    Repo -->|"Git Pull"| MCT
    MCT -->|"Start Campaign"| Live["Live Campaign
(independent clone)"]

    Repo -->|"Branch"| V2["New version branch"]
    V2 -->|"Merge + Pull"| MCT

Git stores the MCT as a directory tree: /phase_name/step_name/ with JSON files for each entity. On pull, the system does smart merging: detects renames, creates new items, updates existing ones.

• Push to Git - exports campaign structure as directory tree with JSON files
• Pull from Git - imports and smart-merges: detects renamed phases by checking both name and sequence, creates new items, updates existing ones
• New Branch - creates a Git branch for the campaign template

Migration: Propagating Template Updates to Live Campaigns

Since template changes do not auto-propagate, the Migration feature provides a controlled way to update existing campaigns:

1. Analyze - the system compares source MCT with target campaign, matches by name, reports unmatched items
2. Create mapping - a tab-delimited mapping file defines which source field maps to which target
3. Choose what to copy: state, result, overrides, patches (each independently)
4. Validate - preview mode shows what would change without persisting
5. Execute - data transferred according to mapping

Variables tagged with the migration_carryover class keep their target value instead of being overwritten - useful for per-campaign customizations.

Template Matching via Classes

Document templates and steps use a class tagging system for matching. A document template is available for a step only if its classes overlap with the step's classes (or it falls back to default). This allows different steps to automatically use different document templates based on their tags.

Document Template Rendering

Document templates are the mechanism that turns raw computed data into formatted deliverables (HTML pages, PDF documents). The system supports three rendering engines:

How rendering works

flowchart TD
    Trigger["Rendering triggered
(computation or preview)"] --> Load["Load template from DB"]
    Load --> Context["Build rendering context:
computed values, i18n, campaign metadata"]
    Context --> Engine{"Which engine?"}
    Engine -->|XSL| XSLT["XSLT transformation"]
    Engine -->|FTL| FM["FreeMarker processing"]
    Engine -->|STATIC| Static["Placeholder replacement"]
    XSLT --> Media{"Output format?"}
    Media -->|HTML| HTML["HTML output"]
    Media -->|PDF| FOP["Apache FOP -> PDF"]
    FM --> HTML
    Static --> HTML
    HTML --> Store["Store as asset"]
    FOP --> Store

Two rendering paths

The system has two fundamentally different ways to build the rendering context:

HTML import and Figma conversion

Designers can upload HTML designs (including Figma exports) as ZIP packages. The system automatically:

1. Extracts HTML and assets (images, CSS, fonts) from the ZIP
2. Rewrites resource paths to cloud storage URIs
3. Converts the HTML to an XSLT stylesheet (making it data-driven)
4. Extracts referenced variable keys for template matching

This means designers can work in their preferred tools and the system converts their output into reusable, data-driven templates.

4. Customer App - The 5-Step Wizard

The Customer App provides a guided experience for creating campaigns through 5 sequential steps:

flowchart TD
    Home["Home Page
(campaign cards)"] --> New["Step 1: Fundamentals"]
    New --> S2["Step 2: Target Audience"]
    S2 --> S3["Step 3: Content Strategy"]
    S3 --> S4["Step 4: Content Execution"]
    S4 --> S5["Step 5: Content Assets"]
    S5 --> Activate["Activate Campaign
(triggers heavy AI computation)"]
    Activate --> WS["Real-time WebSocket updates
(progress bar)"]
    WS --> Generated["View Campaign
(Generated state)"]
    Generated --> Edit45["Edit Steps 4-5
(field handlers for incremental AI updates)"]
    Generated --> Assets["View External/Internal Assets"]
    Generated --> Docs["View Campaign Foundation"]

The 5-Step Flow

Field Handlers (Incremental AI Updates)

After a campaign is generated (state = "Generated"), users can edit fields in Steps 4-5. When they change a field and click "Apply", a field handler fires:

1. The updated field value is sent to the backend
2. The backend identifies which downstream variables are affected
3. Only those affected variables are recomputed (not the whole campaign)
4. The step data auto-refreshes when computation completes

AI Assist

The Customer App includes an embedded AI chat feature called "AI Assist". When available on a step, users can open a chat panel, converse with the AI about their campaign content, and then push approved AI suggestions directly into campaign variables. AI Assist requires a chat-enabled AI model and step-level aiAssistParams configuration.

Dynamic Form System

The Customer App does NOT have hardcoded forms. Every form field comes from the backend as a schema:

1. Backend defines each step's fields: type, validation, dependencies, handler
2. Frontend's FormEngine renders them dynamically
3. Each field can have an applyHandler that triggers backend computation when the user clicks "Apply"
4. Field dependencies are declared: if field A changes, dependent field B is cleared and repopulated

This means the entire Customer App workflow can be changed by modifying backend templates without touching frontend code.

Application State Machine

applicationState transitions:
  "1 / 5"  ->  "2 / 5"  ->  "3 / 5"  ->  "4 / 5"  ->  "5 / 5"  ->  "Generated"
      |           |           |           |           |              |
   (Step 1)   (Step 2)   (Step 3)   (Step 4)   (Step 5 +      (Read-only.
   Next btn    Next btn    Next btn    Next btn   Activate)    Steps 4-5 editable
                                                              via field handlers)

After "Generated", steps 1-3 become read-only. Steps 4-5 remain editable with field handlers that trigger incremental recomputation (not full campaign recomputation).

External vs Internal Assets

GTM Foundation vs Campaign Foundation

5. AI / LLM Features

Full Technical Detail

5.1 Supported Providers

5.2 Model Configuration

Priority chain: Variable-specific model -> Campaign default model -> System default model.

5.3 Prompt Types

Text Prompts

A prompt template stored as an environment variable with placeholders:

Write a marketing headline for {product_name} targeting {audience}.
The tone should be {tone}. Maximum {max_words} words.

Placeholders are replaced with values from other variables. The completed prompt is sent to the AI model.

JSON Structured Output

Like text prompts but the AI must return valid JSON matching a defined schema. The system validates using JSON Schema draft-07. If invalid, retries with error feedback included.

Image Generation

DALL-E and other image models. Style options configurable. The generated image URL becomes the variable's value.

Session Prompts (Multi-turn Conversation)

Creates a persistent session with conversation history. Each message includes full history - token usage grows with each turn. Supports custom "bot instructions" (system prompt) per session.

5.4 Chat Interface

sequenceDiagram
    participant User
    participant Chat as Chat Interface
    participant System as Campaign Manager
    participant AI as AI Provider

    User->>Chat: Opens chat for a step
    Chat->>System: Load history and settings
    User->>Chat: Types message
    Chat->>System: Send message (async)
    System->>System: Build context (prompt + schema + history)
    System->>AI: Send formatted prompt
    AI-->>System: AI response
    alt JSON response invalid
        System->>AI: Retry with error feedback
        AI-->>System: Corrected response
    end
    System-->>Chat: Display response
    User->>Chat: Likes a suggested value
    Chat->>System: Save as Override (APPLIED)
    System->>System: Override CC Item value

Two modes: Document Chat (auto-populated with template keys) and Step Keys Chat (manual key selection).

Chat overrides are the bridge between conversation and campaign data: you chat with AI, refine output, then push approved values into campaign variables (status: Ready -> Applied or Canceled).

5.5 Rate Limiting & Key Pool

• Token bucket rate limiter per model (RPM). Calls block-wait for tokens.
• Key rotation - multiple API keys per provider, auto-failover when a key hits quota.
• Auto-recovery - disabled keys checked every 60 seconds and re-enabled. Passivation timeout: 15s for OpenAI.

5.6 Monitoring Metrics

5.7 AI in Scripts

JavaScript functions can call AI models programmatically:

• llm.request(campaignId, promptKey, arg1, arg2, ...) - single AI call
• llm.requestWithRetry(campaignId, promptKey, retries, arg1, ...) - with custom retry
• llm.request(campaignId, promptKey, jsonSchemaKey, arg1, ...) - structured JSON output

Argument count is validated against prompt template placeholders.

5.8 Analysis Agents (A2A Integration)

Campaign Manager integrates with an external Analysis Agents service - a set of specialized AI agents that analyze campaign data and provide insights. The agents run as a separate Python/FastAPI service and communicate via the A2A (Agent-to-Agent) protocol - Google's JSON-RPC 2.0 based standard.

Available Agents

How it works

• Campaign Manager proxies requests to agents via /a2a/{agent}/rpc (JSON-RPC) and /a2a/{agent}/stream (Server-Sent Events)
• Agents run in isolated AWS ECS containers and have read-only access to the CM database via VPC Peering
• Authentication uses the same cookie-based mechanism as the Asset Viewer - shared session on .velocityengine.co domain
• Users access the Agent Dev Kit UI via a button in the CM menu, routed through auth-redirect for seamless SSO

6. Microsites & Publishing

Business Purpose

A microsite is a company-branded website for publishing campaign deliverables. Think of it as each company's content distribution hub:

• URL: https://acme.velocityengine.co/ (custom subdomain per company)
• One company = one microsite (1:1)
• Multiple campaigns publish to the same microsite under different URL paths
• Backed by S3 (storage) + CloudFront (CDN, HTTPS) + Route53 (DNS)

URL Construction

https://{subdomain}.velocityengine.co/{siteContext}/{campaign.folder}/{phase.folder}/{step.folder}/{asset.file}

Example:
https://acme.velocityengine.co/content/c42/launch-phase/hero-content/assets/brochure.pdf

Each level (campaign, phase, step) has its own configurable folder name. Folders support placeholders like ${campaign.id}, ${phase.nameUrl}.

Multiple Campaigns, One Microsite

flowchart TD
    MS["acme.velocityengine.co
(company microsite)"]
    MS --> C1["/c42/
Campaign: Summer Sale"]
    MS --> C2["/c99/
Campaign: Product Launch"]
    MS --> C3["/c150/
Campaign: Brand Refresh"]

    C1 --> P1["/c42/research/..."]
    C1 --> P2["/c42/content/..."]
    C2 --> P3["/c99/phase1/..."]

    style MS fill:#EEEEFD,stroke:#623CEA

Path isolation ensures campaigns cannot overwrite each other's files. Each campaign has a unique folder (typically using campaign ID).

Microsite Infrastructure

sequenceDiagram
    participant Admin as Admin
    participant CM as Campaign Manager
    participant S3pub as Public S3 Storage
    participant S3ms as Microsite S3 Bucket
    participant CF as CloudFront CDN
    participant DNS as Route53 DNS

    Note over Admin,DNS: One-time microsite setup
    Admin->>CM: Configure microsite (subdomain, HTTPS)
    CM->>S3ms: Create S3 bucket (subdomain.velocityengine.io)
    CM->>DNS: Create DNS record
    opt HTTPS enabled
        CM->>CF: Create CloudFront distribution + SSL cert
        CM->>DNS: Create CNAME to CloudFront
    end

    Note over Admin,DNS: Per-asset deployment
    Admin->>CM: Deploy asset to microsite
    CM->>S3pub: Read asset file from public storage
    CM->>S3ms: Copy file to microsite bucket
    CM-->>Admin: URL: https://subdomain.velocityengine.io/path/asset.pdf

• S3 bucket per company: {subdomain}.velocityengine.io
• Static website hosting enabled on the bucket
• Optional HTTPS via CloudFront distribution with wildcard SSL certificate (*.velocityengine.io)
• Route53 DNS records for subdomain resolution
• SFTP access - microsite users can upload files directly via SFTP (AWS Transfer Family)

SFTP Direct Access

For power users and external tools, microsite users can upload files directly via SFTP:

• Each user gets isolated credentials (username prefixed with subdomain)
• IAM roles restrict access to that company's microsite bucket only
• Password management: generate, reset, delete
• Use case: designers uploading assets from external tools, CI/CD pipelines

Asset Approval Chain

stateDiagram-v2
    [*] --> Created : generated or uploaded
    Created --> ReadyForReview : submit for review
    ReadyForReview --> AssetApproved : reviewer approves content
    ReadyForReview --> NotPublished : rejected
    AssetApproved --> PublicationApproved : publisher approves
    AssetApproved --> NotPublished : publication denied
    PublicationApproved --> Published : deployed to microsite
    Published --> NotPublished : unpublished
    Created --> Error : generation failed

    note right of Published
        File copied from campaign storage
        to microsite S3 bucket.
        Public URL generated.
    end note

Auto-Publishing Stages

CloudFront & Caching

• HTTPS microsites use CloudFront with a shared wildcard SSL certificate (*.velocityengine.co)
• Cache invalidation happens automatically when the origin path changes
• After asset deployment, changes may take a few minutes to propagate globally due to CDN caching
• Manual invalidation can be requested for urgent updates

7. Key Concepts Glossary