# Punkit Creative — Monthly Marketing Report Generator
## Developer Handover & Implementation Guide

This document outlines the architecture, data flow, and deployment steps for **Automation 3: Monthly Marketing Report Generator**. 

---

## 1. System Architecture Overview

*   **Frontend (The Dashboard):** A Vanilla HTML/CSS/JS single-page application (`marketing_report_dashboard.html`). It provides a premium, client-ready UI for viewing aggregated metrics and the AI executive summary.
*   **Backend / AI Engine (n8n):** An n8n automation workflow (`marketing_report_workflow.json`) that acts as the backend API. It aggregates data from Google Analytics 4, Meta Ads, and HubSpot, and sends it to the Groq API (LLaMA 3.3) for high-speed, cost-efficient analysis.

### The Data Flow
1. User clicks "Generate New Report" on the frontend UI.
2. The UI fires a `POST` request to the n8n webhook URL.
3. n8n triggers the workflow. *Note: In this handover version, we use a "Set" node to inject mock data (4,200 visitors, 12% lead increase, etc.). This allows you to preview the report dashboard immediately. **However, for production, it is strictly necessary to replace this Mock Data node with live authenticated nodes for GA4, HubSpot, and Meta Ads.***
4. n8n sends the aggregated JSON metrics to Groq.
5. Groq (LLaMA 3.3) acts as a Senior Marketing Analyst and returns a plain-English, HTML-formatted executive summary.
6. n8n responds to the webhook with the generated HTML and the raw metrics.
7. The UI updates the metric cards and injects the new AI summary into the page dynamically.

---

## 2. Webhook API Schema

### Request (Frontend → n8n)
```json
POST /webhook/marketing-report
Content-Type: application/json
```
*(No body is strictly required for this trigger, but the client ID/name could be passed here in the future).*

### Response (n8n → Frontend)
```json
{
  "report_html": "<p><strong>Overview:</strong> This month saw solid growth...</p>",
  "metrics": {
    "metrics_ga4_visitors": 4200,
    "metrics_hubspot_total_leads": 145,
    "metrics_meta_ad_spend": "R 4,500",
    "metrics_ga4_bounce_rate": "45%",
    "metrics_hubspot_leads_increase": "12%",
    "metrics_meta_top_content": "LinkedIn post about onboarding"
  }
}
```

---

## 3. Implementation Steps

### Phase 1: Deploying the n8n Backend
1. Import the `marketing_report_workflow.json` file into your n8n instance.
2. **Groq API Key:** Open the "Groq API - Generate Report" node (HTTP Request). You will need to create a new credential for `httpHeaderAuth` and input your Groq API Key (Header Name: `Authorization`, Value: `Bearer YOUR_API_KEY`).
3. **Connect Live Accounts (CRITICAL FOR PRODUCTION):** The provided workflow uses a "Mock Data" node so you can preview the UI. For production, you **must** authenticate your agency's actual accounts.
   - Delete the "Mock Data" node.
   - Add a **Google Analytics 4** node (authenticate via OAuth2) to pull `activeUsers` and `bounceRate`.
   - Add a **HubSpot** node (authenticate via Private App Token or OAuth2) to pull `contacts` count.
   - Add a **Meta/Facebook Ads** node (authenticate via OAuth2) to pull `spend`.
   - Route all these values into a "Set" node that matches the schema the AI prompt expects.
4. Activate the workflow and copy the Production Webhook URL.

### Phase 2: Deploying the Frontend Dashboard
1. Host `marketing_report_dashboard.html` on your preferred static hosting.
2. In the UI, click "n8n Integration" in the bottom left corner and paste your Production Webhook URL. The UI will save this to `localStorage`.

---

## 4. Required Dependencies
*   **n8n instance**
*   **Groq API Key** (for high-speed LLaMA 3.3 access).
*   **Live credentials for GA4, HubSpot, and Meta Ads** (Mandatory for production to replace the mock data node).