Add file upload validation endpoint (#5)

- Create modular router structure (api/routes/upload.py)
- Implement /api/v1/upload/validate endpoint
- Add Pydantic schemas for request/response validation
- Include router in main FastAPI app
- Add comprehensive endpoint tests

Features:
- Async file handling for concurrent uploads
- In-memory processing (zero disk storage)
- Proper error handling and logging
- Auto-generated API documentation

Closes #5

backend/api/routes/__init__.py

@@ -0,0 +1 @@
+"""API routes package."""

backend/api/routes/upload.py

@@ -0,0 +1,73 @@
+"""
+File upload endpoints.
+Why: Separate routing from main.py for scalability.
+"""
+from fastapi import APIRouter, UploadFile, File, HTTPException
+from backend.utils.validators import validate_file, FileValidationError
+from backend.models.schemas import FileValidationResponse, ErrorResponse
+from backend.core.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+# Create router (will be included in main.py)
+router = APIRouter(
+    prefix="/api/v1/upload",
+    tags=["File Upload"]
+)
+
+
+@router.post(
+    "/validate",
+    response_model=FileValidationResponse,
+    responses={400: {"model": ErrorResponse}},
+    summary="Validate uploaded file",
+    description="""
+    Validates file type and size without processing.
+    
+    **Privacy:** File is read into memory and immediately discarded.
+    No files are stored on disk.
+    
+    **Supported types:**
+    - Images: JPEG, PNG, WebP
+    - Videos: MP4, MPEG
+    - Documents: PDF
+    
+    **Max size:** 50MB
+    """
+)
+async def validate_upload(
+    file: UploadFile = File(..., description="File to validate")
+):
+    """
+    Validate uploaded file.
+    
+    Why async?
+    - Non-blocking file read
+    - Handles multiple concurrent uploads
+    - FastAPI best practice
+    """
+    try:
+        # Read file into memory
+        file_bytes = await file.read()
+        logger.info(f"Received file: {file.filename}, size: {len(file_bytes)} bytes")
+        
+        # Validate
+        result = validate_file(file_bytes, file.filename)
+        
+        logger.info(f"Validation successful: {result}")
+        return FileValidationResponse(**result)
+        
+    except FileValidationError as e:
+        logger.warning(f"Validation failed for {file.filename}: {str(e)}")
+        raise HTTPException(status_code=400, detail=str(e))
+        
+    except Exception as e:
+        logger.error(f"Unexpected error validating {file.filename}: {str(e)}")
+        raise HTTPException(
+            status_code=500,
+            detail="Internal server error during file validation"
+        )
+    
+    finally:
+        # Ensure file is closed (privacy - no disk storage)
+        await file.close()

backend/main.py

@@ -1,34 +1,26 @@
 """
 VeriFile-X API - Privacy-preserving digital forensics platform.
-
-Architecture:
-- No file storage (all processing in-memory)
-- Modular services for different analysis types
-- Type-safe request/response models
 """
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from contextlib import asynccontextmanager
-from backend.core.logger import setup_logger
+from datetime import datetime
+
 from backend.core.config import settings
+from backend.core.logger import setup_logger
+from backend.api.routes import upload
 
 logger = setup_logger(__name__)
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    """
-    Startup and shutdown events.
-    Why: Resource initialization (models, connections) and cleanup.
-    """
+    """Startup and shutdown events."""
     logger.info("🚀 VeriFile-X API starting up...")
-    # TODO Phase 5: Load AI models here
     yield
     logger.info("🛑 VeriFile-X API shutting down...")
-    # TODO: Cleanup resources
 
 
-# Initialize FastAPI application
 app = FastAPI(
     title=settings.API_TITLE,
     version=settings.API_VERSION,
@@ -36,7 +28,7 @@ app = FastAPI(
     lifespan=lifespan,
 )
 
-# Configure CORS (Cross-Origin Resource Sharing)
+# CORS
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.CORS_ORIGINS,
@@ -45,26 +37,26 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+# Include routers
+app.include_router(upload.router)
+
 
 @app.get("/")
 async def root():
-    """Root endpoint - API information."""
+    """Root endpoint."""
     return {
         "name": settings.API_TITLE,
         "version": settings.API_VERSION,
         "status": "operational",
-        "docs": "/docs"  # Swagger UI
+        "docs": "/docs"
     }
 
 
 @app.get("/health")
 async def health_check():
-    """
-    Health check endpoint for monitoring.
-    Why: Deployment platforms (Render, AWS) ping this to verify service is alive.
-    """
+    """Health check endpoint."""
     return {
         "status": "healthy",
         "debug_mode": settings.DEBUG,
-        "timestamp": "2025-02-12T21:30:00Z"
+        "timestamp": datetime.now().isoformat()
     }

backend/models/schemas.py

@@ -0,0 +1,23 @@
+"""
+Request/Response schemas for API endpoints.
+Why: Type validation, auto-documentation, IDE support.
+"""
+from pydantic import BaseModel, Field
+from typing import Optional
+
+
+class FileValidationResponse(BaseModel):
+    """Response model for file validation."""
+    valid: bool
+    mime_type: str
+    extension: str
+    size_bytes: int
+    size_mb: float
+    filename: str
+    message: Optional[str] = None
+
+
+class ErrorResponse(BaseModel):
+    """Standard error response."""
+    detail: str = Field(..., description="Error message")
+    error_type: Optional[str] = None

backend/tests/test_upload.py

@@ -0,0 +1,40 @@
+"""
+Tests for file upload endpoint.
+"""
+import pytest
+from io import BytesIO
+
+
+def test_validate_upload_success(client, sample_image_bytes):
+    """Test successful file validation."""
+    files = {"file": ("test.png", BytesIO(sample_image_bytes), "image/png")}
+    
+    response = client.post("/api/v1/upload/validate", files=files)
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert data["valid"] is True
+    assert data["mime_type"] == "image/png"
+    assert data["filename"] == "test.png"
+
+
+def test_validate_upload_invalid_type(client):
+    """Test upload with invalid file type."""
+    files = {"file": ("test.txt", BytesIO(b"Plain text"), "text/plain")}
+    
+    response = client.post("/api/v1/upload/validate", files=files)
+    
+    assert response.status_code == 400
+    assert "not allowed" in response.json()["detail"]
+
+
+def test_validate_upload_too_large(client):
+    """Test upload exceeding size limit."""
+    # Create 60MB file
+    large_file = BytesIO(b"x" * (60 * 1024 * 1024))
+    files = {"file": ("huge.bin", large_file, "application/octet-stream")}
+    
+    response = client.post("/api/v1/upload/validate", files=files)
+    
+    assert response.status_code == 400
+    assert "exceeds limit" in response.json()["detail"]