📰 GUIDO: Explainable Clickbait Detection System

An end-to-end explainable machine learning platform that detects clickbait headlines in real time, provides linguistic transparency, and seamlessly integrates with a Chrome browser extension and web UI.

---

📖 Detailed Project Overview

GUIDO (Explainable Clickbait Detection) addresses the growing challenge of misleading, exaggerated, and sensationalized headlines across digital media[cite: 5]. Unlike traditional black-box classification models, GUIDO provides explainable AI predictions by analyzing lexical patterns, sentiment polarization, punctuation frequency, and syntactic clickbait structures[cite: 5].

The system comprises a trained NLP machine learning classifier, a Flask API backend, a web-based dashboard, and an active Manifest V3 Chrome Extension that highlights clickbait links directly as you browse the web[cite: 5].

---

✨ Features Section

• 🧠 Explainable NLP Model: Evaluates text features (sensation scores, punctuation density, emotional intensity, and structural patterns) to explain why a headline is classified as clickbait[cite: 5].
• 🔌 REST API Backend: Flask server powering high-speed batch and single-headline inference endpoints (backend/app.py)[cite: 5].
• 🧩 Live Chrome Extension: Automatically scans webpages, highlights sensational headlines, and displays real-time analytics in an interactive sidepanel/popup (extension/)[cite: 5].
• 📊 Visual Analytics Dashboard: Includes built-in Chart.js analytics for tracking browsing habits, clickbait frequency, and historical detection scores (extension/analytics.html)[cite: 5].
• 📑 Automated SDD & PDF Report Generator: Integrated tools to build system design documentation and technical evaluation reports (generate_report.py, create_algorithmic_sdd.py)[cite: 5].

---

🏗️ GitHub-Compatible Mermaid Architecture Diagram

graph TD
    subgraph Clients [Client Layer]
        WebUI[Web Frontend - index.html]
        ChromeExt[Chrome Extension - Manifest V3]
    end

    subgraph ChromeExtFiles [Extension Subsystem]
        Popup[popup.html / popup.js]
        ContentScript[content.js]
        Background[background.js]
        Analytics[analytics.html / chart.js]
    end

    subgraph BackendApp [Flask Backend Application]
        API[Flask REST Server - backend/app.py]
        Predictor[NLP Feature Extractor & Predictor]
    end

    subgraph MLPipeline [Model & Data Processing]
        Dataset[(clickbait_data.csv)]
        Trainer[Model Trainer - model/train.py]
        TrainedModel[Serialized NLP Model]
    end

    ChromeExt --> Popup
    ChromeExt --> ContentScript
    ChromeExt --> Background
    ChromeExt --> Analytics

    WebUI <-->|HTTP POST /predict| API
    ContentScript <-->|HTTP POST /predict| API
    
    API --> Predictor
    Predictor --> TrainedModel
    Dataset --> Trainer
    Trainer --> TrainedModel

Loading

---

🔄 Clickbait Classification & Explainability Pipeline

flowchart LR
    A[Raw Headline Text] --> B[Preprocessing & Tokenization]
    B --> C[Linguistic Feature Extraction]
    
    subgraph Feature Engineering
        C --> C1[Sensational Word Density]
        C --> C2[Punctuation & Capitalization Ratio]
        C --> C3[Sentiment & Emotional Polarization]
    end
    
    C1 --> D[Vectorization]
    C2 --> D
    C3 --> D
    
    D --> E[ML Classifier Model]
    E --> F[Probability Score]
    E --> G[Linguistic Feature Breakdown]
    F --> H[JSON Output: Score + Explanation]
    G --> H

Loading

---

📸 Chrome Extension Real-Time Detection Flow

sequenceDiagram
    autonumber
    actor User as Web Browser User
    participant Page as Webpage DOM
    participant CS as Extension Content Script
    participant API as Flask Backend API
    participant Model as NLP Inference Engine

    User->>Page: Navigate to News Website
    Page->>CS: Trigger DOM Load Event
    CS->>CS: Extract Article Headlines from DOM
    CS->>API: POST /predict (Payload: Headlines List)
    API->>Model: Run Feature Extraction & Classification
    Model-->>API: Return Clickbait Probability & Explanation
    API-->>CS: JSON Response
    CS->>Page: Highlight Clickbait Links & Attach Tooltips
    CS->>User: Display Clickbait Summary in Popup / Sidepanel

