# Punkit Creative — Competitor Intelligence Monitor
## Developer Handover & Implementation Guide

This document outlines the architecture, data flow, and deployment steps for the **Competitor Intelligence Monitor**. It is designed to help the development team take this fully functional automation prototype and deploy it for production use.

---

## 1. System Architecture Overview

The system operates on a decoupled, two-tier architecture:

*   **Frontend (The Dashboard):** A single-page application (SPA) built with Vanilla HTML/CSS/JS (`competitor_intel_dashboard.html`). It provides a premium, dark-mode UI for triggering scans and reviewing intelligence reports.
*   **Backend / AI Engine (n8n):** An n8n automation workflow (`competitor_monitor_workflow.json`) that acts as the backend API. It orchestrates website scraping via Jina AI, Google News RSS fetching, and LLM analysis via Groq.

### The Data Flow
1. User enters two competitor URLs into the "Run Scan" panel on the frontend UI.
2. User clicks "Analyze Competitors", which fires an asynchronous `POST` request to the n8n webhook URL.
3. n8n extracts the URLs, triggers Jina AI to scrape both competitor websites, and fetches the latest Google News RSS feeds for their domains.
4. n8n injects the scraped content and news headlines into a prompt and queries the **Groq API** (`llama-3.3-70b-versatile`).
5. Groq returns a structured JSON object containing a summary, sales battle card, strategic advice, and a calculated threat level.
6. n8n responds to the webhook with this JSON object.
7. The UI receives the JSON, updates the state, and dynamically renders a new Intelligence Report digest at the top of the dashboard.
8. (Optional branch in n8n) If the threat level is "High", n8n simultaneously triggers a Gmail node to send a high-priority HTML alert email.

---

## 2. Webhook API Schema

When the frontend communicates with the n8n backend, it uses the following schema.

### Request (Frontend → n8n)
```json
POST /webhook/competitor-intel
Content-Type: application/json

{
  "comp1": "https://competitor-one.co.za",
  "comp2": "https://competitor-two.co.za"
}
```

### Response (n8n → Frontend)
```json
{
  "summary": "<ul><li><strong>Competitor 1:</strong> Launched new pricing tier...</li></ul>",
  "battleCard": "<p>When a prospect mentions their new pricing, use this counter-script...</p>",
  "advice": "<p><strong>Campaign 1:</strong> Launch an intercept campaign...</p>",
  "threatLevel": "High" // (Can be "Low", "Medium", or "High")
}
```
*Note: The returned strings contain valid HTML (paragraphs, lists, strong tags) intended for direct rendering in the dashboard.*

---

## 3. Implementation Steps

### Phase 1: Deploying the n8n Backend
1. Import the `competitor_monitor_workflow.json` file into your n8n instance.
2. **Groq API Key:** Open the "Groq AI - Analyze & Generate" node (HTTP Request) and replace `YOUR_GROQ_API_KEY_HERE` in the Authorization header with a valid Groq API key.
3. **Gmail Credentials:** If you intend to use the high-threat email alert feature, open the "Gmail - Send Threat Alert" node and authenticate your Google Workspace account.
4. **Activate Workflow:** Toggle the workflow to "Active" in the top right corner of the n8n UI.
5. Double-click the "Webhook - Dashboard Trigger" node, navigate to "Webhook URLs", and copy the **Production URL**.

### Phase 2: Deploying the Frontend Dashboard
1. The `competitor_intel_dashboard.html` is a standalone file that requires no build step. It can be hosted on any static hosting service (Vercel, Netlify, GitHub Pages, or an AWS S3 bucket).
2. The user will input the n8n Production Webhook URL directly into the dashboard UI when running a scan. The UI uses `localStorage` to save this URL for future sessions.

### Phase 3: Future Database & Persistence (Production Roadmap)
Currently, generated reports are not persisted in a database (they are rendered dynamically on the fly). For a full production rollout:
*   **Action:** Spin up a backend database (e.g., Supabase, Firebase, or MongoDB).
*   **Action:** Update the UI to `fetch()` historical digest data on page load.
*   **Action:** Modify the n8n workflow to `POST` the generated content directly to your database *before* responding to the webhook.

---

## 4. Required Dependencies / API Keys
*   **n8n instance** (Self-hosted or Cloud)
*   **Groq API Key** (For LLaMA 3.3 access)
*   **Jina AI Reader API** (Free tier currently used, no key required, but a key may be added in the future for higher rate limits).
*   **Gmail / Google Workspace** (For email alerts).