Marketing Copilot

An AI-powered marketing analytics web app that analyzes ad campaign performance and uses Gemini 2.5 Flash to generate ad copy, campaign strategies, performance reports, and creative briefs.

---

Stack

Layer	Technology
Frontend	Next.js 16, TypeScript, Tailwind CSS, Recharts, Axios
Backend	Python FastAPI, Uvicorn
AI	Google Gemini 2.5 Flash (google-generativeai)

---

Project Structure

market-agent/
├── backend/
│   ├── main.py                  # FastAPI app + CORS
│   ├── requirements.txt
│   ├── .env                     # GEMINI_API_KEY goes here
│   ├── data/
│   │   └── mock_data.py         # 7 campaigns, 30-day series, 21 ads, 4 audiences
│   ├── prompts/
│   │   └── templates.py         # Gemini prompt templates (structured JSON output)
│   ├── routers/
│   │   ├── campaigns.py         # GET /api/campaigns, GET /api/insights
│   │   └── generate.py          # POST /api/generate/* (4 endpoints)
│   └── services/
│       └── gemini_service.py    # Gemini SDK wrapper
└── frontend/
    ├── app/
    │   ├── page.tsx             # Dashboard
    │   ├── campaigns/page.tsx
    │   ├── studio/page.tsx
    │   └── reports/page.tsx
    ├── components/
    │   ├── layout/Sidebar.tsx
    │   ├── dashboard/           # MetricsCard, PerformanceChart, InsightsPanel
    │   ├── campaigns/           # CampaignTable, CampaignFilters
    │   ├── studio/              # GeneratorForm, GeneratedOutput, AdPreview
    │   └── reports/             # ReportCard, ReportViewer
    ├── lib/
    │   ├── api.ts               # Axios API client
    │   └── utils.ts             # formatCurrency, formatRoas, etc.
    └── types/index.ts           # Shared TypeScript types

---

Getting Started

Prerequisites

• Node.js 18+
• Python 3.10+
• A Google Gemini API key

1. Configure the API key

Open backend/.env and set your key:

GEMINI_API_KEY=your_gemini_api_key_here

2. Start the backend

cd backend
pip install -r requirements.txt
uvicorn main:app --reload

The API will be available at http://localhost:8000.

3. Start the frontend

cd frontend
npm install
npm run dev

The app will be available at http://localhost:3000.

---

API Endpoints

Method	Endpoint	Description
GET	/api/campaigns	List campaigns (filterable by type/status, sortable)
GET	/api/insights	Dashboard summary, top/bottom performers, daily trend
POST	/api/generate/ad-copy	Generate headline/description/CTA variations
POST	/api/generate/strategy	Generate recommendations + budget reallocation
POST	/api/generate/report	Generate sectioned performance report
POST	/api/generate/brief	Generate creative brief for designers

Example: Generate ad copy

curl -X POST http://localhost:8000/api/generate/ad-copy \
  -H "Content-Type: application/json" \
  -d '{"campaign_id": "c1", "tone": "urgent", "num_variations": 3}'

---

Pages

Route	Description
/	Dashboard — metrics, 30-day revenue/spend chart, top/bottom campaign cards
/campaigns	Sortable campaign table with type/status filters; expand rows to see ad variations
/studio	AI Studio with 4 tabs: Ad Copy, Strategy, Report, Creative Brief
/reports	Saved reports from AI Studio, with modal viewer and print support

---

Architecture

System Overview

graph TB
    subgraph Browser["🌐 Browser — localhost:3000"]
        direction TB
        subgraph Pages["Next.js 16 App Router"]
            P1["/ Dashboard"]
            P2["/campaigns"]
            P3["/studio"]
            P4["/reports"]
        end

        subgraph Components["Components"]
            direction LR
            C1["MetricsCard\nPerformanceChart\nInsightsPanel"]
            C2["CampaignTable\nCampaignFilters"]
            C3["GeneratorForm\nGeneratedOutput\nAdPreview"]
            C4["ReportCard\nReportViewer"]
        end

        subgraph ClientLib["lib/"]
            API["api.ts · Axios client"]
            Utils["utils.ts · formatters"]
        end

        LS[("localStorage\nmcp_reports")]
    end

    subgraph Backend["⚙️ FastAPI — localhost:8000"]
        direction TB
        Main["main.py · CORS · routing"]

        subgraph Routers["routers/"]
            R1["campaigns.py\nGET /api/campaigns\nGET /api/insights"]
            R2["generate.py\nPOST /api/generate/ad-copy\nPOST /api/generate/strategy\nPOST /api/generate/report\nPOST /api/generate/brief"]
        end

        subgraph Data["data/"]
            MD["mock_data.py\n7 campaigns · 30-day series\n21 ad variations · 4 audiences"]
        end

        subgraph Services["services/ · prompts/"]
            GS["gemini_service.py"]
            PT["templates.py"]
        end
    end

    subgraph Google["☁️ Google AI"]
        Gemini["Gemini 2.5 Flash"]
    end

    P1 --> C1
    P2 --> C2
    P3 --> C3
    P4 --> C4

    C1 & C2 & C3 --> API
    C3 -->|save| LS
    C4 -->|read| LS

    API -->|HTTP GET| R1
    API -->|HTTP POST| R2

    Main --> R1 & R2
    R1 --> MD
    R2 --> MD
    R2 --> PT --> GS
    GS -->|"generate_content()"| Gemini
    Gemini -->|"structured JSON"| GS

Loading

AI Generation Flow

sequenceDiagram
    actor User
    participant FE as Next.js Frontend
    participant BE as FastAPI Backend
    participant DB as mock_data.py
    participant PT as prompts/templates.py
    participant GM as Gemini 2.5 Flash

    User->>FE: Fill form → click Generate
    FE->>BE: POST /api/generate/ad-copy
    BE->>DB: Fetch campaign + ad variations
    DB-->>BE: campaign dict + ads[]
    BE->>PT: Build structured JSON prompt
    PT-->>BE: Prompt string
    BE->>GM: model.generate_content(prompt)
    GM-->>BE: Raw JSON response
    BE->>BE: Parse + strip markdown fences
    BE-->>FE: { variations: [...], insights: "..." }
    FE->>FE: Render AdPreview cards
    User->>FE: Click "Save to Reports"
    FE->>FE: localStorage.setItem(...)

Loading

---

Mock Data

The backend uses pre-defined mock data — no database required.

Campaigns:

Campaign	Type	Status	ROAS	Score
Summer Sale - Search	Search	active	10.1x	87
Brand Awareness Display	Display	active	3.2x	54
Retargeting - Social	Social	active	7.8x	79
Product Demo Video	Video	active	5.1x	68
Competitor Keywords	Search	paused	2.1x	31
Seasonal Email Blast	Social	active	6.4x	73
YouTube Pre-roll	Video	ended	4.3x	62

Plus 30 days of daily time series data, 3 ad variations per campaign, and 4 audience segments.