Loading

---

📊 Feature Matrix

Feature	Web Interface	Chrome Extension	REST API
Single Headline Analysis	✅	✅	✅
DOM Webpage Auto-Highlighting	❌	✅	❌
Linguistic Explanation Breakdown	✅	✅	✅
Historical Browsing Analytics	❌	✅	❌
Batch Inference Engine	❌	✅	✅

---

⚡ Tech Stack

• Language: Python 3.11+

• Machine Learning & NLP: Scikit-Learn, NLTK, NumPy, Pandas

• Backend Framework: Flask

• Browser Extension: JavaScript (ES6+), Chrome Manifest V3

• Visualization & Reporting: Chart.js, FPDF, ReportLab

---

📂 Complete Project Structure

Explainable-Clickbait-Detection/
├── backend/
│   ├── app.py                      # Flask API endpoints for inference[cite: 5]
│   └── __init__.py
├── extension/                       # Manifest V3 Chrome Extension[cite: 5]
│   ├── analytics.html / .js        # Analytics panel with Chart.js[cite: 5]
│   ├── background.js               # Service worker background handler[cite: 5]
│   ├── chart.js                    # Charting library bundle[cite: 5]
│   ├── content.js                  # DOM scanning & page overlay script[cite: 5]
│   ├── manifest.json               # Extension manifest configuration[cite: 5]
│   ├── popup.html / .js            # Popup user interface[cite: 5]
│   └── style.css                   # Extension styling[cite: 5]
├── frontend/                        # Web Dashboard UI[cite: 5]
│   ├── index.html                  # Landing & analysis interface[cite: 5]
│   ├── script.js                   # Web app logic[cite: 5]
│   └── style.css                   # Web app stylesheet[cite: 5]
├── model/                           # Model Training & Pipeline[cite: 5]
│   ├── train.py                    # NLP feature extraction & training script[cite: 5]
│   └── __init__.py
├── clickbait_data.csv               # Dataset used for model training[cite: 5]
├── create_algorithmic_sdd.py        # System Design Document generator script[cite: 5]
├── generate_report.py               # PDF summary report generator[cite: 5]
├── requirements.txt                 # Python package dependencies[cite: 5]
└── test_model.py                    # Unit testing suite for NLP pipeline[cite: 5]

---

🚀 Installation & Setup

Local Backend Setup

1. Clone the repository:

git clone [https://github.com/your-username/Explainable-Clickbait-Detection.git](https://github.com/your-username/Explainable-Clickbait-Detection.git)
cd Explainable-Clickbait-Detection

2. Set up a Python virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Train the Model (Optional if pre-trained model exists):

python model/train.py

5. Start the Flask Backend API:

python backend/app.py

The backend server will run at http://localhost:5000.

---

Chrome Extension Installation

1. Open Google Chrome and go to chrome://extensions/.
2. Toggle Developer mode in the top-right corner.
3. Click Load unpacked.
4. Select the extension/ directory in this repository.

---

⚙️ Configuration

Parameter	Default Value	Description
API_PORT	5000	Port for the Flask backend API
CLICKBAIT_THRESHOLD	0.65	Probability threshold above which a headline is flagged as clickbait
MAX_HEADLINES_PER_BATCH	50	Maximum headlines scanned per DOM request

---

🔌 API Reference

Analyze Headline Endpoint

• URL: /predict
• Method: POST
• Payload:

{
  "headline": "You Won't Believe What This Celebrity Did Next!"
}

• Response:

{
  "is_clickbait": true,
  "confidence_score": 0.92,
  "explanations": [
    "High density of sensational keywords ('Won't Believe')",
    "Exaggerated emotional polarization",
    "Punctuation intensity flag"
  ]
}

---

🛣️ Future Improvements

• Transformer Model Integration: Upgrade to fine-tuned RoBERTa / DeBERTa embeddings for improved context-aware detection.
• Multi-Language Support: Extend clickbait classification across Spanish, German, and Hindi headlines.
• Browser Cross-Compatibility: Port extension to Mozilla Firefox and Microsoft Edge.