setup

QUICKSTART.md

@@ -0,0 +1,187 @@
+# Quick Reference Guide
+
+## 🚀 Starting the Backend
+
+### First Time Setup (Windows)
+```powershell
+cd backend
+python setup.py
+venv\Scripts\activate
+python main.py
+```
+
+### First Time Setup (macOS/Linux)
+```bash
+cd backend
+python setup.py
+source venv/bin/activate
+python main.py
+```
+
+### Subsequent Times
+```bash
+cd backend
+run.bat      # Windows
+# OR
+./run.sh     # macOS/Linux
+```
+
+## 📡 API Quick Test
+
+### Health Check
+```bash
+curl http://localhost:8000/
+```
+
+### Analyze a File
+```bash
+curl -X POST http://localhost:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4"}'
+```
+
+### Documentation
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+## 🔧 Configuration
+
+Edit `backend/.env`:
+```env
+HOST=127.0.0.1
+PORT=8000
+DEFAULT_DETECTOR_MODEL=mock
+LOG_LEVEL=INFO
+DOWNLOAD_TIMEOUT=30
+MAX_FILE_SIZE=104857600
+```
+
+## 📦 Project Structure
+
+```
+backend/
+├── app/
+│   ├── api/         # Routes
+│   ├── services/    # Business logic (download, ML models, queuing)
+│   ├── models/      # Data schemas
+│   ├── core/        # Configuration
+│   └── utils/       # Exceptions
+├── main.py          # Entry point
+├── README.md        # Full API docs
+└── DEVELOPMENT.md   # Adding models, Redis, etc.
+```
+
+## ➕ Adding a New ML Model
+
+1. Copy `DETECTOR_TEMPLATE.py`
+2. Implement the `detect()` method
+3. Register in `app/services/detector/__init__.py`
+4. Update `.env` if setting as default
+
+See `DEVELOPMENT.md` for detailed steps.
+
+## 🔗 Integrating with Discord Bot
+
+Use `DISCORD_BOT_EXAMPLE.py` as a template:
+
+```python
+from discord_bot_example import setup
+
+# In your bot startup:
+await setup(bot)
+
+# Then use in your bot:
+# !deepfake_check https://example.com/video.mp4
+# !backend_status
+```
+
+## 🐛 Common Issues
+
+| Problem | Solution |
+|---------|----------|
+| `ModuleNotFoundError` | Activate venv first |
+| Port 8000 in use | Change port: `PORT=8001 python main.py` |
+| Import errors | `pip install -r requirements.txt` |
+| Download timeout | Increase: `DOWNLOAD_TIMEOUT=60 python main.py` |
+
+## 📊 Supported File Types
+
+Any file type via URL:
+- Videos: `.mp4`, `.webm`, `.avi`, etc.
+- Images: `.jpg`, `.png`, `.gif`, etc.
+- Any file up to 100 MB (configurable)
+
+## 🔄 Async Support
+
+Backend is fully async:
+- Non-blocking file downloads
+- Concurrent requests supported
+- Scalable to Redis task queuing
+
+## 📝 Logging Levels
+
+```bash
+# Normal operation
+LOG_LEVEL=INFO python main.py
+
+# Verbose debugging
+LOG_LEVEL=DEBUG python main.py
+
+# Warnings and errors only
+LOG_LEVEL=WARNING python main.py
+```
+
+## 🚀 Production Deployment
+
+For production, use Gunicorn with Uvicorn:
+
+```bash
+pip install gunicorn
+gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+```
+
+## 📞 Response Format
+
+**Success:**
+```json
+{
+  "is_deepfake": true,
+  "confidence": 0.95,
+  "analysis_time": 1.5,
+  "model_used": "mock"
+}
+```
+
+**Error:**
+```json
+{
+  "error": "Invalid URL format",
+  "status_code": 400,
+  "details": null
+}
+```
+
+## 🔐 Default Security Settings
+
+- Max file size: 100 MB
+- Download timeout: 30 seconds
+- URL validation: Enabled
+- Error details: Minimal (no leakage)
+
+Increase security for production:
+- Add API keys/authentication
+- Implement rate limiting
+- Use HTTPS
+- Add CORS restrictions
+
+## 🎯 Next Steps
+
+1. ✅ Backend running?
+2. ⏳ Test with sample URLs
+3. ⏳ Create Discord bot using example
+4. ⏳ Add your ML models
+5. ⏳ Deploy to production
+
+---
+
+For complete documentation, see `README.md` and `DEVELOPMENT.md` in the backend folder.

README.md

@@ -1 +0,0 @@
-# DiscordBot

backend/.env.example

@@ -0,0 +1,27 @@
+# Deepfake Detection Service - Environment Variables
+
+# Application Settings
+APP_NAME=Deepfake Detection Service
+APP_VERSION=1.0.0
+DEBUG=True
+
+# Server Configuration
+HOST=127.0.0.1
+PORT=8000
+
+# File Handling
+DOWNLOAD_TIMEOUT=30
+MAX_FILE_SIZE=104857600
+
+# ML Model Configuration
+DEFAULT_DETECTOR_MODEL=mock
+# Supported models: mock, deepseek, openai, etc.
+
+# Redis Configuration (for future queuing)
+REDIS_ENABLED=False
+REDIS_URL=redis://localhost:6379
+REDIS_QUEUE_NAME=deepfake_analysis
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FILE=

backend/.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+venv/
+ENV/
+env/
+.venv
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# Logs
+logs/
+*.log
+*.log.*
+
+# Redis
+dump.rdb
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Temporary files
+*.tmp
+*.temp

backend/DETECTOR_TEMPLATE.py

