# CLAUDE.md

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

## Project Overview

This is a Flask-based web application for real-time object detection and tracking using YOLOv11. The application supports both webcam streaming and uploaded video file processing with object detection overlays.

## Key Dependencies

- **Flask**: Web framework for routing and serving HTML templates
- **OpenCV (cv2)**: Video processing and frame manipulation
- **Ultralytics YOLO**: YOLOv11 model for object detection and tracking
- **NumPy**: Array operations for image data

The YOLO model file (`yolo11s.pt`) must be present in the root directory.

## Running the Application

Start the Flask development server:
```bash
python3 app.py
```

The application runs on `0.0.0.0:8080` and is accessible at `http://localhost:8080`

## Application Architecture

### Single-File Structure
The entire application is contained in `app.py` with no separate modules. All routes, video processing logic, and model initialization are in this single file.

### Core Components

**YOLO Model (lines 10-11)**
- Model loaded once at application startup: `model = YOLO("yolo11s.pt")`
- Class names extracted from model for labeling: `names = model.model.names`

**Video Processing Pattern**
Both webcam and uploaded video processing share identical detection logic:
1. Frame skipping: Only processes every 2nd frame (`count % 2 != 0`) for performance
2. Frame resizing: All frames resized to (1020, 600) for consistent output
3. YOLO tracking: Uses `model.track(frame, persist=True)` to maintain object IDs across frames
4. Annotation: Draws bounding boxes and labels with format `{track_id} - {class_name}`
5. Streaming: Yields JPEG frames as multipart HTTP response

**Duplicate Code**
The functions `detect_objects_from_webcam()` (lines 21-52) and `detect_objects_from_video()` (lines 86-118) contain nearly identical logic - only the video source differs (webcam vs. file path).

### Routes and Flow

**Main Routes:**
- `/` - Landing page (index.html) with video upload form and webcam button
- `/start_webcam` - Webcam detection page (webcam.html)
- `/upload` [POST] - Handles video file uploads, saves to `uploads/` directory
- `/uploads/<filename>` - Video playback page (play_video.html)

**Streaming Routes:**
- `/webcam_feed` - Streams processed webcam frames with detections
- `/video_feed/<filename>` - Streams processed video file frames with detections
- `/video/<filename>` - Serves raw video files from uploads directory

### Templates
All templates follow the same pattern:
- Centered layout with flex containers
- Fixed dimensions (1020x600) for video display
- "Back to Home" link for navigation

## Important Notes

**File Uploads**
- Uploaded videos are saved to `uploads/` directory (created automatically if missing)
- No file size limits or validation beyond checking file existence
- No cleanup mechanism for uploaded files

**Performance Optimization**
- Frame skipping (every 2nd frame) reduces CPU load but may miss fast-moving objects
- Frame resizing to 1020x600 is hardcoded throughout

**Object Tracking**
- Uses persistent tracking (`persist=True`) to maintain object IDs across frames
- Track IDs are displayed alongside class names in the format: `{track_id} - {class_name}`
- Tracking state persists within a single video stream session

**Webcam Access**
- Uses `cv2.VideoCapture(0)` for default webcam
- No error handling if webcam is unavailable or already in use