pahvalentines/CLAUDE.md

CLAUDE.md

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

Important: Read the Spec First

At the start of every session, read /documents/spec.md. It contains the complete technical specification including API endpoints, database schema, background worker logic, and video generation details.

Project Overview

Valentine's Day 2026 AI-powered Pet Love Song Generator Microsite for Pets at Home. Users submit pet info, upload/crop a photo, and receive an AI-generated music video combining their pet photo with a custom song.

Stack: PHP (server-side rendering) + Alpine.js (reactive forms) + Cropper.js (image cropping) | FastAPI + Celery + PostgreSQL + Redis (backend)

Running the Project

# Frontend (PHP)
php -S localhost:8000

# Backend (Docker - recommended)
cd backend && docker compose up --build

# Backend (local venv alternative)
cd backend
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8000

# Run migrations (from backend/)
alembic upgrade head

Project Structure

/                       # PHP frontend pages
├── index.php           # Form page (Alpine.js + Cropper.js)
├── waiting.php         # Loading page with polling
├── result.php          # Results UI with video player
├── header.php          # Shared header
├── footer.php          # Shared footer
├── assets/
│   ├── js/home.js      # Alpine.js form component + SessionManager
│   └── css/style.css   # Complete styling
├── backend/            # FastAPI service
│   ├── app/
│   │   ├── main.py     # FastAPI app entry point
│   │   ├── routers/    # API endpoints (submissions, webhook, results, health)
│   │   ├── models.py   # SQLAlchemy models
│   │   ├── schemas.py  # Pydantic schemas
│   │   └── config.py   # Settings
│   ├── tasks/
│   │   ├── celery_app.py   # Celery configuration + Beat schedule
│   │   └── workers.py      # Background tasks
│   ├── video_generator/    # Video creation script
│   ├── alembic/            # Database migrations
│   └── docker-compose.yml
├── documents/
│   └── spec.md         # Full specification (1166 lines)
└── storage/            # Runtime outputs (uploads/audio/video)

Architecture & Data Flow

1. User submits form → POST /api/submissions → returns session_id
2. Celery Beat picks up pending submissions → sends to Sonauto API
3. Sonauto webhook callback → triggers Celery task chain
4. Task chain: fetch details → download audio → create video (FFmpeg)
5. Frontend polls /api/submissions/{session_id}/status until complete
6. Results page displays video at /api/results/{session_id}

Status Flow

pending → processing → success / fail

Key Patterns

Frontend (Alpine.js)

• Form component petSongForm in assets/js/home.js
• SessionManager module handles localStorage (submission_data key)
• Image cropping: 600x600px JPEG at 0.9 quality
• Rate limiting: 10 submissions per cookie_id (client + server enforced)

Backend (Celery Tasks)

• process_pending_queue: runs every 60s, sends to Sonauto API
• check_credits: runs every 10min, caches in Redis
• check_timeouts: runs every 5min, marks stale submissions as failed
• cleanup_old_files: runs daily at 3 AM, deletes old files

Video Generation

• Uses FFmpeg, generates ~45 frames per rotation cycle
• Streams frames to FFmpeg (no temp files)
• Output: 720x720px MP4, 15fps, rotating vinyl record effect

External Dependencies

• Sonauto API (https://api.sonauto.ai/v1) - AI music generation
• FFmpeg - Video generation (must be installed in Docker/system)

Environment Variables

Copy .env.example to .env and configure:

SONAUTO_API_KEY=your_key_here
WEBHOOK_BASE_URL=https://your-domain.com

Code Style

• PHP/HTML: 4-space indentation, lowercase filenames
• JavaScript: 4-space indentation, semicolons
• Python: snake_case, Pydantic models, FastAPI routers in backend/app/routers/
• Commit style: short imperative subject, sometimes scoped (e.g., result: add video poster)

Workflow

Always commit and push changes immediately after making them. Do not wait for the user to ask - after any code modification, commit with a descriptive message and push to remote.

Testing

No automated test suite. Validate manually:

• Frontend: run PHP server, exercise form flow
• Backend: hit /api/health, simulate submission/status endpoints