@@ -0,0 +1,105 @@
+"""
+Template for creating new detector models.
+
+Copy this file and implement the detect() method with your custom ML logic.
+Then register it in app/services/detector/__init__.py
+
+Example:
+    # Copy this file as app/services/detector/mydetector.py
+    # Modify the class and model_name
+    # Add to get_detector() in __init__.py
+"""
+
+import logging
+import time
+from typing import Dict, Any
+
+from app.services.detector.base import BaseDetector
+
+logger = logging.getLogger(__name__)
+
+
+class MyDetector(BaseDetector):
+    """
+    Template detector implementation.
+    
+    Replace 'MyDetector' with your detector name.
+    """
+    
+    def __init__(self):
+        """Initialize the detector."""
+        # Change 'mydetector' to your model name
+        super().__init__("mydetector")
+    
+    async def detect(self, file_bytes: bytes) -> Dict[str, Any]:
+        """
+        Detect if file is a deepfake.
+        
+        Args:
+            file_bytes: The file contents as bytes
+            
+        Returns:
+            Dictionary with:
+            - is_deepfake: Boolean
+            - confidence: Float between 0.0 and 1.0
+            - analysis_time: Float in seconds
+        """
+        logger.info(f"Starting detection with {self.model_name}...")
+        
+        start_time = time.time()
+        
+        # ========================================
+        # TODO: Implement your ML model logic here
+        # ========================================
+        # Example:
+        # 1. Preprocess file_bytes if needed
+        # 2. Load your ML model
+        # 3. Run inference
+        # 4. Post-process results
+        
+        # For now, return placeholder results
+        is_deepfake = True
+        confidence = 0.85
+        
+        analysis_time = time.time() - start_time
+        
+        result = {
+            "is_deepfake": is_deepfake,
+            "confidence": round(confidence, 3),
+            "analysis_time": round(analysis_time, 3),
+        }
+        
+        logger.info(f"Detection completed. Result: {result}")
+        return result
+
+
+# =====================================================
+# REGISTRATION INSTRUCTIONS:
+# =====================================================
+# 
+# 1. Save this file as: app/services/detector/mydetector.py
+# 
+# 2. Update app/services/detector/__init__.py:
+#    
+#    from app.services.detector.mydetector import MyDetector
+#    
+#    def get_detector(model_name: str = "mock") -> BaseDetector:
+#        detectors = {
+#            "mock": MockDetector,
+#            "mydetector": MyDetector,  # ADD THIS LINE
+#        }
+#        # ... rest of function
+# 
+# 3. Update .env.example:
+#    
+#    DEFAULT_DETECTOR_MODEL=mydetector
+# 
+# 4. Test your detector:
+#    
+#    POST /analyze
+#    {
+#        "file_url": "https://example.com/video.mp4",
+#        "model": "mydetector"
+#    }
+#
+# =====================================================

backend/DEVELOPMENT.md

