veo3/CLAUDE.md

CLAUDE.md

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

Project Overview

This is a full-stack web application for integrating Google's Veo 3.0 video generation model. The project consists of:

• Backend: Flask REST API that interfaces with Google's Gen AI SDK (v1.17.0) for Veo 3.0 video generation
• Frontend: React single-page application with Material-UI components and MSAL authentication
• Storage: Google Cloud Storage for temporary video and image file storage
• Deployment: Production-ready with systemd service and Apache reverse proxy configuration

Key Features

• Text-to-video and image-to-video generation
• Dual model support (Veo 3.0 and Veo 3.0 Fast)
• Real-time progress tracking with job status polling
• Azure AD SSO authentication (with dev mode bypass)
• Automatic file cleanup and download management
• Usage tracking via webhook integration

Project Structure

veo3_poc/
├── backend/                    # Flask backend application
│   ├── routes/                # API routes (api.py, health.py)
│   ├── utils/                 # Utilities (auth.py, storage.py)
│   ├── app.py                # Flask app initialization
│   ├── config.py             # Configuration management
│   ├── video_generator.py   # Core Veo 3.0 integration
│   └── requirements.txt      # Python dependencies
├── frontend/                  # React frontend application
│   ├── src/
│   │   ├── components/       # React components (VideoForm, ProgressIndicator, etc.)
│   │   ├── services/         # API service layer
│   │   └── config/           # MSAL configuration
│   └── package.json          # Node.js dependencies
└── service-account.json       # Google Cloud service account key

Configuration Requirements

Backend Configuration (backend/.env)

The backend uses environment-specific files:

• .env.development: Local development with debug mode and localhost CORS
• .env.production: Production deployment with strict CORS and optimized settings

Key environment variables:

• PROJECT_ID: Google Cloud project ID
• OUTPUT_GCS_BUCKET_NAME: GCS bucket for temporary storage
• REGION: Google Cloud region (us-central1)
• MODEL_ID: Veo model identifier (veo-3.0-generate-preview)
• MODEL_FAST_ID: Veo Fast model identifier (veo-3.0-fast-generate-preview)
• SERVICE_ACCOUNT_KEY_PATH: Path to service account JSON (../service-account.json)
• PORT: Backend server port (7394)
• FRONTEND_URL: Frontend URL for CORS configuration

Frontend Configuration (frontend/.env)

Environment-specific files:

• .env.development: Localhost API, auth bypass enabled (VITE_DEV_MODE=true)
• .env.production: Production API, MSAL authentication enabled

Key environment variables:

• VITE_API_BASE_URL: Backend API URL
• VITE_DEV_MODE: Enable/disable auth bypass
• VITE_MSAL_CLIENT_ID: Azure AD client ID
• VITE_MSAL_AUTHORITY: Azure AD authority URL
• VITE_MSAL_REDIRECT_URI: Authentication redirect URI

Running the Application

Quick Start (Development)

# Run both frontend and backend with one command
./run-dev.sh

# Access:
# Frontend: http://localhost:3000
# Backend API: http://localhost:7394

Manual Start

Backend:

cd backend
cp .env.development .env
python app.py

Frontend:

cd frontend
npm install  # first time only
npm run dev

Production Deployment

1. Build frontend: cd frontend && npm run build
2. Copy dist/ contents to Apache web root
3. Configure systemd service: veo-video-generator.service
4. Configure Apache: apache.conf and apache-htaccess.txt

Key Dependencies

Backend

• flask==3.0.0 - Web framework
• google-genai==1.17.0 - Google Gen AI SDK for Veo 3.0 (replaces deprecated google-generativeai)
• google-cloud-storage==2.12.0 - GCS operations
• Pillow==10.1.0 - Image processing

Frontend

• react==18.2.0 - UI framework
• @mui/material==5.15.1 - Material-UI components
• @azure/msal-react==2.0.7 - Microsoft authentication
• vite==5.0.8 - Build tool

Video Generation Flow

1. User submits request via React frontend (prompt + optional image + parameters)
2. Backend creates job with unique UUID and initializes status tracking
3. Image processing (if provided): validate, convert to JPEG, upload to GCS
4. API call to Google using Gen AI SDK with Veo 3.0 model
5. Backend polls long-running operation every 30 seconds
6. Frontend polls status endpoint every 2 seconds for progress updates
7. Video download from GCS to backend temp storage when complete
8. User downloads video and backend automatically cleans up temp files

Important Implementation Details

• Job tracking: In-memory dictionary (job_status) stores generation status (consider Redis for production scaling)
• Authentication: Azure AD SSO in production, bypassed in dev mode (VITE_DEV_MODE=true)
• File cleanup: Automatic deletion after download, configurable cleanup endpoint
• CORS: Development allows localhost, production restricts to specific domain
• Image formats: All Pillow-supported formats accepted, automatically converted to JPEG
• Model selection: UI allows choosing between Veo 3.0 (high-quality) and Veo 3.0 Fast (optimized)
• Usage tracking: Optional webhook integration sends generation data to external endpoint