SafeComments AI 🛡️

SafeComments AI is a production-ready, full-stack web application built for content creators to analyze social media comment sections using Machine Learning and NLP. It ingests comment data via CSV uploads, runs each comment through a decoupled multi-stage AI analysis pipeline, and presents insights through an interactive, glassmorphic dark-mode analytics dashboard.

---

🏗️ Architecture & Pipeline Flow

flowchart TD
    subgraph Frontend ["React Frontend (Vite + TanStack Query)"]
        UI[Upload / Dashboard / Explorer]
    end

    subgraph Backend ["Flask Backend API"]
        UploadAPI[POST /upload]
        StatusAPI[GET /posts/id/status]
        ReadAPI[GET /comments & /dashboard]
        
        Parser[CSV Parser Service]
        Orchestrator[CommentAnalyzer Service]
        
        subgraph Pipeline ["AI Processing Pipeline"]
            Lang[Language Detection\nlangdetect + Hinglish Heuristic]
            Sent[Sentiment Analysis\ncardiffnlp/twitter-xlm-roberta-base-sentiment]
            Tox[Toxicity Analysis\nDetoxify original]
            Sev[Severity & Category Derivation\nDeterministic Thresholds]
        end
    end

    subgraph Storage ["Database"]
        DB[(MySQL 8.0)]
    end

    UI -->|1. CSV Upload| UploadAPI
    UploadAPI -->|2. Validate & Read| Parser
    Parser -->|3. Persist Raw Comments| DB
    UploadAPI -->|4. Trigger Background Worker| Orchestrator
    
    Orchestrator --> Lang --> Sent --> Tox --> Sev
    Sev -->|5. Store Analysis Results| DB
    
    UI -->|Poll Status| StatusAPI
    UI -->|Fetch Aggregates & Items| ReadAPI
    ReadAPI -->|Query| DB

Loading

---

✨ Core Features

• 📁 CSV Ingestion & Validation: Ingest comment sections via CSV. Includes UTF-8 encoding validation, mandatory column checks (username, comment), empty row filtering, and whitespace normalization.
• 🌐 Language Detection: Classifies comments into English, Devanagari Hindi, or code-mixed Hinglish (Latin-script Hindi) using a custom lexicon ratio heuristic and langdetect.
• 🎭 Multilingual Sentiment Analysis: Powered by cardiffnlp/twitter-xlm-roberta-base-sentiment to score emotional polarity (Positive, Neutral, Negative) with confidence metrics.
• ☠️ 6-Class Toxicity Detection: Utilizes Detoxify('original') to compute probability scores across toxicity, severe_toxicity, threat, insult, obscene, and identity_attack.
• ⚡ Deterministic Severity & Escalation:
  • Scores mapped to safe (< 0.20), low (0.20–0.45), medium (0.45–0.70), high (0.70–0.90), or critical (≥ 0.90).
  • Threat score escalation: Any comment with threat ≥ 0.5 is automatically escalated to at least high severity.
• 📊 Analytics Dashboard:
  • 10 Metric Cards: Total Comments, Positive %, Negative %, Neutral %, Avg Toxicity, Most Toxic Comment Link, Top Category, Threats Count, Spam Count, Bullying Count.
  • Interactive Recharts: Sentiment Donut Chart, Category Bar Breakdown, and a 10-bucket Toxicity Histogram.
  • AI Narrative Summary: Automated high-level overview of audience reaction and tone.
• 🔍 Filterable & Sortable Explorer: Real-time multi-dimensional filter bar (sentiment, severity, category, language, username search, keyword search) with sortable columns.
• 🔄 Asynchronous Background Processing: Off-thread task execution via concurrent.futures.ThreadPoolExecutor paired with front-end status polling (GET /posts/{id}/status).

---

🛠️ Tech Stack

Layer	Technology
Frontend	React 19, React Router v7, TanStack Query v5, Recharts, Plain CSS (Glassmorphism design system)
Backend	Flask 3.1 (Application Factory), Flask-SQLAlchemy, Pydantic v2, Alembic
Database	MySQL 8.0
AI Models	HuggingFace Transformers, PyTorch, Detoxify, langdetect
DevOps & Containers	Docker, Docker Compose
Testing	pytest (Backend unit & integration tests)

---

🚀 Quick Start (Docker Compose)

1. Clone the repository

git clone https://github.com/your-username/SafeComments-AI.git
cd SafeComments-AI

2. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

3. Launch Services

docker compose up --build

4. Access Points

• 🎨 Frontend UI: http://localhost:5173
• ⚡ Backend API: http://localhost:5000
• 🩺 Health Check: http://localhost:5000/health
• 🗄️ MySQL Database: localhost:3307 (mapped from container 3306)

---

📡 REST API Reference

Method	Endpoint	Description	Query / Payload Parameters
POST	/upload	Upload CSV for processing	multipart/form-data with file
GET	/posts/{id}/status	Get post analysis status	Response: { status, analyzed, total }
GET	/dashboard	Fetch dashboard statistics	post_id (required)
GET	/comments	Query comments with filters	post_id, sentiment, severity, category, language, username, q, sort
GET	/analysis/{comment_id}	Get full AI score breakdown	comment_id
GET	/health	Application & DB health status	None

---

🧪 Running Automated Tests

The backend suite includes unit tests for the CSV parser, AI pipeline singletons, severity thresholds, and API endpoints using pytest:

# Run tests inside the running Docker container
docker compose exec backend pytest tests/ -v

---

📂 Repository Structure

.
├── backend/
│   ├── app/
│   │   ├── api/          # Blueprints (upload, comments, dashboard)
│   │   ├── database/     # SQLAlchemy engine & session management
│   │   ├── models/       # Database ORM models (User, Post, Comment, Analysis)
│   │   ├── schemas/      # Pydantic validation & response contracts
│   │   ├── services/     # Ingestion & AI Pipeline (csv_parser, analyzer, sentiment, toxicity, language, severity, report)
│   │   ├── utils/        # Structured JSON logging & exceptions
│   │   ├── config.py     # Pydantic BaseSettings
│   │   └── main.py       # Flask Application Factory
│   ├── alembic/          # DB Migrations
│   ├── tests/            # Test suite & sample CSV fixtures
│   ├── Dockerfile
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── charts/       # Recharts visualizations
│   │   ├── components/   # Reusable UI components
│   │   ├── hooks/        # React Query hooks
│   │   ├── pages/        # HomePage, CommentsPage, DashboardPage
│   │   ├── services/     # API Client
│   │   ├── App.jsx
│   │   └── index.css     # Glassmorphism Design Tokens
│   ├── Dockerfile
│   └── package.json
├── docker-compose.yml
├── DECISIONS.md          # Key architecture decisions & tradeoffs
└── README.md

---

📄 License

Distributed under the MIT License. See LICENSE for more information.