backend/README.md

Deepfake Detection Service Backend

A scalable FastAPI backend for deepfake detection with support for multiple ML models and future Redis integration for task queuing.

📁 Project Structure

backend/
├── app/
│   ├── core/                 # Core configuration and setup
│   │   ├── config.py        # Settings management
│   │   └── logging_config.py # Logging setup
│   ├── models/              # Data models
│   │   └── schemas.py       # Pydantic request/response models
│   ├── services/            # Business logic layer
│   │   ├── download.py      # File download service
│   │   ├── queue.py         # Task queue service (Redis-ready)
│   │   └── detector/        # ML detector models
│   │       ├── base.py      # Abstract base detector class
│   │       └── mock.py      # Mock detector implementation
│   ├── api/                 # API endpoints
│   │   └── routes.py        # Route handlers
│   └── utils/               # Utilities
│       └── exceptions.py    # Custom exceptions
├── main.py                  # Application entry point
├── requirements.txt         # Python dependencies
├── .env.example            # Example environment variables
└── README.md               # This file

🚀 Quick Start

Prerequisites

• Python 3.8+
• pip or conda

Installation

1. Navigate to the backend directory:

   cd backend
   

2. Create a virtual environment (recommended):

   # Using venv
   python -m venv venv
   
   # Activate virtual environment
   # On Windows:
   venv\Scripts\activate
   # On macOS/Linux:
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the server:

   python main.py
   

The server will start on http://127.0.0.1:8000

📖 API Documentation

Once the server is running, interactive API documentation is available at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

🔌 API Endpoints

Health Check

GET /

Returns service status and available models.

Response:

{
  "status": "ok",
  "service": "Deepfake Detection Service",
  "version": "1.0.0",
  "available_models": ["mock"]
}

Analyze File

POST /analyze
Content-Type: application/json

{
  "file_url": "https://example.com/video.mp4",
  "model": "mock"
}

Request Parameters:

• file_url (required): URL of the file to analyze
• model (optional): Detector model to use. Defaults to configured model

Response (200 OK):

{
  "is_deepfake": true,
  "confidence": 0.847,
  "analysis_time": 1.234,
  "model_used": "mock"
}

Error Responses:

• 400 Bad Request: Invalid URL, file too large, or unsupported model
• 408 Request Timeout: File download timed out
• 500 Internal Server Error: Server error during analysis

⚙️ Configuration

Configuration is managed through environment variables. Create a .env file in the backend/ directory:

cp .env.example .env

Edit .env with your settings:

# Server
HOST=127.0.0.1
PORT=8000

# File handling
DOWNLOAD_TIMEOUT=30
MAX_FILE_SIZE=104857600  # 100 MB

# ML Model
DEFAULT_DETECTOR_MODEL=mock

# Redis (for future use)
REDIS_ENABLED=False
REDIS_URL=redis://localhost:6379

# Logging
LOG_LEVEL=INFO
LOG_FILE=

🎯 Adding New ML Models

The architecture supports easy addition of new detector models:

1. Create a new detector class in app/services/detector/:

# app/services/detector/deepseek.py
from app.services.detector.base import BaseDetector

class DeepseekDetector(BaseDetector):
    def __init__(self):
        super().__init__("deepseek")
    
    async def detect(self, file_bytes: bytes) -> dict:
        # Your ML model implementation
        return {
            "is_deepfake": False,
            "confidence": 0.95,
            "analysis_time": 2.5
        }

2. Register the detector in app/services/detector/__init__.py:

def get_detector(model_name: str = "mock") -> BaseDetector:
    detectors = {
        "mock": MockDetector,
        "deepseek": DeepseekDetector,  # Add this
        # ... more models
    }
    # ... rest of code

3. Update .env.example to document the new model

🚦 Future Redis Integration

The queue service is designed to support Redis task queuing without major refactoring:

1. Set REDIS_ENABLED=True in .env
2. Set correct REDIS_URL
3. The queue service will automatically use Redis for task management

Redis support will enable:

• Asynchronous task processing
• Task result caching
• Improved scalability for high-volume requests

📝 Logging

Logs are configured in app/core/logging_config.py. By default:

• Level: INFO
• Output: Console
• Rotation: Automatic (if LOG_FILE is set)

Configure logging level via environment:

LOG_LEVEL=DEBUG  # For verbose logging

🧪 Testing the API

Using curl:

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{"file_url": "https://example.com/video.mp4"}'

Using Python requests:

import requests

response = requests.post(
    "http://localhost:8000/analyze",
    json={"file_url": "https://example.com/video.mp4"}
)
print(response.json())

Using httpx (async):

import httpx
import asyncio

async def test():
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/analyze",
            json={"file_url": "https://example.com/video.mp4"}
        )
        print(response.json())

asyncio.run(test())

🔒 Error Handling

The API provides comprehensive error handling:

# Invalid URL
{
  "error": "Invalid URL format",
  "status_code": 400,
  "details": null
}

# File too large
{
  "error": "File size exceeds maximum allowed size of 104857600 bytes",
  "status_code": 400,
  "details": null
}

# Download timeout
{
  "error": "File download timed out",
  "status_code": 408,
  "details": null
}

# Unsupported model
{
  "error": "Detector model 'invalid' is not supported. Available models: mock",
  "status_code": 400,
  "details": null
}

🔧 Troubleshooting

Port already in use:

# Change port via environment variable
PORT=8001 python main.py

Import errors:

# Ensure you're in the backend directory and have activated venv
cd backend
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt

Timeout issues:

# Increase timeout for slow downloads
DOWNLOAD_TIMEOUT=60 python main.py

📦 Dependencies

• FastAPI: Modern async web framework
• Uvicorn: ASGI server
• Pydantic: Data validation and settings
• httpx: Async HTTP client for file downloads

See requirements.txt for exact versions.

📄 License

This project is part of the DiscordBot backend service.

🤝 Contributing

To add new features or models:

1. Follow the existing code structure
2. Implement abstract base classes for new functionality
3. Add comprehensive logging
4. Update documentation and examples

📧 Support

For issues or questions, please refer to the project documentation or contact the development team.