COVID Tweet Insight Analyzer

A production-ready web application that analyzes COVID-19 related tweets using AI/ML models for sentiment analysis, toxicity detection, and content classification.

---

📋 Features

Core Analysis

• Sentiment Analysis: Positive, Negative, Neutral detection using CardiffNLP Twitter-RoBERTa
• Toxicity Detection: Multi-category toxicity analysis using TOXIC-BERT
• Sarcasm Detection: Detect sarcastic content using fine-tuned T5 model
• Content Classification: Categorize tweets as Informational, Abusive, Hate Speech, Spam, or Not Useful
• Risk Assessment: Calculate risk levels (Low/Medium/High) based on toxicity

Features

• ✅ Direct tweet text input
• ✅ Twitter/X link extraction and analysis
• ✅ Real-time sentiment & toxicity analysis
• ✅ Confidence scores for all predictions
• ✅ Beautiful dark medical theme with GSAP animations
• ✅ Responsive mobile design
• ✅ MongoDB integration for tweet storage (optional)
• ✅ Statistics dashboard
• ✅ RESTful API with FastAPI
• ✅ Production-ready error handling

---

🛠 Tech Stack

Backend

• FastAPI: High-performance API framework
• Python 3.8+: Core language
• Transformers (HuggingFace): ML models
• Torch: Deep learning framework
• Motor: Async MongoDB driver
• Tweepy: Twitter API integration
• Uvicorn: ASGI server

Frontend

• React 18.2: UI framework
• Vite: Build tool
• Tailwind CSS: Styling
• GSAP 3: Premium animations
• Axios: HTTP client

Database

• MongoDB: Document database (optional)

---

📦 Installation

Prerequisites

• Python 3.8+
• Node.js 16+
• MongoDB (optional, for tweet storage)
• Git

Backend Setup

1. Clone the repository

cd PandemicSentinel

2. Create Python virtual environment

# Windows
python -m venv venv
venv\Scripts\activate

# macOS/Linux
python3 -m venv venv
source venv/bin/activate

3. Install Python dependencies

cd backend
pip install -r requirements.txt

4. Create .env file (in project root)

cp ..\.env.example ..\.env
# Edit .env with your settings

5. Run backend server

cd ..
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

Backend will be available at: http://localhost:8000

Frontend Setup

1. Install Node dependencies

cd frontend
npm install

2. Create .env.local file

# Windows
echo VITE_API_URL=http://localhost:8000 > .env.local

# macOS/Linux
echo "VITE_API_URL=http://localhost:8000" > .env.local

3. Start development server

npm run dev

Frontend will be available at: http://localhost:5173

---

🚀 Running the Full Stack

Terminal 1: Backend

cd backend
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cd ..
uvicorn backend.main:app --reload

Terminal 2: Frontend

cd frontend
npm install
npm run dev

Terminal 3: MongoDB (if needed)

mongod
# or use Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

---

📚 API Endpoints

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0"
}

Analyze Direct Text

POST /analyze-text
Content-Type: application/json

{
  "text": "Your tweet text here"
}

Response:

{
  "tweet_text": "...",
  "classification": "Informational",
  "tone": "Positive",
  "confidence": {
    "sentiment": 0.95,
    "toxicity": 0.05,
    "sarcasm": 0.02,
    "toxicity_details": {
      "toxicity": 0.01,
      "severe_toxicity": 0.0,
      "obscene": 0.0,
      "identity_attack": 0.0,
      "insult": 0.02,
      "threat": 0.0
    }
  },
  "toxicity_score": 0.05,
  "sarcasm_detected": false,
  "risk_level": "Low",
  "summary": "..."
}

Analyze Twitter Link

POST /analyze-link
Content-Type: application/json

{
  "link": "https://twitter.com/user/status/1234567890"
}

Get Statistics

GET /statistics

Response:

{
  "status": "success",
  "statistics": {
    "total_analyzed": 42,
    "toxic_percentage": 15.5,
    "informational_percentage": 45.2,
    "positive_tone_percentage": 60.8
  }
}

---

🎨 UI Components

Hero Section

• Animated gradient text
• Floating particle background
• Call-to-action buttons
• Feature preview cards

Analyzer

• Textarea for tweet input
• Auto-detect text/link input
• Character counter
• Real-time validation
• Error messages

Result Card

• Tweet text display
• Summary paragraph
• Classification badge
• Tone indicator
• Risk meter with needle animation
• Confidence score progress bars
• Toxicity breakdown grid

Risk Meter

• Animated gauge visualization
• Color-coded risk levels (Green/Yellow/Red)
• Rotating needle based on toxicity
• Real-time percentage display

---

🧠 ML Models Used

1. Sentiment Analysis

Model: cardiffnlp/twitter-roberta-base-sentiment

• Detects Positive, Negative, Neutral sentiment
• Fine-tuned on Twitter data
• High accuracy for social media

2. Toxicity Detection

Model: unitary/toxic-bert

• Detects 6 categories of toxicity
• Identity attacks
• Abusive language
• Threat detection
• Insults and obscenity

3. Sarcasm Detection

Model: mrm8488/t5-base-finetuned-sarcasm-twitter

• Trained on Twitter sarcasm dataset
• T5 architecture
• Context-aware detection

