<aside>

🚀 AI Marketing Performance Optimizer

Turn your marketing data into actionable strategic insights using Generative AI.

This Full-Stack application ingests campaign performance data (via CSV or Real-Time Webhooks), calculates key metrics like ROAS and CPA, and uses an AI Agent (Google Gemini 1.5 Flash) to generate professional audit reports and budget allocation recommendations.

🌟 Key Features

• 📊 Interactive Dashboard: Visualizes spending, revenue, and efficiency trends using Streamlit and Plotly.
• 🤖 AI Strategic Consultant: An embedded AI agent analyzes your data patterns to identify budget waste and scaling opportunities.
• ⚡ Real-Time Ingestion: A dedicated Webhook endpoint designed to receive leads directly from automation tools like n8n, Make, or Zapier.
• 🧮 Advanced Analytics: Automated calculation of complex metrics (ROAS, Conversion Rate, CPA) using a vectorized Pandas engine.
• 🛡️ Data Validation: Robust data integrity checks using Pydantic schemas.

🛠️ Tech Stack

• Backend: FastAPI (Python 3.10+)
• Frontend: Streamlit
• AI Model: Google Gemini 1.5 Flash (via google-generativeai)
• Data Processing: Pandas, NumPy
• Validation: Pydantic, Email-Validator
• Containerization: Docker & DevContainers

🚀 Quick Start (Local Development)

1. Clone the Repository

git clone <https://github.com/AlvLeoAI/marketing-optimizer.git>
cd marketing-optimizer

2. Environment Setup

Create a virtual environment and install dependencies:

# Create venv
python -m venv venv

# Activate venv (Windows)
.\\venv\\Scripts\\activate

# Activate venv (Mac/Linux)
source venv/bin/activate

# Install packages
pip install -r requirements.txt

3. Configuration (.env)

Create a .env file in the root directory and add your API Key:

GEMINI_API_KEY="your_google_ai_studio_key"ENV="development"

4. Run the Application

You need to run both the Backend and Frontend terminals.

Terminal 1: Backend API

uvicorn backend.main:app --reload
# Server starts at <http://127.0.0.1:8000>

Terminal 2: Frontend Dashboard

streamlit run frontend/app.py
# App opens at <http://localhost:8501>

📖 Usage Guide

A. Batch Analysis (CSV)

1. Go to the "Upload Data" page.
2. Upload a CSV file containing: date, channel, spend, revenue, clicks, conversions.
3. Click "Process Data with AI".
4. Navigate to "Dashboard" to see the charts.
5. Navigate to "AI Insights" to get the strategic report.

B. Real-Time Webhook (n8n / Make)

Send a POST request to ingest leads automatically:

Endpoint: POST /integrations/webhook/ingest-data

Payload Example:

{
  "source": "Facebook Ads",
  "lead_email": "new.client@example.com",
  "metadata": {
    "campaign_name": "Q3_Growth",
    "is_vip": true
  }
}

Check the "Dashboard" → "Live Leads Feed" section to see them appear in real-time.

🧪 Testing

Run the automated test suite to ensure system stability:

# Run all tests
pytest

# Run only unit tests
pytest tests/unit

# Run frontend smoke tests
pytest frontend/tests

📂 Project Structure

marketing-optimizer/ ├── backend/ # FastAPI Logic │ ├── routers/ # API Endpoints (Analytics, AI, Integrations) │ ├── services/ # Business Logic (Math Engine, Gemini Client) │ └── models/ # Pydantic Schemas ├── frontend/ # Streamlit App │ ├── pages/ # Dashboard Pages │ ├── components/ # UI Widgets │ └── utils/ # API Clients ├── tests/ # Pytest Suite └── data/ # Sample Datasets

Deployment 🚀

The architecture follows a decoupled pattern:

• Backend (API): Deployed as a Serverless Container on Google Cloud Run.
• Frontend (UI): Deployed on Streamlit Cloud (or any static/app hosting).

🏗️ Part 1: Backend Deployment (Google Cloud Run)

We use Google Cloud Run because it scales automatically (scale-to-zero) and supports Docker containers natively.

Prerequisites

• Google Cloud Platform (GCP) Account.
• Google Cloud CLI installed (gcloud).
• Docker installed (optional, but recommended for local testing).

Steps

1. Initialize Google Cloud CLI

Login to your account and select your project:

gcloud auth login
gcloud config set project YOUR_PROJECT_ID

2. Enable Services

Ensure Cloud Run and Container Registry APIs are enabled:

gcloud services enable run.googleapis.com containerregistry.googleapis.com

3. Deploy to Cloud Run

Run the following command from the project root. This builds the Docker image and deploys it in one go.

gcloud run deploy ai-marketing-backend \\
  --source . \\
  --platform managed \\
  --region us-central1 \\
  --allow-unauthenticated

• -source .: Uses the Dockerfile in the current directory.
• -allow-unauthenticated: Makes the API public (necessary for the Frontend to access it).

4. Set Environment Variables

Once deployed, you need to configure your secrets (API Keys) in the Cloud Run dashboard or via CLI:

gcloud run services update ai-marketing-backend \\
  --set-env-vars GEMINI_API_KEY="your_actual_api_key"

5. Get the Backend URL

After successful deployment, Google will provide a URL (e.g., https://ai-marketing-backend-xyz.a.run.app). Copy this URL. You will need it for the Frontend.

🎨 Part 2: Frontend Deployment (Streamlit Cloud)

Streamlit Cloud is the easiest way to host the dashboard directly from your GitHub repository.

Steps

1. Push Code to GitHub

Ensure your project is in a public (or private) GitHub repository.

2. Connect to Streamlit Cloud

1. Go to share.streamlit.io.
2. Click "New App".
3. Select your repository, branch (main), and the main file path: frontend/app.py.

3. Configure Backend Connection

Before clicking "Deploy", go to the "Advanced Settings" → "Secrets" section (or wait until it deploys and go to Settings).

You need to tell the Frontend where the Backend lives. Add this to your Streamlit Secrets:

[general]
API_BASE_URL = "<https://ai-marketing-backend-xyz.a.run.app>"

(Replace the URL with the one you got from Google Cloud Run).

Note: You will need to update frontend/utils/api_client.py to read this secret instead of localhost if you haven't already.

4. Deploy!

Click "Deploy". Streamlit will install the dependencies from requirements.txt and launch the app.

</aside>

View GitHub Repository:

https://github.com/AlvLeoAI/marketing-optimizer