mediagateway: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MediaRouter is an open-source unified API gateway for AI video generation providers (OpenAI Sora, Runway, Kling AI). It provides an OpenAI-compatible API with BYOK (Bring Your Own Keys) model, built with FastAPI backend and React frontend.

Development Commands

Quick Start (Recommended - Uses Pre-built Images)

./setup.sh                    # Initial setup - pulls pre-built images automatically
docker compose up -d          # Start all services
docker compose down           # Stop all services
docker compose pull           # Update to latest images
docker compose restart backend   # Restart backend only
docker compose logs -f backend   # View backend logs

Pre-built Docker images are automatically pulled from GitHub Container Registry (ghcr.io). No build time required!

Local Development (Building from Source)

For development when you need to modify code:

# Use local build compose file
docker compose -f docker-compose.local.yml up --build

# Or uncomment "build:" lines in docker-compose.yml and:
docker compose build
docker compose up -d

Local Development (Without Docker)

Backend:

cd backend
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt
python run.py  # Runs on http://localhost:3001

Frontend:

cd frontend
npm install
npm run dev  # Runs on http://localhost:5173 or :3000

Backend with hot reload:

cd backend
uvicorn src.main:app --reload --port 3001

Testing

# Backend tests
cd backend
pytest

# Frontend linting
cd frontend
npm run lint

# Frontend build
npm run build

Architecture Overview

Provider System

Adding a new video provider:

1. Create new file in backend/src/providers/newprovider.py
2. Inherit from VideoProvider base class (see backend/src/providers/base.py)
3. Implement required methods:
   • name property
   • models property
   • validate_key() - Validate API key
   • generate_video() - Start video generation
   • check_status() - Poll generation status
   • get_supported_features() - Declare provider capabilities
4. Register in backend/src/providers/__init__.py:
   • Add to PROVIDERS dict
   • Add models to MODEL_PROVIDER_MAP