🛡️ Image Moderation Service

A comprehensive AI-powered image moderation system that detects NSFW (Not Safe For Work) content using OpenNSFW2. Built with FastAPI, MongoDB, and Streamlit in a microservices architecture.

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │    Backend      │    │   Moderation    │
│   (Streamlit)   │◄──►│   (FastAPI)     │◄──►│   Service       │
│   Port: 8501    │    │   Port: 7000    │    │  (OpenNSFW2)    │
└─────────────────┘    └─────────────────┘    │   Port: 8000    │
                                │              └─────────────────┘
                                ▼
                       ┌─────────────────┐
                       │    MongoDB      │
                       │   Port: 27017   │
                       └─────────────────┘

🎯 Features

• 🔍 NSFW Detection: AI-powered content analysis using OpenNSFW2 model
• 🧠 Machine Learning: Pure Python TensorFlow implementation for accurate detection
• 🔐 JWT Authentication: Secure token-based authentication with session management
• 📤 File Upload: Support for multiple image formats (PNG, JPG, JPEG, GIF, BMP, WebP)
• 📊 Detailed Analysis: Confidence scores, probability metrics, and threshold-based classification
• 🏥 Health Monitoring: Service health checks and model status monitoring
• 🐳 Docker Support: Complete containerized deployment with model caching
• 🎨 Modern UI: Clean Streamlit dashboard interface with real-time results

🚀 Quick Start

Prerequisites

• Docker Desktop installed
• 4GB+ RAM (for OpenNSFW2 model)

Start Services

# Clone and start (model downloads on first run - takes 2-5 minutes)
git clone <repository-url>
cd ImageModeration
docker-compose up --build -d

# Monitor model loading progress
docker-compose logs -f moderation

Access

• Dashboard: http://localhost:8501
• API Docs: http://localhost:7000/docs
• Credentials: admin / adminpassword

🛠️ Development Setup

Local Development

# Backend
cd backend
python -m venv .venv && .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:MONGODB_URI="mongodb://admin:adminpassword@localhost:27017/image_moderation?authSource=admin"
$env:MODERATION_SERVICE_URL="http://localhost:8000"
uvicorn app.main:app --port 7000 --reload

# Frontend (new terminal)
cd frontend
python -m venv .venv && .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
$env:BACKEND_URL="http://localhost:7000"
streamlit run app.py

# Moderation Service (new terminal)
cd moderation-service
python -m venv .venv && .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --port 8000 --reload

🧪 Testing

# Run tests
cd backend && pytest ../tests/ -v

# Manual API test
curl -X POST "http://localhost:7000/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=adminpassword"

# Upload image (replace YOUR_JWT_TOKEN)
curl -X POST "http://localhost:7000/moderate/" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@path/to/image.jpg"

📁 Project Structure

ImageModeration/
├── backend/                    # FastAPI backend service
├── frontend/                   # Streamlit dashboard
├── moderation-service/         # OpenNSFW2 AI service
├── tests/                      # Test suite
├── docker-compose.yml          # Service orchestration
└── README.md

🐳 Docker Commands

# Essential operations
docker-compose up --build -d     # Start all services
docker-compose down              # Stop services
docker-compose logs -f           # View all logs
docker-compose ps               # Check status

# Service-specific
docker-compose logs -f moderation    # Model loading progress
docker-compose restart backend       # Restart specific service
docker-compose build --no-cache moderation  # Force rebuild

# Cleanup
docker-compose down -v          # Remove volumes (clears model cache)

🔧 Configuration

Environment Variables

# Backend
MONGODB_URI=mongodb://admin:adminpassword@mongodb:27017/image_moderation?authSource=admin
MODERATION_SERVICE_URL=http://moderation:8000
SECRET_KEY=your-super-secret-jwt-key-change-in-production

# Frontend
BACKEND_URL=http://backend:7000

# Moderation Service
THRESHOLD=0.5                    # NSFW detection threshold
MAX_FILE_SIZE=50MB              # Upload limit

📡 API Endpoints

Authentication

• POST /auth/token - Login and get JWT token
• GET /auth/tokens - List active user tokens
• DELETE /auth/tokens/{jti} - Revoke specific token
• POST /auth/logout - Logout current session

Moderation

• POST /moderate/ - Upload and analyze image for NSFW content
• GET /moderate/health - Check moderation service and model status

Health

• GET / - Backend service health check
• GET /health - Detailed moderation service health

Response Example

{
  "user": "admin",
  "moderation": {
    "is_nsfw": false,
    "nsfw_probability": 0.0234,
    "safe_probability": 0.9766,
    "confidence": 0.9766,
    "model_type": "OpenNSFW2"
  }
}

🚨 Troubleshooting

Model Loading Issues

# Check model download progress
docker-compose logs -f moderation

# Expected: "INFO: OpenNSFW2 model loaded successfully"
# If fails: docker-compose restart moderation

Service Connection Issues

# Check all services running
docker-compose ps

# View specific service logs
docker-compose logs backend

# Clean restart
docker-compose down && docker-compose up --build -d

Authentication Issues

# Test login
curl -X POST "http://localhost:7000/auth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=adminpassword"

# Check MongoDB connection
docker-compose logs mongodb

Performance Issues

# Monitor resource usage
docker stats

# Clear model cache if needed
docker-compose down -v
docker-compose up --build -d

🔐 Security Features

• JWT Authentication with token revocation
• Bcrypt password hashing with salt
• Input validation for file types and sizes
• Internal service communication (not externally exposed)
• Health monitoring with configurable checks

🤖 AI Model Details

OpenNSFW2

• Framework: Pure Python TensorFlow 2.x
• Input: PIL Images (auto-resized to 224x224)
• Output: NSFW probability score (0.0-1.0)
• Cache: Models cached in Docker volumes for faster restarts
• Memory: ~1GB RAM when loaded

🔄 Maintenance

Update Dependencies

# Check outdated packages
pip list --outdated

# Update and rebuild
pip install --upgrade package_name
docker-compose build --no-cache

Database Operations

# Access MongoDB
docker-compose exec mongodb mongosh -u admin -p adminpassword

# Common operations
use image_moderation
db.tokens.find().pretty()
db.tokens.deleteMany({"expires_at": {"$lt": new Date()}})  # Clean expired tokens

📊 Development Tools

# Code quality
pip install pre-commit && pre-commit install
pre-commit run --all-files

# Performance testing
time curl -X POST "http://localhost:7000/moderate/" \
  -H "Authorization: Bearer TOKEN" -F "file=@test.jpg"

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

1. Fork repository
2. Create feature branch
3. Run pre-commit run --all-files
4. Add tests and run pytest tests/ -v
5. Submit pull request

📞 Support

• Check troubleshooting section above
• Review logs: docker-compose logs -f
• Test health endpoints
• Open GitHub issue with full error logs

---

Made with ❤️ using FastAPI, Streamlit, OpenNSFW2, and Docker

AI-powered content moderation made simple and accessible