@@ -0,0 +1,351 @@
+# Development Guide for Deepfake Detection Backend
+
+## Project Overview
+
+This is a production-ready FastAPI backend for deepfake detection with a modular, extensible architecture. It's designed to support multiple ML models and easy integration with task queues like Redis.
+
+## Architecture Overview
+
+```
+FastAPI Application (app/__init__.py)
+├── API Routes (app/api/routes.py)
+│   ├── GET / (Health check)
+│   └── POST /analyze (Main endpoint)
+├── Services Layer (app/services/)
+│   ├── download.py (File downloading)
+│   ├── queue.py (Redis-ready task queue)
+│   └── detector/ (ML model implementations)
+│       ├── base.py (Abstract interface)
+│       ├── mock.py (Test implementation)
+│       └── [custom_detector].py (Add your models here)
+├── Models/Schemas (app/models/schemas.py)
+└── Core Configuration (app/core/)
+    ├── config.py (Settings)
+    └── logging_config.py (Logging setup)
+```
+
+## Adding a New ML Model
+
+### Step 1: Create Your Detector Class
+
+Create a new file in `app/services/detector/` (e.g., `deepseek.py`):
+
+```python
+import logging
+import time
+from typing import Dict, Any
+from app.services.detector.base import BaseDetector
+
+logger = logging.getLogger(__name__)
+
+class DeepseekDetector(BaseDetector):
+    def __init__(self):
+        super().__init__("deepseek")
+        # Initialize your model here
+        # self.model = load_deepseek_model()
+    
+    async def detect(self, file_bytes: bytes) -> Dict[str, Any]:
+        logger.info("Starting Deepseek detection...")
+        start_time = time.time()
+        
+        # Your detection logic
+        is_deepfake = False  # Your ML logic
+        confidence = 0.95
+        
+        analysis_time = time.time() - start_time
+        
+        return {
+            "is_deepfake": is_deepfake,
+            "confidence": round(confidence, 3),
+            "analysis_time": round(analysis_time, 3),
+        }
+```
+
+### Step 2: Register the Detector
+
+Update `app/services/detector/__init__.py`:
+
+```python
+from app.services.detector.deepseek import DeepseekDetector
+
+def get_detector(model_name: str = "mock") -> BaseDetector:
+    detectors = {
+        "mock": MockDetector,
+        "deepseek": DeepseekDetector,  # Add this
+    }
+    # ... rest of code
+```
+
+### Step 3: Update Configuration
+
+Add to `.env`:
+```
+DEFAULT_DETECTOR_MODEL=deepseek
+```
+
+### Step 4: Test Your Model
+
+```bash
+curl -X POST http://localhost:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4", "model": "deepseek"}'
+```
+
+## Adding Redis Task Queuing
+
+### Step 1: Install Redis
+
+```bash
+pip install redis aioredis
+```
+
+### Step 2: Update requirements.txt
+
+Add to `requirements.txt`:
+```
+redis==5.0.0
+aioredis==2.0.1
+```
+
+### Step 3: Enable Redis
+
+In `.env`:
+```
+REDIS_ENABLED=True
+REDIS_URL=redis://localhost:6379
+```
+
+### Step 4: Implement Queue Service
+
+Update `app/services/queue.py` to implement async Redis operations:
+
+```python
+import aioredis
+import json
+
+class QueueService:
+    async def _initialize_redis(self):
+        self.redis_client = await aioredis.create_redis_pool(
+            self.settings.REDIS_URL
+        )
+    
+    async def enqueue_analysis(self, file_url: str, model: str, task_id: str):
+        task_data = {
+            "task_id": task_id,
+            "file_url": file_url,
+            "model": model,
+        }
+        await self.redis_client.lpush(
+            self.settings.REDIS_QUEUE_NAME,
+            json.dumps(task_data)
+        )
+    
+    async def get_task_result(self, task_id: str):
+        result = await self.redis_client.get(f"result:{task_id}")
+        return json.loads(result) if result else None
+```
+
+### Step 5: Create Worker
+
+Create `worker.py` in the backend directory:
+
+```python
+import asyncio
+import json
+import aioredis
+from app.services.detector import get_detector
+from app.services.download import download_file
+
+async def worker():
+    redis = await aioredis.create_redis_pool("redis://localhost:6379")
+    
+    while True:
+        task_json = await redis.rpop("deepfake_analysis")
+        if not task_json:
+            await asyncio.sleep(1)
+            continue
+        
+        task = json.loads(task_json)
+        try:
+            file_bytes = await download_file(task["file_url"])
+            detector = get_detector(task["model"])
+            result = await detector.detect(file_bytes)
+            
+            await redis.set(
+                f"result:{task['task_id']}",
+                json.dumps(result)
+            )
+        except Exception as e:
+            logger.error(f"Task failed: {e}")
+        
+        await asyncio.sleep(0.1)
+
+if __name__ == "__main__":
+    asyncio.run(worker())
+```
+
+## Configuration Options
+
+See `.env.example` for all available settings:
+
+- `HOST`, `PORT` - Server address
+- `DOWNLOAD_TIMEOUT` - File download timeout in seconds
+- `MAX_FILE_SIZE` - Maximum file size in bytes
+- `DEFAULT_DETECTOR_MODEL` - Default ML model to use
+- `REDIS_ENABLED` - Enable Redis queuing
+- `LOG_LEVEL` - Logging verbosity (DEBUG, INFO, WARNING, ERROR)
+
+## API Response Format
+
+All responses follow a consistent format:
+
+**Success (200):**
+```json
+{
+  "is_deepfake": boolean,
+  "confidence": float,
+  "analysis_time": float,
+  "model_used": "model_name"
+}
+```
+
+**Error (4xx/5xx):**
+```json
+{
+  "error": "Error message",
+  "status_code": 400,
+  "details": "Optional additional details"
+}
+```
+
+## Error Handling
+
+The service handles:
+- **400 Bad Request**: Invalid URL, file too large, unsupported model
+- **408 Request Timeout**: Download timeout
+- **500 Internal Server Error**: Detector failure or unexpected error
+
+Custom exceptions in `app/utils/exceptions.py` provide specific error types for proper handling.
+
+## Logging
+
+All operations are logged with timestamps and levels:
+
+```python
+logger.info("User action")        # Normal operations
+logger.warning("Something odd")   # Unexpected but handled
+logger.error("Failed action")     # Error occurred
+logger.debug("Detailed info")     # Debug information (if enabled)
+```
+
+Enable debug logging:
+```
+LOG_LEVEL=DEBUG python main.py
+```
+
+## Testing
+
+### Unit Test Example
+
+```python
+# tests/test_detector.py
+import pytest
+from app.services.detector import get_detector
+
+@pytest.mark.asyncio
+async def test_mock_detector():
+    detector = get_detector("mock")
+    result = await detector.detect(b"test_data")
+    
+    assert "is_deepfake" in result
+    assert 0.0 <= result["confidence"] <= 1.0
+    assert result["analysis_time"] > 0
+```
+
+### Integration Test Example
+
+```python
+# tests/test_api.py
+from fastapi.testclient import TestClient
+from app import create_app
+
+client = TestClient(create_app())
+
+def test_health():
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json()["status"] == "ok"
+
+@pytest.mark.asyncio
+async def test_analyze():
+    response = await client.post(
+        "/analyze",
+        json={"file_url": "https://example.com/file.mp4"}
+    )
+    assert response.status_code == 200
+```
+
+## Performance Considerations
+
+1. **Async Operations**: All I/O is non-blocking using async/await
+2. **Connection Pooling**: httpx uses connection pooling for downloads
+3. **Memory Management**: Files are kept in memory (configure MAX_FILE_SIZE)
+4. **Timeouts**: All operations have configurable timeouts
+5. **Logging Overhead**: Disable debug logging in production
+
+## Security Considerations
+
+- Validate all URLs with Pydantic's HttpUrl validator
+- Limit file size to prevent DoS attacks
+- Add rate limiting for production use (FastAPI-limiter)
+- Sanitize error messages to avoid information leakage
+- Use HTTPS in production
+- Add API authentication/authorization
+
+## Deployment
+
+For production deployment:
+
+1. Use a production ASGI server (Gunicorn + Uvicorn)
+2. Set `DEBUG=False` in `.env`
+3. Configure logging to file
+4. Enable Redis for scalability
+5. Use environment secrets management
+6. Add reverse proxy (nginx/Apache)
+7. Enable CORS if needed
+8. Add health checks for monitoring
+
+## Common Issues and Solutions
+
+**Issue**: Port 8000 already in use
+```bash
+PORT=8001 python main.py
+```
+
+**Issue**: Module import errors
+```bash
+# Make sure you're in backend directory and venv is activated
+cd backend
+source venv/bin/activate  # or venv\Scripts\activate on Windows
+```
+
+**Issue**: File download fails
+- Check URL is accessible
+- Increase DOWNLOAD_TIMEOUT
+- Check MAX_FILE_SIZE limit
+
+**Issue**: Detector not found
+- Check model name spelling
+- Verify registration in `get_detector()`
+- List available models: `GET /`
+
+## Additional Resources
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [Pydantic Validation](https://docs.pydantic.dev/)
+- [Uvicorn Configuration](https://www.uvicorn.org/)
+- [Python asyncio](https://docs.python.org/3/library/asyncio.html)
+
+---
+
+For more help, refer to README.md or the inline code documentation.

backend/DISCORD_BOT_EXAMPLE.py

@@ -0,0 +1,277 @@
+"""
+Example: Integrating the Deepfake Detection Backend with Discord Bot
+
+This example shows how to call the backend API from a Discord bot.
+"""
+
+import discord
+from discord.ext import commands
+import httpx
+import asyncio
+from typing import Optional
+
+# Backend configuration
+BACKEND_URL = "http://127.0.0.1:8000"
+BACKEND_TIMEOUT = 60  # seconds
+
+
+class DeepfakeDetector(commands.Cog):
+    """Discord bot cog for deepfake detection."""
+    
+    def __init__(self, bot: commands.Bot):
+        self.bot = bot
+        self.backend_url = BACKEND_URL
+        self.http_client = None
+    
+    @commands.Cog.listener()
+    async def on_ready(self):
+        """Initialize HTTP client when bot is ready."""
+        if self.http_client is None:
+            self.http_client = httpx.AsyncClient(timeout=BACKEND_TIMEOUT)
+        print(f"Deepfake detector loaded - Backend: {self.backend_url}")
+    
+    async def analyze_url(self, file_url: str, model: str = "mock") -> Optional[dict]:
+        """
+        Send a file URL to the backend for deepfake analysis.
+        
+        Args:
+            file_url: URL of the file to analyze
+            model: Model to use for detection
+            
+        Returns:
+            Analysis result or None if failed
+        """
+        try:
+            if self.http_client is None:
+                self.http_client = httpx.AsyncClient(timeout=BACKEND_TIMEOUT)
+            
+            response = await self.http_client.post(
+                f"{self.backend_url}/analyze",
+                json={"file_url": file_url, "model": model},
+            )
+            
+            if response.status_code == 200:
+                return response.json()
+            else:
+                print(f"Backend error: {response.status_code} - {response.text}")
+                return None
+        except Exception as e:
+            print(f"Failed to analyze: {e}")
+            return None
+    
+    @commands.command(name="deepfake_check")
+    async def deepfake_check(self, ctx: commands.Context, url: str):
+        """
+        Check if a file at the given URL is a deepfake.
+        
+        Usage:
+            !deepfake_check https://example.com/video.mp4
+        """
+        # Validate URL format
+        if not url.startswith(("http://", "https://")):
+            await ctx.send("❌ Invalid URL. Please provide a valid HTTP(S) URL.")
+            return
+        
+        # Show loading message
+        async with ctx.typing():
+            # Check if backend is running
+            try:
+                health_response = await self.http_client.get(f"{self.backend_url}/")
+                if health_response.status_code != 200:
+                    await ctx.send("❌ Backend service is not responding. Please try again later.")
+                    return
+            except Exception as e:
+                await ctx.send(f"❌ Cannot connect to backend service: {e}")
+                return
+            
+            # Analyze the file
+            await ctx.send(f"🔍 Analyzing file from: {url}\nThis may take a moment...")
+            
+            result = await self.analyze_url(url)
+            
+            if result is None:
+                await ctx.send("❌ Analysis failed. Please check the URL and try again.")
+                return
+        
+        # Format and display results
+        is_deepfake = result["is_deepfake"]
+        confidence = result["confidence"]
+        analysis_time = result["analysis_time"]
+        model_used = result.get("model_used", "unknown")
+        
+        # Create embed for nice formatting
+        embed = discord.Embed(
+            title="🔬 Deepfake Detection Result",
+            color=discord.Color.red() if is_deepfake else discord.Color.green(),
+        )
+        
+        embed.add_field(
+            name="Detection Result",
+            value="⚠️ **DEEPFAKE DETECTED**" if is_deepfake else "✅ **AUTHENTIC**",
+            inline=False,
+        )
+        
+        embed.add_field(
+            name="Confidence",
+            value=f"{confidence:.1%}",
+            inline=True,
+        )
+        
+        embed.add_field(
+            name="Analysis Time",
+            value=f"{analysis_time:.2f}s",
+            inline=True,
+        )
+        
+        embed.add_field(
+            name="Model Used",
+            value=model_used,
+            inline=True,
+        )
+        
+        embed.set_footer(text="Analysis performed by Deepfake Detection Service")
+        
+        await ctx.send(embed=embed)
+    
+    @commands.command(name="backend_status")
+    async def backend_status(self, ctx: commands.Context):
+        """Check the status of the deepfake detection backend."""
+        try:
+            async with ctx.typing():
+                response = await self.http_client.get(f"{self.backend_url}/")
+                
+                if response.status_code == 200:
+                    data = response.json()
+                    embed = discord.Embed(
+                        title="🟢 Backend Status",
+                        color=discord.Color.green(),
+                    )
+                    embed.add_field(
+                        name="Service",
+                        value=data["service"],
+                        inline=True,
+                    )
+                    embed.add_field(
+                        name="Version",
+                        value=data["version"],
+                        inline=True,
+                    )
+                    embed.add_field(
+                        name="Available Models",
+                        value=", ".join(data["available_models"]),
+                        inline=False,
+                    )
+                    await ctx.send(embed=embed)
+                else:
+                    await ctx.send("❌ Backend is not responding properly.")
+        except Exception as e:
+            await ctx.send(f"❌ Cannot connect to backend: {e}")
+    
+    async def cog_unload(self):
+        """Cleanup when cog is unloaded."""
+        if self.http_client:
+            await self.http_client.aclose()
+
+
+# Setup function to add this cog to your bot
+async def setup(bot: commands.Bot):
+    """Add the deepfake detector cog to the bot."""
+    await bot.add_cog(DeepfakeDetector(bot))
+
+
+# ============================================================================
+# EXAMPLE BOT IMPLEMENTATION
+# ============================================================================
+
+# If you want to use this as a standalone bot, here's how:
+
+# bot = commands.Bot(command_prefix="!", intents=discord.Intents.default())
+
+# @bot.event
+# async def on_ready():
+#     print(f"Bot logged in as {bot.user}")
+
+# async def main():
+#     async with bot:
+#         await setup(bot)
+#         await bot.start("YOUR_BOT_TOKEN")
+
+# if __name__ == "__main__":
+#     asyncio.run(main())
+
+# ============================================================================
+# USAGE IN YOUR BOT
+# ============================================================================
+
+# 1. Save this file as: discord_bot_example.py or similar
+# 
+# 2. In your main bot file, add:
+#    
+#    from discord_bot_example import setup
+#    
+#    async def main():
+#        async with bot:
+#            await setup(bot)  # Load the deepfake detector cog
+#            await bot.start(TOKEN)
+#
+# 3. Start the backend server:
+#    cd backend
+#    python main.py
+#
+# 4. Run your Discord bot
+#
+# 5. In Discord, use the commands:
+#    !deepfake_check https://example.com/video.mp4
+#    !backend_status
+
+# ============================================================================
+# COMMAND EXAMPLES
+# ============================================================================
+
+# !deepfake_check https://example.com/suspicious_video.mp4
+#   Analyzes the video at the given URL for deepfake content
+#
+# !backend_status
+#   Shows the current status and available models of the backend
+
+# ============================================================================
+# API RESPONSE HANDLING
+# ============================================================================
+
+# The backend returns responses like:
+# {
+#   "is_deepfake": true,
+#   "confidence": 0.847,
+#   "analysis_time": 1.234,
+#   "model_used": "mock"
+# }
+#
+# Error responses:
+# {
+#   "error": "Invalid URL format",
+#   "status_code": 400,
+#   "details": null
+# }
+
+# ============================================================================
+# CUSTOMIZATION OPTIONS
+# ============================================================================
+
+# 1. Change model selection:
+#    await detector.analyze_url(url, model="deepseek")
+#
+# 2. Add custom formatting:
+#    - Modify the embed creation in deepfake_check()
+#    - Add database logging of results
+#    - Notify admins of detected deepfakes
+#
+# 3. Add rate limiting:
+#    - Use discord.ext.commands.cooldown decorator
+#    - Implement per-user/channel limits
+#
+# 4. Add file upload support:
+#    - Check message attachments
+#    - Upload to temporary storage
+#    - Generate URL for backend analysis
+
+print("Discord Bot Deepfake Detector Example - Ready to integrate!")

backend/README.md

@@ -0,0 +1,332 @@
+# 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:**
+   ```bash
+   cd backend
+   ```
+
+2. **Create a virtual environment (recommended):**
+   ```bash
+   # Using venv
+   python -m venv venv
+   
+   # Activate virtual environment
+   # On Windows:
+   venv\Scripts\activate
+   # On macOS/Linux:
+   source venv/bin/activate
+   ```
+
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Run the server:**
+   ```bash
+   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
+```bash
+GET /
+```
+
+Returns service status and available models.
+
+**Response:**
+```json
+{
+  "status": "ok",
+  "service": "Deepfake Detection Service",
+  "version": "1.0.0",
+  "available_models": ["mock"]
+}
+```
+
+### Analyze File
+```bash
+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):**
+```json
+{
+  "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:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` with your settings:
+
+```env
+# 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/`:
+
+```python
+# 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`:
+
+```python
+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:
+```bash
+LOG_LEVEL=DEBUG  # For verbose logging
+```
+
+## 🧪 Testing the API
+
+### Using curl:
+```bash
+curl -X POST http://localhost:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{"file_url": "https://example.com/video.mp4"}'
+```
+
+### Using Python requests:
+```python
+import requests
+
+response = requests.post(
+    "http://localhost:8000/analyze",
+    json={"file_url": "https://example.com/video.mp4"}
+)
+print(response.json())
+```
+
+### Using httpx (async):
+```python
+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:
+
+```python
+# 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:**
+```bash
+# Change port via environment variable
+PORT=8001 python main.py
+```
+
+**Import errors:**
+```bash
+# 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:**
+```bash
+# 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.

backend/app/__init__.py

@@ -0,0 +1,36 @@
+"""Deepfake Detection Service Application"""
+
+from fastapi import FastAPI
+from app.api.routes import router as api_router
+from app.core.logging_config import setup_logging
+from app.core.config import Settings
+
+__version__ = Settings.APP_VERSION or "1.0.0"
+
+
+def create_app() -> FastAPI:
+    """Create and configure the FastAPI application."""
+    setup_logging()
+    
+    app = FastAPI(
+        title="Deepfake Detection Service",
+        description="Backend service for deepfake detection with support for multiple ML models",
+        version=__version__,
+    )
+    
+    # Include API routes
+    app.include_router(api_router)
+    
+    @app.on_event("startup")
+    async def startup_event():
+        import logging
+        logger = logging.getLogger(__name__)
+        logger.info("Deepfake Detection Service is starting up...")
+    
+    @app.on_event("shutdown")
+    async def shutdown_event():
+        import logging
+        logger = logging.getLogger(__name__)
+        logger.info("Deepfake Detection Service is shutting down...")
+    
+    return app

backend/app/api/__init__.py

@@ -0,0 +1 @@
+"""API routes and endpoints."""

backend/app/api/routes.py

@@ -0,0 +1,127 @@
+"""API route handlers."""
+
+import logging
+from fastapi import APIRouter, HTTPException
+
+from app.models.schemas import (
+    AnalysisRequest,
+    AnalysisResponse,
+    ErrorResponse,
+    HealthResponse,
+)
+from app.services.download import download_file
+from app.services.detector import get_detector
+from app.core.config import get_settings
+from app.utils.exceptions import DeepfakeDetectionError
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get(
+    "/",
+    response_model=HealthResponse,
+    tags=["Health"],
+    summary="Health check endpoint",
+)
+async def health_check() -> HealthResponse:
+    """
+    Health check endpoint to verify service is running.
+    
+    Returns:
+        Service status and version information
+    """
+    settings = get_settings()
+    logger.info("Health check endpoint accessed")
+    
+    available_models = ["mock"]  # Add more as you implement them
+    
+    return HealthResponse(
+        status="ok",
+        service="Deepfake Detection Service",
+        version=settings.APP_VERSION,
+        available_models=available_models,
+    )
+
+
+@router.post(
+    "/analyze",
+    response_model=AnalysisResponse,
+    responses={
+        400: {"model": ErrorResponse, "description": "Bad request"},
+        408: {"model": ErrorResponse, "description": "Request timeout"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+    tags=["Analysis"],
+    summary="Analyze file for deepfake detection",
+)
+async def analyze(request: AnalysisRequest) -> AnalysisResponse:
+    """
+    Analyze a file for deepfake detection.
+    
+    Args:
+        request: AnalysisRequest containing file_url and optional model selection
+        
+    Returns:
+        AnalysisResponse with detection results
+        
+    Raises:
+        HTTPException: For various error conditions during processing
+    """
+    settings = get_settings()
+    detector_model = request.model or settings.DEFAULT_DETECTOR_MODEL
+    
+    logger.info(
+        f"Received analysis request for URL: {request.file_url} "
+        f"using model: {detector_model}"
+    )
+    
+    try:
+        try:
+            detector = get_detector(detector_model)
+        except ValueError as e:
+            logger.error(f"Invalid detector model: {str(e)}")
+            raise HTTPException(
+                status_code=400,
+                detail=str(e),
+            )
+        
+        file_bytes = await download_file(str(request.file_url))
+        
+        if not file_bytes:
+            logger.error("File download returned empty bytes")
+            raise HTTPException(
+                status_code=500,
+                detail="Failed to download and process file",
+            )
+        
+        analysis_result = await detector.detect(file_bytes)
+        
+        logger.info(
+            f"Analysis request completed successfully. "
+            f"File URL: {request.file_url}, Model: {detector_model}, "
+            f"Result: {analysis_result}"
+        )
+        
+        return AnalysisResponse(
+            is_deepfake=analysis_result["is_deepfake"],
+            confidence=analysis_result["confidence"],
+            analysis_time=analysis_result["analysis_time"],
+            model_used=detector_model,
+        )
+        
+    except HTTPException:
+        raise
+    except DeepfakeDetectionError as e:
+        logger.error(f"Detection error: {e.message}")
+        raise HTTPException(
+            status_code=e.status_code,
+            detail=e.message,
+        )
+    except Exception as e:
+        logger.error(f"Unexpected error during analysis: {str(e)}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail="An unexpected error occurred during analysis. Please try again later.",
+        )

backend/app/core/__init__.py

@@ -0,0 +1 @@
+"""Core application configuration and setup."""

backend/app/core/config.py

@@ -0,0 +1,39 @@
+import os
+from typing import Optional
+from functools import lru_cache
+
+
+class Settings:
+    """Application settings with environment variable support."""
+    
+    # Application
+    APP_NAME: str = "Deepfake Detection Service"
+    APP_VERSION: str = "1.0.0"
+    DEBUG: bool = os.getenv("DEBUG", "True").lower() == "true"
+    
+    # Server
+    HOST: str = os.getenv("HOST", "127.0.0.1")
+    PORT: int = int(os.getenv("PORT", "8000"))
+    
+    # File handling
+    DOWNLOAD_TIMEOUT: int = int(os.getenv("DOWNLOAD_TIMEOUT", "30"))
+    MAX_FILE_SIZE: int = int(os.getenv("MAX_FILE_SIZE", str(100 * 1024 * 1024)))  # 100 MB
+    
+    # ML Model configuration
+    DEFAULT_DETECTOR_MODEL: str = os.getenv("DEFAULT_DETECTOR_MODEL", "mock")
+    # Supported models: "mock", "deepseek", "openai", etc. (easy to add more)
+    
+    # Redis configuration (for future queuing)
+    REDIS_ENABLED: bool = os.getenv("REDIS_ENABLED", "False").lower() == "true"
+    REDIS_URL: str = os.getenv("REDIS_URL", "redis://localhost:6379")
+    REDIS_QUEUE_NAME: str = os.getenv("REDIS_QUEUE_NAME", "deepfake_analysis")
+    
+    # Logging
+    LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
+    LOG_FILE: Optional[str] = os.getenv("LOG_FILE", None)
+
+
+@lru_cache()
+def get_settings() -> Settings:
+    """Get cached application settings."""
+    return Settings()

backend/app/core/logging_config.py

@@ -0,0 +1,35 @@
+import logging
+import logging.handlers
+from app.core.config import get_settings
+
+
+def setup_logging():
+    """Configure logging for the application."""
+    settings = get_settings()
+    
+    # Create logger
+    logger = logging.getLogger()
+    logger.setLevel(getattr(logging, settings.LOG_LEVEL))
+    
+    # Remove existing handlers
+    logger.handlers.clear()
+    
+    # Console handler
+    console_handler = logging.StreamHandler()
+    console_handler.setLevel(getattr(logging, settings.LOG_LEVEL))
+    formatter = logging.Formatter(
+        "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+    )
+    console_handler.setFormatter(formatter)
+    logger.addHandler(console_handler)
+    
+    # File handler (if specified)
+    if settings.LOG_FILE:
+        file_handler = logging.handlers.RotatingFileHandler(
+            settings.LOG_FILE,
+            maxBytes=10485760,  # 10 MB
+            backupCount=5,
+        )
+        file_handler.setLevel(getattr(logging, settings.LOG_LEVEL))
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)

backend/app/models/__init__.py

@@ -0,0 +1 @@
+"""Data models and schemas."""

backend/app/models/schemas.py

@@ -0,0 +1,76 @@
+from pydantic import BaseModel, HttpUrl, Field
+from typing import Optional
+
+
+class AnalysisRequest(BaseModel):
+    """Request model for deepfake analysis."""
+    
+    file_url: HttpUrl = Field(
+        ..., description="URL of the file to analyze for deepfake detection"
+    )
+    model: Optional[str] = Field(
+        None, description="Detector model to use (e.g., 'mock', 'deepseek', 'openai')"
+    )
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "file_url": "https://example.com/video.mp4",
+                "model": "mock"
+            }
+        }
+
+
+class AnalysisResponse(BaseModel):
+    """Response model for deepfake analysis results."""
+    
+    is_deepfake: bool = Field(
+        ..., description="Whether the file is detected as a deepfake"
+    )
+    confidence: float = Field(
+        ..., ge=0.0, le=1.0, description="Confidence score between 0.0 and 1.0"
+    )
+    analysis_time: float = Field(
+        ..., description="Time taken for analysis in seconds"
+    )
+    model_used: str = Field(
+        ..., description="The detector model that was used"
+    )
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "is_deepfake": True,
+                "confidence": 0.847,
+                "analysis_time": 1.234,
+                "model_used": "mock"
+            }
+        }
+
+
+class ErrorResponse(BaseModel):
+    """Response model for errors."""
+    
+    error: str = Field(..., description="Error message")
+    status_code: int = Field(..., description="HTTP status code")
+    details: Optional[str] = Field(
+        None, description="Additional error details"
+    )
+    
+    class Config:
+        json_schema_extra = {
+            "example": {
+                "error": "Invalid URL format",
+                "status_code": 400,
+                "details": "The provided file_url is not a valid URL"
+            }
+        }
+
+
+class HealthResponse(BaseModel):
+    """Response model for health check."""
+    
+    status: str = Field(..., description="Service status")
+    service: str = Field(..., description="Service name")
+    version: str = Field(..., description="Service version")
+    available_models: list = Field(..., description="Available detector models")

backend/app/services/__init__.py

@@ -0,0 +1 @@
+"""Service layer for business logic."""

backend/app/services/detector/__init__.py

@@ -0,0 +1,37 @@
+"""Detector models for deepfake detection."""
+
+from app.services.detector.base import BaseDetector
+from app.services.detector.mock import MockDetector
+
+__all__ = ["BaseDetector", "MockDetector", "get_detector"]
+
+
+def get_detector(model_name: str = "mock") -> BaseDetector:
+    """
+    Factory function to get detector instance by model name.
+    
+    Args:
+        model_name: Name of the detector model
+        
+    Returns:
+        Instance of the requested detector
+        
+    Raises:
+        ValueError: If model is not supported
+    """
+    detectors = {
+        "mock": MockDetector,
+        # Future models:
+        # "deepseek": DeepseekDetector,
+        # "openai": OpenAIDetector,
+        # "huggingface": HuggingFaceDetector,
+    }
+    
+    if model_name not in detectors:
+        available = ", ".join(detectors.keys())
+        raise ValueError(
+            f"Detector model '{model_name}' is not supported. "
+            f"Available models: {available}"
+        )
+    
+    return detectors[model_name]()

backend/app/services/detector/base.py

@@ -0,0 +1,38 @@
+"""Base detector class defining the interface for all detectors."""
+
+from abc import ABC, abstractmethod
+from typing import Dict, Any
+
+
+class BaseDetector(ABC):
+    """
+    Abstract base class for deepfake detectors.
+    
+    All detector implementations should inherit from this class and implement
+    the detect() method.
+    """
+    
+    def __init__(self, model_name: str):
+        """
+        Initialize the detector.
+        
+        Args:
+            model_name: Name of the detector model
+        """
+        self.model_name = model_name
+    
+    @abstractmethod
+    async def detect(self, file_bytes: bytes) -> Dict[str, Any]:
+        """
+        Detect if file is a deepfake.
+        
+        Args:
+            file_bytes: The file contents as bytes
+            
+        Returns:
+            Dictionary containing:
+            - is_deepfake: Boolean indicating if file is a deepfake
+            - confidence: Float between 0.0 and 1.0
+            - analysis_time: Float representing processing time
+        """
+        pass

backend/app/services/detector/mock.py

@@ -0,0 +1,56 @@
+"""Mock detector implementation for testing and development."""
+
+import asyncio
+import logging
+import time
+from typing import Dict, Any
+
+from app.services.detector.base import BaseDetector
+
+logger = logging.getLogger(__name__)
+
+
+class MockDetector(BaseDetector):
+    """
+    Mock detector for testing and development.
+    
+    Simulates deepfake detection without requiring actual ML models.
+    """
+    
+    def __init__(self):
+        """Initialize the mock detector."""
+        super().__init__("mock")
+    
+    async def detect(self, file_bytes: bytes) -> Dict[str, Any]:
+        """
+        Simulate deepfake detection with a random result.
+        
+        Args:
+            file_bytes: The file contents as bytes
+            
+        Returns:
+            Dictionary with is_deepfake, confidence, and analysis_time
+        """
+        logger.info("Starting mock deepfake analysis...")
+        
+        start_time = time.time()
+        
+        # Simulate processing delay (1 to 2 seconds)
+        delay = 1.0 + (hash(file_bytes) % 100) / 100.0
+        await asyncio.sleep(delay)
+        
+        analysis_time = time.time() - start_time
+        
+        # Simulate ML model output (deterministic based on file content hash)
+        file_hash = hash(file_bytes) % 100
+        is_deepfake = file_hash > 50  # ~50% chance
+        confidence = (file_hash % 100) / 100.0
+        
+        result = {
+            "is_deepfake": is_deepfake,
+            "confidence": round(confidence, 3),
+            "analysis_time": round(analysis_time, 3),
+        }
+        
+        logger.info(f"Mock analysis completed. Result: {result}")
+        return result

backend/app/services/download.py

@@ -0,0 +1,92 @@
+import logging
+import httpx
+
+from app.core.config import get_settings
+from app.utils.exceptions import (
+    FileDownloadError,
+    InvalidURLError,
+    DownloadTimeoutError,
+    FileSizeError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+async def download_file(file_url: str) -> bytes:
+    """
+    Asynchronously download a file from the given URL.
+    
+    Args:
+        file_url: The URL of the file to download
+        
+    Returns:
+        The file contents as bytes
+        
+    Raises:
+        InvalidURLError: If the URL is invalid
+        DownloadTimeoutError: If download times out
+        FileSizeError: If file size exceeds limit
+        FileDownloadError: If download fails for other reasons
+    """
+    settings = get_settings()
+    logger.info(f"Starting file download from: {file_url}")
+    
+    try:
+        async with httpx.AsyncClient(timeout=settings.DOWNLOAD_TIMEOUT) as client:
+            response = await client.get(file_url, follow_redirects=True)
+            
+            # Check for HTTP errors
+            if response.status_code != 200:
+                logger.error(
+                    f"Failed to download file. Status code: {response.status_code}"
+                )
+                raise FileDownloadError(
+                    f"Failed to download file. Server returned status code {response.status_code}",
+                    status_code=response.status_code,
+                )
+            
+            # Check content length header
+            content_length = response.headers.get("content-length")
+            if content_length and int(content_length) > settings.MAX_FILE_SIZE:
+                logger.error(
+                    f"File size exceeds maximum allowed size: {content_length} bytes"
+                )
+                raise FileSizeError(
+                    f"File size exceeds maximum allowed size of {settings.MAX_FILE_SIZE} bytes"
+                )
+            
+            file_bytes = response.content
+            
+            # Check actual content size
+            if len(file_bytes) > settings.MAX_FILE_SIZE:
+                logger.error(
+                    f"Downloaded file exceeds maximum size: {len(file_bytes)} bytes"
+                )
+                raise FileSizeError(
+                    f"File size exceeds maximum allowed size of {settings.MAX_FILE_SIZE} bytes"
+                )
+            
+            logger.info(
+                f"File download completed successfully. Size: {len(file_bytes)} bytes"
+            )
+            return file_bytes
+            
+    except httpx.InvalidURL as e:
+        logger.error(f"Invalid URL provided: {file_url} - {str(e)}")
+        raise InvalidURLError("Invalid URL format")
+    except httpx.TimeoutException as e:
+        logger.error(f"Download timeout for URL: {file_url}")
+        raise DownloadTimeoutError("File download timed out. Please try again with a faster source.")
+    except (FileSizeError, InvalidURLError, DownloadTimeoutError):
+        # Re-raise custom exceptions
+        raise
+    except httpx.RequestError as e:
+        logger.error(f"Failed to download file from {file_url}: {str(e)}")
+        raise FileDownloadError(
+            "Failed to download file from the provided URL. Please check the URL and try again."
+        )
+    except Exception as e:
+        logger.error(f"Unexpected error during file download: {str(e)}")
+        raise FileDownloadError(
+            "An unexpected error occurred during file download."
+        )

backend/app/services/queue.py

@@ -0,0 +1,97 @@
+import logging
+from typing import Optional, Any, Dict
+import json
+
+from app.core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+class QueueService:
+    """
+    Queue service for managing asynchronous analysis tasks.
+    
+    Currently uses in-memory queue, can be extended to use Redis.
+    """
+    
+    def __init__(self):
+        """Initialize the queue service."""
+        self.settings = get_settings()
+        self.redis_client = None
+        
+        if self.settings.REDIS_ENABLED:
+            self._initialize_redis()
+    
+    def _initialize_redis(self):
+        """Initialize Redis connection (future implementation)."""
+        # This will be implemented when Redis support is added
+        logger.info(
+            f"Redis queue service initialized: {self.settings.REDIS_URL}"
+        )
+    
+    async def enqueue_analysis(
+        self,
+        file_url: str,
+        model: str,
+        task_id: str,
+    ) -> bool:
+        """
+        Enqueue an analysis task.
+        
+        Args:
+            file_url: URL of the file to analyze
+            model: Detector model to use
+            task_id: Unique task identifier
+            
+        Returns:
+            True if successful, False otherwise
+        """
+        task_data = {
+            "task_id": task_id,
+            "file_url": file_url,
+            "model": model,
+        }
+        
+        logger.info(f"Enqueuing analysis task: {task_id}")
+        
+        if self.settings.REDIS_ENABLED:
+            # Future: Push to Redis queue
+            # await self.redis_client.lpush(
+            #     self.settings.REDIS_QUEUE_NAME,
+            #     json.dumps(task_data)
+            # )
+            pass
+        
+        return True
+    
+    async def get_task_result(self, task_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get analysis result for a task.
+        
+        Args:
+            task_id: Task identifier
+            
+        Returns:
+            Analysis result or None if not found
+        """
+        logger.info(f"Retrieving result for task: {task_id}")
+        
+        if self.settings.REDIS_ENABLED:
+            # Future: Get from Redis
+            # result = await self.redis_client.get(f"result:{task_id}")
+            # return json.loads(result) if result else None
+            pass
+        
+        return None
+
+
+# Singleton instance
+_queue_service: Optional[QueueService] = None
+
+
+def get_queue_service() -> QueueService:
+    """Get or create the queue service singleton."""
+    global _queue_service
+    if _queue_service is None:
+        _queue_service = QueueService()
+    return _queue_service

backend/app/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions and exception classes."""

backend/app/utils/exceptions.py

@@ -0,0 +1,53 @@
+"""Custom exception classes."""
+
+
+class DeepfakeDetectionError(Exception):
+    """Base exception for deepfake detection service."""
+    
+    def __init__(self, message: str, status_code: int = 500):
+        self.message = message
+        self.status_code = status_code
+        super().__init__(self.message)
+
+
+class FileDownloadError(DeepfakeDetectionError):
+    """Exception raised when file download fails."""
+    
+    def __init__(self, message: str, status_code: int = 400):
+        super().__init__(message, status_code)
+
+
+class InvalidURLError(DeepfakeDetectionError):
+    """Exception raised when URL is invalid."""
+    
+    def __init__(self, message: str = "Invalid URL format"):
+        super().__init__(message, 400)
+
+
+class DownloadTimeoutError(DeepfakeDetectionError):
+    """Exception raised when file download times out."""
+    
+    def __init__(self, message: str = "File download timed out"):
+        super().__init__(message, 408)
+
+
+class FileSizeError(DeepfakeDetectionError):
+    """Exception raised when file size exceeds limit."""
+    
+    def __init__(self, message: str = "File size exceeds maximum allowed size"):
+        super().__init__(message, 400)
+
+
+class DetectorError(DeepfakeDetectionError):
+    """Exception raised when detector model fails."""
+    
+    def __init__(self, message: str = "Deepfake detection failed"):
+        super().__init__(message, 500)
+
+
+class UnsupportedModelError(DeepfakeDetectionError):
+    """Exception raised when requested model is not supported."""
+    
+    def __init__(self, model_name: str):
+        message = f"Detector model '{model_name}' is not supported"
+        super().__init__(message, 400)

backend/main.py

@@ -0,0 +1,35 @@
+"""
+Deepfake Detection Service - Backend Entry Point
+
+This is the main entry point for the FastAPI application.
+Run this file directly to start the server on localhost:8000
+"""
+
+import logging
+from app import create_app
+from app.core.config import get_settings
+
+logger = logging.getLogger(__name__)
+
+
+def main():
+    """Initialize and run the FastAPI application."""
+    settings = get_settings()
+    app = create_app()
+    
+    import uvicorn
+    
+    logger.info(
+        f"Starting {settings.APP_NAME} on {settings.HOST}:{settings.PORT}"
+    )
+    
+    uvicorn.run(
+        app,
+        host=settings.HOST,
+        port=settings.PORT,
+        log_level=settings.LOG_LEVEL.lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

backend/requirements.txt

@@ -0,0 +1,6 @@
+fastapi==0.115.0
+uvicorn[standard]==0.30.0
+httpx==0.27.0
+pydantic==2.8.2
+pydantic-settings==2.3.1
+python-multipart==0.0.6

backend/run.bat

@@ -0,0 +1,6 @@
+@echo off
+REM Deepfake Detection Service - Windows Run Script
+
+echo Starting Deepfake Detection Service Backend...
+python main.py
+pause

backend/setup.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+"""
+Setup script for the Deepfake Detection Service backend.
+
+Run: python setup.py
+"""
+
+import os
+import sys
+import subprocess
+
+
+def run_command(command, description):
+    """Run a command and handle errors."""
+    print(f"\n{'='*60}")
+    print(f"📍 {description}")
+    print(f"{'='*60}")
+    try:
+        result = subprocess.run(command, shell=True, check=True)
+        return result.returncode == 0
+    except subprocess.CalledProcessError as e:
+        print(f"❌ Error: {description} failed")
+        return False
+
+
+def main():
+    """Setup the development environment."""
+    print("\n" + "="*60)
+    print("🚀 Deepfake Detection Service - Backend Setup")
+    print("="*60)
+    
+    # Check Python version
+    if sys.version_info < (3, 8):
+        print("❌ Python 3.8 or higher is required")
+        sys.exit(1)
+    
+    print(f"✅ Python version: {sys.version}")
+    
+    # Determine OS for venv activation
+    is_windows = sys.platform == "win32"
+    venv_path = "venv"
+    
+    # Create virtual environment
+    if not run_command(
+        f"{sys.executable} -m venv {venv_path}",
+        "Creating virtual environment"
+    ):
+        sys.exit(1)
+    
+    # Activate venv and install dependencies
+    if is_windows:
+        activate_cmd = f"{venv_path}\\Scripts\\activate && pip install -r requirements.txt"
+    else:
+        activate_cmd = f"source {venv_path}/bin/activate && pip install -r requirements.txt"
+    
+    if not run_command(activate_cmd, "Installing dependencies"):
+        sys.exit(1)
+    
+    # Create .env file if it doesn't exist
+    if not os.path.exists(".env"):
+        run_command("copy .env.example .env" if is_windows else "cp .env.example .env",
+                   "Creating .env file from template")
+    
+    print("\n" + "="*60)
+    print("✅ Setup completed successfully!")
+    print("="*60)
+    print("\n📝 Next steps:")
+    print(f"  1. Activate virtual environment:")
+    if is_windows:
+        print(f"     {venv_path}\\Scripts\\activate")
+    else:
+        print(f"     source {venv_path}/bin/activate")
+    print(f"\n  2. Start the server:")
+    print(f"     python main.py")
+    print(f"\n  3. Visit http://127.0.0.1:8000/docs for interactive API docs")
+    print(f"\n  4. Check .env file for configuration options")
+    print("\n" + "="*60)
+
+
+if __name__ == "__main__":
+    main()