README.md

FastAPI Video Backend

A FastAPI backend for the multi-agent video generation system using Pydantic for data modeling, Clerk for authentication, and Redis for caching and job queuing.

Features

• FastAPI Framework: Modern, fast web framework for building APIs
• Pydantic Models: Data validation and serialization
• Clerk Authentication: Secure user authentication and management
• Redis Integration: Caching and job queue management
• Structured Logging: JSON-formatted logging with structlog
• Environment Configuration: Flexible configuration with Pydantic Settings
• CORS Support: Cross-origin resource sharing configuration
• Health Checks: Built-in health monitoring endpoints
• Testing Suite: Comprehensive test coverage with pytest

Quick Start

Prerequisites

• Python 3.11+
• Redis server
• Clerk account (for authentication)

Installation

1. Clone the repository

   git clone <repository-url>
   cd fastapi-video-backend
   

2. Install dependencies

   pip install -e .
   

3. Set up development environment

   python scripts/setup.py
   

4. Configure environment variables

   Update the .env file with your actual configuration:

   # Required: Get these from your Clerk dashboard
   CLERK_SECRET_KEY=your_actual_clerk_secret_key
   CLERK_PUBLISHABLE_KEY=your_actual_clerk_publishable_key
   
   # Required: Generate a secure secret key
   SECRET_KEY=your_super_secret_key_here
   

5. Start Redis server

   redis-server
   

6. Run the application

   # Development mode
   python -m src.app.main
   
   # Or using the script
   python -m uvicorn src.app.main:app --reload
   

7. Access the API

   • API Documentation: http://localhost:8000/docs
   • Alternative Docs: http://localhost:8000/redoc
   • Health Check: http://localhost:8000/health

Project Structure

src/
├── app/
│   ├── main.py                    # FastAPI application entry point
│   ├── api/                       # API layer
│   │   ├── dependencies.py        # Shared dependencies
│   │   └── v1/                    # API version 1
│   │       ├── videos.py          # Video generation endpoints
│   │       ├── jobs.py            # Job management endpoints
│   │       └── system.py          # System health endpoints
│   ├── core/                      # Core utilities and configurations
│   │   ├── config.py              # Application settings
│   │   ├── redis.py               # Redis connection and utilities
│   │   ├── auth.py                # Clerk authentication utilities
│   │   ├── logger.py              # Logging configuration
│   │   └── exceptions.py          # Custom exceptions
│   ├── services/                  # Business logic layer
│   │   ├── video_service.py       # Video generation business logic
│   │   ├── job_service.py         # Job management logic
│   │   └── queue_service.py       # Redis queue management
│   ├── models/                    # Pydantic models
│   │   ├── job.py                 # Job data models
│   │   ├── video.py               # Video metadata models
│   │   ├── user.py                # User data models
│   │   └── system.py              # System status models
│   ├── middleware/                # Custom middleware
│   │   ├── cors.py                # CORS middleware
│   │   ├── clerk_auth.py          # Clerk authentication middleware
│   │   └── error_handling.py      # Global error handling
│   └── utils/                     # Utility functions
│       ├── file_utils.py          # File handling utilities
│       └── helpers.py             # General helper functions
├── tests/                         # Test suite
└── scripts/                       # Utility scripts

Configuration

The application uses environment-based configuration with Pydantic Settings. All configuration options are documented in .env.example.

Key Configuration Sections

• Application Settings: Basic app configuration
• Server Settings: Host, port, and server options
• Redis Settings: Redis connection and caching configuration
• Clerk Settings: Authentication configuration
• Security Settings: JWT and security configuration
• Logging Settings: Structured logging configuration

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src

# Run specific test file
pytest tests/test_main.py

Code Quality

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

Development Scripts

• python scripts/setup.py - Set up development environment
• python -m src.app.main - Run development server
• pytest - Run test suite

API Documentation

Once the application is running, you can access:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

Health Monitoring

The application includes built-in health check endpoints:

• GET /health - Basic health status
• GET / - Root endpoint with basic information

Logging

The application uses structured logging with configurable output formats:

• Development: Colorized console output
• Production: JSON-formatted logs

Log levels and formats can be configured via environment variables.

Security

• Authentication: Clerk-based JWT authentication
• CORS: Configurable cross-origin resource sharing
• Rate Limiting: Built-in rate limiting support
• Input Validation: Pydantic-based request validation
• Security Headers: Automatic security header injection

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.