CLAUDE.md

# CLAUDE.md

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

## Development Commands

### Running the Application
```bash
# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
uvicorn app:app --host 0.0.0.0 --port 7860

# Alternative development server with reload
uvicorn app:app --reload
```

### Docker Deployment
```bash
# Build the Docker image
docker build -t sportsai .

# Run the container
docker run -p 7860:7860 sportsai
```

### Environment Setup
- Create `.env` file with required environment variables:
  - `API_URL`: External API endpoint URL
  - `API_KEY`: Authentication key for external API
  - `AI_API_TOKEN`: Token for authenticating incoming requests

## Architecture Overview

### Core Components

**FastAPI Application (`app.py`)**
- Main web server with two primary endpoints:
  - `/upload`: General video processing with pose estimation
  - `/exercise/salto_alto`: Specialized high jump exercise analysis
- Uses background tasks for asynchronous video processing
- Handles file uploads and API authentication

**Pose Estimation (`vitpose.py`)**
- Wraps the `rt-pose` library with VitPose model
- Provides pose estimation pipeline with CUDA/CPU support
- Handles video-to-frames conversion and frame annotation
- Automatically rotates landscape videos to portrait orientation

**Video Analysis (`tasks.py`)**
- Contains `process_salto_alto()` function for high jump analysis
- Implements comprehensive jump metrics calculation:
  - Jump height detection using pose keypoints
  - Sayer power estimation
  - Repetition counting
  - Metrics visualization overlay
- Sends results to external API endpoints via webhooks

**Configuration (`config.py`)**
- Manages environment variables and API credentials
- Uses python-dotenv for environment file loading

### Key Features

**High Jump Analysis Pipeline:**
1. Video upload and pose estimation using VitPose
2. Calibration using person height in first frame
3. Jump detection based on ankle movement thresholds
4. Real-time metrics calculation and overlay visualization
5. Results packaging and webhook delivery

**Pose Estimation:**
- Uses PekingU/rtdetr object detection + usyd-community/vitpose-plus-small
- Supports both CUDA and CPU inference
- Model compilation enabled for performance optimization

**Video Processing:**
- Automatic landscape-to-portrait rotation
- Skeleton visualization with keypoint connections
- Metrics overlay with rounded rectangles and real-time updates

### Dependencies
- **FastAPI**: Web framework for API endpoints
- **rt-pose**: Pose estimation pipeline
- **OpenCV**: Video processing and computer vision
- **Supervision**: Keypoint visualization utilities
- **PyTorch**: Deep learning framework for pose models

### File Structure
- `app.py`: Main FastAPI application
- `vitpose.py`: VitPose wrapper class
- `tasks.py`: Video processing and analysis functions
- `config.py`: Environment configuration
- `requirements.txt`: Python dependencies
- `Dockerfile`: Container deployment configuration
- `static/`: Directory for processed video outputs (git-ignored)

### API Authentication
All endpoints require token-based authentication via header or body parameters. Unauthorized requests return 401 status codes.