---

🔧 Configuration

Environment Variables

# Backend
BACKEND_PORT=8000
ALLOWED_ORIGINS=http://localhost:5173,http://localhost:3000

# Database
MONGODB_URL=mongodb://localhost:27017

# Twitter API (Optional)
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_BEARER_TOKEN=your_bearer_token

# Frontend
VITE_API_URL=http://localhost:8000

Backend Structure

backend/
├── main.py              # Entry point
├── schemas.py           # Pydantic models
├── database.py          # MongoDB async driver
├── requirements.txt     # Dependencies
├── models/
│   ├── sentiment.py      # Sentiment analyzer
│   ├── toxicity.py       # Toxicity detector
│   └── sarcasm.py        # Sarcasm detector
└── services/
    ├── twitter_service.py # Tweet fetching
    └── analyzer.py        # Analysis orchestration

Frontend Structure

frontend/
├── index.html
├── package.json
├── vite.config.js
├── tailwind.config.js
├── postcss.config.js
└── src/
    ├── App.jsx
    ├── main.jsx
    ├── index.css
    ├── components/
    │   ├── Hero.jsx        # Landing section
    │   ├── Analyzer.jsx    # Main analyzer
    │   ├── ResultCard.jsx  # Results display
    │   ├── RiskMeter.jsx   # Risk gauge
    │   └── Loader.jsx      # Loading animation
    ├── pages/
    │   └── Home.jsx        # Main page
    └── animations/
        └── gsapAnimations.js # GSAP animations

---

🎬 GSAP Animations Included

• Hero Text: Staggered fade-up reveal
• Particles: Floating background effect
• Input Focus: Neon glow effect
• Submit: Morph and scale animation
• Result Cards: Slide-in with fade
• Progress Bars: Animated count-up
• Risk Meter: Rotated needle animation
• Scroll Triggers: Section animations
• Page Transitions: Fade and blur effects

---

📊 Production Deployment

Backend (Using Gunicorn)

pip install gunicorn
gunicorn backend.main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker

Frontend (Build)

npm run build
# Outputs to /dist for serving with Nginx/Apache

Docker Deployment (Optional)

Backend Dockerfile:

FROM python:3.10-slim
WORKDIR /app
COPY backend/requirements.txt .
RUN pip install -r requirements.txt
COPY backend/ .
CMD ["uvicorn", "main:app", "--host", "0.0.0.0"]

Docker Compose:

version: '3.8'
services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - MONGODB_URL=mongodb://mongodb:27017
    depends_on:
      - mongodb

  frontend:
    build: ./frontend
    ports:
      - "5173:5173"

  mongodb:
    image: mongo:latest
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

---

⚖️ Important Disclaimer

⚠️ Medical Information Disclaimer

This tool analyzes the tone and content of tweets but should NOT be used as a sole source for COVID-19 medical information.

Always verify information with:

• WHO (World Health Organization)
• CDC (Centers for Disease Control)
• Your local health authorities
• Licensed medical professionals

The analysis provided is for informational and research purposes only.

---

🔐 Security Considerations

• Input validation on all endpoints
• CORS protection enabled
• No sensitive data stored in client
• Environment variables for secrets
• Rate limiting (recommended for production)
• Input sanitization for text analysis

---

🐛 Troubleshooting

Backend Issues

Models not downloading

# Clear cache and restart
rm -rf .huggingface_cache
python main.py

MongoDB connection error

• Ensure MongoDB is running: mongod or Docker container
• Check MONGODB_URL in .env
• Can run without MongoDB (in-memory mode)

Port already in use

# Change port in .env: BACKEND_PORT=8001
uvicorn backend.main:app --reload --port 8001

Frontend Issues

Vite port conflict

npm run dev -- --port 5174

API connection failed

• Check VITE_API_URL in .env.local
• Verify backend is running on correct port
• Check browser console for CORS errors

---

📈 Performance Optimization

• Models are lazy-loaded on first request
• Async database operations
• Caching of model predictions (optional)
• Frontend bundle minification
• GSAP animations optimized for 60 FPS

---

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create feature branch
3. Commit changes
4. Push to branch
5. Open pull request

---

📄 License

MIT License - see LICENSE file for details

---

👨‍💻 Author

Created as a comprehensive full-stack AI application demonstrating:

• FastAPI for modern backend development
• React with advanced animations
• Multi-model ML inference
• Production-ready architecture

---

📞 Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Check existing documentation
• Review API documentation at /docs

---

🎓 Educational Value

This project demonstrates:

• ✅ Production-grade FastAPI application
• ✅ Async Python development
• ✅ HuggingFace transformer models
• ✅ Modern React patterns
• ✅ GSAP animation mastery
• ✅ Full-stack integration
• ✅ Database integration
• ✅ RESTful API design
• ✅ Error handling & validation
• ✅ Responsive UI/UX

---

🚀 Future Enhancements

• Real-time tweet streaming
• Dashboard with analytics
• User authentication
• Tweet history & favorites
• Multi-language support
• Advanced NLP summarization
• Batch analysis
• Export results to CSV/PDF
• Dark/Light theme toggle
• WebSocket for real-time updates

---

Last Updated: February 2024 Status: Production Ready ✅