Deploy backend to HF with player video visibility fix

.env.example

@@ -0,0 +1,380 @@
+# Supabase configuration
+SUPABASE_URL=your_supabase_url_here
+SUPABASE_KEY=your_supabase_anon_key_here
+SUPABASE_SERVICE_KEY=your_supabase_service_role_key_here
+
+# JWT Configuration
+JWT_SECRET=your_jwt_secret_here
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_MINUTES=1440
+
+# Application settings
+DEBUG=false
+HOST=0.0.0.0
+PORT=8000
+REQUEST_TIMEOUT_SECONDS=120
+
+# CORS (comma-separated list). Example:
+# CORS_ORIGINS=http://localhost:5173,http://localhost:3000,https://yourapp.com
+CORS_ORIGINS=
+
+# File storage
+UPLOAD_DIR=./uploads
+MAX_UPLOAD_SIZE_MB=500
+SERVE_UPLOADS_IN_DEBUG=true
+
+# GPU settings
+GPU_ENABLED=true
+CUDA_DEVICE=0
+
+# Model paths
+PLAYER_DETECTOR_PATH=models/player_detector.pt
+BALL_DETECTOR_PATH=models/ball_detector_model.pt
+COURT_KEYPOINT_DETECTOR_PATH=models/court_keypoint_detector.pt
+POSE_MODEL_PATH=models/yolov8n-pose.pt
+# Train simple CNN model
+
+
+What matters is not just that the model predicts 18 keypoints, but that your backend has a canonical meaning for each index so the system always knows:
+
+which side of the court the point belongs to
+
+whether it is boundary, paint, or midline
+
+where it should land on the tactical map
+
+how to recover if some points are missing or swapped
+
+From your new model:
+
+0 = far left, top boundary
+
+10 = far right, top boundary
+
+5 = far left, bottom boundary
+
+15 = far right, bottom boundary
+
+8 and 9 = centre line top/bottom
+
+2, 3, 6, 7 = left paint box
+
+12, 13, 16, 17 = right paint box
+
+1 and 4 = left baseline inner markers
+
+11 and 14 = right baseline inner markers
+
+So the first thing is: your code must stop treating these as just “18 anonymous points”. It should treat them as a court geometry schema.
+
+Recommended canonical keypoint meaning
+
+Use this exact mapping in code:
+
+COURT_KEYPOINTS = {
+    0: "left_outer_top",
+    1: "left_baseline_upper_inner",
+    2: "left_paint_outer_top",
+    3: "left_paint_outer_bottom",
+    4: "left_baseline_lower_inner",
+    5: "left_outer_bottom",
+
+    6: "left_paint_inner_top",
+    7: "left_paint_inner_bottom",
+
+    8: "midline_top",
+    9: "midline_bottom",
+
+    10: "right_outer_top",
+    11: "right_baseline_upper_inner",
+    12: "right_paint_outer_top",
+    13: "right_paint_outer_bottom",
+    14: "right_baseline_lower_inner",
+    15: "right_outer_bottom",
+
+    16: "right_paint_inner_top",
+    17: "right_paint_inner_bottom",
+}
+
+That gives the model output real meaning.
+
+Very important logic rule
+
+Your system should always think in two spaces:
+
+1. Image space
+
+These are the predicted coordinates from the model:
+
+[(x0, y0), (x1, y1), ..., (x17, y17)]
+2. Court space
+
+These are the fixed coordinates on your tactical board.
+
+For example:
+
+COURT_MODEL_POINTS = {
+    0:  (0, 0),
+    1:  (0, 10),
+    2:  (0, 20),
+    3:  (0, 30),
+    4:  (0, 40),
+    5:  (0, 50),
+
+    6:  (15, 20),
+    7:  (15, 30),
+
+    8:  (47, 0),
+    9:  (47, 50),
+
+    10: (94, 0),
+    11: (94, 10),
+    12: (94, 20),
+    13: (94, 30),
+    14: (94, 40),
+    15: (94, 50),
+
+    16: (79, 20),
+    17: (79, 30),
+}
+
+These values are example tactical-map coordinates using your 94 × 50 style court.
+
+Then your homography becomes:
+
+src = predicted_image_points
+dst = tactical_model_points
+H, _ = cv2.findHomography(src, dst, cv2.RANSAC)
+
+That is what makes player projection work.
+
+The real refinement you need
+
+Your current logic probably assumes:
+
+all points are present
+
+all points are in the correct order
+
+no side confusion happens
+
+That is risky.
+
+You need 4 layers of logic:
+
+1. Semantic index map
+
+Every index must have a fixed court meaning.
+
+2. Side validation
+
+The system should check if left-side points are actually left of right-side points.
+
+Example:
+
+x(0) < x(8) < x(10)
+
+x(5) < x(9) < x(15)
+
+left paint should be left of midline
+
+right paint should be right of midline
+
+3. Structural validation
+
+Check the court shape is geometrically plausible.
+
+Examples:
+
+0 and 10 should be roughly same y-level
+
+5 and 15 should be roughly same y-level
+
+8 should be above 9
+
+2 and 6 should be roughly same y-level
+
+3 and 7 should be roughly same y-level
+
+12 and 16 should be roughly same y-level
+
+13 and 17 should be roughly same y-level
+
+4. Missing-point recovery
+
+If one or two points are low-confidence or absent, use the rest and continue.
+
+Best mental grouping for the 18 points
+
+This helps your code a lot.
+
+Outer boundary
+OUTER_CORNERS = [0, 5, 10, 15]
+Midline
+MIDLINE = [8, 9]
+Left baseline vertical markers
+LEFT_BASELINE_CHAIN = [0, 1, 2, 3, 4, 5]
+Right baseline vertical markers
+RIGHT_BASELINE_CHAIN = [10, 11, 12, 13, 14, 15]
+Left paint box
+LEFT_PAINT = [2, 6, 7, 3]
+Right paint box
+RIGHT_PAINT = [12, 16, 17, 13]
+
+This lets you reason about the court as shapes, not isolated dots.
+
+Adjacency logic you should encode
+
+This is useful for drawing, validation, and debugging.
+
+COURT_EDGES = [
+    (0, 8), (8, 10),          # top boundary
+    (5, 9), (9, 15),          # bottom boundary
+    (0, 1), (1, 2), (2, 3), (3, 4), (4, 5),   # left side chain
+    (10, 11), (11, 12), (12, 13), (13, 14), (14, 15),  # right side chain
+    (8, 9),                   # center line
+    (2, 6), (6, 7), (7, 3),   # left paint
+    (12, 16), (16, 17), (17, 13),  # right paint
+]
+
+This makes your rendered court match the actual geometry in your Roboflow template.
+
+What the model should “know”
+
+The model itself does not truly know basketball meaning unless your logic gives it that meaning.
+
+So after inference, do this:
+
+Step 1: collect points with confidence
+keypoints = [
+    {"id": 0, "x": x0, "y": y0, "conf": c0},
+    ...
+]
+Step 2: attach semantics
+for kp in keypoints:
+    kp["name"] = COURT_KEYPOINTS[kp["id"]]
+    kp["side"] = (
+        "left" if kp["id"] in [0,1,2,3,4,5,6,7]
+        else "right" if kp["id"] in [10,11,12,13,14,15,16,17]
+        else "center"
+    )
+Step 3: validate court orientation
+
+For example:
+
+left average x must be less than centre average x
+
+centre average x must be less than right average x
+
+Step 4: build homography only from valid points
+Strong recommendation: use named coordinates instead of raw index logic everywhere
+
+Instead of this:
+
+p0 = pts[0]
+p1 = pts[1]
+p2 = pts[2]
+
+Do this:
+
+named = {COURT_KEYPOINTS[i]: pts[i] for i in range(len(pts))}
+
+left_outer_top = named["left_outer_top"]
+midline_top = named["midline_top"]
+right_outer_top = named["right_outer_top"]
+
+That makes the whole pipeline easier to debug.
+
+Suggested tactical coordinates for your exact new model
+
+Here is a cleaner court-map layout you can start with:
+
+TACTICAL_POINTS = {
+    0:  (0, 0),
+    1:  (0, 8),
+    2:  (0, 18),
+    3:  (0, 32),
+    4:  (0, 42),
+    5:  (0, 50),
+
+    6:  (18, 18),
+    7:  (18, 32),
+
+    8:  (47, 0),
+    9:  (47, 50),
+
+    10: (94, 0),
+    11: (94, 8),
+    12: (94, 18),
+    13: (94, 32),
+    14: (94, 42),
+    15: (94, 50),
+
+    16: (76, 18),
+    17: (76, 32),
+}
+
+You can tune these to match your SVG court exactly.
+
+Validation function you should add
+
+Something like this:
+
+def validate_court_keypoints(points):
+    """
+    points: dict[int, tuple[float, float]]
+    """
+    errors = []
+
+    required = [0,5,8,9,10,15]
+    for idx in required:
+        if idx not in points:
+            errors.append(f"Missing critical point {idx}")
+
+    if all(k in points for k in [0, 8, 10]):
+        if not (points[0][0] < points[8][0] < points[10][0]):
+            errors.append("Top row x-order invalid")
+
+    if all(k in points for k in [5, 9, 15]):
+        if not (points[5][0] < points[9][0] < points[15][0]):
+            errors.append("Bottom row x-order invalid")
+
+    if all(k in points for k in [8, 9]):
+        if not (points[8][1] < points[9][1]):
+            errors.append("Midline top/bottom order invalid")
+
+    if all(k in points for k in [2, 6]):
+        if not (points[2][0] < points[6][0]):
+            errors.append("Left paint width invalid")
+
+    if all(k in points for k in [16, 12]):
+        if not (points[16][0] < points[12][0]):
+            errors.append("Right paint width invalid")
+
+    return errors
+
+This alone will save you from many bad projections.
+
+Best upgrade for your backend prompt / Antigravity
+
+Tell it this:
+
+The court keypoint model has 18 semantically fixed points. The backend must not treat them as anonymous ordered points only. It must maintain a canonical index-to-court-location mapping, validate court orientation and geometry after inference, and compute homography using only structurally valid keypoints. Missing or low-confidence points should be handled with graceful degradation, and all downstream tactical projection must rely on named semantic court points rather than raw positional assumptions.
+
+In simple terms
+
+Your new logic should understand:
+
+0–5 = left boundary column
+
+10–15 = right boundary column
+
+8 and 9 = centre line
+
+2,3,6,7 = left paint rectangle
+
+12,13,16,17 = right paint rectangle
+
+So yes — your model can still work, but your code now needs a court-geometry interpretation layer, not just raw keypoint indexing.
+
+I can write you the exact Python module for this next: a court_keypoints.py file with mappings, validation, homography preparation, and named-point conversion.

.gitattributes

@@ -0,0 +1,9 @@
+*.png filter=xet diff=xet merge=xet
+*.jpg filter=xet diff=xet merge=xet
+*.jpeg filter=xet diff=xet merge=xet
+*.gif filter=xet diff=xet merge=xet
+*.pt filter=xet diff=xet merge=xet
+*.pth filter=xet diff=xet merge=xet
+*.weights filter=xet diff=xet merge=xet
+*.png filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,62 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+venv/
+ENV/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# dotenv
+.env
+.venv
+
+# pytest
+.pytest_cache/
+
+# mypy
+.mypy_cache/
+
+# Project specific
+models/*.pt
+*.pt
+input_videos/
+output_videos/
+uploads/
+tmp/
+analysis_log.txt
+*.mp4
+*.avi
+*.mov
+
+# IDEs
+.vscode/
+.idea/
+.DS_Store
+stubs/
+*.pkl

DEPLOYMENT.md

@@ -0,0 +1,39 @@
+# BAKO-AI Deployment Guide
+
+This guide explains how to manage and deploy the BAKO-AI analysis pipeline to Hugging Face.
+
+## 🏗 Architecture Overview
+- **Application**: Hosted on Hugging Face Spaces (`icanedit2/BakoAI`).
+- **Models**: Hosted on a dedicated Hugging Face Model Repository (`icanedit2/bakoai-models`).
+- **Storage/DB**: Managed via Supabase.
+
+## 🚀 Deployment Workflow
+
+### 1. Push Code Changes
+To push local changes from the `back-end` folder to the Hugging Face Space root:
+```bash
+# From the root directory:
+git subtree split --prefix back-end -b hf-production-build
+git push hf hf-production-build:main --force
+git branch -D hf-production-build
+```
+
+### 🧠 2. Managing Models
+Models are stored in the `icanedit2/bakoai-models` repository to prevent `git push` from deleting them.
+- To add a new model, upload it to the `bakoai-models` repo.
+- Update `download_models.py` in the Space repo to include the new filename.
+- The build process will automatically download models into `/home/user/app/models/`.
+
+### 🔐 3. Security (Hugging Face Secrets)
+Ensure the following Secrets are set in your Space Settings:
+- `HF_TOKEN`: Required for downloading models from private repositories.
+- `SUPABASE_URL`: Your Supabase project URL.
+- `SUPABASE_KEY`: Your Supabase anonymous/service key.
+- `JWT_SECRET`: For authentication.
+
+## 🎬 Video Playback Optimization
+All annotated videos are processed through FFmpeg with the following settings for maximum browser compatibility:
+- **Codec**: libx264
+- **Pixel Format**: yuv420p
+- **Dimensions**: Forced to even values (H.264 requirement)
+- **Streaming**: `+faststart` enabled for instant playback.

Dockerfile

@@ -0,0 +1,49 @@
+# Use an official Python runtime as a parent image
+FROM python:3.11-slim
+
+# Set environment variables
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    DEBIAN_FRONTEND=noninteractive
+
+# Set the working directory
+WORKDIR /app
+
+# Install system dependencies for OpenCV, PyTesseract, and PDF processing
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    ffmpeg \
+    libsm6 \
+    libxext6 \
+    poppler-utils \
+    tesseract-ocr \
+    libgl1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create a non-root user required by Hugging Face Spaces
+RUN useradd -m -u 1000 user
+
+# Set the working directory
+WORKDIR /app
+
+# Ensure /app is owned by the user so we don't get PermissionError on startup
+RUN chown -R user:user /app
+
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+# Copy requirements first to leverage Docker cache
+COPY --chown=user requirements.txt .
+
+# Install dependencies
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt
+
+# Copy the rest of the application code
+COPY --chown=user . .
+
+# Expose the port Hugging Face Spaces expects
+EXPOSE 7860
+
+# Command to run the application
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]

INDEPENDENT_MODELS_MIGRATION.md

@@ -0,0 +1,91 @@
+# Independent Models Migration
+
+**Date:** February 24, 2026
+
+## Summary
+The system has been updated to use independently trained YOLOv5 models for player and ball detection instead of the combined models.
+
+## Changes Made
+
+### 1. Config Files Updated
+- **`back-end/configs/configs.py`**
+  - `PLAYER_DETECTOR_PATH`: Changed from `TEAM_MODEL_PATH` → `models/player_detector_v1.pt`
+  - `BALL_DETECTOR_PATH`: Changed from `TEAM_MODEL_PATH` → `models/ball_detector_v1.pt`
+
+- **`back-end/app/config.py`**
+  - `player_detector_path`: Updated from `"models/nbl_v3_combined.pt"` → `"models/player_detector_v1.pt"`
+  - `ball_detector_path`: Updated from `"models/nbl_v3_combined.pt"` → `"models/ball_detector_v1.pt"`
+  - `team_model_path`: Now uses `"models/nbl_v4_combined.pt"` (for team analysis)
+  - `personal_model_path`: Still uses `"models/nbl_v2_combined.pt"` (for personal analysis)
+
+- **`back-end/test_system.py`**
+  - Model loader updated to use new independent model paths
+
+### 2. Model Files in Production
+```
+back-end/models/
+├── player_detector_v1.pt      (165 MB) - trained Feb 24 16:23
+├── ball_detector_v1.pt        (165 MB) - trained Feb 24 17:10
+├── court_keypoint_detector.pt (399 MB) - existing
+├── nbl_v3_combined.pt         (165 MB) - kept for reference
+└── nbl_v4_combined.pt         (5.3 MB) - for team analysis
+```
+
+### 3. Training Metrics
+
+#### Player Detector (train5)
+- Model: YOLOv5l6u
+- Epochs: 100
+- mAP50: 0.745
+- mAP50-95: 0.381
+- Per-class performance:
+  - player: 0.851 (mAP50)
+  - hoop: 0.836
+  - referee: 0.802
+  - basketball: 0.744
+  - shot-clock: 0.518
+
+#### Ball Detector (train6)
+- Model: YOLOv5l6u
+- Epochs: 100
+- mAP50: 0.731
+- mAP50-95: 0.403
+- Per-class performance:
+  - player: 0.865 (mAP50)
+  - hoop: 0.909
+  - referee: 0.780
+  - basketball: 0.646
+  - shot-clock: 0.454
+
+### 4. System Components Affected
+The following components now use independent models:
+- `trackers/player_tracker.py` - loads `player_detector_v1.pt`
+- `trackers/ball_tracker.py` - loads `ball_detector_v1.pt`
+- All video analysis pipelines pass the correct model paths via config
+
+### 5. Backward Compatibility
+- Combined models are still available in `models/` for reference
+- `team_analysis.py` still uses team-oriented combined models for compatibility
+- `personal_analysis.py` still uses personal analysis combined models
+
+## Benefits
+1. **Specialized Training**: Each detector trained specifically for its object class
+2. **Better Performance**: Dedicated models allow for task-specific optimization
+3. **Modular Architecture**: Easier to update individual detectors without affecting others
+4. **Production Ready**: Both models trained on identical NBL-6 dataset for consistency
+
+## Rollback Instructions
+If needed, to revert to combined models:
+```python
+# In back-end/configs/configs.py
+PLAYER_DETECTOR_PATH = TEAM_MODEL_PATH  # = 'models/nbl_v4_combined.pt'
+BALL_DETECTOR_PATH = TEAM_MODEL_PATH     # = 'models/nbl_v4_combined.pt'
+```
+
+## Verification
+All imports verified working:
+```python
+from configs import PLAYER_DETECTOR_PATH, BALL_DETECTOR_PATH
+# PLAYER_DETECTOR_PATH = 'models/player_detector_v1.pt' ✓
+# BALL_DETECTOR_PATH = 'models/ball_detector_v1.pt' ✓
+```

QUICK_REFERENCE.md

@@ -0,0 +1,228 @@
+# Basketball Analysis System - Quick Reference
+
+## 🚀 Quick Start Commands
+
+### Using the convenience script (Recommended):
+
+```bash
+# Check if system is ready
+./run.sh --check
+
+# Run analysis on a video
+./run.sh input_videos/video_1.mp4
+
+# Run full system test
+./run.sh --test
+```
+
+### Using Python directly:
+
+```bash
+# Activate virtual environment first
+source venv/bin/activate
+
+# Check system
+python test_system.py --check-only
+
+# Analyze a video
+python main.py input_videos/video_1.mp4
+
+# With custom output
+python main.py input_videos/video_1.mp4 --output_video output_videos/my_output.avi
+```
+
+---
+
+## 📋 System Status
+
+### ✅ Models Ready
+All three pre-trained models from the basketball_analysis repository are installed:
+- `player_detector.pt` - YOLO v11 player detection
+- `ball_detector.pt` - YOLO v5 ball detection with motion blur handling
+- `court_keypoint_detector.pt` - YOLO v8 court keypoint detection
+
+### 📁 Directory Structure
+```
+back-end/
+├── models/              # Pre-trained YOLO models ✓
+├── input_videos/        # Place test videos here
+├── output_videos/       # Analysis results saved here
+├── stubs/              # Cached intermediate results (auto-created)
+├── main.py             # Main analysis pipeline
+├── test_system.py      # System testing script
+├── run.sh              # Convenience script
+└── TESTING_GUIDE.md    # Detailed testing guide
+```
+
+---
+
+## 🎯 What Gets Analyzed
+
+The system performs comprehensive basketball video analysis:
+
+1. **Player Detection & Tracking** - Detects and tracks all players across frames
+2. **Ball Detection & Tracking** - Tracks basketball with interpolation for smooth trajectories
+3. **Court Keypoint Detection** - Identifies court lines, corners, and key zones
+4. **Team Assignment** - Classifies players by jersey color using zero-shot classification
+5. **Ball Possession** - Determines which player has the ball at each moment
+6. **Pass Detection** - Identifies passes between players
+7. **Interception Detection** - Detects when passes are intercepted
+8. **Tactical View** - Creates top-down tactical visualization (mini-map)
+9. **Speed & Distance Calculation** - Calculates player movement metrics
+
+---
+
+## 📊 Output Features
+
+The analyzed video includes overlays for:
+- ✓ Player bounding boxes (color-coded by team)
+- ✓ Ball tracking visualization
+- ✓ Court keypoint markers
+- ✓ Team ball control statistics
+- ✓ Pass and interception indicators
+- ✓ Tactical view (top-down mini-map)
+- ✓ Player speed and distance metrics
+- ✓ Frame numbers
+
+---
+
+## ⚡ Performance Tips
+
+### Speed Optimization
+1. **Use GPU** - System automatically uses CUDA if available
+2. **Use Stubs** - Cached results make re-runs much faster
+3. **Start Small** - Test with short clips (10-30 seconds) first
+4. **Resolution** - Lower resolution videos process faster
+
+### Expected Processing Times
+- **With GPU**: ~1-3 minutes per minute of video
+- **CPU Only**: ~5-15 minutes per minute of video
+- **First Run**: Slower (no cached stubs)
+- **Subsequent Runs**: Much faster (uses cached stubs)
+
+---
+
+## 🎥 Video Requirements
+
+### Recommended Video Characteristics
+- **Format**: MP4 or AVI
+- **Resolution**: 720p or 1080p
+- **Frame Rate**: 30fps or higher
+- **Content**: Clear view of basketball court
+- **Lighting**: Good lighting conditions
+- **Camera**: Stable camera angle (minimal movement)
+
+### What Makes a Good Test Video
+✓ Clear court view
+✓ Multiple players visible
+✓ Ball clearly visible
+✓ Court lines visible
+✓ Stable camera position
+
+---
+
+## 🔧 Troubleshooting
+
+### Dependencies Not Installed
+```bash
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+### CUDA Out of Memory
+The system will automatically fall back to CPU if GPU memory is insufficient.
+
+### Slow Processing
+- Use GPU if available
+- Process shorter clips
+- Enable stub caching (default)
+- Reduce video resolution
+
+### Poor Detection Quality
+- Use higher quality videos
+- Ensure good lighting
+- Use clear court views
+- Avoid extreme camera angles
+
+---
+
+## 📖 Documentation
+
+- **TESTING_GUIDE.md** - Comprehensive testing guide with detailed instructions
+- **test_system.py** - Automated system testing and validation
+- **main.py** - Main analysis pipeline (see code for details)
+
+---
+
+## 🎬 Example Workflow
+
+### First Time Setup
+```bash
+# 1. Check system is ready
+./run.sh --check
+
+# 2. Run test with sample video
+./run.sh --test
+```
+
+### Analyzing Your Own Videos
+```bash
+# 1. Add your video to input_videos/
+cp /path/to/your/video.mp4 input_videos/
+
+# 2. Run analysis
+./run.sh input_videos/your_video.mp4
+
+# 3. Check output
+ls -lh output_videos/analyzed_your_video.avi
+```
+
+### Iterating on Analysis
+```bash
+# First run (slower - creates stubs)
+./run.sh input_videos/video_1.mp4
+
+# Subsequent runs (faster - uses stubs)
+./run.sh input_videos/video_1.mp4
+
+# Force fresh analysis (delete stubs)
+rm -rf stubs/
+./run.sh input_videos/video_1.mp4
+```
+
+---
+
+## 🔍 Verification Checklist
+
+Before deploying or integrating:
+
+- [ ] System check passes (`./run.sh --check`)
+- [ ] Models load successfully
+- [ ] Test video analyzes successfully
+- [ ] Output video is created and viewable
+- [ ] All analysis features visible in output:
+  - [ ] Player detection
+  - [ ] Ball tracking
+  - [ ] Court keypoints
+  - [ ] Team assignment
+  - [ ] Ball possession
+  - [ ] Passes/interceptions
+  - [ ] Tactical view
+  - [ ] Speed/distance metrics
+- [ ] Stub caching works (second run faster)
+
+---
+
+## 📞 Need Help?
+
+1. Check **TESTING_GUIDE.md** for detailed troubleshooting
+2. Run `./run.sh --check` to diagnose issues
+3. Verify all dependencies: `source venv/bin/activate && pip list`
+4. Check error messages in console output
+5. Test with provided sample videos first
+
+---
+
+**System Ready! 🏀**
+
+Start with: `./run.sh --check`

README.md

@@ -0,0 +1,209 @@
+---
+title: BakoAI
+emoji: 🏀
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# 🏀 Basketball Video Analysis
+
+Analyze basketball footage with automated detection of players, ball, team assignment, and more. This repository integrates object tracking, zero-shot classification, and custom keypoint detection for a fully annotated basketball game experience.
+
+Leveraging the convenience of Roboflow for dataset management and Ultralytics' YOLO models for both training and inference, this project provides a robust framework for basketball video analysis.
+
+Training notebooks are included to help you customize and fine-tune models to suit your specific needs, ensuring a seamless and efficient workflow.
+
+## 📁 Table of Contents
+
+1.  [Features](#-features)
+2.  [Prerequisites](#-prerequisites)
+3.  [Demo Video](#-demo-video)
+4.  [Installation](#-installation)
+5.  [Training the Models](#-training-the-models)
+6.  [Usage](#-usage)
+7.  [Project Structure](#-project-structure)
+8.  [Future Work](#-future-work)
+9.  [Contributing](#-contributing)
+10. [License](#-license)
+
+---
+
+## ✨ Features
+
+- Player and ball detection/tracking using pretrained models.
+- Court keypoint detection for visualizing important zones.
+- Team assignment with jersey color classification.
+- Ball possession detection, pass detection, and interception detection.
+- Easy stubbing to skip repeated computation for fast iteration.
+- Various “drawers” to overlay detected elements onto frames.
+
+---
+
+## 🎮 Demo Video
+
+Below is the final annotated output video.
+
+[![BasketBall Analysis Demo Video](https://img.youtube.com/vi/xWpP0LjEUng/0.jpg)](https://youtu.be/xWpP0LjEUng)
+
+## 🔧 Prerequisites
+
+- Python 3.8+
+- (Optional) Docker
+
+---
+
+## ⚙️ Installation
+
+Setup your environment locally or via Docker.
+
+### Python Environment
+
+1. Create a virtual environment (e.g., venv/conda).
+2. Install the required packages:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Docker
+
+#### Build the Docker image:
+
+```bash
+docker build -t basketball-analysis .
+```
+
+#### Verify the image:
+
+```bash
+docker images
+```
+
+## 🎓 Training the Models
+
+Harnessing the powerful tools offered by Roboflow and Ultralytics makes it straightforward to manage datasets, handle annotations, and train advanced object detection models. Roboflow provides an intuitive platform for dataset preprocessing and augmentation, while Ultralytics’ YOLO architectures (v5, v8, and beyond) deliver state-of-the-art detection performance.
+
+This repository relies on trained models for detecting basketballs, players, and court keypoints. You have two options to get these models:
+
+1. Download the Pretrained Weights
+
+   - ball_detector_model.pt  
+     (https://drive.google.com/file/d/1KejdrcEnto2AKjdgdo1U1syr5gODp6EL/view?usp=sharing)
+   - court_keypoint_detector.pt  
+     (https://drive.google.com/file/d/1nGoG-pUkSg4bWAUIeQ8aN6n7O1fOkXU0/view?usp=sharing)
+   - player_detector.pt  
+     (https://drive.google.com/file/d/1fVBLZtPy9Yu6Tf186oS4siotkioHBLHy/view?usp=sharing)
+
+   Simply download these files and place them into the `models/` folder in your project. This allows you to run the pipelines without manually retraining.
+
+2. Train Your Own Models  
+   The training scripts are provided in the `training_notebooks/` folder. These Jupyter notebooks use Roboflow datasets and the Ultralytics YOLO frameworks to train various detection tasks:
+
+   - `basketball_ball_training.ipynb`: Trains a basketball ball detector (using YOLOv5). Incorporates motion blur augmentations to improve ball detection accuracy on fast-moving game footage.
+   - `basketball_court_keypoint_training.ipynb`: Uses YOLOv8 to detect keypoints on the court (e.g., lines, corners, key zones).
+   - `basketball_player_detection_training.ipynb`: Trains a player detection model (using YOLO v11) to identify players in each frame.
+
+   You can easily run these notebooks in Google Colab or another environment with GPU access. After training, download the newly generated `.pt` files and place them in the `models/` folder.
+
+## Once you have your models in place, you may proceed with the usage steps described above. If you want to retrain or fine-tune for your specific dataset, remember to adjust the paths in the notebooks and in `main.py` to point to the newly generated models.
+
+## 🚀 Usage
+
+You can run this repository’s core functionality (analysis pipeline) with Python or Docker.
+
+### 1) Using Python Directly
+
+Run the main entry point with your chosen video file:
+
+```bash
+python main.py path_to_input_video.mp4 --output_video output_videos/output_result.avi
+```
+
+- By default, intermediate “stubs” (pickled detection results) are used if found, allowing you to skip repeated detection/tracking.
+- Use the `--stub_path` flag to specify a custom stub folder, or disable stubs if you want to run everything fresh.
+
+### 2) Using Docker
+
+#### Build the container if not built already:
+
+```bash
+docker build -t basketball-analysis .
+```
+
+#### Run the container, mounting your local input video folder:
+
+```bash
+docker run \
+  -v $(pwd)/videos:/app/videos \
+  -v $(pwd)/output_videos:/app/output_videos \
+  basketball-analysis \
+  python main.py videos/input_video.mp4 --output_video output_videos/output_result.avi
+```
+
+---
+
+## 🏰 Project Structure
+
+- `main.py`  
+  – Orchestrates the entire pipeline: reading video frames, running detection/tracking, team assignment, drawing results, and saving the output video.
+
+- `trackers/`  
+  – Houses `PlayerTracker` and `BallTracker`, which use detection models to generate bounding boxes and track objects across frames.
+
+- `utils/`  
+  – Contains helper functions like `bbox_utils.py` for geometric calculations, `stubs_utils.py` for reading and saving intermediate results, and `video_utils.py` for reading/saving videos.
+
+- `drawers/`  
+  – Contains classes that overlay bounding boxes, court lines, passes, etc., onto frames.
+
+- `ball_aquisition/`  
+  – Logic for identifying which player is in possession of the ball.
+
+- `pass_and_interception_detector/`  
+  – Identifies passing events and interceptions.
+
+- `court_keypoint_detector/`  
+  – Detects lines and keypoints on the court using the specified model.
+
+- `team_assigner/`  
+  – Uses zero-shot classification (Hugging Face or similar) to assign players to teams based on jersey color.
+
+- `configs/`  
+  – Holds default paths for models, stubs, and output video.
+
+---
+
+## 🔮 Future Work
+
+As we continue to enhance the capabilities of this basketball video analysis tool, several areas for future development have been identified:
+
+1. **Integrating a Pose Model for Advanced Rule Detection**  
+   Incorporating a pose detection model could enable the identification of complex basketball rules such as double dribbling and traveling. By analyzing player movements and positions, the system could automatically flag these infractions, adding another layer of analysis to the video footage.
+
+These enhancements will further refine the analysis capabilities and provide users with more comprehensive insights into basketball games.
+
+## 🤝 Contributing
+
+Contributions are welcome!
+
+1. Fork the repository.
+2. Create a new branch for your feature or bug fix.
+3. Submit a pull request with a clear explanation of your changes.
+
+---
+
+## 🐜 License
+
+This project is licensed under the MIT License.  
+See `LICENSE` for details.
+
+---
+
+## 💬 Questions or Feedback?
+
+Feel free to open an issue or reach out via email if you have questions about the project, suggestions for improvements, or just want to say hi!
+
+Enjoy analyzing basketball footage with automatic detection and tracking!

SETUP_COMPLETE.md

@@ -0,0 +1,268 @@
+# 🏀 Basketball Analysis System - Setup Complete! ✅
+
+## System Status: READY FOR TESTING
+
+Your basketball analysis system is now fully configured and ready to test with the pre-trained models from the [basketball_analysis repository](https://github.com/abdullahtarek/basketball_analysis).
+
+---
+
+## ✅ What's Been Set Up
+
+### 1. **Pre-trained Models** (All Downloaded & Verified)
+- ✓ `player_detector.pt` (164.65 MB) - YOLO v11 player detection
+- ✓ `ball_detector_model.pt` (164.67 MB) - YOLO v5 ball detection
+- ✓ `court_keypoint_detector.pt` (398.37 MB) - YOLO v8 court keypoints
+
+### 2. **Dependencies** (All Installed)
+- ✓ OpenCV 4.13.0
+- ✓ NumPy 2.3.5
+- ✓ Pandas 3.0.0
+- ✓ PyTorch 2.10.0+cpu (CPU version for compatibility)
+- ✓ Ultralytics 8.4.9
+- ✓ Supervision 0.27.0
+- ✓ Transformers 5.0.0
+- ✓ Pillow 12.0.0
+
+### 3. **Test Videos Available**
+- ✓ video_1.mp4 (4.24 MB)
+- ✓ video_2.mp4 (6.69 MB)
+- ✓ video_3.mp4 (9.06 MB)
+- ✓ video_4.mp4 (6.60 MB)
+
+### 4. **Testing Scripts Created**
+- ✓ `test_system.py` - Comprehensive system testing
+- ✓ `run.sh` - Convenient bash wrapper
+- ✓ `TESTING_GUIDE.md` - Detailed testing guide
+- ✓ `QUICK_REFERENCE.md` - Quick command reference
+
+---
+
+## 🚀 Quick Start - Test the System Now!
+
+### Option 1: Using the Convenience Script (Easiest)
+
+```bash
+# Navigate to back-end directory
+cd /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end
+
+# Run analysis on first test video
+./run.sh input_videos/video_1.mp4
+```
+
+### Option 2: Using Python Directly
+
+```bash
+# Navigate to back-end directory
+cd /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end
+
+# Activate virtual environment
+source venv/bin/activate
+
+# Run analysis
+python main.py input_videos/video_1.mp4
+```
+
+### Option 3: Using the Test Script
+
+```bash
+cd /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end
+
+source venv/bin/activate
+
+# Run full test
+python test_system.py
+```
+
+---
+
+## 📊 What the Analysis Does
+
+The system performs comprehensive basketball video analysis:
+
+1. **Player Detection & Tracking** - Identifies and tracks all players
+2. **Ball Detection & Tracking** - Tracks basketball with smooth interpolation
+3. **Court Keypoint Detection** - Identifies court lines and zones
+4. **Team Assignment** - Classifies players by jersey color
+5. **Ball Possession** - Determines who has the ball
+6. **Pass Detection** - Identifies passes between players
+7. **Interception Detection** - Detects intercepted passes
+8. **Tactical View** - Creates top-down mini-map
+9. **Speed & Distance** - Calculates player movement metrics
+
+### Output Features
+The analyzed video will include:
+- Player bounding boxes (color-coded by team)
+- Ball tracking visualization
+- Court keypoint overlays
+- Team ball control statistics
+- Pass and interception markers
+- Tactical view (mini-map)
+- Player speed and distance metrics
+- Frame numbers
+
+---
+
+## ⏱️ Expected Processing Time
+
+### First Run (No Cached Data)
+- **CPU Only**: ~5-15 minutes per minute of video
+- The system will create "stubs" (cached intermediate results)
+
+### Subsequent Runs (With Cached Data)
+- **Much Faster**: Reuses cached player/ball detections
+- Only recomputes final visualization
+
+### Performance Tips
+- Start with short clips (10-30 seconds) for faster testing
+- Keep the `stubs/` directory for faster re-runs
+- Delete `stubs/` to force fresh analysis
+
+---
+
+## 📁 Output Location
+
+Analyzed videos will be saved to:
+```
+/home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end/output_videos/
+```
+
+Default output filename: `output_video.avi` (or custom name if specified)
+
+---
+
+## 🎥 Adding Your Own Test Videos
+
+1. Place basketball video files in:
+   ```
+   /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end/input_videos/
+   ```
+
+2. Supported formats: `.mp4`, `.avi`
+
+3. Recommended video characteristics:
+   - Resolution: 720p or 1080p
+   - Frame rate: 30fps or higher
+   - Clear view of basketball court
+   - Good lighting
+   - Stable camera angle
+
+4. Run analysis:
+   ```bash
+   ./run.sh input_videos/your_video.mp4
+   ```
+
+---
+
+## 🔍 System Verification
+
+All checks passed ✅:
+- [x] All dependencies installed
+- [x] All models present and loading correctly
+- [x] Test videos available
+- [x] Directory structure set up
+- [x] Virtual environment configured
+
+---
+
+## 📖 Documentation
+
+- **TESTING_GUIDE.md** - Comprehensive testing guide with troubleshooting
+- **QUICK_REFERENCE.md** - Quick command reference
+- **test_system.py** - Automated system testing
+- **run.sh** - Convenience script for running analysis
+
+---
+
+## 🐛 Troubleshooting
+
+### If you encounter issues:
+
+1. **Ensure virtual environment is activated**:
+   ```bash
+   source venv/bin/activate
+   ```
+
+2. **Check system status**:
+   ```bash
+   python test_system.py --check-only
+   ```
+
+3. **View detailed logs**: Check console output for error messages
+
+4. **Clear cache and retry**:
+   ```bash
+   rm -rf stubs/
+   python main.py input_videos/video_1.mp4
+   ```
+
+---
+
+## 📝 Notes
+
+- **CPU vs GPU**: Currently using PyTorch CPU version for compatibility
+  - Processing will be slower than GPU but fully functional
+  - If you have CUDA-capable GPU and want to use it, you can reinstall PyTorch with CUDA support
+
+- **Stub Caching**: The system caches intermediate results in `stubs/`
+  - First run: Slower (creates cache)
+  - Subsequent runs: Much faster (uses cache)
+  - Delete `stubs/` to force fresh analysis
+
+- **Video Quality**: Better quality input videos = better detection results
+  - Clear court view
+  - Good lighting
+  - Stable camera
+  - Visible players and ball
+
+---
+
+## 🎯 Next Steps
+
+### 1. Test the System (NOW!)
+```bash
+cd /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end
+./run.sh input_videos/video_1.mp4
+```
+
+### 2. Review Output
+- Check `output_videos/` for the analyzed video
+- Verify all analysis features are working
+- Test with different input videos
+
+### 3. Integration Planning
+Once testing is successful:
+- Integrate with FastAPI backend
+- Add video upload endpoints
+- Implement async processing
+- Store results in Supabase
+- Connect to frontend
+
+---
+
+## 🎉 Ready to Go!
+
+Your system is fully prepared and ready for testing. Run your first analysis now:
+
+```bash
+cd /home/okidi6/Documents/Personalised-AI-Basketball-Skill-Analysis-System./back-end
+./run.sh input_videos/video_1.mp4
+```
+
+**Good luck with your testing! 🏀**
+
+---
+
+## 📞 Support Resources
+
+- **TESTING_GUIDE.md** - Detailed testing instructions
+- **QUICK_REFERENCE.md** - Command reference
+- **Original Repository**: https://github.com/abdullahtarek/basketball_analysis
+- **System Check**: `python test_system.py --check-only`
+
+---
+
+**System Status**: ✅ **READY FOR TESTING**
+
+**Last Verified**: 2026-02-01 13:16 UTC
+
+**All Systems**: ✅ **GO!**

SHOT_DETECTION.md

@@ -0,0 +1,315 @@
+# Shot Success Rate Detection
+
+## Overview
+
+The shot success rate detection feature adds comprehensive shooting analytics to both **Personal** and **Team** analysis modes. This critical basketball metric tracks not only shot attempts but also whether shots are made or missed, providing essential performance insights.
+
+## Features
+
+### 🎯 Shot Detection Capabilities
+
+1. **Shot Attempt Detection**
+   - Automatically identifies shooting motions by analyzing ball trajectory
+   - Detects upward arc patterns characteristic of basketball shots
+   - Filters out non-shot ball movements
+
+2. **Shot Outcome Detection**
+   - Determines if shots are **made** (ball goes through hoop)
+   - Identifies **missed** shots (ball does not pass through hoop region)
+   - Provides confidence scores for each outcome determination
+
+3. **Shot Type Classification**
+   - **Layup**: Close-range shots with low arc
+   - **Mid-range**: Medium-distance jump shots
+   - **Three-pointer**: Long-range shots beyond the arc
+   - Automatic classification based on distance and trajectory
+
+4. **Statistical Analysis**
+   - Overall shooting percentage
+   - Breakdown by shot type (layup %, mid-range %, 3PT %)
+   - Made/missed shot counts
+   - Shot locations and timing
+
+## How It Works
+
+### Detection Algorithm
+
+The shot detector uses a multi-stage approach:
+
+1. **Ball Trajectory Analysis**
+   - Tracks ball position across frames
+   - Calculates velocity and direction
+   - Identifies upward arcs indicating shot attempts
+
+2. **Hoop Detection**
+   - Uses YOLO model to detect basketball hoop location
+   - Falls back to heuristic methods if hoop model unavailable
+   - Maintains stable hoop position across frames
+
+3. **Outcome Determination**
+   - Checks if ball passes through hoop region
+   - Verifies ball is descending (downward trajectory)
+   - Measures proximity to rim/backboard
+   - Assigns confidence score based on trajectory clarity
+
+4. **Shot Type Classification**
+   - Calculates horizontal distance from shooter to hoop
+   - Analyzes shot arc height
+   - Classifies based on basketball shot type definitions
+
+### Key Parameters
+
+```python
+ShotDetector(
+    min_shot_arc_height=50,          # Minimum pixels for valid shot arc
+    hoop_proximity_threshold=100,     # Max distance to count as "made"
+    trajectory_window=30,             # Frames to analyze trajectory
+    success_time_window=15            # Frames after peak to check outcome
+)
+```
+
+## Usage
+
+### Personal Analysis Mode
+
+```python
+from analysis.personal_analysis import run_personal_analysis
+
+# Run analysis with shot detection (enabled by default)
+results = await run_personal_analysis(
+    video_path="training_session.mp4",
+    options={'detect_shots': True}
+)
+
+# Access shooting statistics
+print(f"Shot Attempts: {results['shot_attempts']}")
+print(f"Shots Made: {results['shots_made']}")
+print(f"Success Rate: {results['shot_success_rate']}%")
+print(f"Shot Breakdown: {results['shot_breakdown_by_type']}")
+```
+
+### Team Analysis Mode
+
+```python
+from analysis.team_analysis import run_team_analysis
+
+# Run team analysis (shot detection automatic)
+results = await run_team_analysis(video_path="game_footage.mp4")
+
+# Access team shooting stats
+print(f"Team 1 Shooting: {results['team_1_shooting_percentage']}%")
+print(f"Team 2 Shooting: {results['team_2_shooting_percentage']}%")
+print(f"Overall: {results['overall_shooting_percentage']}%")
+```
+
+### Testing
+
+Use the included test script to verify shot detection:
+
+```bash
+# Test personal analysis
+python test_shot_detection.py input_videos/training.mp4 --mode personal
+
+# Test team analysis
+python test_shot_detection.py input_videos/game.mp4 --mode team
+
+# Test both modes
+python test_shot_detection.py input_videos/video.mp4 --mode both
+```
+
+## Output Data Structure
+
+### Personal Analysis
+
+```json
+{
+  "shot_attempts": 15,
+  "shots_made": 9,
+  "shots_missed": 6,
+  "shot_success_rate": 60.0,
+  "shot_form_consistency": 75.3,
+  "shot_breakdown_by_type": {
+    "layup": {
+      "attempts": 5,
+      "made": 4,
+      "missed": 1,
+      "percentage": 80.0
+    },
+    "mid-range": {
+      "attempts": 7,
+      "made": 3,
+      "missed": 4,
+      "percentage": 42.9
+    },
+    "three-pointer": {
+      "attempts": 3,
+      "made": 2,
+      "missed": 1,
+      "percentage": 66.7
+    }
+  },
+  "shot_details": [
+    {
+      "start_frame": 245,
+      "outcome": "made",
+      "shot_type": "mid-range",
+      "timestamp_seconds": 8.2,
+      "confidence": 0.85,
+      "arc_height_pixels": 120.5
+    }
+  ]
+}
+```
+
+### Team Analysis
+
+```json
+{
+  "total_shot_attempts": 42,
+  "total_shots_made": 24,
+  "total_shots_missed": 18,
+  "overall_shooting_percentage": 57.1,
+  
+  "team_1_shot_attempts": 23,
+  "team_1_shots_made": 14,
+  "team_1_shooting_percentage": 60.9,
+  "team_1_shot_breakdown": {
+    "layup": {"attempts": 8, "made": 6, "percentage": 75.0},
+    "mid-range": {"attempts": 10, "made": 5, "percentage": 50.0},
+    "three-pointer": {"attempts": 5, "made": 3, "percentage": 60.0}
+  },
+  
+  "team_2_shot_attempts": 19,
+  "team_2_shots_made": 10,
+  "team_2_shooting_percentage": 52.6,
+  "team_2_shot_breakdown": {
+    "layup": {"attempts": 6, "made": 4, "percentage": 66.7},
+    "mid-range": {"attempts": 9, "made": 4, "percentage": 44.4},
+    "three-pointer": {"attempts": 4, "made": 2, "percentage": 50.0}
+  }
+}
+```
+
+## API Integration
+
+### Updated Analytics Models
+
+**PlayerAnalyticsSummary** now includes:
+- `total_shot_attempts`
+- `total_shots_made`
+- `total_shots_missed`
+- `shot_success_rate`
+
+**TeamAnalyticsSummary** now includes:
+- `total_shot_attempts`
+- `total_shots_made`
+- `team_shooting_percentage`
+
+### Database Storage
+
+Shot statistics are automatically saved to the `analytics` table with the following metric types:
+
+- `shot_attempt` - Total attempts (count)
+- `shot_made` - Successful shots (count)
+- `shot_missed` - Missed shots (count)
+- `shot_percentage` - Success rate (0-100)
+- `layup_percentage` - Layup success rate
+- `midrange_percentage` - Mid-range success rate
+- `three_point_percentage` - Three-point success rate
+
+## Performance Considerations
+
+### Accuracy Factors
+
+Shot detection accuracy depends on:
+
+1. **Video Quality**: Higher resolution improves detection
+2. **Camera Angle**: Side or elevated views work best
+3. **Hoop Visibility**: Hoop must be visible in frame
+4. **Ball Tracking**: Clear ball visibility throughout trajectory
+5. **Frame Rate**: Higher FPS (30+) improves trajectory analysis
+
+### Optimization
+
+- Ball tracking uses interpolation for smoother trajectories
+- Hoop detection caches stable positions
+- Trajectory analysis uses sliding windows for efficiency
+- Batch processing for multiple frames
+
+## Limitations & Future Enhancements
+
+### Current Limitations
+
+1. Requires hoop to be visible in frame
+2. May struggle with extreme camera angles
+3. Blocked shots may be misclassified
+4. Requires clear ball visibility
+
+### Planned Enhancements
+
+1. **Machine Learning Enhancement**
+   - Train ML model specifically for shot outcome
+   - Learn from labeled shooting data
+   - Improve classification accuracy
+
+2. **Advanced Metrics**
+   - Shot charts (visual heat maps)
+   - Shooting zones analysis
+   - Shot quality assessment
+   - Contested vs. uncontested shots
+
+3. **3D Trajectory Analysis**
+   - Account for camera perspective
+   - More accurate distance calculations
+   - Better arc analysis
+
+4. **Free Throw Detection**
+   - Specific free throw line detection
+   - Free throw percentage tracking
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue**: No shots detected
+- **Solution**: Ensure ball is visible and video contains shooting actions
+- Check that `detect_shots=True` in options
+- Verify video contains full shot arcs (not cut off)
+
+**Issue**: Low accuracy (many "unknown" outcomes)
+- **Solution**: Ensure hoop is visible in frame
+- Check video quality and resolution
+- Consider using hoop detection model
+
+**Issue**: Wrong shot type classification
+- **Solution**: May need to calibrate distance thresholds
+- Ensure court keypoints are detected for better spatial understanding
+
+**Issue**: Performance is slow
+- **Solution**: Process shorter video clips
+- Reduce trajectory window size
+- Use lower resolution for testing
+
+## Examples
+
+See `test_shot_detection.py` for complete examples of:
+- Personal training session analysis
+- Team game footage analysis
+- Accessing and displaying shot statistics
+- Interpreting shot details
+
+## Contributing
+
+To improve shot detection:
+
+1. Test with diverse video footage
+2. Report accuracy issues with specific videos
+3. Suggest parameter tuning for different scenarios
+4. Contribute labeled shot data for validation
+
+## Related Documentation
+
+- [Personal Analysis Pipeline](./analysis/personal_analysis.py)
+- [Team Analysis Pipeline](./analysis/team_analysis.py)
+- [Analytics API](./app/api/analytics.py)
+- [Analytics Models](./app/models/analytics.py)

SHOT_IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,230 @@
+# Shot Success Rate Implementation - Summary
+
+## ✅ Implementation Complete
+
+Shot success rate detection has been successfully implemented for your basketball analysis system!
+
+## 📦 What Was Added
+
+### 1. **New Shot Detector Module** (`shot_detector/`)
+   - `shot_detector.py` - Core detection logic with 500+ lines
+   - Detects shot attempts via ball trajectory analysis
+   - Determines shot outcomes (made/missed)
+   - Classifies shot types (layup, mid-range, 3-pointer)
+   - Calculates comprehensive statistics
+
+### 2. **Integration with Personal Analysis**
+   - Added shot detection to `analysis/personal_analysis.py`
+   - Tracks individual shooting performance
+   - Returns detailed shot statistics per session
+
+### 3. **Integration with Team Analysis**
+   - Added shot detection to `analysis/team_analysis.py`
+   - Separates shots by team
+   - Provides team-specific shooting percentages
+
+### 4. **Updated Data Models**
+   - Enhanced `PlayerAnalyticsSummary` with shot metrics
+   - Enhanced `TeamAnalyticsSummary` with shooting stats
+   - New fields: shots_made, shots_missed, shot_success_rate
+
+### 5. **Testing & Documentation**
+   - `test_shot_detection.py` - Complete test script
+   - `SHOT_DETECTION.md` - Full documentation
+   - Usage examples and troubleshooting guide
+
+## 🎯 Key Features
+
+### Shot Detection Capabilities
+- ✅ Automatic shot attempt detection
+- ✅ Made vs. missed determination
+- ✅ Shot type classification
+- ✅ Confidence scoring
+- ✅ Timing and location tracking
+- ✅ Statistical aggregation
+
+### Statistics Provided
+
+**Personal Mode:**
+- Total attempts, made, missed
+- Overall shooting percentage
+- Breakdown by shot type
+- Individual shot details
+- Form consistency correlation
+
+**Team Mode:**
+- Overall game statistics
+- Team 1 vs Team 2 comparison
+- Per-team shooting percentages
+- Shot type distribution
+- Player-specific attribution
+
+## 📊 Output Example
+
+```json
+{
+  "shot_attempts": 15,
+  "shots_made": 9,
+  "shots_missed": 6,
+  "shot_success_rate": 60.0,
+  "shot_breakdown_by_type": {
+    "layup": {"attempts": 5, "made": 4, "percentage": 80.0},
+    "mid-range": {"attempts": 7, "made": 3, "percentage": 42.9},
+    "three-pointer": {"attempts": 3, "made": 2, "percentage": 66.7}
+  }
+}
+```
+
+## 🚀 How to Use
+
+### Quick Start
+
+```bash
+# Test with a video
+python test_shot_detection.py input_videos/your_video.mp4 --mode personal
+
+# Or use in your API
+# Shot detection is now automatically enabled in both analysis modes
+```
+
+### API Usage
+
+```python
+from analysis.personal_analysis import run_personal_analysis
+
+results = await run_personal_analysis("video.mp4")
+print(f"Shooting: {results['shots_made']}/{results['shot_attempts']}")
+print(f"Percentage: {results['shot_success_rate']}%")
+```
+
+## 🔧 How It Works
+
+1. **Ball Trajectory Tracking**
+   - Tracks ball position frame-by-frame
+   - Calculates velocity and acceleration
+   - Identifies upward arcs characteristic of shots
+
+2. **Hoop Detection**
+   - Locates basketball hoop in frame
+   - Uses YOLO model (class 2: hoop) if available
+   - Maintains stable position across frames
+
+3. **Outcome Analysis**
+   - Checks if ball passes through hoop region
+   - Verifies downward trajectory at rim level
+   - Measures proximity to hoop center
+   - Assigns confidence based on trajectory clarity
+
+4. **Classification**
+   - Calculates shooter-to-hoop distance
+   - Analyzes arc height and trajectory
+   - Classifies as layup, mid-range, or 3-pointer
+
+## ⚙️ Configuration
+
+Tunable parameters in `ShotDetector`:
+
+```python
+ShotDetector(
+    min_shot_arc_height=50,        # Min pixels for valid shot
+    hoop_proximity_threshold=100,   # Distance to count as "made"
+    trajectory_window=30,           # Frames to analyze
+    success_time_window=15          # Frames to check outcome
+)
+```
+
+## 📈 Impact on Your System
+
+### Before (Missing)
+- ❌ Shot attempts only (no outcomes)
+- ❌ No made/missed tracking
+- ❌ No shooting percentages
+- ❌ No shot type breakdown
+
+### After (Complete!) ✅
+- ✅ Full shot attempt detection
+- ✅ Made vs missed determination
+- ✅ Shooting percentage calculation
+- ✅ Shot type classification
+- ✅ Per-team statistics (team mode)
+- ✅ Individual shot details
+- ✅ Confidence scoring
+
+## 🎓 Advanced Features
+
+- **Shot Details**: Every shot includes timestamp, location, type, outcome
+- **Confidence Scores**: Each determination has reliability metric
+- **Type Breakdown**: Separate stats for layups, mid-range, 3-pointers
+- **Team Attribution**: Assigns shots to correct team in team mode
+- **Error Handling**: Graceful fallbacks if hoop not detected
+
+## 🧪 Testing
+
+The system has been validated with:
+- ✅ Syntax compilation checks
+- ✅ Module import verification
+- ✅ Integration with existing pipelines
+- ✅ Test script creation
+
+**Next Steps for Testing:**
+1. Run with actual video: `python test_shot_detection.py input_videos/your_video.mp4`
+2. Verify shot counts match visual inspection
+3. Check shooting percentages for accuracy
+4. Fine-tune parameters if needed
+
+## 📝 Files Modified/Created
+
+**New Files:**
+- `shot_detector/__init__.py`
+- `shot_detector/shot_detector.py`
+- `test_shot_detection.py`
+- `SHOT_DETECTION.md`
+- `SHOT_IMPLEMENTATION_SUMMARY.md` (this file)
+
+**Modified Files:**
+- `analysis/personal_analysis.py`
+- `analysis/team_analysis.py`
+- `app/models/analytics.py`
+
+## 🎯 What Makes This Important
+
+Shot success rate is arguably **THE most critical basketball metric**:
+
+1. **Universal Metric**: Used at all levels (NBA, college, high school)
+2. **Performance Indicator**: Direct measure of scoring efficiency
+3. **Training Feedback**: Shows improvement over time
+4. **Game Analysis**: Identifies hot/cold shooters
+5. **Strategic Planning**: Informs shot selection and play calling
+
+Your system now provides this essential analysis automatically!
+
+## 🔜 Future Enhancements (Optional)
+
+Potential improvements for later:
+- Shot charts (visual heat maps)
+- Contested vs. uncontested shots
+- Shot clock awareness
+- Free throw specific detection
+- Arc angle optimization
+- Machine learning for better accuracy
+
+## 💡 Pro Tips
+
+1. **Best Results**: Use videos where hoop is visible
+2. **Camera Angle**: Side or elevated views work best
+3. **Video Quality**: Higher resolution = better detection
+4. **Frame Rate**: 30+ FPS recommended
+5. **Testing**: Start with short clips to verify accuracy
+
+## ✨ Summary
+
+Your basketball analysis system now includes comprehensive **shot success rate detection**! This was the #1 missing critical feature, and it's now fully implemented with:
+
+- Automatic detection of shot attempts
+- Made vs. missed determination  
+- Shot type classification
+- Statistical aggregation
+- Team and personal mode support
+- Detailed documentation and testing tools
+
+**Ready to use!** 🏀

TEAM_ANALYSIS_OUTPUTS.md

@@ -0,0 +1,56 @@
+# Team Video Analysis - Output Metrics & Analytics
+
+This document outlines the comprehensive analysis metrics and data points generated by the **Team Analysis Mode** of the AI Basketball Skill Analysis System.
+
+## 1. General Game Metadata
+- **Total Frames**: Total number of frames processed.
+- **Duration**: Total game time analyzed (seconds/minutes).
+- **Player Count**: Number of unique players detected and tracked.
+- **Team Identification**: Automatic assignment of players to Team 1 or Team 2 based on jersey color analysis.
+
+## 2. Possession & Control
+- **Team Possession Percentage**: Percentage of time each team spent in possession of the ball.
+- **Ball Possession Log**: Frame-by-frame tracking of which specific player ID had control of the ball.
+- **Persistence Handling**: Grace periods for ball occlusions to ensure consistent possession attribution.
+
+## 3. Shooting Analytics (Team & Individual)
+The system analyzes every shot attempt for both teams, providing:
+- **Shot Volume**: Total attempts, makes, and misses.
+- **Shooting Percentage**: Overall and team-specific success rates.
+- **Shot Type Classification**:
+    - **Layups**: Close-range shots near the hoop.
+    - **Mid-range**: Medium-distance jump shots.
+    - **Three-Pointers**: Long-range shots (calibrated using 2D Euclidean distance).
+- **Tactical Shot Quality**:
+    - **Contestedness**: Classified as *Wide Open*, *Contested*, or *Heavily Contested* based on defender proximity.
+    - **Shot Quality**: Assessment (e.g., *High Quality*, *Average*, *Difficult Make*) based on outcome and pressure.
+- **Shot Breakdown**: Detailed stats per shot type for each team.
+
+## 4. Playmaking & Defense
+- **Pass Detection**: Identifies successful passes between teammates.
+- **Total Passes**: Count per team/game.
+- **Interceptions**: Detects when a defender gains possession of the ball from the opposing team's pass or dribble.
+- **Total Interceptions**: Defensive impact count.
+
+## 5. Movement & Spatial Data
+- **Tactical View Transformation**: Conversion of camera-view coordinates to a top-down 2D court representation.
+- **Speed Tracking**: Real-time speed calculation for all tracked players (meters per second).
+- **Distance Covered**: Cumulative distance traveled by each player throughout the analyzed period.
+- **Court Keypoints**: Detectable landmarks and boundaries of the basketball court for spatial context.
+
+## 6. Visual Overlays (Output Video)
+The analyzed video output includes:
+- **Player Tracking Ellipses**: Color-coded by team (e.g., Grey for Team 1, Red for Team 2).
+- **Possession Indicator**: A triangle above the player currently holding the ball.
+- **Live Scoreboard**: Persistent display of Team 1 vs. Team 2 score and possession dominance.
+- **Made/Missed Notifications**: Contextual notifications showing shot outcome, distance, and contestedness.
+- **Hoop Detection Visuals**: Highlighting the rim and backboard regions used for analysis.
+- **Tactical Map (Optional)**: Mini top-down view showing player positioning.
+
+## 7. Data Structure (API/Json)
+For technical integration, the system returns a JSON object containing:
+- `events`: Array of triggered events (passes, shots, interceptions) with timestamps.
+- `detections`: Raw tracking data for every frame.
+- `shot_details`: Array of objects containing outcome, type, distance, and quality metrics for every shot.
+- `team_1_shot_breakdown` & `team_2_shot_breakdown`: Nested objects with attempts/makes/percentages per type.
+- `duration_seconds`: Calculated total video length.

__init__.py

@@ -0,0 +1 @@
+from .ball_aquisition_detector import BallAquisitionDetector

analysis/__init__.py

@@ -0,0 +1,12 @@
+"""
+Analysis module for video processing pipelines.
+"""
+from analysis.dispatcher import dispatch_analysis
+from analysis.team_analysis import run_team_analysis
+from analysis.personal_analysis import run_personal_analysis
+
+__all__ = [
+    "dispatch_analysis",
+    "run_team_analysis",
+    "run_personal_analysis",
+]

analysis/dispatcher.py

@@ -0,0 +1,82 @@
+"""
+Analysis Dispatcher - Routes analysis requests to appropriate pipelines.
+
+This module dispatches video analysis jobs to either TEAM or PERSONAL
+analysis pipelines based on the analysis_mode configuration.
+"""
+import os
+import sys
+import time
+from typing import Dict, Any, Optional
+from datetime import datetime
+
+# Add parent dir to path for template imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.models.video import AnalysisMode
+
+
+async def dispatch_analysis(video_path: str, mode: AnalysisMode, options: Optional[Dict[str, Any]] = None, video_id: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Dispatch video analysis to the appropriate pipeline.
+    
+    Args:
+        video_path: Path to the video file
+        mode: Analysis mode (TEAM or PERSONAL)
+        video_id: UUID of the video for status updates
+        
+    Returns:
+        Dictionary containing analysis results
+    """
+    start_time = time.time()
+    
+    if mode == AnalysisMode.TEAM:
+        from analysis.team_analysis import run_team_analysis
+        result = await run_team_analysis(video_path, options=options, video_id=video_id)
+    else:
+        from analysis.personal_analysis import run_personal_analysis
+        result = await run_personal_analysis(video_path, options=options, video_id=video_id)
+    
+    processing_time = time.time() - start_time
+    
+    return {
+        **result,
+        "processing_time_seconds": processing_time,
+    }
+
+
+def get_video_metrics(video_path: str) -> Dict[str, Any]:
+    """
+    Extract basic video metrics using OpenCV.
+    
+    Args:
+        video_path: Path to the video file
+        
+    Returns:
+        Dictionary with fps, frame_count, duration, width, height
+    """
+    try:
+        import cv2
+        cap = cv2.VideoCapture(video_path)
+        
+        if not cap.isOpened():
+            return {}
+        
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        duration = frame_count / fps if fps > 0 else 0
+        
+        cap.release()
+        
+        return {
+            "fps": fps,
+            "frame_count": frame_count,
+            "width": width,
+            "height": height,
+            "duration_seconds": duration,
+        }
+    except Exception as e:
+        print(f"Error extracting video metrics: {e}")
+        return {}

analysis/personal_analysis.py

@@ -0,0 +1,559 @@
+"""
+Personal Analysis Pipeline - Individual skill analysis with pose estimation.
+
+This module provides personal training video analysis focused on a single player,
+extracting skill metrics like shot form, dribbling patterns, and movement quality.
+"""
+import os
+import sys
+import math
+from typing import Dict, Any, List, Tuple, Optional
+
+# Add parent directory for template imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+async def run_personal_analysis(video_path: str, options: Optional[Dict[str, Any]] = None, video_id: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Run personal analysis pipeline on a training video.
+    
+    Focuses on a single primary subject and extracts:
+    - Pose keypoints and joint angles
+    - Shot form analysis and success rate
+    - Dribbling patterns
+    - Movement metrics (speed, distance)
+    
+    Args:
+        video_path: Path to the video file
+        options: Optional configuration dict with keys:
+            - detections_stride: Frame stride for detections
+            - max_detections: Max detections to return
+            - detect_shots: Whether to run shot detection (default: True)
+        
+    Returns:
+        Dictionary containing personal analysis results
+    """
+    from utils import read_video
+    from app.config import get_settings
+    from shot_detector import ShotDetector
+    from trackers import BallTracker
+    from configs import PERSONAL_MODEL_PATH
+    from analysis.skill_diagnostic import SkillDiagnosticService
+    
+    settings = get_settings()
+    
+    # Read video frames
+    video_frames = read_video(video_path)
+    total_frames = len(video_frames)
+    
+    if total_frames == 0:
+        return {
+            "error": "Could not read video frames",
+            "total_frames": 0,
+        }
+    
+    # Get video FPS
+    fps = 30
+    try:
+        import cv2
+        cap = cv2.VideoCapture(video_path)
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30
+        cap.release()
+    except:
+        pass
+    
+    duration_seconds = total_frames / fps
+    
+    # Initialize YOLO pose model
+    try:
+        from ultralytics import YOLO
+        pose_model = YOLO(settings.pose_model_path)
+        has_pose = True
+    except Exception as e:
+        print(f"Could not load pose model: {e}")
+        has_pose = False
+    
+    # Track all detections and select primary subject
+    all_detections = []
+    player_stats = {}  # track_id -> {frames: int, total_area: float, ball_interaction: int}
+    
+    if has_pose:
+        # Run pose detection with tracking
+        batch_size = 20
+        for i in range(0, len(video_frames), batch_size):
+            batch = video_frames[i:i+batch_size]
+            results = pose_model.track(batch, conf=0.5, classes=[0], persist=True)  # Class 0 = person
+            
+            # Check for ball in these frames to find interaction
+            # (Heuristic: who is closest to the ball or hoop later)
+            
+            for frame_offset, result in enumerate(results):
+                frame_idx = i + frame_offset
+                
+                if result.boxes is not None and len(result.boxes) > 0:
+                    for j, box in enumerate(result.boxes):
+                        bbox = box.xyxy[0].tolist()
+                        track_id = int(box.id[0]) if box.id is not None else -1
+                        if track_id == -1: continue
+                        
+                        # Calculate bbox area
+                        area = (bbox[2] - bbox[0]) * (bbox[3] - bbox[1])
+                        
+                        if track_id not in player_stats:
+                            player_stats[track_id] = {'frames': 0, 'total_area': 0, 'interaction_score': 0}
+                        
+                        player_stats[track_id]['frames'] += 1
+                        player_stats[track_id]['total_area'] += area
+                        
+                        # Get keypoints
+                        keypoints = None
+                        if result.keypoints is not None and j < len(result.keypoints):
+                            kp = result.keypoints[j].xy[0].tolist()
+                            keypoints = kp
+                            
+                            # Heuristic: person moving their arms significantly or near the center
+                            # tends to be the player.
+                            if len(kp) > 10:
+                                wrist_y = kp[10][1]
+                                shoulder_y = kp[6][1]
+                                if wrist_y < shoulder_y: # Arm raised
+                                    player_stats[track_id]['interaction_score'] += 1
+                        
+                        all_detections.append({
+                            "frame": frame_idx,
+                            "track_id": track_id,
+                            "bbox": bbox,
+                            "keypoints": keypoints,
+                        })
+    
+    # Select primary subject (Prioritize interaction > presence > size)
+    if player_stats:
+        scores = {}
+        for tid, stats in player_stats.items():
+            presence = stats['frames'] / total_frames
+            avg_size = stats['total_area'] / stats['frames']
+            interaction = stats['interaction_score'] / stats['frames']
+            
+            # Weighted score
+            scores[tid] = (interaction * 1.0) + (presence * 0.5) + (avg_size / 200000 * 0.3)
+        
+        primary_player = max(scores, key=scores.get)
+    else:
+        primary_player = None
+    
+    # Filter detections for primary player
+    primary_detections = [d for d in all_detections if d["track_id"] == primary_player]
+
+    # Build per-frame detections for overlays (optional, can be large)
+    detections_stride = 1
+    max_detections = 200_000
+    if options:
+        try:
+            detections_stride = int(options.get("detections_stride", detections_stride))
+        except Exception:
+            pass
+        try:
+            max_detections = int(options.get("max_detections", max_detections))
+        except Exception:
+            pass
+
+    detections_stride = max(1, min(30, detections_stride))
+    max_detections = max(1_000, max_detections)
+
+    detections: List[Dict[str, Any]] = []
+    for det in primary_detections:
+        frame_num = int(det.get("frame", 0))
+        if frame_num % detections_stride != 0:
+            continue
+        bbox = det.get("bbox")
+        if not bbox:
+            continue
+        detections.append({
+            "frame": frame_num,
+            "object_type": "player",
+            "track_id": int(det.get("track_id", 0) or 0),
+            "bbox": bbox,
+            "confidence": 1.0,
+            "keypoints": det.get("keypoints"),
+            "team_id": None,
+            "has_ball": False,
+        })
+        if len(detections) >= max_detections:
+            break
+    
+    # Analyze pose data for skill metrics
+    shot_attempts = 0
+    form_scores = []
+    dribble_count = 0
+    positions = []
+    
+    knee_angles = []
+    elbow_angles = []
+    
+    for det in primary_detections:
+        kp = det.get("keypoints")
+        if kp and len(kp) >= 17:
+            # Extract key joint positions (COCO keypoint format)
+            # 0:nose, 5:left_shoulder, 6:right_shoulder, 7:left_elbow, 8:right_elbow
+            # 9:left_wrist, 10:right_wrist, 11:left_hip, 12:right_hip
+            # 13:left_knee, 14:right_knee, 15:left_ankle, 16:right_ankle
+            
+            # Calculate knee angle (for shot form)
+            left_knee_angle = calculate_angle(kp[11], kp[13], kp[15])  # hip-knee-ankle
+            right_knee_angle = calculate_angle(kp[12], kp[14], kp[16])
+            
+            if left_knee_angle:
+                knee_angles.append(left_knee_angle)
+            if right_knee_angle:
+                knee_angles.append(right_knee_angle)
+            
+            # Calculate elbow angle (for shooting form)
+            left_elbow_angle = calculate_angle(kp[5], kp[7], kp[9])  # shoulder-elbow-wrist
+            right_elbow_angle = calculate_angle(kp[6], kp[8], kp[10])
+            
+            if left_elbow_angle:
+                elbow_angles.append(left_elbow_angle)
+            if right_elbow_angle:
+                elbow_angles.append(right_elbow_angle)
+            
+            # Track wrist position for dribble detection
+            left_wrist = kp[9] if len(kp) > 9 else None
+            right_wrist = kp[10] if len(kp) > 10 else None
+            
+            # Store position (hip center) for movement tracking
+            if len(kp) > 12:
+                hip_center = [
+                    (kp[11][0] + kp[12][0]) / 2,
+                    (kp[11][1] + kp[12][1]) / 2
+                ]
+                positions.append({
+                    "frame": det["frame"],
+                    "position": hip_center
+                })
+    
+    # Detect shot attempts (arm raise events)
+    shot_attempts = detect_shot_attempts(primary_detections)
+    
+    # Detect dribbles (rapid vertical wrist movements)
+    dribble_count = detect_dribbles(primary_detections)
+    
+    # Calculate movement metrics
+    total_distance = 0
+    speeds = []
+    
+    for i in range(1, len(positions)):
+        prev_pos = positions[i-1]["position"]
+        curr_pos = positions[i]["position"]
+        frame_diff = positions[i]["frame"] - positions[i-1]["frame"]
+        
+        # Calculate pixel distance
+        dist = math.sqrt((curr_pos[0] - prev_pos[0])**2 + (curr_pos[1] - prev_pos[1])**2)
+        
+        # Convert to approximate meters (assuming standard court proportions)
+        # This is a rough estimate - 1 pixel ≈ 0.01 meters for normalized view
+        dist_meters = dist * 0.01
+        total_distance += dist_meters
+        
+        # Calculate speed (m/s)
+        if frame_diff > 0:
+            time_diff = frame_diff / fps
+            speed = dist_meters / time_diff
+            speeds.append(speed)
+    
+    # Calculate averages
+    avg_speed = sum(speeds) / len(speeds) if speeds else 0
+    max_speed = max(speeds) if speeds else 0
+    
+    # Convert to km/h
+    avg_speed_kmh = avg_speed * 3.6
+    max_speed_kmh = max_speed * 3.6
+    
+    # Calculate form consistency (standard deviation of angles)
+    form_consistency = 100 - min(100, calculate_consistency(elbow_angles) * 2)
+    
+    # Calculate averages
+    avg_knee_angle = sum(knee_angles) / len(knee_angles) if knee_angles else None
+    avg_elbow_angle = sum(elbow_angles) / len(elbow_angles) if elbow_angles else None
+    
+    # Dribbles per minute
+    dribble_frequency = (dribble_count / duration_seconds) * 60 if duration_seconds > 0 else 0
+    
+    # Acceleration events (significant speed changes)
+    acceleration_events = 0
+    for i in range(1, len(speeds)):
+        accel = abs(speeds[i] - speeds[i-1])
+        if accel > 2:  # Threshold for significant acceleration
+            acceleration_events += 1
+    
+    # Shot Success Detection
+    shot_stats = {
+        'total_attempts': shot_attempts,
+        'total_made': 0,
+        'total_missed': 0,
+        'overall_percentage': 0.0,
+        'by_type': {},
+        'shots': []
+    }
+    
+    # Run shot detection if enabled (default: True)
+    detect_shots = options.get('detect_shots', True) if options else True
+    
+    if detect_shots:
+        try:
+            # Check if ball detector model exists
+            model_path = PERSONAL_MODEL_PATH
+            if model_path is None or not os.path.exists(str(model_path)):
+                # Try relative path if absolute fails
+                if os.path.exists('models/nbl_v2_combined.pt'):
+                    model_path = 'models/nbl_v2_combined.pt'
+                else:
+                    model_path = None
+            
+            if model_path is None:
+                print(f"Warning: Ball detector model not found, skipping shot detection")
+            else:
+                # Initialize ball tracker and shot detector
+                ball_tracker = BallTracker(model_path)
+                shot_detector = ShotDetector(
+                    hoop_detection_model_path=model_path,
+                    min_shot_arc_height=50,
+                    hoop_proximity_threshold=100,
+                    trajectory_window=30,
+                    success_time_window=45
+                )
+                
+                # Track ball
+                ball_tracks = ball_tracker.get_object_tracks(
+                    video_frames, 
+                    read_from_stub=False
+                )
+                ball_tracks = ball_tracker.interpolate_ball_positions(ball_tracks)
+                
+                # Detect hoop (if model available, otherwise use heuristics)
+                hoop_detections = shot_detector.detect_hoop_locations(
+                    video_frames,
+                    read_from_stub=False
+                )
+                
+                # Detect and analyze shots
+                shots = shot_detector.detect_shots(
+                    ball_tracks,
+                    hoop_detections,
+                    fps=fps
+                )
+                
+                # Calculate shot statistics
+                shot_stats = shot_detector.calculate_shot_statistics(shots)
+                
+                # Add ball and hoop detections to the main detections list for visualization
+                for f_idx, tracks in enumerate(ball_tracks):
+                    for b_id, b_track in tracks.items():
+                        if 'bbox' in b_track:
+                            detections.append({
+                                "frame": f_idx,
+                                "object_type": "ball",
+                                "track_id": b_id,
+                                "bbox": b_track['bbox']
+                            })
+                for f_idx, hoop in enumerate(hoop_detections):
+                    if hoop and 'bbox' in hoop:
+                        detections.append({
+                            "frame": f_idx,
+                            "object_type": "hoop",
+                            "track_id": 0,
+                            "bbox": hoop['bbox']
+                        })
+                # --- Skill Diagnostic Logic Integration ---
+                try:
+                    diagnostic_service = SkillDiagnosticService()
+                    # Convert primary_detections to the format expected by the service
+                    pose_tracks_formatted = [{} for _ in range(total_frames)]
+                    for det in primary_detections:
+                        f = det['frame']
+                        tid = det['track_id']
+                        if 0 <= f < total_frames:
+                            pose_tracks_formatted[f][tid] = {'keypoints': det['keypoints']}
+                    
+                    # Analyze each shot and attach feedback
+                    coached_shots = []
+                    for s in shots:
+                        # Find matching entry angle from shot detector result
+                        analysis = diagnostic_service.analyze_single_shot(s, pose_tracks_formatted)
+                        coached_shots.append({
+                            **s,
+                            'biometrics': analysis['biometrics'],
+                            'faults': analysis['faults'],
+                            'feedback': analysis['feedback']
+                        })
+                    
+                    # Update shot_stats to include coached details
+                    shot_stats['shots'] = coached_shots
+                    
+                except Exception as diag_err:
+                    print(f"Skill Diagnostic failed: {diag_err}")
+                # -------------------------------------------
+
+                
+        except Exception as e:
+            print(f"Shot detection failed: {e}")
+            # Keep default shot_stats
+
+    
+    # Training load score (composite metric)
+    training_load = min(100, (
+        (dribble_count * 0.5) +
+        (shot_stats['total_attempts'] * 5) +
+        (total_distance * 2) +
+        (acceleration_events * 1)
+    ))
+
+    
+    return {
+        "total_frames": total_frames,
+        "duration_seconds": duration_seconds,
+        "primary_player_frames": len(primary_detections),
+        
+        # Skill metrics
+        "shot_attempts": shot_stats['total_attempts'],
+        "shots_made": shot_stats['total_made'],
+        "shots_missed": shot_stats['total_missed'],
+        "shot_success_rate": shot_stats['overall_percentage'],
+        "shot_form_consistency": round(form_consistency, 1),
+        "shot_breakdown_by_type": shot_stats['by_type'],
+        "shot_details": shot_stats.get('shots', []),
+        "dribble_count": dribble_count,
+        "dribble_frequency_per_minute": round(dribble_frequency, 1),
+        
+        # Movement metrics
+        "total_distance_meters": round(total_distance, 1),
+        "avg_speed_kmh": round(avg_speed_kmh, 1),
+        "max_speed_kmh": round(max_speed_kmh, 1),
+        "acceleration_events": acceleration_events,
+        
+        # Pose analysis
+        "avg_knee_bend_angle": round(avg_knee_angle, 1) if avg_knee_angle else None,
+        "avg_elbow_angle_shooting": round(avg_elbow_angle, 1) if avg_elbow_angle else None,
+        
+        # Training load
+        "training_load_score": round(training_load, 1),
+        "detections": detections,
+    }
+
+
+
+def calculate_angle(p1: List[float], p2: List[float], p3: List[float]) -> Optional[float]:
+    """
+    Calculate angle at p2 given three points.
+    
+    Args:
+        p1, p2, p3: Points as [x, y] coordinates
+        
+    Returns:
+        Angle in degrees at p2, or None if invalid
+    """
+    if not all([p1, p2, p3]) or len(p1) < 2 or len(p2) < 2 or len(p3) < 2:
+        return None
+    
+    # Check for valid coordinates (not 0,0)
+    if p1[0] == 0 and p1[1] == 0:
+        return None
+    if p2[0] == 0 and p2[1] == 0:
+        return None
+    if p3[0] == 0 and p3[1] == 0:
+        return None
+    
+    try:
+        v1 = [p1[0] - p2[0], p1[1] - p2[1]]
+        v2 = [p3[0] - p2[0], p3[1] - p2[1]]
+        
+        dot = v1[0] * v2[0] + v1[1] * v2[1]
+        mag1 = math.sqrt(v1[0]**2 + v1[1]**2)
+        mag2 = math.sqrt(v2[0]**2 + v2[1]**2)
+        
+        if mag1 * mag2 == 0:
+            return None
+        
+        cos_angle = dot / (mag1 * mag2)
+        cos_angle = max(-1, min(1, cos_angle))  # Clamp to valid range
+        
+        angle = math.degrees(math.acos(cos_angle))
+        return angle
+    except:
+        return None
+
+
+def calculate_consistency(values: List[float]) -> float:
+    """Calculate standard deviation as a measure of consistency."""
+    if not values or len(values) < 2:
+        return 0
+    
+    mean = sum(values) / len(values)
+    variance = sum((x - mean) ** 2 for x in values) / len(values)
+    return math.sqrt(variance)
+
+
+def detect_shot_attempts(detections: List[Dict]) -> int:
+    """
+    Detect shot attempts by analyzing arm raise patterns.
+    
+    A shot attempt is detected when the wrist rises significantly above
+    the shoulder and then drops.
+    """
+    shots = 0
+    arm_raised = False
+    
+    for det in detections:
+        kp = det.get("keypoints")
+        if not kp or len(kp) < 11:
+            continue
+        
+        # Check right arm (more common for right-handed shooters)
+        shoulder_y = kp[6][1] if len(kp) > 6 else 0
+        wrist_y = kp[10][1] if len(kp) > 10 else 0
+        
+        # Check if wrist is significantly above shoulder (negative Y is up)
+        if shoulder_y > 0 and wrist_y > 0:
+            if wrist_y < shoulder_y - 50:  # Wrist 50+ pixels above shoulder
+                if not arm_raised:
+                    arm_raised = True
+            elif wrist_y > shoulder_y:
+                if arm_raised:
+                    shots += 1
+                    arm_raised = False
+    
+    return shots
+
+
+def detect_dribbles(detections: List[Dict]) -> int:
+    """
+    Detect dribbles by analyzing rapid vertical wrist movements.
+    """
+    dribbles = 0
+    prev_wrist_y = None
+    direction = None  # 'up' or 'down'
+    
+    for det in detections:
+        kp = det.get("keypoints")
+        if not kp or len(kp) < 11:
+            continue
+        
+        # Track dominant hand wrist
+        wrist_y = kp[10][1] if len(kp) > 10 and kp[10][1] > 0 else None
+        
+        if wrist_y is None or prev_wrist_y is None:
+            prev_wrist_y = wrist_y
+            continue
+        
+        diff = wrist_y - prev_wrist_y
+        
+        # Detect direction change (dribble = down then up motion)
+        if diff > 10:  # Moving down
+            if direction == 'up':
+                dribbles += 1
+            direction = 'down'
+        elif diff < -10:  # Moving up
+            direction = 'up'
+        
+        prev_wrist_y = wrist_y
+    
+    return dribbles

analysis/skill_diagnostic.py

@@ -0,0 +1,145 @@
+import math
+import numpy as np
+from typing import Dict, List, Any, Optional
+
+class SkillDiagnosticService:
+    """
+    Analyzes basketball skills (shooting, dribbling) using pose data.
+    Implements the 4-phase shot diagnostic logic: DIP, SET, RELEASE, FINISH.
+    """
+    
+    def __init__(self):
+        # Ideal thresholds for coaching feedback
+        self.THRESHOLDS = {
+            'MIN_ELBOW_EXTENSION': 165.0,  # Degrees
+            'IDEAL_KNEE_DIP': 125.0,       # Degrees
+            'MIN_ARC_ANGLE': 40.0,         # Degrees
+            'MAX_ELBOW_FLARE': 15.0        # Degrees from shoulder-wrist line
+        }
+
+    def analyze_shooting_session(self, shots: List[Dict], pose_tracks: List[Dict]) -> List[Dict]:
+        """
+        Analyzes a full session of shots and provides diagnostic feedback.
+        """
+        diagnostics = []
+        for shot in shots:
+            diagnostic = self.analyze_single_shot(shot, pose_tracks)
+            diagnostics.append(diagnostic)
+        return diagnostics
+
+    def analyze_single_shot(self, shot: Dict, pose_tracks: List[Dict]) -> Dict:
+        """
+        Diagnoses a single shot attempt.
+        """
+        release_frame = shot.get('release_frame')
+        outcome = shot.get('outcome')
+        
+        # 1. Identify Keyframes (Dip, Set, Release, Finish)
+        keyframes = self._extract_keyframes(shot, pose_tracks)
+        
+        # 2. Calculate Biometrics
+        biometrics = self._calculate_biometrics(keyframes)
+        
+        # 3. Detect Faults based on biometrics & outcome
+        faults = self._detect_faults(biometrics, outcome)
+        
+        # 4. Synthesize AI Coaching Feedback
+        feedback = self._generate_feedback(faults, outcome)
+        
+        return {
+            'shot_id': shot.get('id'),
+            'outcome': outcome,
+            'keyframes': keyframes,
+            'biometrics': biometrics,
+            'faults': faults,
+            'feedback': feedback
+        }
+
+    def _extract_keyframes(self, shot: Dict, pose_tracks: List[Dict]) -> Dict:
+        """Extracts the 4 critical frames for a shot."""
+        # Simple heuristic implementation - in production this would use AI classification
+        release_idx = shot.get('release_frame', 0)
+        
+        # Heuristics for phases (assuming 30fps)
+        return {
+            'dip': self._get_pose(pose_tracks, release_idx - 20),
+            'set': self._get_pose(pose_tracks, release_idx - 5),
+            'release': self._get_pose(pose_tracks, release_idx),
+            'finish': self._get_pose(pose_tracks, release_idx + 15)
+        }
+
+    def _calculate_biometrics(self, keyframes: Dict) -> Dict:
+        """Calculates angles and positions for keyframes."""
+        metrics = {}
+        
+        # Elbow Extension at Release
+        release_pose = keyframes.get('release')
+        if release_pose:
+            metrics['elbow_extension'] = self._calculate_angle(
+                release_pose[5], release_pose[7], release_pose[9]
+            ) # shoulder-elbow-wrist (left or right depends on player, using dummy for now)
+
+        # Knee Dip
+        dip_pose = keyframes.get('dip')
+        if dip_pose:
+            metrics['knee_dip'] = self._calculate_angle(
+                dip_pose[11], dip_pose[13], dip_pose[15]
+            ) # hip-knee-ankle
+            
+        return metrics
+
+    def _detect_faults(self, biometrics: Dict, outcome: str) -> List[str]:
+        """Identifies technical errors."""
+        faults = []
+        if outcome == 'missed':
+            ext = biometrics.get('elbow_extension')
+            if ext and ext < self.THRESHOLDS['MIN_ELBOW_EXTENSION']:
+                faults.append('SHORT_ARM')
+                
+            dip = biometrics.get('knee_dip')
+            if dip and dip > 140:
+                faults.append('STIFF_LEGS')
+                
+        return faults
+
+    def _generate_feedback(self, faults: List[str], outcome: str) -> str:
+        """Creates human-readable coaching tips."""
+        if outcome == 'made' and not faults:
+            return "Great shot! Form is consistent. Keep holding that follow-through."
+        
+        tips = []
+        if 'SHORT_ARM' in faults:
+            tips.append("Extend your shooting arm fully. You're losing arc by releasing too early.")
+        if 'STIFF_LEGS' in faults:
+            tips.append("Dip lower into your legs. Your power should come from the ground up.")
+            
+        if not tips and outcome == 'missed':
+            return "Good form, just a bit off. Keep practicing the same motion."
+            
+        return " ".join(tips)
+
+    def _get_pose(self, pose_tracks: List[Dict], frame_idx: int) -> Optional[List]:
+        if 0 <= frame_idx < len(pose_tracks):
+            # Return first player pose found in that frame for now
+            poses = pose_tracks[frame_idx]
+            if poses:
+                first_id = list(poses.keys())[0]
+                return poses[first_id].get('keypoints')
+        return None
+
+    @staticmethod
+    def _calculate_angle(p1, p2, p3):
+        if not p1 or not p2 or not p3: return None
+        try:
+            a = np.array(p1[:2])
+            b = np.array(p2[:2])
+            c = np.array(p3[:2])
+            
+            ba = a - b
+            bc = c - b
+            
+            cosine_angle = np.dot(ba, bc) / (np.linalg.norm(ba) * np.linalg.norm(bc))
+            angle = np.arccos(cosine_angle)
+            return np.degrees(angle)
+        except:
+            return None

analysis/team_analysis.py

@@ -0,0 +1,307 @@
+"""
+Web API Wrapper for Team Analysis - Uses main.py as the core engine
+
+This module provides the async/web interface to the core team analysis logic
+defined in main.py. It handles:
+- Progress updates via database
+- Jersey color customization
+- Stub management options
+"""
+import os
+import sys
+import time
+import threading
+from typing import Dict, Any, Optional
+
+# Add parent directory for imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from main import run_team_analysis as core_run_team_analysis
+
+
+async def run_team_analysis(
+    video_path: str,
+    options: Optional[Dict[str, Any]] = None,
+    video_id: Optional[str] = None
+) -> Dict[str, Any]:
+    """
+    Async wrapper for team analysis (Web API interface).
+    
+    Uses the core analysis from main.py with web-specific features:
+    - Progress updates to database
+    - Jersey color customization
+    - Stub management options
+    
+    Args:
+        video_path: Path to input video
+        options: Analysis options dict with keys:
+            - our_team_jersey: Team jersey description
+            - opponent_jersey: Opponent jersey description
+            - our_team_id: Team ID (1 or 2)
+            - read_from_stub: Use cached detections
+            - clear_stubs_after: Clear stubs after analysis
+        video_id: Video UUID for progress tracking in database
+        
+    Returns:
+        Dictionary with analysis results
+    """
+    import anyio
+    from app.services.supabase_client import get_supabase_service
+    
+    supabase = get_supabase_service()
+    
+    # Shared state for progress updates between threads
+    progress_state = {"step": "Initializing", "percent": 0, "finished": False}
+    progress_lock = threading.Lock()
+    
+    def sync_progress_callback(step: str, percent: int):
+        """
+        Synchronous callback for progress updates - stores in shared state.
+        The async updater will periodically read and push to database.
+        """
+        # Cap at 99% until the very end to avoid updater exiting early
+        db_percent = min(percent, 99)
+        with progress_lock:
+            progress_state["step"] = step
+            progress_state["percent"] = db_percent
+        print(f"[{percent}%] {step}")
+    
+    async def background_progress_updater():
+        """
+        Periodically reads progress state and updates the database.
+        Runs in parallel with the analysis thread.
+        """
+        if not (video_id and supabase):
+            return
+        
+        last_update = 0
+        while True:
+            await anyio.sleep(0.5)  # Check every 500ms
+            
+            with progress_lock:
+                current_step = progress_state["step"]
+                current_percent = progress_state["percent"]
+                is_finished = progress_state["finished"]
+            
+            # Update database if progress changed
+            if current_percent > last_update:
+                try:
+                    await supabase.update("videos", video_id, {
+                        "current_step": current_step,
+                        "progress_percent": current_percent
+                    })
+                    last_update = current_percent
+                except Exception as e:
+                    print(f"⚠️  Error updating progress: {e}")
+            
+            # Exit when signaled
+            if is_finished:
+                break
+    
+    try:
+        # Parse options with defaults - MUST come from user input (web form)
+        options = options or {}
+        
+        # Jersey colors MUST be provided by user
+        our_team_jersey = str(options.get("our_team_jersey") or "").strip()
+        opponent_jersey = str(options.get("opponent_jersey") or "").strip()
+        
+        if not our_team_jersey or not opponent_jersey:
+            raise ValueError("Jersey colors are required - user must select team colors in the web form")
+        
+        try:
+            our_team_id = int(options.get("our_team_id") or 1)
+        except Exception:
+            our_team_id = 1
+        our_team_id = 1 if our_team_id not in (1, 2) else our_team_id
+        
+        read_from_stub = bool(options.get("read_from_stub", False))
+        clear_stubs_after = bool(options.get("clear_stubs_after", True))
+        save_annotated_video = bool(options.get("save_annotated_video", True))
+        
+        # Detection parameters (from user selections)
+        player_confidence = float(options.get("player_confidence", 0.3))
+        ball_confidence = float(options.get("ball_confidence", 0.15))
+        detection_batch_size = int(options.get("detection_batch_size", 10))
+        image_size = int(options.get("image_size", 1080))
+        max_players_on_court = int(options.get("max_players_on_court", 10))
+        
+        # Display parameters (from user preferences)
+        render_speed_text = bool(options.get("render_speed_text", True))
+        render_distance_text = bool(options.get("render_distance_text", True))
+        render_tactical_view = bool(options.get("render_tactical_view", True))
+        render_court_keypoints = bool(options.get("render_court_keypoints", True))
+        
+        # Output paths (use absolute paths to avoid working directory issues)
+        from configs import STUBS_DEFAULT_PATH
+        stub_root = os.path.join(STUBS_DEFAULT_PATH, "api", str(video_id or "no-id"))
+        
+        # Create absolute path for output video
+        backend_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+        annotated_dir = os.path.join(backend_dir, "output_videos", "annotated")
+        os.makedirs(annotated_dir, exist_ok=True)
+        output_path = os.path.join(annotated_dir, f"{video_id or 'latest'}.mp4")
+        
+        # Start progress updater task and analysis in parallel
+        async with anyio.create_task_group() as tg:
+            # Start the background progress updater
+            tg.start_soon(background_progress_updater)
+            
+            # Run the analysis in a thread
+            def run_sync():
+                """Synchronous wrapper for core analysis."""
+                return core_run_team_analysis(
+                    video_path=video_path,
+                    output_path=output_path,
+                    stub_path=stub_root,
+                    our_team_jersey=our_team_jersey,
+                    opponent_jersey=opponent_jersey,
+                    our_team_id=our_team_id,
+                    read_from_stub=read_from_stub,
+                    clear_stubs_after=clear_stubs_after,
+                    save_annotated_video=save_annotated_video,
+                    progress_callback=sync_progress_callback,
+                    player_confidence=player_confidence,
+                    ball_confidence=ball_confidence,
+                    detection_batch_size=detection_batch_size,
+                    image_size=image_size,
+                    max_players_on_court=max_players_on_court,
+                    render_speed_text=render_speed_text,
+                    render_distance_text=render_distance_text,
+                    render_tactical_view=render_tactical_view,
+                    render_court_keypoints=render_court_keypoints,
+                )
+            
+            # Wait for analysis to complete
+            result = await anyio.to_thread.run_sync(run_sync)
+        
+            # Run advanced analytics if requested
+            if result.get("status") == "completed" and options.get("enable_advanced_analytics", False):
+                try:
+                    sync_progress_callback("Running advanced analytics", 95)
+                    from analytics_engine import AnalyticsCoordinator
+                    from utils import read_video
+                    
+                    # Re-read frames for advanced analytics
+                    video_frames = await anyio.to_thread.run_sync(read_video, video_path)
+                    
+                    coordinator = AnalyticsCoordinator()
+                    advanced_results = await anyio.to_thread.run_sync(
+                        coordinator.process_all,
+                        video_frames,
+                        [], # player_tracks
+                        [], # ball_tracks
+                        [], # tactical_positions
+                        [], # player_assignment
+                        [], # ball_possession
+                        result.get("events", []),
+                        [], # shots
+                        [], # court_keypoints
+                        [], # speeds
+                        video_path,
+                        result.get("fps", 30.0)
+                    )
+                    
+                    result["advanced_analytics"] = advanced_results
+                    sync_progress_callback("Advanced analytics complete", 98)
+                except Exception as e:
+                    print(f"⚠️  Advanced analytics failed: {e}")
+            
+            # Signal background updater to finish
+            with progress_lock:
+                progress_state["finished"] = True
+        
+        
+        # Final progress update — upload annotated video to Supabase Storage first
+        annotated_url = None
+        if result.get("status") == "completed" and os.path.exists(output_path):
+            try:
+                sync_progress_callback("Uploading annotated video to cloud", 99)
+                BUCKET = "annotated-videos"
+                storage_key = f"{video_id}/annotated.mp4"
+
+                # Ensure the bucket exists (public so frontend can stream directly)
+                await supabase.ensure_bucket(BUCKET, public=True)
+
+                # Stream the file to Supabase Storage
+                await supabase.upload_file_from_path(
+                    bucket=BUCKET,
+                    storage_path=storage_key,
+                    local_path=output_path,
+                    content_type="video/mp4",
+                )
+
+                # Build a permanent public URL (no expiry)
+                annotated_url = supabase.get_public_url(BUCKET, storage_key)
+                print(f"✅  Annotated video uploaded to Supabase Storage: {annotated_url}")
+
+                # Remove the local copy to save disk space
+                try:
+                    os.remove(output_path)
+                except Exception:
+                    pass
+
+            except Exception as upload_err:
+                print(f"⚠️  Failed to upload annotated video to Supabase Storage: {upload_err}")
+                # Still mark has_annotated True — frontend will fall back to local disk endpoint
+
+        if video_id and supabase:
+            update_payload = {
+                "current_step": "Analysis complete",
+                "progress_percent": 100,
+                "status": result.get("status", "completed"),
+                "has_annotated": result.get("status") == "completed",
+            }
+            if annotated_url:
+                update_payload["annotated_url"] = annotated_url
+
+            await supabase.update("videos", video_id, update_payload)
+        
+        # Ensure all required fields are present (never null)
+        if result.get("status") == "completed":
+            required_fields = {
+                "total_frames": lambda r: r.get("total_frames") or 0,
+                "duration_seconds": lambda r: r.get("duration_seconds") or 0.0,
+                "players_detected": lambda r: r.get("players_detected") or 0,
+                "team_1_possession_percent": lambda r: r.get("team_1_possession_percent") or 50.0,
+                "team_2_possession_percent": lambda r: r.get("team_2_possession_percent") or 50.0,
+                "total_passes": lambda r: r.get("total_passes") or 0,
+                "team_1_passes": lambda r: r.get("team_1_passes") or 0,
+                "team_2_passes": lambda r: r.get("team_2_passes") or 0,
+                "total_interceptions": lambda r: r.get("total_interceptions") or 0,
+                "team_1_interceptions": lambda r: r.get("team_1_interceptions") or 0,
+                "team_2_interceptions": lambda r: r.get("team_2_interceptions") or 0,
+                "defensive_actions": lambda r: r.get("defensive_actions") or 0,
+                "overall_shooting_percentage": lambda r: r.get("overall_shooting_percentage") or 0.0,
+                "total_distance_meters": lambda r: r.get("total_distance_meters") or 0.0,
+                "avg_speed_kmh": lambda r: r.get("avg_speed_kmh") or 0.0,
+                "max_speed_kmh": lambda r: r.get("max_speed_kmh") or 0.0,
+                "processing_time_seconds": lambda r: r.get("processing_time_seconds") or 0.0,
+                "annotated_video_path": lambda r: r.get("annotated_video_path") or "",
+            }
+            for field, getter in required_fields.items():
+                if field not in result or result[field] is None:
+                    result[field] = getter(result)
+        
+        return result
+        
+    except Exception as e:
+        print(f"❌ Team analysis failed: {e}")
+        import traceback
+        traceback.print_exc()
+        
+        # Update status to failed
+        if video_id and supabase:
+            try:
+                await supabase.update("videos", video_id, {
+                    "status": "failed",
+                    "error": str(e)
+                })
+            except:
+                pass
+        
+        return {
+            "status": "failed",
+            "error": str(e)
+        }
+

analysis/team_analysis_old.py

@@ -0,0 +1,545 @@
+"""
+Team Analysis Pipeline - Wraps template components for team video analysis.
+
+This module uses the existing template components (PlayerTracker, BallTracker, etc.)
+to analyze multi-player basketball footage for team-level insights.
+"""
+import os
+import sys
+import shutil
+from typing import Dict, Any, List, Optional
+
+# Add parent directory for template imports
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+def clear_video_stubs(stub_root: str) -> bool:
+    """
+    Clear all stub files for a video to prepare for fresh analysis.
+    
+    Args:
+        stub_root: Root directory containing stubs for this video
+        
+    Returns:
+        True if successful, False otherwise
+    """
+    try:
+        if os.path.exists(stub_root):
+            shutil.rmtree(stub_root)
+            os.makedirs(stub_root, exist_ok=True)
+            return True
+    except Exception as e:
+        print(f"⚠️  Warning: Could not clear video stubs at {stub_root}: {e}")
+        return False
+    
+    return True
+
+
+async def run_team_analysis(video_path: str, options: Optional[Dict[str, Any]] = None, video_id: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Run team analysis pipeline on a video.
+    """
+    # Import template components (keep aligned with back-end/main.py)
+    from utils import read_video, save_video
+    from trackers import PlayerTracker, BallTracker
+    from team_assigner import TeamAssigner
+    from court_keypoint_detector import CourtKeypointDetector
+    from ball_aquisition.ball_aquisition_detector import BallAquisitionDetector
+    from pass_and_interception_detector import PassAndInterceptionDetector
+    from tactical_view_converter import TacticalViewConverter
+    from speed_and_distance_calculator import SpeedAndDistanceCalculator
+    from shot_detector import ShotDetector
+    from drawers import (
+        PlayerTracksDrawer,
+        BallTracksDrawer,
+        FrameNumberDrawer,
+        TeamBallControlDrawer,
+        PassInterceptionDrawer,
+        TacticalViewDrawer,
+        SpeedAndDistanceDrawer,
+        ShotDrawer,
+    )
+    from configs import (
+        STUBS_DEFAULT_PATH,
+        PLAYER_DETECTOR_PATH,
+        BALL_DETECTOR_PATH,
+        TEAM_MODEL_PATH,
+        COURT_KEYPOINT_DETECTOR_PATH,
+    )
+    from app.services.supabase_client import get_supabase_service
+    supabase = get_supabase_service()
+
+    async def update_progress(step: str, percent: int):
+        if video_id and supabase:
+            try:
+                await supabase.update("videos", video_id, {
+                    "current_step": step,
+                    "progress_percent": percent
+                })
+            except Exception as e:
+                print(f"Error updating progress: {e}")
+
+    await update_progress("Reading video", 5)
+    video_frames = read_video(video_path)
+    total_frames = len(video_frames)
+    
+    if total_frames == 0:
+        return {"error": "Could not read video frames", "total_frames": 0}
+
+    # Options (align with CLI args in back-end/main.py)
+    options = options or {}
+    our_team_jersey = str(options.get("our_team_jersey") or "white jersey")
+    opponent_jersey = str(options.get("opponent_jersey") or "dark blue jersey")
+    try:
+        our_team_id = int(options.get("our_team_id") or 1)
+    except Exception:
+        our_team_id = 1
+    our_team_id = 1 if our_team_id not in (1, 2) else our_team_id
+    max_players = 10
+    try:
+        max_players = int(options.get("max_players_on_court") or max_players)
+    except Exception:
+        pass
+    max_players = max(1, min(20, max_players))
+    
+    # Stub management options
+    clear_stubs_after = bool(options.get("clear_stubs_after", True))
+    read_from_stub = bool(options.get("read_from_stub", False))
+
+    # Use a per-video stub folder to avoid cross-video contamination.
+    stub_root = os.path.join(STUBS_DEFAULT_PATH, "api", str(video_id or "no-id"))
+    os.makedirs(stub_root, exist_ok=True)
+
+    # Initialize trackers/detectors
+    await update_progress("Initializing tracking models", 10)
+    player_tracker = PlayerTracker(PLAYER_DETECTOR_PATH)
+    ball_tracker = BallTracker(BALL_DETECTOR_PATH)
+    court_keypoint_detector = CourtKeypointDetector(COURT_KEYPOINT_DETECTOR_PATH)
+
+    # Detection & tracking (this path already enforces a max player limit inside PlayerTracker)
+    await update_progress("Tracking players and referees", 20)
+    player_tracks = player_tracker.get_object_tracks(
+        video_frames,
+        read_from_stub=read_from_stub,
+        stub_path=os.path.join(stub_root, "player_track_stubs.pkl"),
+    )
+
+    # Optional: tighten per-frame player cap if caller requests a smaller number than 10
+    if max_players < 10:
+        capped_tracks: List[Dict[int, Dict[str, Any]]] = []
+        for frame_tracks in player_tracks:
+            players = [(tid, t) for tid, t in (frame_tracks or {}).items() if str(t.get("class", "")).lower() == "player"]
+            refs = [(tid, t) for tid, t in (frame_tracks or {}).items() if str(t.get("class", "")).lower() == "referee"]
+            players.sort(key=lambda x: float(x[1].get("confidence", 0.0)), reverse=True)
+            keep = {tid: t for tid, t in players[:max_players]}
+            for tid, t in refs:
+                keep[tid] = t
+            capped_tracks.append(keep)
+        player_tracks = capped_tracks
+
+    await update_progress("Detecting and tracking ball", 35)
+    ball_tracks = ball_tracker.get_object_tracks(
+        video_frames,
+        read_from_stub=read_from_stub,
+        stub_path=os.path.join(stub_root, "ball_track_stubs.pkl"),
+    )
+
+    # Ball cleaning (improves continuity & reduces false positives)
+    ball_tracks = ball_tracker.remove_wrong_detections(ball_tracks)
+    ball_tracks = ball_tracker.interpolate_ball_positions(ball_tracks)
+
+    # Court keypoints
+    await update_progress("Detecting court layout", 50)
+    court_keypoints = court_keypoint_detector.get_court_keypoints(
+        video_frames,
+        read_from_stub=read_from_stub,
+        stub_path=os.path.join(stub_root, "court_key_points_stub.pkl"),
+    )
+
+    # Team assignment (jersey descriptions are critical for team accounts)
+    await update_progress("Assigning players to teams", 65)
+    team_assigner = TeamAssigner(team_1_class_name=our_team_jersey, team_2_class_name=opponent_jersey)
+    player_assignment = team_assigner.get_player_teams_across_frames(
+        video_frames,
+        player_tracks,
+        read_from_stub=read_from_stub,
+        stub_path=os.path.join(stub_root, "player_assignment_stub.pkl"),
+    )
+
+    # Ball possession + events
+    await update_progress("Analyzing ball possession", 75)
+    ball_aquisition_detector = BallAquisitionDetector()
+    ball_possession = ball_aquisition_detector.detect_ball_possession(player_tracks, ball_tracks)
+
+    await update_progress("Detecting passes and interceptions", 82)
+    pass_detector = PassAndInterceptionDetector()
+    passes = pass_detector.detect_passes(ball_possession, player_assignment)
+    interceptions = pass_detector.detect_interceptions(ball_possession, player_assignment)
+    
+    # Tactical view and speed calculations
+    tactical_converter = TacticalViewConverter(court_image_path="./images/basketball_court.png")
+    court_keypoints = tactical_converter.validate_keypoints(court_keypoints)
+    tactical_positions = tactical_converter.transform_players_to_tactical_view(court_keypoints, player_tracks)
+    
+    # Transform ball to tactical view
+    ball_xy_frames = []
+    for f_tracks in ball_tracks:
+        f_ball = {}
+        for b_id, b_data in (f_tracks or {}).items():
+            bbox = (b_data or {}).get("bbox")
+            if not bbox:
+                continue
+            f_ball[b_id] = [(bbox[0] + bbox[2]) / 2, bbox[3]]  # bottom-center
+        ball_xy_frames.append(f_ball)
+    tactical_ball_positions = tactical_converter.transform_points_to_tactical(court_keypoints, ball_xy_frames)
+    
+    speed_calculator = SpeedAndDistanceCalculator(
+        tactical_converter.width,
+        tactical_converter.height,
+        tactical_converter.actual_width_in_meters,
+        tactical_converter.actual_height_in_meters
+    )
+    distances = speed_calculator.calculate_distance(tactical_positions)
+    speeds = speed_calculator.calculate_speed(distances)
+    
+    # Calculate team possession percentages
+    team_1_possession = 0
+    team_2_possession = 0
+    
+    for frame_idx, (possession, assignment) in enumerate(zip(ball_possession, player_assignment)):
+        if possession != -1 and possession in assignment:
+            team = assignment[possession]
+            if team == 1:
+                team_1_possession += 1
+            elif team == 2:
+                team_2_possession += 1
+    
+    total_possession = team_1_possession + team_2_possession
+    team_1_pct = (team_1_possession / total_possession * 100) if total_possession > 0 else 50
+    team_2_pct = (team_2_possession / total_possession * 100) if total_possession > 0 else 50
+    
+    # Count unique tracked entities (players + referees)
+    unique_players = set()
+    for frame_tracks in player_tracks:
+        unique_players.update((frame_tracks or {}).keys())
+    
+    # Shot Detection and Analysis (also gives hoop locations for overlays)
+    await update_progress("Detecting hoop and shots", 88)
+    try:
+        shot_detector = ShotDetector(
+            hoop_detection_model_path=TEAM_MODEL_PATH,
+            min_shot_arc_height=50,
+            hoop_proximity_threshold=100,
+            trajectory_window=30,
+            success_time_window=15
+        )
+
+        hoop_detections = shot_detector.detect_hoop_locations(
+            video_frames,
+            read_from_stub=read_from_stub,
+            stub_path=os.path.join(stub_root, "hoop_detections_stub.pkl"),
+        )
+        
+        # Get video FPS
+        fps = 30  # Default
+        try:
+            import cv2
+            cap = cv2.VideoCapture(video_path)
+            fps = cap.get(cv2.CAP_PROP_FPS) or 30
+            cap.release()
+        except:
+            pass
+        
+        # Detect shots
+        shots = shot_detector.detect_shots(
+            ball_tracks,
+            hoop_detections,
+            player_tracks=player_tracks,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            fps=fps,
+            court_keypoints=court_keypoints
+        )
+        
+        # Calculate overall shot statistics
+        shot_stats = shot_detector.calculate_shot_statistics(shots)
+        
+        # Break down shots by team
+        team_1_shots = []
+        team_2_shots = []
+        
+        for shot in shots:
+            start_frame = int(shot['start_frame'])
+            if start_frame < len(ball_possession) and start_frame < len(player_assignment):
+                player_with_ball = ball_possession[start_frame]
+                if player_with_ball != -1 and player_with_ball in player_assignment[start_frame]:
+                    team = player_assignment[start_frame][player_with_ball]
+                    # Update the shot in the main list so it's attribution stays for events
+                    shot['team_id'] = int(team)
+                    shot['player_id'] = int(player_with_ball)
+                    
+                    if team == 1:
+                        team_1_shots.append(shot)
+                    elif team == 2:
+                        team_2_shots.append(shot)
+        
+        team_1_shot_stats = shot_detector.calculate_shot_statistics(team_1_shots)
+        team_2_shot_stats = shot_detector.calculate_shot_statistics(team_2_shots)
+        
+    except Exception as e:
+        print(f"Shot detection failed: {e}")
+        hoop_detections = [None for _ in range(total_frames)]
+        shot_stats = {
+            'total_attempts': 0,
+            'total_made': 0,
+            'total_missed': 0,
+            'overall_percentage': 0.0,
+            'by_type': {},
+            'shots': []
+        }
+        team_1_shot_stats = shot_stats.copy()
+        team_2_shot_stats = shot_stats.copy()
+
+    # Render annotated output video (clean, consistent overlays)
+    await update_progress("Rendering annotated video", 92)
+    try:
+        if our_team_id == 1:
+            our_color = [0, 120, 255]
+            opp_color = [0, 0, 200]
+        else:
+            our_color = [0, 0, 200]
+            opp_color = [0, 120, 255]
+
+        player_tracks_drawer = PlayerTracksDrawer(team_1_color=our_color, team_2_color=opp_color)
+        ball_tracks_drawer = BallTracksDrawer()
+        frame_number_drawer = FrameNumberDrawer()
+        team_ball_control_drawer = TeamBallControlDrawer()
+        pass_and_interceptions_drawer = PassInterceptionDrawer()
+        tactical_view_drawer = TacticalViewDrawer()
+        speed_and_distance_drawer = SpeedAndDistanceDrawer()
+        shot_drawer = ShotDrawer()
+
+        output_video_frames = player_tracks_drawer.draw(video_frames, player_tracks, player_assignment, ball_possession)
+        output_video_frames = ball_tracks_drawer.draw(output_video_frames, ball_tracks)
+        output_video_frames = frame_number_drawer.draw(output_video_frames)
+        output_video_frames = team_ball_control_drawer.draw(output_video_frames, player_assignment, ball_possession)
+        output_video_frames = pass_and_interceptions_drawer.draw(output_video_frames, passes, interceptions)
+        output_video_frames = shot_drawer.draw(output_video_frames, shots, hoop_detections=hoop_detections)
+        output_video_frames = speed_and_distance_drawer.draw(output_video_frames, player_tracks, distances, speeds)
+        output_video_frames = tactical_view_drawer.draw(
+            output_video_frames,
+            tactical_converter.court_image_path,
+            tactical_converter.width,
+            tactical_converter.height,
+            tactical_converter.key_points,
+            tactical_positions,
+            player_assignment,
+            ball_possession,
+        )
+
+        annotated_path = os.path.join("output_videos", "annotated", f"{video_id or 'latest'}.mp4")
+        save_video(output_video_frames, annotated_path)
+    except Exception as e:
+        print(f"Annotated video rendering failed: {e}")
+
+    # Build per-frame detections for overlays (optional, can be large)
+    detections_stride = 1
+    max_detections = 200_000
+    if options:
+        try:
+            detections_stride = int(options.get("detections_stride", detections_stride))
+        except Exception:
+            pass
+        try:
+            max_detections = int(options.get("max_detections", max_detections))
+        except Exception:
+            pass
+
+    detections_stride = max(1, min(30, detections_stride))
+    max_detections = max(1_000, max_detections)
+
+    detections: List[Dict[str, Any]] = []
+    for frame_idx in range(0, total_frames, detections_stride):
+        # Players
+        assignment = player_assignment[frame_idx] if frame_idx < len(player_assignment) else {}
+        possession_player = ball_possession[frame_idx] if frame_idx < len(ball_possession) else -1
+        current_player_tracks = player_tracks[frame_idx] if frame_idx < len(player_tracks) else []
+        for track_id, track in (current_player_tracks or {}).items():
+            bbox = track.get("bbox")
+            if not bbox:
+                continue
+            # Get tactical position for this player in this frame
+            current_tactical = tactical_positions[frame_idx] if frame_idx < len(tactical_positions) else {}
+            player_tactical = current_tactical.get(track_id)
+            
+            detections.append({
+                "frame": int(frame_idx),
+                "object_type": str(track.get("class", "player")),
+                "track_id": int(track_id),
+                "bbox": [float(b) for b in bbox] if bbox else None,
+                "confidence": float(track.get("confidence", 1.0)),
+                "team_id": int(assignment.get(track_id)) if assignment.get(track_id) is not None else None,
+                "has_ball": bool(possession_player == track_id),
+                "tactical_x": float(player_tactical[0]) if player_tactical else None,
+                "tactical_y": float(player_tactical[1]) if player_tactical else None,
+                "keypoints": None,
+            })
+            if len(detections) >= max_detections:
+                break
+
+        if len(detections) >= max_detections:
+            break
+
+        # Ball
+        current_ball_tracks = ball_tracks[frame_idx] if frame_idx < len(ball_tracks) else []
+        ball = (current_ball_tracks or {}).get(1)
+        if ball and ball.get("bbox"):
+            # Get tactical ball position
+            current_ball_tactical = tactical_ball_positions[frame_idx] if frame_idx < len(tactical_ball_positions) else {}
+            ball_tactical = current_ball_tactical.get(1)
+            
+            detections.append({
+                "frame": int(frame_idx),
+                "object_type": "ball",
+                "track_id": 1,
+                "bbox": [float(b) for b in ball.get("bbox")] if ball.get("bbox") else None,
+                "confidence": float(ball.get("confidence", 1.0)),
+                "team_id": None,
+                "has_ball": False,
+                "tactical_x": float(ball_tactical[0]) if ball_tactical else None,
+                "tactical_y": float(ball_tactical[1]) if ball_tactical else None,
+                "keypoints": None,
+            })
+        # Hoops
+        hoop = hoop_detections[frame_idx] if frame_idx < len(hoop_detections) else None
+        if hoop and hoop.get("bbox"):
+            detections.append({
+                "frame": int(frame_idx),
+                "object_type": "hoop",
+                "track_id": 0,
+                "bbox": [float(b) for b in hoop.get("bbox")] if hoop.get("bbox") else None,
+                "confidence": float(hoop.get("confidence", 1.0)),
+                "team_id": None,
+                "has_ball": False,
+                "keypoints": None,
+            })
+    
+    # Build events list
+    events = []
+    for frame_num, team_id in enumerate(passes):
+        if team_id != -1:
+            events.append({
+                "event_type": "pass",
+                "frame": frame_num,
+                "timestamp_seconds": frame_num / fps,
+                "details": {"team": team_id}
+            })
+    
+    for frame_num, team_id in enumerate(interceptions):
+        if team_id != -1:
+            events.append({
+                "event_type": "interception",
+                "frame": frame_num,
+                "timestamp_seconds": frame_num / fps,
+                "details": {"team": team_id}
+            })
+    
+    # Add shots to events
+    for shot in shots:
+        events.append({
+            "event_type": "shot",
+            "frame": int(shot['start_frame']),
+            "timestamp_seconds": float(shot['start_frame'] / fps),
+            "details": {
+                "outcome": str(shot['outcome']),
+                "team": int(shot.get('team_id')) if shot.get('team_id') is not None else None,
+                "player": int(shot.get('player_id')) if shot.get('player_id') is not None else None,
+                "type": str(shot.get('shot_type', 'unknown'))
+            }
+        })
+    
+    # Get video duration
+    fps = 30  # Default assumption
+    try:
+        import cv2
+        cap = cv2.VideoCapture(video_path)
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30
+        cap.release()
+    except:
+        pass
+    
+    duration_seconds = total_frames / fps
+    
+    # ============================================
+    # ADVANCED ANALYTICS (OPT-IN)
+    # ============================================
+    advanced_analytics = None
+    if options and options.get("enable_advanced_analytics", False):
+        try:
+            print("Running advanced analytics...")
+            from analytics_engine import AnalyticsCoordinator
+            
+            coordinator = AnalyticsCoordinator()
+            advanced_analytics = coordinator.process_all(
+                video_frames=video_frames,
+                player_tracks=player_tracks,
+                ball_tracks=ball_tracks,
+                tactical_positions=tactical_positions,
+                player_assignment=player_assignment,
+                ball_possession=ball_possession,
+                events=events,
+                shots=shots,
+                court_keypoints=court_keypoints,
+                speeds=speeds,
+                video_path=video_path,
+                fps=fps
+            )
+            print(f"Advanced analytics complete: {len(advanced_analytics.get('modules_executed', []))} modules succeeded")
+        except Exception as e:
+            print(f"Advanced analytics failed: {e}")
+            advanced_analytics = {"error": str(e), "status": "failed"}
+    
+    # Build result dictionary
+    result = {
+        "total_frames": int(total_frames),
+        "duration_seconds": float(duration_seconds),
+        "players_detected": int(len(unique_players)),
+        "team_1_possession_percent": float(round(team_1_pct, 1)),
+        "team_2_possession_percent": float(round(team_2_pct, 1)),
+        "total_passes": int(len([p for p in passes if p != -1])),
+        "total_interceptions": int(len([i for i in interceptions if i != -1])),
+        
+        # Shot statistics
+        "shot_attempts": int(shot_stats['total_attempts']),
+        "shots_made": int(shot_stats['total_made']),
+        "shots_missed": int(shot_stats['total_missed']),
+        "shooting_percentage": float(shot_stats['overall_percentage']),
+        "shot_breakdown_by_type": shot_stats['by_type'],
+        
+        # Team 1 shooting
+        "team_1_shot_attempts": int(team_1_shot_stats['total_attempts']),
+        "team_1_shots_made": int(team_1_shot_stats['total_made']),
+        
+        # Team 2 shooting
+        "team_2_shot_attempts": int(team_2_shot_stats['total_attempts']),
+        "team_2_shots_made": int(team_2_shot_stats['total_made']),
+        
+        "events": events,
+        "detections": detections,
+    }
+    
+    # Add advanced analytics if available
+    if advanced_analytics:
+        result["advanced_analytics"] = advanced_analytics
+    
+    # Clear stubs if requested (ensures fresh analysis on next run)
+    if clear_stubs_after:
+        await update_progress("Cleaning up cached data", 98)
+        try:
+            clear_video_stubs(stub_root)
+            print(f"✅ Cleared stubs for video {video_id or 'unknown'}")
+        except Exception as e:
+            print(f"⚠️  Could not clear stubs: {e}")
+    
+    return result
+

analytics_engine/__init__.py

@@ -0,0 +1,26 @@
+"""
+Advanced Analytics Engine for Basketball Video Analysis.
+
+This package provides 7 analytics modules that use geometric reasoning
+and time-series analysis to extract advanced insights from tracking data.
+"""
+
+from .coordinator import AnalyticsCoordinator
+from .spacing_engine import SpacingEngine
+from .defensive_reaction import DefensiveReactionEngine
+from .transition_effort import TransitionEffortEngine
+from .decision_quality import DecisionQualityEngine
+from .lineup_impact import LineupImpactEngine
+from .fatigue_tracker import FatigueTracker
+from .clip_generator import ClipGenerator
+
+__all__ = [
+    "AnalyticsCoordinator",
+    "SpacingEngine",
+    "DefensiveReactionEngine",
+    "TransitionEffortEngine",
+    "DecisionQualityEngine",
+    "LineupImpactEngine",
+    "FatigueTracker",
+    "ClipGenerator",
+]

analytics_engine/base.py

@@ -0,0 +1,90 @@
+"""
+Base class for all analytics modules.
+
+Provides common interface and error handling for analytics processing.
+"""
+from abc import ABC, abstractmethod
+from typing import Dict, Any, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class BaseAnalyticsModule(ABC):
+    """Abstract base class for analytics modules."""
+    
+    def __init__(self, module_name: str):
+        """
+        Initialize the analytics module.
+        
+        Args:
+            module_name: Name of the module for logging
+        """
+        self.module_name = module_name
+        self.logger = logging.getLogger(f"analytics_engine.{module_name}")
+    
+    @abstractmethod
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Process analytics for the given video data.
+        
+        Args:
+            video_frames: List of video frames
+            player_tracks: Per-frame player tracking data
+            ball_tracks: Per-frame ball tracking data
+            tactical_positions: 2D court positions for players
+            player_assignment: Per-frame team assignments
+            ball_possession: Per-frame ball possession (track_id or -1)
+            events: List of detected events (passes, interceptions, etc.)
+            shots: List of detected shots with metadata
+            court_keypoints: Court boundary keypoints
+            speeds: Per-frame player speeds
+            video_path: Path to original video file
+            fps: Video frames per second
+            **kwargs: Additional module-specific parameters
+        
+        Returns:
+            Dictionary containing module-specific analytics results
+        """
+        pass
+    
+    def safe_process(self, *args, **kwargs) -> Dict[str, Any]:
+        """
+        Safely execute process() with error handling.
+        
+        Returns partial results on error instead of crashing.
+        """
+        try:
+            return self.process(*args, **kwargs)
+        except Exception as e:
+            self.logger.error(f"{self.module_name} processing failed: {e}", exc_info=True)
+            return {
+                "error": str(e),
+                "module": self.module_name,
+                "status": "failed"
+            }
+    
+    def _get_frame_time(self, frame_idx: int, fps: float) -> float:
+        """Convert frame index to timestamp in seconds."""
+        return frame_idx / fps if fps > 0 else 0.0
+    
+    def _euclidean_distance(self, pos1: List[float], pos2: List[float]) -> float:
+        """Calculate Euclidean distance between two 2D positions."""
+        if not pos1 or not pos2 or len(pos1) < 2 or len(pos2) < 2:
+            return float('inf')
+        return ((pos1[0] - pos2[0]) ** 2 + (pos1[1] - pos2[1]) ** 2) ** 0.5

analytics_engine/clip_generator.py

@@ -0,0 +1,260 @@
+"""
+Clip Generator - Automatically extracts coaching highlight clips.
+
+Creates short video clips (±5 seconds) around flagged events for coaching review.
+"""
+from typing import Dict, Any, List
+import os
+import subprocess
+from .base import BaseAnalyticsModule
+
+
+class ClipGenerator(BaseAnalyticsModule):
+    """Generates coaching highlight clips from flagged events."""
+    
+    def __init__(
+        self,
+        clip_duration_seconds: float = 10.0,  # Total duration (5s before + 5s after)
+        output_base_dir: str = "output_videos/clips",
+    ):
+        """
+        Initialize clip generator.
+        
+        Args:
+            clip_duration_seconds: Total duration of each clip
+            output_base_dir: Base directory for clip output
+        """
+        super().__init__("clip_generator")
+        self.clip_duration = clip_duration_seconds
+        self.output_base_dir = output_base_dir
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Generate coaching clips for flagged events.
+        
+        Returns:
+            Dictionary with clip metadata
+        """
+        # Get analytics results from kwargs
+        spacing_metrics = kwargs.get("spacing_metrics", [])
+        defensive_reactions = kwargs.get("defensive_reactions", [])
+        transition_efforts = kwargs.get("transition_efforts", [])
+        decision_analyses = kwargs.get("decision_analyses", [])
+        
+        # Identify events to clip
+        clip_events = []
+        
+        # Poor spacing events
+        poor_spacing_frames = [
+            m for m in spacing_metrics
+            if m.get("spacing_quality") == "poor"
+        ]
+        # Sample every Nth poor spacing event to avoid too many clips
+        for i, m in enumerate(poor_spacing_frames):
+            if i % 10 == 0:  # Every 10th poor spacing frame
+                clip_events.append({
+                    "type": "poor_spacing",
+                    "frame": m["frame"],
+                    "timestamp": m["timestamp"],
+                    "players_involved": list(m.get("player_positions", {}).keys()),
+                    "metadata": {
+                        "spacing_quality": m["spacing_quality"],
+                        "avg_distance_m": m["avg_distance_m"],
+                        "paint_players": m["paint_players"]
+                    }
+                })
+        
+        # Late rotation events
+        late_rotations = [
+            r for r in defensive_reactions
+            if r.get("late_closeout", False)
+        ]
+        for r in late_rotations[:20]:  # Limit to 20 clips
+            clip_events.append({
+                "type": "late_rotation",
+                "frame": r["event_frame"],
+                "timestamp": r["event_frame"] / fps if fps > 0 else 0,
+                "players_involved": [r["defender_track_id"], r["offensive_player_track_id"]],
+                "metadata": {
+                    "reaction_delay_ms": r.get("reaction_delay_ms"),
+                    "closeout_speed_mps": r.get("closeout_speed_mps")
+                }
+            })
+        
+        # Poor transition effort
+        poor_transitions = [
+            t for t in transition_efforts
+            if t.get("effort_type") == "walk"
+        ]
+        for t in poor_transitions[:15]:  # Limit to 15 clips
+            clip_events.append({
+                "type": "poor_transition",
+                "frame": t["possession_change_frame"],
+                "timestamp": t["possession_change_frame"] / fps if fps > 0 else 0,
+                "players_involved": [t["player_track_id"]],
+                "metadata": {
+                    "effort_type": t["effort_type"],
+                    "max_speed_mps": t["max_speed_mps"],
+                    "effort_score": t["effort_score"]
+                }
+            })
+        
+        # Low decision quality shots
+        low_ev_shots = [
+            d for d in decision_analyses
+            if d.get("decision_quality") == "low_expected_value"
+        ]
+        for d in low_ev_shots[:20]:  # Limit to 20 clips
+            clip_events.append({
+                "type": "low_decision_quality",
+                "frame": d["shot_frame"],
+                "timestamp": d["shot_frame"] / fps if fps > 0 else 0,
+                "players_involved": [d["shooter_track_id"]],
+                "metadata": {
+                    "decision_quality": d["decision_quality"],
+                    "open_teammates": d["open_teammates"],
+                    "shooter_contested_distance": d["shooter_contested_distance"]
+                }
+            })
+        
+        # Generate clips using ffmpeg
+        auto_clips = []
+        video_id = os.path.splitext(os.path.basename(video_path))[0]
+        clip_dir = os.path.join(self.output_base_dir, video_id)
+        
+        # Create output directory
+        os.makedirs(clip_dir, exist_ok=True)
+        
+        half_duration = self.clip_duration / 2
+        
+        for i, event in enumerate(clip_events):
+            timestamp = event["timestamp"]
+            clip_type = event["type"]
+            
+            # Calculate start and end times
+            start_time = max(0, timestamp - half_duration)
+            end_time = timestamp + half_duration
+            
+            # Generate clip filename
+            clip_filename = f"{clip_type}_{int(timestamp)}.mp4"
+            clip_path = os.path.join(clip_dir, clip_filename)
+            
+            # Extract clip using ffmpeg
+            success = self._extract_clip(
+                video_path,
+                clip_path,
+                start_time,
+                end_time
+            )
+            
+            if success:
+                # Generate description
+                description = self._generate_description(event)
+                
+                auto_clips.append({
+                    "clip_type": clip_type,
+                    "timestamp_start": float(start_time),
+                    "timestamp_end": float(end_time),
+                    "frame_start": int(start_time * fps) if fps > 0 else 0,
+                    "frame_end": int(end_time * fps) if fps > 0 else 0,
+                    "players_involved": [int(p) for p in event["players_involved"] if isinstance(p, (int, str))],
+                    "file_path": clip_path,
+                    "description": description,
+                    "metadata": event["metadata"]
+                })
+        
+        # Calculate summary
+        clip_type_counts = {}
+        for clip in auto_clips:
+            clip_type = clip["clip_type"]
+            clip_type_counts[clip_type] = clip_type_counts.get(clip_type, 0) + 1
+        
+        summary = {
+            "total_clips_generated": len(auto_clips),
+            "clips_by_type": clip_type_counts,
+            "output_directory": clip_dir
+        }
+        
+        return {
+            "auto_clips": auto_clips,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _extract_clip(
+        self,
+        video_path: str,
+        output_path: str,
+        start_time: float,
+        end_time: float
+    ) -> bool:
+        """
+        Extract a video clip using ffmpeg.
+        
+        Args:
+            video_path: Path to source video
+            output_path: Path for output clip
+            start_time: Start time in seconds
+            end_time: End time in seconds
+        
+        Returns:
+            True if successful, False otherwise
+        """
+        try:
+            duration = end_time - start_time
+            
+            # ffmpeg command
+            cmd = [
+                "ffmpeg",
+                "-i", video_path,
+                "-ss", str(start_time),
+                "-t", str(duration),
+                "-c:v", "libx264",
+                "-c:a", "aac",
+                "-y",  # Overwrite output file
+                output_path
+            ]
+            
+            # Run ffmpeg (suppress output)
+            result = subprocess.run(
+                cmd,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                timeout=30
+            )
+            
+            return result.returncode == 0
+        except Exception as e:
+            self.logger.error(f"Failed to extract clip: {e}")
+            return False
+    
+    def _generate_description(self, event: Dict) -> str:
+        """Generate human-readable description for clip."""
+        clip_type = event["type"]
+        metadata = event.get("metadata", {})
+        
+        if clip_type == "poor_spacing":
+            return f"Poor offensive spacing: {metadata.get('paint_players', 0)} players in paint, avg distance {metadata.get('avg_distance_m', 0):.1f}m"
+        elif clip_type == "late_rotation":
+            return f"Late defensive rotation: {metadata.get('reaction_delay_ms', 0):.0f}ms delay, {metadata.get('closeout_speed_mps', 0):.1f}m/s closeout"
+        elif clip_type == "poor_transition":
+            return f"Low transition effort: {metadata.get('effort_type', 'unknown')} at {metadata.get('max_speed_mps', 0):.1f}m/s"
+        elif clip_type == "low_decision_quality":
+            return f"Questionable shot selection: {metadata.get('open_teammates', 0)} open teammates, shooter contested at {metadata.get('shooter_contested_distance', 0):.1f}m"
+        else:
+            return f"Flagged event: {clip_type}"

analytics_engine/coordinator.py

@@ -0,0 +1,261 @@
+"""
+Analytics Coordinator - Orchestrates all analytics modules.
+
+Runs all 7 analytics modules in the correct order and aggregates results.
+"""
+from typing import Dict, Any, List
+import logging
+
+from .spacing_engine import SpacingEngine
+from .defensive_reaction import DefensiveReactionEngine
+from .transition_effort import TransitionEffortEngine
+from .decision_quality import DecisionQualityEngine
+from .lineup_impact import LineupImpactEngine
+from .fatigue_tracker import FatigueTracker
+from .clip_generator import ClipGenerator
+
+logger = logging.getLogger(__name__)
+
+
+class AnalyticsCoordinator:
+    """Coordinates execution of all advanced analytics modules."""
+    
+    def __init__(self):
+        """Initialize all analytics modules."""
+        self.spacing_engine = SpacingEngine()
+        self.defensive_reaction = DefensiveReactionEngine()
+        self.transition_effort = TransitionEffortEngine()
+        self.decision_quality = DecisionQualityEngine()
+        self.lineup_impact = LineupImpactEngine()
+        self.fatigue_tracker = FatigueTracker()
+        self.clip_generator = ClipGenerator()
+    
+    def process_all(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float
+    ) -> Dict[str, Any]:
+        """
+        Run all analytics modules and aggregate results.
+        
+        Modules are executed in dependency order:
+        1. Spacing Engine (independent)
+        2. Defensive Reaction Engine (independent)
+        3. Transition Effort Engine (independent)
+        4. Decision Quality Engine (independent)
+        5. Lineup Impact Engine (depends on spacing + defensive reactions)
+        6. Fatigue Tracker (depends on defensive reactions)
+        7. Clip Generator (depends on all previous modules)
+        
+        Args:
+            video_frames: List of video frames
+            player_tracks: Per-frame player tracking data
+            ball_tracks: Per-frame ball tracking data
+            tactical_positions: 2D court positions for players
+            player_assignment: Per-frame team assignments
+            ball_possession: Per-frame ball possession
+            events: List of detected events
+            shots: List of detected shots
+            court_keypoints: Court boundary keypoints
+            speeds: Per-frame player speeds
+            video_path: Path to original video
+            fps: Frames per second
+        
+        Returns:
+            Aggregated analytics results from all modules
+        """
+        logger.info("Starting advanced analytics processing")
+        
+        results = {
+            "modules_executed": [],
+            "modules_failed": [],
+        }
+        
+        # Module 1: Spacing Engine
+        logger.info("Running Spacing Engine")
+        spacing_result = self.spacing_engine.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps
+        )
+        
+        if spacing_result.get("status") == "success":
+            results["spacing"] = spacing_result
+            results["modules_executed"].append("spacing_engine")
+        else:
+            results["modules_failed"].append("spacing_engine")
+            logger.error(f"Spacing Engine failed: {spacing_result.get('error')}")
+        
+        # Module 2: Defensive Reaction Engine
+        logger.info("Running Defensive Reaction Engine")
+        defensive_result = self.defensive_reaction.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps
+        )
+        
+        if defensive_result.get("status") == "success":
+            results["defensive_reactions"] = defensive_result
+            results["modules_executed"].append("defensive_reaction")
+        else:
+            results["modules_failed"].append("defensive_reaction")
+            logger.error(f"Defensive Reaction Engine failed: {defensive_result.get('error')}")
+        
+        # Module 3: Transition Effort Engine
+        logger.info("Running Transition Effort Engine")
+        transition_result = self.transition_effort.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps
+        )
+        
+        if transition_result.get("status") == "success":
+            results["transition_effort"] = transition_result
+            results["modules_executed"].append("transition_effort")
+        else:
+            results["modules_failed"].append("transition_effort")
+            logger.error(f"Transition Effort Engine failed: {transition_result.get('error')}")
+        
+        # Module 4: Decision Quality Engine
+        logger.info("Running Decision Quality Engine")
+        decision_result = self.decision_quality.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps
+        )
+        
+        if decision_result.get("status") == "success":
+            results["decision_quality"] = decision_result
+            results["modules_executed"].append("decision_quality")
+        else:
+            results["modules_failed"].append("decision_quality")
+            logger.error(f"Decision Quality Engine failed: {decision_result.get('error')}")
+        
+        # Module 5: Lineup Impact Engine (depends on spacing + defensive reactions)
+        logger.info("Running Lineup Impact Engine")
+        lineup_result = self.lineup_impact.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps,
+            spacing_metrics=spacing_result.get("spacing_metrics", []),
+            defensive_reactions=defensive_result.get("defensive_reactions", [])
+        )
+        
+        if lineup_result.get("status") == "success":
+            results["lineup_impact"] = lineup_result
+            results["modules_executed"].append("lineup_impact")
+        else:
+            results["modules_failed"].append("lineup_impact")
+            logger.error(f"Lineup Impact Engine failed: {lineup_result.get('error')}")
+        
+        # Module 6: Fatigue Tracker (depends on defensive reactions)
+        logger.info("Running Fatigue Tracker")
+        fatigue_result = self.fatigue_tracker.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps,
+            defensive_reactions=defensive_result.get("defensive_reactions", [])
+        )
+        
+        if fatigue_result.get("status") == "success":
+            results["fatigue"] = fatigue_result
+            results["modules_executed"].append("fatigue_tracker")
+        else:
+            results["modules_failed"].append("fatigue_tracker")
+            logger.error(f"Fatigue Tracker failed: {fatigue_result.get('error')}")
+        
+        # Module 7: Clip Generator (depends on all previous modules)
+        logger.info("Running Clip Generator")
+        clip_result = self.clip_generator.safe_process(
+            video_frames=video_frames,
+            player_tracks=player_tracks,
+            ball_tracks=ball_tracks,
+            tactical_positions=tactical_positions,
+            player_assignment=player_assignment,
+            ball_possession=ball_possession,
+            events=events,
+            shots=shots,
+            court_keypoints=court_keypoints,
+            speeds=speeds,
+            video_path=video_path,
+            fps=fps,
+            spacing_metrics=spacing_result.get("spacing_metrics", []),
+            defensive_reactions=defensive_result.get("defensive_reactions", []),
+            transition_efforts=transition_result.get("transition_efforts", []),
+            decision_analyses=decision_result.get("decision_analyses", [])
+        )
+        
+        if clip_result.get("status") == "success":
+            results["clips"] = clip_result
+            results["modules_executed"].append("clip_generator")
+        else:
+            results["modules_failed"].append("clip_generator")
+            logger.error(f"Clip Generator failed: {clip_result.get('error')}")
+        
+        logger.info(f"Advanced analytics complete. Executed: {len(results['modules_executed'])}, Failed: {len(results['modules_failed'])}")
+        
+        return results

analytics_engine/decision_quality.py

@@ -0,0 +1,173 @@
+"""
+Decision Quality Engine - Analyzes shot decision quality.
+
+Compares shooter's contested distance vs. teammate openness to evaluate
+whether the shot was the best available option.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class DecisionQualityEngine(BaseAnalyticsModule):
+    """Analyzes shot decision quality based on player openness."""
+    
+    def __init__(
+        self,
+        open_threshold_m: float = 2.5,
+        contested_threshold_m: float = 1.5,
+    ):
+        """
+        Initialize decision quality engine.
+        
+        Args:
+            open_threshold_m: Distance to defender for "open" classification
+            contested_threshold_m: Distance to defender for "contested" classification
+        """
+        super().__init__("decision_quality")
+        self.open_threshold = open_threshold_m
+        self.contested_threshold = contested_threshold_m
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Analyze decision quality for all shots.
+        
+        Returns:
+            Dictionary with decision analysis for each shot
+        """
+        decision_analyses = []
+        
+        for shot in shots:
+            frame = shot.get("start_frame", shot.get("frame", 0))
+            if frame >= len(player_assignment) or frame >= len(tactical_positions):
+                continue
+            
+            assignment = player_assignment[frame]
+            tactical_pos = tactical_positions[frame]
+            
+            shooter_id = shot.get("player_id")
+            if not shooter_id or shooter_id not in assignment:
+                continue
+            
+            offense_team = assignment[shooter_id]
+            defense_team = 1 if offense_team == 2 else 2
+            
+            shooter_pos = tactical_pos.get(shooter_id)
+            if not shooter_pos:
+                continue
+            
+            # Find nearest defender to shooter
+            shooter_contested_distance = float('inf')
+            for player_id, team_id in assignment.items():
+                if team_id == defense_team and player_id in tactical_pos:
+                    defender_pos = tactical_pos[player_id]
+                    dist = self._euclidean_distance(shooter_pos, defender_pos)
+                    if dist < shooter_contested_distance:
+                        shooter_contested_distance = dist
+            
+            # Analyze teammates' openness
+            open_teammates = 0
+            best_teammate_openness = 0.0
+            teammate_data = []
+            
+            for player_id, team_id in assignment.items():
+                if team_id == offense_team and player_id != shooter_id and player_id in tactical_pos:
+                    teammate_pos = tactical_pos[player_id]
+                    
+                    # Find nearest defender to this teammate
+                    min_defender_dist = float('inf')
+                    for def_id, def_team in assignment.items():
+                        if def_team == defense_team and def_id in tactical_pos:
+                            def_pos = tactical_pos[def_id]
+                            dist = self._euclidean_distance(teammate_pos, def_pos)
+                            if dist < min_defender_dist:
+                                min_defender_dist = dist
+                    
+                    teammate_data.append({
+                        "player_id": player_id,
+                        "defender_distance": float(min_defender_dist)
+                    })
+                    
+                    if min_defender_dist > self.open_threshold:
+                        open_teammates += 1
+                        if min_defender_dist > best_teammate_openness:
+                            best_teammate_openness = min_defender_dist
+            
+            # Determine decision quality
+            shooter_is_contested = shooter_contested_distance < self.contested_threshold
+            has_open_teammate = open_teammates > 0
+            
+            if shooter_is_contested and has_open_teammate:
+                # Bad decision: shooter contested but open teammate available
+                decision_quality = "low_expected_value"
+            elif not shooter_is_contested:
+                # Good decision: shooter is open
+                decision_quality = "high_expected_value"
+            else:
+                # Acceptable: shooter contested but no better options
+                decision_quality = "acceptable"
+            
+            decision_analyses.append({
+                "event_id": f"shot_{frame}",
+                "shot_frame": frame,
+                "shooter_track_id": shooter_id,
+                "shooter_contested_distance": float(shooter_contested_distance),
+                "open_teammates": open_teammates,
+                "best_teammate_openness": float(best_teammate_openness) if best_teammate_openness > 0 else None,
+                "decision_quality": decision_quality,
+                "teammate_positions": teammate_data,
+                "shot_outcome": shot.get("outcome", "unknown")
+            })
+        
+        # Calculate summary statistics
+        if decision_analyses:
+            quality_counts = {
+                "high_expected_value": 0,
+                "acceptable": 0,
+                "low_expected_value": 0
+            }
+            for analysis in decision_analyses:
+                quality_counts[analysis["decision_quality"]] += 1
+            
+            total = len(decision_analyses)
+            
+            summary = {
+                "total_shots_analyzed": total,
+                "high_ev_shots": quality_counts["high_expected_value"],
+                "acceptable_shots": quality_counts["acceptable"],
+                "low_ev_shots": quality_counts["low_expected_value"],
+                "low_ev_rate": (quality_counts["low_expected_value"] / total * 100) if total > 0 else 0,
+                "avg_shooter_contested_distance": float(np.mean([
+                    a["shooter_contested_distance"] for a in decision_analyses
+                ])),
+            }
+        else:
+            summary = {
+                "total_shots_analyzed": 0,
+                "high_ev_shots": 0,
+                "acceptable_shots": 0,
+                "low_ev_shots": 0,
+                "low_ev_rate": 0,
+                "avg_shooter_contested_distance": 0,
+            }
+        
+        return {
+            "decision_analyses": decision_analyses,
+            "summary": summary,
+            "status": "success"
+        }

analytics_engine/defensive_reaction.py

@@ -0,0 +1,273 @@
+"""
+Defensive Reaction Engine - Analyzes defensive reaction times and closeout speeds.
+
+For every offensive event (shot, pass, drive), measures how quickly the nearest
+defender reacts and closes out.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class DefensiveReactionEngine(BaseAnalyticsModule):
+    """Analyzes defensive reaction times and closeout quality."""
+    
+    def __init__(
+        self,
+        late_closeout_delay_ms: float = 500,
+        late_closeout_speed_mps: float = 4.0,
+        reaction_window_frames: int = 30,  # ~1 second at 30fps
+    ):
+        """
+        Initialize defensive reaction engine.
+        
+        Args:
+            late_closeout_delay_ms: Reaction delay threshold for "late" classification
+            late_closeout_speed_mps: Speed threshold for "late" classification
+            reaction_window_frames: Number of frames to analyze after event
+        """
+        super().__init__("defensive_reaction")
+        self.late_delay_threshold = late_closeout_delay_ms
+        self.late_speed_threshold = late_closeout_speed_mps
+        self.reaction_window = reaction_window_frames
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Analyze defensive reactions for all offensive events.
+        
+        Returns:
+            Dictionary with defensive reaction metrics for each event
+        """
+        defensive_reactions = []
+        
+        # Analyze shots (primary offensive events)
+        for shot in shots:
+            frame = shot.get("start_frame", shot.get("frame", 0))
+            if frame >= len(player_assignment) or frame >= len(tactical_positions):
+                continue
+            
+            assignment = player_assignment[frame]
+            tactical_pos = tactical_positions[frame]
+            
+            # Get shooter info
+            shooter_id = shot.get("player_id")
+            if not shooter_id or shooter_id not in assignment:
+                continue
+            
+            offense_team = assignment[shooter_id]
+            defense_team = 1 if offense_team == 2 else 2
+            
+            # Find nearest defender
+            shooter_pos = tactical_pos.get(shooter_id)
+            if not shooter_pos:
+                continue
+            
+            nearest_defender = None
+            min_distance = float('inf')
+            
+            for player_id, team_id in assignment.items():
+                if team_id == defense_team and player_id in tactical_pos:
+                    defender_pos = tactical_pos[player_id]
+                    dist = self._euclidean_distance(shooter_pos, defender_pos)
+                    if dist < min_distance:
+                        min_distance = dist
+                        nearest_defender = player_id
+            
+            if not nearest_defender:
+                continue
+            
+            # Measure reaction (simplified: check if defender moved toward shooter)
+            reaction_metrics = self._measure_reaction(
+                frame,
+                nearest_defender,
+                shooter_id,
+                tactical_positions,
+                speeds,
+                fps
+            )
+            
+            defensive_reactions.append({
+                "event_id": f"shot_{frame}",
+                "event_type": "shot",
+                "event_frame": frame,
+                "defender_track_id": nearest_defender,
+                "offensive_player_track_id": shooter_id,
+                "distance_at_event": float(min_distance),
+                **reaction_metrics
+            })
+        
+        # Analyze passes
+        for event in events:
+            if event.get("event_type") != "pass":
+                continue
+            
+            frame = event.get("frame", 0)
+            if frame >= len(player_assignment) or frame >= len(tactical_positions):
+                continue
+            
+            assignment = player_assignment[frame]
+            tactical_pos = tactical_positions[frame]
+            
+            passer_id = event.get("player_id")
+            if not passer_id or passer_id not in assignment:
+                continue
+            
+            offense_team = assignment[passer_id]
+            defense_team = 1 if offense_team == 2 else 2
+            
+            passer_pos = tactical_pos.get(passer_id)
+            if not passer_pos:
+                continue
+            
+            # Find nearest defender
+            nearest_defender = None
+            min_distance = float('inf')
+            
+            for player_id, team_id in assignment.items():
+                if team_id == defense_team and player_id in tactical_pos:
+                    defender_pos = tactical_pos[player_id]
+                    dist = self._euclidean_distance(passer_pos, defender_pos)
+                    if dist < min_distance:
+                        min_distance = dist
+                        nearest_defender = player_id
+            
+            if not nearest_defender:
+                continue
+            
+            reaction_metrics = self._measure_reaction(
+                frame,
+                nearest_defender,
+                passer_id,
+                tactical_positions,
+                speeds,
+                fps
+            )
+            
+            defensive_reactions.append({
+                "event_id": f"pass_{frame}",
+                "event_type": "pass",
+                "event_frame": frame,
+                "defender_track_id": nearest_defender,
+                "offensive_player_track_id": passer_id,
+                "distance_at_event": float(min_distance),
+                **reaction_metrics
+            })
+        
+        # Calculate summary statistics
+        if defensive_reactions:
+            late_closeouts = sum(1 for r in defensive_reactions if r.get("late_closeout", False))
+            avg_reaction_delay = np.mean([
+                r["reaction_delay_ms"] for r in defensive_reactions 
+                if r.get("reaction_delay_ms") is not None
+            ])
+            avg_closeout_speed = np.mean([
+                r["closeout_speed_mps"] for r in defensive_reactions 
+                if r.get("closeout_speed_mps") is not None
+            ])
+            
+            summary = {
+                "total_defensive_events": len(defensive_reactions),
+                "late_closeouts": late_closeouts,
+                "late_closeout_rate": (late_closeouts / len(defensive_reactions) * 100),
+                "avg_reaction_delay_ms": float(avg_reaction_delay) if not np.isnan(avg_reaction_delay) else None,
+                "avg_closeout_speed_mps": float(avg_closeout_speed) if not np.isnan(avg_closeout_speed) else None,
+            }
+        else:
+            summary = {
+                "total_defensive_events": 0,
+                "late_closeouts": 0,
+                "late_closeout_rate": 0,
+                "avg_reaction_delay_ms": None,
+                "avg_closeout_speed_mps": None,
+            }
+        
+        return {
+            "defensive_reactions": defensive_reactions,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _measure_reaction(
+        self,
+        event_frame: int,
+        defender_id: int,
+        offensive_player_id: int,
+        tactical_positions: List[Dict],
+        speeds: List[Dict],
+        fps: float
+    ) -> Dict[str, Any]:
+        """
+        Measure defender's reaction to an offensive event.
+        
+        Args:
+            event_frame: Frame when event occurred
+            defender_id: Track ID of defender
+            offensive_player_id: Track ID of offensive player
+            tactical_positions: All tactical positions
+            speeds: All speed data
+            fps: Frames per second
+        
+        Returns:
+            Dictionary with reaction metrics
+        """
+        # Simplified reaction measurement
+        # In full implementation, would track defender movement vector toward offensive player
+        
+        reaction_start_frame = None
+        max_speed = 0.0
+        
+        # Look at next N frames after event
+        for offset in range(1, min(self.reaction_window, len(tactical_positions) - event_frame)):
+            frame_idx = event_frame + offset
+            
+            if frame_idx >= len(speeds):
+                break
+            
+            # Get defender speed in this frame
+            frame_speeds = speeds[frame_idx]
+            if defender_id in frame_speeds:
+                speed = frame_speeds[defender_id]
+                if speed > max_speed:
+                    max_speed = speed
+                
+                # Detect reaction start (speed increase)
+                if speed > 3.0 and reaction_start_frame is None:  # 3 m/s threshold
+                    reaction_start_frame = frame_idx
+        
+        # Calculate metrics
+        if reaction_start_frame:
+            reaction_delay_frames = reaction_start_frame - event_frame
+            reaction_delay_ms = (reaction_delay_frames / fps) * 1000 if fps > 0 else 0
+        else:
+            reaction_delay_ms = None
+        
+        closeout_speed_mps = max_speed if max_speed > 0 else None
+        
+        # Determine if late closeout
+        late_closeout = False
+        if reaction_delay_ms and reaction_delay_ms > self.late_delay_threshold:
+            late_closeout = True
+        if closeout_speed_mps and closeout_speed_mps < self.late_speed_threshold:
+            late_closeout = True
+        
+        return {
+            "reaction_start_frame": reaction_start_frame,
+            "reaction_delay_ms": reaction_delay_ms,
+            "closeout_speed_mps": closeout_speed_mps,
+            "late_closeout": late_closeout
+        }

analytics_engine/fatigue_tracker.py

@@ -0,0 +1,228 @@
+"""
+Fatigue Tracker - Monitors player fatigue indicators over time.
+
+Tracks speed decline and reaction delay increase to identify fatigue patterns.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class FatigueTracker(BaseAnalyticsModule):
+    """Tracks player fatigue indicators using speed and reaction metrics."""
+    
+    def __init__(
+        self,
+        time_window_minutes: float = 2.0,
+        baseline_window_minutes: float = 3.0,
+        low_fatigue_threshold: float = 5.0,
+        medium_fatigue_threshold: float = 15.0,
+    ):
+        """
+        Initialize fatigue tracker.
+        
+        Args:
+            time_window_minutes: Size of rolling time window for analysis
+            baseline_window_minutes: Duration of early-game baseline period
+            low_fatigue_threshold: Percentage decline for low fatigue
+            medium_fatigue_threshold: Percentage decline for medium fatigue
+        """
+        super().__init__("fatigue_tracker")
+        self.time_window_minutes = time_window_minutes
+        self.baseline_window_minutes = baseline_window_minutes
+        self.low_threshold = low_fatigue_threshold
+        self.medium_threshold = medium_fatigue_threshold
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Track fatigue indicators for all players over time.
+        
+        Returns:
+            Dictionary with fatigue metrics per player per time window
+        """
+        defensive_reactions = kwargs.get("defensive_reactions", [])
+        
+        fatigue_indices = []
+        
+        # Get all unique players
+        all_players = set()
+        for assignment in player_assignment:
+            all_players.update(assignment.keys())
+        
+        # Calculate baseline metrics (first N minutes)
+        baseline_frames = int(self.baseline_window_minutes * 60 * fps)
+        baseline_metrics = self._calculate_baseline_metrics(
+            all_players,
+            speeds[:baseline_frames],
+            defensive_reactions,
+            baseline_frames
+        )
+        
+        # Analyze in time windows
+        window_frames = int(self.time_window_minutes * 60 * fps)
+        total_frames = len(speeds)
+        
+        for window_start in range(0, total_frames, window_frames):
+            window_end = min(window_start + window_frames, total_frames)
+            window_minute = int((window_start / fps) / 60)
+            
+            # Skip if this is the baseline window
+            if window_start < baseline_frames:
+                continue
+            
+            window_speeds = speeds[window_start:window_end]
+            
+            for player_id in all_players:
+                # Calculate current window metrics
+                player_speeds = []
+                for frame_speeds in window_speeds:
+                    if player_id in frame_speeds:
+                        player_speeds.append(frame_speeds[player_id])
+                
+                if not player_speeds:
+                    continue
+                
+                current_avg_speed = np.mean(player_speeds)
+                
+                # Get baseline for this player
+                baseline_speed = baseline_metrics.get(player_id, {}).get("avg_speed", 0)
+                baseline_reaction = baseline_metrics.get(player_id, {}).get("avg_reaction_ms")
+                
+                if baseline_speed == 0:
+                    continue
+                
+                # Calculate speed decline
+                speed_drop_pct = ((baseline_speed - current_avg_speed) / baseline_speed) * 100
+                
+                # Calculate reaction delay increase (if available)
+                window_reactions = [
+                    r for r in defensive_reactions
+                    if r.get("defender_track_id") == player_id
+                    and window_start <= r.get("event_frame", 0) < window_end
+                    and r.get("reaction_delay_ms") is not None
+                ]
+                
+                if window_reactions and baseline_reaction:
+                    current_reaction = np.mean([r["reaction_delay_ms"] for r in window_reactions])
+                    reaction_increase_pct = ((current_reaction - baseline_reaction) / baseline_reaction) * 100
+                else:
+                    current_reaction = None
+                    reaction_increase_pct = None
+                
+                # Classify fatigue level
+                if speed_drop_pct < self.low_threshold:
+                    fatigue_level = "low"
+                elif speed_drop_pct < self.medium_threshold:
+                    fatigue_level = "medium"
+                else:
+                    fatigue_level = "high"
+                
+                fatigue_indices.append({
+                    "player_track_id": player_id,
+                    "time_window_start": window_start / fps if fps > 0 else 0,
+                    "time_window_end": window_end / fps if fps > 0 else 0,
+                    "minute": window_minute,
+                    "baseline_speed_mps": float(baseline_speed),
+                    "current_speed_mps": float(current_avg_speed),
+                    "speed_drop_percentage": float(speed_drop_pct),
+                    "baseline_reaction_ms": float(baseline_reaction) if baseline_reaction else None,
+                    "current_reaction_ms": float(current_reaction) if current_reaction else None,
+                    "reaction_delay_increase_percentage": float(reaction_increase_pct) if reaction_increase_pct else None,
+                    "fatigue_level": fatigue_level
+                })
+        
+        # Calculate summary statistics
+        if fatigue_indices:
+            high_fatigue_count = sum(1 for f in fatigue_indices if f["fatigue_level"] == "high")
+            medium_fatigue_count = sum(1 for f in fatigue_indices if f["fatigue_level"] == "medium")
+            
+            summary = {
+                "total_measurements": len(fatigue_indices),
+                "high_fatigue_instances": high_fatigue_count,
+                "medium_fatigue_instances": medium_fatigue_count,
+                "avg_speed_drop_pct": float(np.mean([f["speed_drop_percentage"] for f in fatigue_indices])),
+                "max_speed_drop_pct": float(max(f["speed_drop_percentage"] for f in fatigue_indices)),
+            }
+        else:
+            summary = {
+                "total_measurements": 0,
+                "high_fatigue_instances": 0,
+                "medium_fatigue_instances": 0,
+                "avg_speed_drop_pct": 0,
+                "max_speed_drop_pct": 0,
+            }
+        
+        return {
+            "fatigue_indices": fatigue_indices,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _calculate_baseline_metrics(
+        self,
+        players: set,
+        baseline_speeds: List[Dict],
+        defensive_reactions: List[Dict],
+        baseline_frames: int
+    ) -> Dict[int, Dict[str, float]]:
+        """
+        Calculate baseline metrics for each player from early game.
+        
+        Args:
+            players: Set of player IDs
+            baseline_speeds: Speed data from baseline period
+            defensive_reactions: All defensive reaction data
+            baseline_frames: Number of frames in baseline
+        
+        Returns:
+            Dictionary mapping player_id to baseline metrics
+        """
+        baseline_metrics = {}
+        
+        for player_id in players:
+            # Collect speeds
+            player_speeds = []
+            for frame_speeds in baseline_speeds:
+                if player_id in frame_speeds:
+                    player_speeds.append(frame_speeds[player_id])
+            
+            if player_speeds:
+                avg_speed = np.mean(player_speeds)
+            else:
+                avg_speed = 0
+            
+            # Collect reaction times
+            player_reactions = [
+                r["reaction_delay_ms"]
+                for r in defensive_reactions
+                if r.get("defender_track_id") == player_id
+                and r.get("event_frame", 0) < baseline_frames
+                and r.get("reaction_delay_ms") is not None
+            ]
+            
+            if player_reactions:
+                avg_reaction = np.mean(player_reactions)
+            else:
+                avg_reaction = None
+            
+            baseline_metrics[player_id] = {
+                "avg_speed": avg_speed,
+                "avg_reaction_ms": avg_reaction
+            }
+        
+        return baseline_metrics

analytics_engine/lineup_impact.py

@@ -0,0 +1,261 @@
+"""
+Lineup Impact Engine - Analyzes performance of specific 5-player combinations.
+
+Segments game by unique lineups and calculates offensive/defensive ratings,
+spacing quality, and error rates for each combination.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class LineupImpactEngine(BaseAnalyticsModule):
+    """Analyzes performance metrics for specific player combinations."""
+    
+    def __init__(self):
+        """Initialize lineup impact engine."""
+        super().__init__("lineup_impact")
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Analyze lineup performance across the game.
+        
+        Returns:
+            Dictionary with lineup metrics
+        """
+        # Get spacing metrics and defensive reactions from kwargs if available
+        spacing_metrics = kwargs.get("spacing_metrics", [])
+        defensive_reactions = kwargs.get("defensive_reactions", [])
+        
+        # Detect lineup segments
+        lineup_segments = self._detect_lineup_segments(
+            player_assignment,
+            ball_possession,
+            fps
+        )
+        
+        lineup_metrics = []
+        
+        for segment in lineup_segments:
+            team_id = segment["team_id"]
+            lineup_hash = segment["lineup_hash"]
+            player_ids = segment["player_ids"]
+            start_frame = segment["start_frame"]
+            end_frame = segment["end_frame"]
+            
+            # Calculate metrics for this lineup segment
+            segment_shots = [
+                s for s in shots
+                if start_frame <= s.get("start_frame", s.get("frame", 0)) < end_frame
+                and s.get("team") == team_id
+            ]
+            
+            segment_shots_allowed = [
+                s for s in shots
+                if start_frame <= s.get("start_frame", s.get("frame", 0)) < end_frame
+                and s.get("team") != team_id
+            ]
+            
+            # Points scored (simplified: 2 points per made shot)
+            points_scored = sum(2 for s in segment_shots if s.get("outcome") == "made")
+            points_allowed = sum(2 for s in segment_shots_allowed if s.get("outcome") == "made")
+            
+            # Possessions (estimate from shots + turnovers)
+            possessions = len(segment_shots)  # Simplified
+            
+            # Offensive/defensive ratings (per 100 possessions)
+            if possessions > 0:
+                offensive_rating = (points_scored / possessions) * 100
+                defensive_rating = (points_allowed / possessions) * 100
+                net_rating = offensive_rating - defensive_rating
+            else:
+                offensive_rating = 0
+                defensive_rating = 0
+                net_rating = 0
+            
+            # Average spacing score for this lineup
+            segment_spacing = [
+                m for m in spacing_metrics
+                if start_frame <= m.get("frame", 0) < end_frame
+            ]
+            
+            if segment_spacing:
+                # Convert quality to numeric score
+                quality_scores = []
+                for m in segment_spacing:
+                    if m["spacing_quality"] == "good":
+                        quality_scores.append(3.0)
+                    elif m["spacing_quality"] == "average":
+                        quality_scores.append(2.0)
+                    else:
+                        quality_scores.append(1.0)
+                avg_spacing_score = float(np.mean(quality_scores))
+            else:
+                avg_spacing_score = 0.0
+            
+            # Defensive error rate (late closeouts / total defensive events)
+            segment_def_reactions = [
+                r for r in defensive_reactions
+                if start_frame <= r.get("event_frame", 0) < end_frame
+            ]
+            
+            if segment_def_reactions:
+                late_closeouts = sum(1 for r in segment_def_reactions if r.get("late_closeout", False))
+                defensive_error_rate = late_closeouts / len(segment_def_reactions)
+            else:
+                defensive_error_rate = 0.0
+            
+            # Turnovers (from interceptions)
+            segment_interceptions = [
+                e for e in events
+                if e.get("event_type") == "interception"
+                and start_frame <= e.get("frame", 0) < end_frame
+            ]
+            turnovers = len(segment_interceptions)
+            
+            # Duration
+            duration_seconds = (end_frame - start_frame) / fps if fps > 0 else 0
+            duration_minutes = duration_seconds / 60
+            
+            lineup_metrics.append({
+                "team_id": team_id,
+                "lineup_hash": lineup_hash,
+                "player_track_ids": player_ids,
+                "possessions_count": possessions,
+                "points_scored": points_scored,
+                "points_allowed": points_allowed,
+                "offensive_rating": float(offensive_rating),
+                "defensive_rating": float(defensive_rating),
+                "net_rating": float(net_rating),
+                "avg_spacing_score": avg_spacing_score,
+                "turnovers": turnovers,
+                "defensive_error_rate": float(defensive_error_rate),
+                "total_minutes": float(duration_minutes),
+                "start_frame": start_frame,
+                "end_frame": end_frame
+            })
+        
+        # Calculate summary statistics
+        if lineup_metrics:
+            best_lineup = max(lineup_metrics, key=lambda x: x["net_rating"])
+            worst_lineup = min(lineup_metrics, key=lambda x: x["net_rating"])
+            
+            summary = {
+                "total_lineups": len(lineup_metrics),
+                "best_lineup_hash": best_lineup["lineup_hash"],
+                "best_lineup_net_rating": best_lineup["net_rating"],
+                "worst_lineup_hash": worst_lineup["lineup_hash"],
+                "worst_lineup_net_rating": worst_lineup["net_rating"],
+                "avg_net_rating": float(np.mean([m["net_rating"] for m in lineup_metrics])),
+            }
+        else:
+            summary = {
+                "total_lineups": 0,
+                "best_lineup_hash": None,
+                "best_lineup_net_rating": 0,
+                "worst_lineup_hash": None,
+                "worst_lineup_net_rating": 0,
+                "avg_net_rating": 0,
+            }
+        
+        return {
+            "lineup_metrics": lineup_metrics,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _detect_lineup_segments(
+        self,
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        fps: float,
+        min_duration_seconds: float = 30.0
+    ) -> List[Dict]:
+        """
+        Detect continuous segments with the same 5-player lineup.
+        
+        Args:
+            player_assignment: Per-frame team assignments
+            ball_possession: Per-frame possession
+            fps: Frames per second
+            min_duration_seconds: Minimum segment duration to track
+        
+        Returns:
+            List of lineup segments
+        """
+        segments = []
+        current_lineups = {1: None, 2: None}  # Track lineup for each team
+        segment_starts = {1: 0, 2: 0}
+        
+        min_frames = int(min_duration_seconds * fps)
+        
+        for frame_idx in range(len(player_assignment)):
+            assignment = player_assignment[frame_idx]
+            
+            # Get players for each team
+            team_1_players = sorted([pid for pid, team in assignment.items() if team == 1])
+            team_2_players = sorted([pid for pid, team in assignment.items() if team == 2])
+            
+            # Create lineup hashes
+            lineup_1_hash = "_".join(map(str, team_1_players)) if len(team_1_players) >= 3 else None
+            lineup_2_hash = "_".join(map(str, team_2_players)) if len(team_2_players) >= 3 else None
+            
+            # Check for lineup changes
+            for team_id, lineup_hash, players in [
+                (1, lineup_1_hash, team_1_players),
+                (2, lineup_2_hash, team_2_players)
+            ]:
+                if lineup_hash is None:
+                    continue
+                
+                if current_lineups[team_id] != lineup_hash:
+                    # Lineup changed
+                    if current_lineups[team_id] is not None:
+                        # Save previous segment if long enough
+                        duration = frame_idx - segment_starts[team_id]
+                        if duration >= min_frames:
+                            segments.append({
+                                "team_id": team_id,
+                                "lineup_hash": current_lineups[team_id],
+                                "player_ids": self._parse_lineup_hash(current_lineups[team_id]),
+                                "start_frame": segment_starts[team_id],
+                                "end_frame": frame_idx
+                            })
+                    
+                    # Start new segment
+                    current_lineups[team_id] = lineup_hash
+                    segment_starts[team_id] = frame_idx
+        
+        # Close final segments
+        for team_id in [1, 2]:
+            if current_lineups[team_id] is not None:
+                duration = len(player_assignment) - segment_starts[team_id]
+                if duration >= min_frames:
+                    segments.append({
+                        "team_id": team_id,
+                        "lineup_hash": current_lineups[team_id],
+                        "player_ids": self._parse_lineup_hash(current_lineups[team_id]),
+                        "start_frame": segment_starts[team_id],
+                        "end_frame": len(player_assignment)
+                    })
+        
+        return segments
+    
+    def _parse_lineup_hash(self, lineup_hash: str) -> List[int]:
+        """Parse lineup hash back to list of player IDs."""
+        return [int(x) for x in lineup_hash.split("_")]

analytics_engine/spacing_engine.py

@@ -0,0 +1,192 @@
+"""
+Spacing Engine - Analyzes offensive spacing quality.
+
+Computes pairwise distances, paint density, and clustering to evaluate
+how well offensive players are spaced on the court.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class SpacingEngine(BaseAnalyticsModule):
+    """Analyzes offensive spacing quality using geometric analysis."""
+    
+    def __init__(
+        self,
+        clustering_threshold_m: float = 1.5,
+        good_spacing_threshold_m: float = 3.0,
+        average_spacing_threshold_m: float = 2.0,
+        paint_width_m: float = 4.9,  # Standard NBA paint width
+        paint_length_m: float = 5.8,  # Standard NBA paint length
+    ):
+        """
+        Initialize spacing engine.
+        
+        Args:
+            clustering_threshold_m: Distance below which players are considered clustered
+            good_spacing_threshold_m: Average distance for "good" spacing
+            average_spacing_threshold_m: Average distance for "average" spacing
+            paint_width_m: Width of the paint area in meters
+            paint_length_m: Length of the paint area in meters
+        """
+        super().__init__("spacing_engine")
+        self.clustering_threshold = clustering_threshold_m
+        self.good_threshold = good_spacing_threshold_m
+        self.average_threshold = average_spacing_threshold_m
+        self.paint_width = paint_width_m
+        self.paint_length = paint_length_m
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Analyze spacing quality across all frames.
+        
+        Returns:
+            Dictionary with spacing metrics for each frame with possession
+        """
+        spacing_metrics = []
+        
+        for frame_idx in range(len(player_tracks)):
+            if frame_idx >= len(tactical_positions) or frame_idx >= len(player_assignment):
+                continue
+            
+            if frame_idx >= len(ball_possession):
+                continue
+            
+            possession_player = ball_possession[frame_idx]
+            if possession_player == -1:
+                continue  # No possession, skip
+            
+            assignment = player_assignment[frame_idx]
+            if possession_player not in assignment:
+                continue
+            
+            offense_team = assignment[possession_player]
+            
+            # Get offensive players' tactical positions
+            tactical_pos = tactical_positions[frame_idx]
+            offensive_positions = []
+            offensive_player_ids = []
+            
+            for player_id, team_id in assignment.items():
+                if team_id == offense_team and player_id in tactical_pos:
+                    pos = tactical_pos[player_id]
+                    if isinstance(pos, (list, tuple)) and len(pos) >= 2:
+                        offensive_positions.append(pos)
+                        offensive_player_ids.append(player_id)
+            
+            if len(offensive_positions) < 2:
+                continue  # Need at least 2 players for spacing analysis
+            
+            # Compute pairwise distances
+            distances = []
+            for i in range(len(offensive_positions)):
+                for j in range(i + 1, len(offensive_positions)):
+                    dist = self._euclidean_distance(
+                        offensive_positions[i],
+                        offensive_positions[j]
+                    )
+                    if dist != float('inf'):
+                        distances.append(dist)
+            
+            if not distances:
+                continue
+            
+            avg_distance = np.mean(distances)
+            
+            # Count players in paint (simplified: check if near hoop)
+            # Assuming tactical view has hoop at specific location
+            # For now, use a heuristic based on y-coordinate
+            paint_players = self._count_paint_players(offensive_positions)
+            
+            # Detect overlaps (clustering)
+            overlap_count = sum(1 for d in distances if d < self.clustering_threshold)
+            
+            # Classify spacing quality
+            if avg_distance >= self.good_threshold:
+                quality = "good"
+            elif avg_distance >= self.average_threshold:
+                quality = "average"
+            else:
+                quality = "poor"
+            
+            spacing_metrics.append({
+                "frame": frame_idx,
+                "timestamp": self._get_frame_time(frame_idx, fps),
+                "spacing_quality": quality,
+                "avg_distance_m": float(avg_distance),
+                "paint_players": paint_players,
+                "overlap_count": overlap_count,
+                "player_positions": {
+                    str(pid): pos for pid, pos in zip(offensive_player_ids, offensive_positions)
+                },
+                "offense_team": offense_team,
+            })
+        
+        # Aggregate statistics
+        if spacing_metrics:
+            quality_counts = {"good": 0, "average": 0, "poor": 0}
+            for metric in spacing_metrics:
+                quality_counts[metric["spacing_quality"]] += 1
+            
+            total = len(spacing_metrics)
+            summary = {
+                "total_frames_analyzed": total,
+                "good_spacing_pct": (quality_counts["good"] / total * 100) if total > 0 else 0,
+                "average_spacing_pct": (quality_counts["average"] / total * 100) if total > 0 else 0,
+                "poor_spacing_pct": (quality_counts["poor"] / total * 100) if total > 0 else 0,
+                "avg_distance_overall": float(np.mean([m["avg_distance_m"] for m in spacing_metrics])),
+            }
+        else:
+            summary = {
+                "total_frames_analyzed": 0,
+                "good_spacing_pct": 0,
+                "average_spacing_pct": 0,
+                "poor_spacing_pct": 0,
+                "avg_distance_overall": 0,
+            }
+        
+        return {
+            "spacing_metrics": spacing_metrics,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _count_paint_players(self, positions: List[List[float]]) -> int:
+        """
+        Count how many players are in the paint area.
+        
+        This is a simplified heuristic. In a full implementation, you would
+        use court keypoints to define the exact paint boundaries.
+        
+        Args:
+            positions: List of [x, y] positions in tactical view
+        
+        Returns:
+            Number of players in paint
+        """
+        # Simplified: assume tactical view has hoop at top (y=0) and paint extends downward
+        # This is a placeholder - real implementation should use court_keypoints
+        paint_count = 0
+        for pos in positions:
+            if len(pos) >= 2:
+                # Heuristic: if y-coordinate is in top portion of court
+                # (This assumes tactical view normalization)
+                if pos[1] < 6.0:  # Within ~6m of hoop
+                    paint_count += 1
+        return paint_count

analytics_engine/transition_effort.py

@@ -0,0 +1,234 @@
+"""
+Transition Effort Engine - Analyzes player effort during transition phases.
+
+Tracks player speeds during the 3 seconds after possession changes and
+classifies effort as sprint, jog, or walk.
+"""
+from typing import Dict, Any, List
+import numpy as np
+from .base import BaseAnalyticsModule
+
+
+class TransitionEffortEngine(BaseAnalyticsModule):
+    """Analyzes player effort during offensive/defensive transitions."""
+    
+    def __init__(
+        self,
+        sprint_threshold_mps: float = 5.5,
+        jog_threshold_mps: float = 3.0,
+        transition_duration_seconds: float = 3.0,
+    ):
+        """
+        Initialize transition effort engine.
+        
+        Args:
+            sprint_threshold_mps: Speed threshold for sprint classification
+            jog_threshold_mps: Speed threshold for jog classification
+            transition_duration_seconds: How long to track after possession change
+        """
+        super().__init__("transition_effort")
+        self.sprint_threshold = sprint_threshold_mps
+        self.jog_threshold = jog_threshold_mps
+        self.transition_duration = transition_duration_seconds
+    
+    def process(
+        self,
+        video_frames: List[Any],
+        player_tracks: List[Dict],
+        ball_tracks: List[Dict],
+        tactical_positions: List[Dict],
+        player_assignment: List[Dict],
+        ball_possession: List[int],
+        events: List[Dict],
+        shots: List[Dict],
+        court_keypoints: List[Dict],
+        speeds: List[Dict],
+        video_path: str,
+        fps: float,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Analyze transition effort for all possession changes.
+        
+        Returns:
+            Dictionary with transition effort metrics
+        """
+        transition_efforts = []
+        
+        # Detect possession changes
+        possession_changes = self._detect_possession_changes(
+            ball_possession,
+            player_assignment
+        )
+        
+        transition_window_frames = int(self.transition_duration * fps)
+        
+        for change in possession_changes:
+            frame = change["frame"]
+            old_team = change["old_team"]
+            new_team = change["new_team"]
+            
+            # Analyze effort for both teams
+            # Team gaining possession: offense transition
+            # Team losing possession: defense transition
+            
+            end_frame = min(frame + transition_window_frames, len(speeds))
+            
+            for analyze_frame in range(frame, end_frame):
+                if analyze_frame >= len(player_assignment) or analyze_frame >= len(speeds):
+                    break
+                
+                assignment = player_assignment[analyze_frame]
+                frame_speeds = speeds[analyze_frame]
+                
+                for player_id, team_id in assignment.items():
+                    if player_id not in frame_speeds:
+                        continue
+                    
+                    speed = frame_speeds[player_id]
+                    
+                    # Classify effort
+                    if speed >= self.sprint_threshold:
+                        effort_type = "sprint"
+                        effort_score = 100
+                    elif speed >= self.jog_threshold:
+                        effort_type = "jog"
+                        effort_score = 60
+                    else:
+                        effort_type = "walk"
+                        effort_score = 20
+                    
+                    # Determine transition type
+                    if team_id == new_team:
+                        transition_type = "defense_to_offense"
+                    else:
+                        transition_type = "offense_to_defense"
+                    
+                    transition_efforts.append({
+                        "possession_change_frame": frame,
+                        "player_track_id": player_id,
+                        "team_id": team_id,
+                        "transition_type": transition_type,
+                        "effort_type": effort_type,
+                        "max_speed_mps": float(speed),
+                        "effort_score": effort_score,
+                        "frame": analyze_frame,
+                        "timestamp": self._get_frame_time(analyze_frame, fps)
+                    })
+        
+        # Aggregate by possession change
+        aggregated_efforts = []
+        for change in possession_changes:
+            frame = change["frame"]
+            change_efforts = [e for e in transition_efforts if e["possession_change_frame"] == frame]
+            
+            if change_efforts:
+                # Group by player
+                player_efforts = {}
+                for effort in change_efforts:
+                    pid = effort["player_track_id"]
+                    if pid not in player_efforts:
+                        player_efforts[pid] = []
+                    player_efforts[pid].append(effort)
+                
+                # Calculate max speed and avg effort for each player
+                for pid, efforts in player_efforts.items():
+                    max_speed = max(e["max_speed_mps"] for e in efforts)
+                    avg_speed = np.mean([e["max_speed_mps"] for e in efforts])
+                    avg_effort_score = np.mean([e["effort_score"] for e in efforts])
+                    
+                    # Determine overall effort type based on max speed
+                    if max_speed >= self.sprint_threshold:
+                        overall_effort = "sprint"
+                    elif max_speed >= self.jog_threshold:
+                        overall_effort = "jog"
+                    else:
+                        overall_effort = "walk"
+                    
+                    aggregated_efforts.append({
+                        "possession_change_frame": frame,
+                        "player_track_id": pid,
+                        "team_id": efforts[0]["team_id"],
+                        "transition_type": efforts[0]["transition_type"],
+                        "effort_type": overall_effort,
+                        "max_speed_mps": float(max_speed),
+                        "avg_speed_mps": float(avg_speed),
+                        "effort_score": float(avg_effort_score),
+                        "duration_seconds": self.transition_duration
+                    })
+        
+        # Calculate summary statistics
+        if aggregated_efforts:
+            sprint_count = sum(1 for e in aggregated_efforts if e["effort_type"] == "sprint")
+            jog_count = sum(1 for e in aggregated_efforts if e["effort_type"] == "jog")
+            walk_count = sum(1 for e in aggregated_efforts if e["effort_type"] == "walk")
+            total = len(aggregated_efforts)
+            
+            summary = {
+                "total_transition_events": total,
+                "sprint_count": sprint_count,
+                "jog_count": jog_count,
+                "walk_count": walk_count,
+                "sprint_rate": (sprint_count / total * 100) if total > 0 else 0,
+                "avg_effort_score": float(np.mean([e["effort_score"] for e in aggregated_efforts])),
+                "avg_max_speed_mps": float(np.mean([e["max_speed_mps"] for e in aggregated_efforts])),
+            }
+        else:
+            summary = {
+                "total_transition_events": 0,
+                "sprint_count": 0,
+                "jog_count": 0,
+                "walk_count": 0,
+                "sprint_rate": 0,
+                "avg_effort_score": 0,
+                "avg_max_speed_mps": 0,
+            }
+        
+        return {
+            "transition_efforts": aggregated_efforts,
+            "summary": summary,
+            "status": "success"
+        }
+    
+    def _detect_possession_changes(
+        self,
+        ball_possession: List[int],
+        player_assignment: List[Dict]
+    ) -> List[Dict]:
+        """
+        Detect frames where possession changes between teams.
+        
+        Args:
+            ball_possession: Per-frame possession (track_id or -1)
+            player_assignment: Per-frame team assignments
+        
+        Returns:
+            List of possession change events
+        """
+        changes = []
+        prev_team = None
+        
+        for frame_idx in range(len(ball_possession)):
+            if frame_idx >= len(player_assignment):
+                break
+            
+            possession_player = ball_possession[frame_idx]
+            if possession_player == -1:
+                continue
+            
+            assignment = player_assignment[frame_idx]
+            if possession_player not in assignment:
+                continue
+            
+            current_team = assignment[possession_player]
+            
+            if prev_team is not None and current_team != prev_team:
+                changes.append({
+                    "frame": frame_idx,
+                    "old_team": prev_team,
+                    "new_team": current_team
+                })
+            
+            prev_team = current_team
+        
+        return changes

app/__init__.py

@@ -0,0 +1,4 @@
+# AI Basketball Performance Analysis Backend API
+"""Backend application for basketball performance analysis."""
+
+__version__ = "1.0.0"

app/api/admin.py

@@ -0,0 +1,1158 @@
+"""
+Admin API endpoints (Team/Organization Management).
+"""
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional, List
+from fastapi import APIRouter, Depends, HTTPException, Query, status, UploadFile, File, BackgroundTasks
+
+from app.dependencies import (
+    get_supabase, 
+    get_current_user,
+    require_team_account, 
+    require_organization_admin,
+    require_staff_member,
+    require_linked_account
+)
+from app.services.supabase_client import SupabaseService
+from app.models.user import User, AccountType
+from app.models.player import Player, PlayerCreate, PlayerUpdate
+from app.models.schedule import Schedule, ScheduleCreate, ScheduleUpdate
+from app.models.match import Match, MatchCreate, MatchUpdate
+from app.models.notification import Notification, NotificationCreate, NotificationListResponse
+from app.models.team import Organization, OrganizationUpdate
+from app.models.stats import MatchStatUploadResponse, StatsConfirmRequest
+from app.services.stats_extraction_service import extract_stats_from_file_background
+from app.services.player_linking_service import auto_link_players_to_roster
+
+router = APIRouter()
+
+@router.put("/organization", response_model=Organization)
+async def update_organization(
+    org_data: OrganizationUpdate,
+    current_user: dict = Depends(require_organization_admin),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update details of the current user's organization.
+    """
+    # Find organization owned by current user
+    orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+    if not orgs:
+        raise HTTPException(status_code=404, detail="Organization not found")
+    
+    org_id = orgs[0]["id"]
+    update_dict = org_data.model_dump(exclude_unset=True)
+    
+    if not update_dict:
+        raise HTTPException(status_code=400, detail="No fields to update")
+        
+    updated = await supabase.update("organizations", org_id, update_dict)
+    return updated
+
+# ============================================
+# USERS & PLAYERS MANAGEMENT
+# ============================================
+
+@router.put("/users/{user_id}/role")
+async def update_user_role(
+    user_id: str,
+    role_data: dict,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update a user's role (e.g. within the team context, or maybe account_type).
+    """
+    # Verify ownership/permission
+    # Assuming this updates metadata or account_type?
+    # User roles in this system seem to be 'account_type'.
+    # If frontend means 'player role' (Forward, Guard), that's usually on player profile.
+    # adminAPI.js calls `updateUserRole`.
+    
+    # If it's account_type (team/personal), that's critical.
+    # If it's a team role (Captain, Starter), that's not in Users table.
+    
+    # Assuming it updates 'role' metadata for now.
+    user_update = {"role": role_data.get("role")}
+    updated = await supabase.update("users", user_id, user_update)
+    return updated
+
+
+@router.get("/users")
+async def get_users(
+    role: Optional[str] = None,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get users (players) managed by the admin/team owner.
+    """
+    # Determine organization_id
+    org_id = current_user.get("organization_id")
+    if not org_id and current_user.get("account_type") == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            return []
+        org_id = orgs[0]["id"]
+    
+    if not org_id:
+        return []
+
+    # Get players in the org
+    players = await supabase.select("players", filters={"organization_id": str(org_id)})
+    
+    # Identify linked users to fetch their personal profiles for data fallback
+    linked_user_ids = [str(p["user_id"]) for p in players if p.get("user_id")]
+    personal_profiles = {}
+    
+    if linked_user_ids:
+        try:
+            # Batch fetch all potential personal profiles for these users
+            all_profiles = await supabase.select_in("players", "user_id", linked_user_ids)
+            # Filter for true personal profiles (no organization_id)
+            for prof in all_profiles:
+                if not prof.get("organization_id"):
+                    personal_profiles[str(prof["user_id"])] = prof
+        except Exception as e:
+            print(f"Warning: Failed to fetch personal profiles for roster fallback: {e}")
+
+    # Ensure all fields for the roster are present, falling back to personal data if team data is blank
+    for p in players:
+        user_id_str = str(p.get("user_id")) if p.get("user_id") else None
+        personal = personal_profiles.get(user_id_str) if user_id_str else None
+        
+        # Helper to get value with fallback
+        def get_val(field, default=None):
+            v = p.get(field)
+            # If team-specific value exists and isn't empty, use it
+            if v is not None and v != "":
+                return v
+            # Otherwise, try to use the player's personal profile value
+            if personal and personal.get(field) is not None and personal.get(field) != "":
+                return personal[field]
+            return default
+
+        p["jersey_number"] = get_val("jersey_number", None)
+        p["position"] = get_val("position", "Not set")
+        p["status"] = get_val("status", "active")
+        # PPG is typically calculated per organization/team context
+        p_ppg = p.get("ppg")
+        p["ppg"] = float(p_ppg) if p_ppg is not None and p_ppg != "" else 0.0
+        
+    return players
+
+@router.post("/players")
+async def create_player(
+    player_data: PlayerCreate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Add a new player to the team roster.
+    """
+    org_id = current_user.get("organization_id")
+    if not org_id and current_user.get("account_type") == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            raise HTTPException(status_code=400, detail="No organization found for this account")
+        org_id = orgs[0]["id"]
+    
+    if not org_id:
+         raise HTTPException(status_code=403, detail="Account not linked to an organization")
+    player_dict = player_data.model_dump()
+    player_dict["organization_id"] = str(org_id)
+    player_dict["id"] = str(uuid4())
+    player_dict["created_at"] = datetime.now().isoformat()
+    
+    # Handle date_of_birth if present
+    if player_dict.get("date_of_birth"):
+        player_dict["date_of_birth"] = player_dict["date_of_birth"].isoformat()
+        
+    saved = await supabase.insert("players", player_dict)
+    return saved
+
+@router.put("/players/{player_id}")
+async def update_player(
+    player_id: str,
+    player_data: PlayerUpdate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update a player's profile.
+    """
+    # Verify access
+    player = await supabase.select_one("players", player_id)
+    if not player:
+        raise HTTPException(status_code=404, detail="Player not found")
+        
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if player.get("organization_id"):
+            org = await supabase.select_one("organizations", str(player["organization_id"]))
+            has_access = org and str(org.get("owner_id")) == str(current_user["id"])
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        coach_org = current_user.get("organization_id")
+        if coach_org and str(player.get("organization_id")) == str(coach_org):
+            has_access = True
+            
+    if not has_access:
+        raise HTTPException(status_code=403, detail="Access denied")
+        
+    update_dict = player_data.model_dump(exclude_unset=True)
+    if "date_of_birth" in update_dict and update_dict["date_of_birth"]:
+        update_dict["date_of_birth"] = update_dict["date_of_birth"].isoformat()
+        
+    updated = await supabase.update("players", player_id, update_dict)
+    return updated
+
+@router.get("/players")
+async def get_roster(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get team roster (alias for players).
+    """
+    return await get_users(role="player", current_user=current_user, supabase=supabase)
+
+@router.patch("/players/{player_id}/status")
+async def update_player_status(
+    player_id: str,
+    status_data: dict,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update player status (active/injured/etc).
+    Note: status field might need to be added to players table or handled via metadata.
+    """
+    # Check if player belongs to owner's org
+    player = await supabase.select_one("players", player_id)
+    if not player:
+        raise HTTPException(status_code=404, detail="Player not found")
+        
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+            
+    if not org_id or str(player.get("organization_id")) != str(org_id):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    try:
+        updated = await supabase.update("players", player_id, {"status": status_data.get("status")})
+        return updated
+    except Exception:
+        return player
+
+
+@router.delete("/players/{player_id}")
+async def delete_player(
+    player_id: str,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Remove a player from the organization's roster.
+    This deletes the roster entry and unlinks the user account if linked.
+    """
+    # 1. Get player
+    player = await supabase.select_one("players", player_id)
+    if not player:
+        raise HTTPException(status_code=404, detail="Player not found")
+        
+    # 2. Get organization id
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+             raise HTTPException(status_code=404, detail="Organization not found")
+        org_id = orgs[0]["id"]
+        
+    # 3. Verify ownership
+    if player.get("organization_id") != org_id:
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    # 4. Unlink user if associated
+    linked_user_id = player.get("user_id")
+    if linked_user_id:
+        try:
+            await supabase.update("users", str(linked_user_id), {"organization_id": None})
+        except Exception as e:
+            print(f"Warning: Failed to unlink user {linked_user_id}: {e}")
+
+    # 5. Delete roster entry
+    await supabase.delete("players", player_id)
+    
+    return {"message": "Player removed from roster and unlinked successfully"}
+
+@router.post("/players/{player_id}/link")
+async def link_player_account(
+    player_id: str,
+    link_data: dict,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Link a roster player to an actual user account by email.
+    If player_id is "new", it will search for the user and create a roster entry.
+    """
+    email = link_data.get("email")
+    if not email:
+        raise HTTPException(status_code=400, detail="Email is required")
+
+    # 1. Get organization
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        try:
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if not orgs:
+                raise HTTPException(status_code=404, detail="Organization not found. You must create an organization profile first.")
+            org_id = orgs[0]["id"]
+        except HTTPException:
+            raise
+        except Exception as e:
+            print(f"Error fetching organization for linking: {e}")
+            raise HTTPException(status_code=500, detail="Error retrieving organization data")
+
+    # 2. Search for user by email
+    try:
+        users = await supabase.select("users", filters={"email": email})
+        if not users:
+            raise HTTPException(status_code=404, detail=f"No account found with email {email}. The player must sign up first.")
+        target_user = users[0]
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"Error searching for user by email {email}: {e}")
+        raise HTTPException(status_code=500, detail="Error searching for player account")
+    
+    # Check if already linked to another org
+    current_linked_org = target_user.get("organization_id")
+    if current_linked_org and str(current_linked_org) != str(org_id):
+        raise HTTPException(status_code=400, detail="This user is already linked to another organization")
+
+    # 3. Handle player roster entry
+    org_name = "your team"
+    if org_id:
+        try:
+            org_record = await supabase.select_one("organizations", str(org_id))
+            if org_record:
+                org_name = org_record.get("name", "your team")
+        except Exception:
+            pass
+
+    try:
+        if player_id == "new":
+            # Check if already in roster
+            existing_roster = await supabase.select("players", filters={
+                "organization_id": str(org_id),
+                "user_id": str(target_user["id"])
+            })
+            if existing_roster:
+                raise HTTPException(status_code=400, detail="This player is already in your roster")
+            
+            # Search for an existing personal player profile for this user
+            personal_profiles = await supabase.select("players", filters={"user_id": str(target_user["id"])})
+            # Filter for the one without an org (personal)
+            personal_profile = next((p for p in personal_profiles if not p.get("organization_id")), None)
+
+            # Create new roster entry
+            new_player_id = str(uuid4())
+            new_player_record = {
+                "id": new_player_id,
+                "organization_id": str(org_id),
+                "user_id": str(target_user["id"]),
+                "name": target_user.get("full_name") or target_user.get("email") or "New Player",
+                "created_at": datetime.now().isoformat()
+            }
+
+            # If they have a personal profile, copy the stats
+            if personal_profile:
+                fields_to_copy = [
+                    "jersey_number", "position", "height_cm", "weight_kg", 
+                    "date_of_birth", "avatar_url", "phone", "address", 
+                    "experience_years", "bio", "status"
+                ]
+                for field in fields_to_copy:
+                    if personal_profile.get(field) is not None:
+                        new_player_record[field] = personal_profile[field]
+
+            await supabase.insert("players", new_player_record)
+            player_id = new_player_id
+        else:
+            # Verify existing player belongs to owner's org
+            player = await supabase.select_one("players", player_id)
+            if not player:
+                raise HTTPException(status_code=404, detail="Player not found")
+            if str(player.get("organization_id")) != str(org_id):
+                raise HTTPException(status_code=403, detail="Access denied")
+            
+            # Update player profile with user_id
+            await supabase.update("players", player_id, {"user_id": target_user["id"]})
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"Error updating/creating roster entry: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to update team roster: {e}")
+    
+    # 4. Update user profile with organization_id
+    try:
+        await supabase.update("users", target_user["id"], {"organization_id": str(org_id)})
+    except Exception as e:
+        print(f"Error updating user organization link: {e}")
+        # Not a fatal error if roster was linked, but still problematic
+    
+    # 5. Create a notification
+    try:
+        await supabase.insert("notifications", {
+            "id": str(uuid4()),
+            "recipient_id": target_user["id"],
+            "title": "Team Link",
+            "message": f"You have been added to the team roster of {org_name}.",
+            "type": "team_invite",
+            "read": False,
+            "created_at": datetime.now().isoformat()
+        })
+    except Exception as e:
+        print(f"Failed to create link notification: {e}")
+
+    return {"message": "Account linked successfully", "user": {"id": target_user["id"], "name": target_user.get("full_name") or target_user.get("email")}}
+
+@router.get("/staff")
+async def get_staff(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get coaching staff linked to the organization.
+    """
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+             return []
+        org_id = orgs[0]["id"]
+        
+    staff_all = await supabase.select("users", filters={
+        "organization_id": org_id
+    })
+    staff = [u for u in staff_all if u.get("account_type") in ("coach", "team")]
+    return staff
+
+
+
+@router.post("/staff/link")
+async def link_staff_member(
+    link_data: dict, # email, role
+    current_user: dict = Depends(require_organization_admin),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Link a coach account to the organization and assign a role.
+    """
+    email = link_data.get("email")
+    role = link_data.get("role", "Coach")
+    if not email:
+        raise HTTPException(status_code=400, detail="Email is required")
+
+    # 1. Get organization
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+             raise HTTPException(status_code=404, detail="Organization not found")
+        org_id = orgs[0]["id"]
+    
+    # 2. Search for user by email
+    users = await supabase.select("users", filters={"email": email})
+    if not users:
+        raise HTTPException(status_code=404, detail=f"No account found with email {email}. The coach must sign up first.")
+    
+    target_user = users[0]
+    
+    if target_user["account_type"] != "coach":
+         raise HTTPException(status_code=400, detail="This account is not a Coach account.")
+
+    if target_user.get("organization_id") and target_user.get("organization_id") != org_id:
+        raise HTTPException(status_code=400, detail="This coach is already linked to another organization")
+
+    # 3. Update user profile
+    await supabase.update("users", target_user["id"], {
+        "organization_id": org_id,
+        "staff_role": role
+    })
+    
+    # 4. Create notification
+    try:
+        await supabase.insert("notifications", {
+            "id": str(uuid4()),
+            "recipient_id": target_user["id"],
+            "title": "Staff Invitation",
+            "message": f"You have been added as a {role} to the organization.",
+            "type": "team_invite",
+            "read": False,
+            "created_at": datetime.now().isoformat()
+        })
+    except Exception:
+        pass
+
+    return {"message": "Staff member linked successfully", "user": {"id": target_user["id"], "role": role}}
+
+@router.delete("/staff/{user_id}")
+async def remove_staff_member(
+    user_id: str,
+    current_user: dict = Depends(require_organization_admin),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Remove a staff member from the organization.
+    """
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+             raise HTTPException(status_code=404, detail="Organization not found")
+        org_id = orgs[0]["id"]
+
+    # Verify user belongs to org
+    target_user = await supabase.select_one("users", user_id)
+    if not target_user or target_user.get("organization_id") != org_id:
+        raise HTTPException(status_code=403, detail="Access denied or user not found")
+
+    # Unlink
+    await supabase.update("users", user_id, {
+        "organization_id": None,
+        "staff_role": None
+    })
+    
+    return {"message": "Staff member removed successfully"}
+
+# ============================================
+# SCHEDULE MANAGEMENT
+# ============================================
+
+@router.get("/schedule")
+async def get_schedule(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Get team schedule."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            return []
+        org_id = orgs[0]["id"]
+        
+    schedules = await supabase.select("schedules", filters={"organization_id": org_id})
+    return schedules
+
+@router.post("/schedule")
+async def create_schedule_event(
+    event_data: ScheduleCreate,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Create a schedule event (Coach only)."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        raise HTTPException(status_code=403, detail="You must be linked to an organization")
+        
+    event_dict = event_data.model_dump()
+    event_dict["organization_id"] = str(org_id)
+    event_dict["created_by"] = current_user["id"]
+    event_dict["id"] = str(uuid4())
+    
+    event_dict["start_time"] = event_dict["start_time"].isoformat()
+    event_dict["end_time"] = event_dict["end_time"].isoformat()
+    
+    # Extract extra fields
+    player_ids = event_dict.pop("playerIds", None)
+    event_date = event_dict.pop("date", "the scheduled date")
+    event_dict.pop("coachId", None)
+
+    saved = await supabase.insert("schedules", event_dict)
+    
+    # Notify assigned players
+    if player_ids:
+        try:
+            for pid in player_ids:
+                # Look up the player to get their user_id
+                player = await supabase.select_one("players", pid)
+                if player and player.get("user_id"):
+                    await supabase.insert("notifications", {
+                        "id": str(uuid4()),
+                        "recipient_id": player["user_id"],
+                        "title": f"New Event: {event_dict['title']}",
+                        "message": f"You have been assigned to {event_dict['title']} on {event_date}.",
+                        "type": "training",
+                        "read": False,
+                        "created_at": datetime.now().isoformat()
+                    })
+        except Exception as e:
+            print(f"Warning: Failed to send schedule notifications: {e}")
+
+    return saved
+
+@router.put("/schedule/{event_id}")
+async def update_schedule_event(
+    event_id: str,
+    event_data: ScheduleUpdate,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Update a schedule event (Coach only)."""
+    # Verify owner's org match
+    event = await supabase.select_one("schedules", event_id)
+    if not event or event.get("organization_id") != current_user.get("organization_id"):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    update_dict = event_data.model_dump(exclude_unset=True)
+    if not update_dict:
+        raise HTTPException(status_code=400, detail="No fields to update")
+        
+    if "start_time" in update_dict:
+        update_dict["start_time"] = update_dict["start_time"].isoformat()
+    if "end_time" in update_dict:
+        update_dict["end_time"] = update_dict["end_time"].isoformat()
+        
+    updated = await supabase.update("schedules", event_id, update_dict)
+    return updated
+
+@router.delete("/schedule/{event_id}")
+async def delete_schedule_event(
+    event_id: str,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Delete a schedule event (Coach only)."""
+    event = await supabase.select_one("schedules", event_id)
+    if not event or event.get("organization_id") != current_user.get("organization_id"):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    await supabase.delete("schedules", event_id)
+    return {"message": "Event deleted"}
+# ============================================
+# MATCH MANAGEMENT
+# ============================================
+
+@router.get("/matches")
+async def get_matches(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Get matches for the current user's organization (Owner or Staff)."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            return []
+        org_id = orgs[0]["id"]
+        
+    matches = await supabase.select("matches", filters={"organization_id": org_id})
+    return matches
+
+@router.post("/matches")
+async def create_match(
+    match_data: MatchCreate,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Create a match (Coach only)."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        raise HTTPException(status_code=403, detail="You must be linked to an organization")
+        
+    match_dict = match_data.model_dump()
+    match_dict["id"] = str(uuid4())
+    match_dict["organization_id"] = str(org_id)
+    match_dict["date"] = match_dict["date"].isoformat()
+    
+    saved = await supabase.insert("matches", match_dict)
+    return saved
+
+@router.put("/matches/{match_id}")
+async def update_match(
+    match_id: str,
+    match_data: MatchUpdate,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Update a match (Coach only)."""
+    match = await supabase.select_one("matches", match_id)
+    if not match or match.get("organization_id") != current_user.get("organization_id"):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    update_dict = match_data.model_dump(exclude_unset=True)
+    if "date" in update_dict:
+        update_dict["date"] = update_dict["date"].isoformat()
+        
+    updated = await supabase.update("matches", match_id, update_dict)
+    return updated
+
+@router.delete("/matches/{match_id}")
+async def delete_match(
+    match_id: str,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Delete a match (Coach only)."""
+    match = await supabase.select_one("matches", match_id)
+    if not match or match.get("organization_id") != current_user.get("organization_id"):
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    await supabase.delete("matches", match_id)
+    return {"message": "Match deleted"}
+
+
+@router.get("/matches/{match_id}/player-stats")
+async def get_match_player_stats(
+    match_id: str,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Get all player stats for a specific match, enriched with player name/jersey info."""
+    # Verify org access
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            return []
+        org_id = orgs[0]["id"]
+
+    stats = await supabase.select("match_player_stats", filters={
+        "match_id": match_id,
+        "organization_id": org_id
+    })
+
+    # Enrich each stat row with player name/jersey from the players table
+    player_ids = list({s["player_profile_id"] for s in stats if s.get("player_profile_id")})
+    players = []
+    if player_ids:
+        players = await supabase.select_in("players", "id", player_ids)
+    player_map = {p["id"]: p for p in players}
+
+    for s in stats:
+        pid = s.get("player_profile_id")
+        p = player_map.get(pid, {})
+        s["player_name"] = p.get("name", "Unknown")
+        s["player_jersey"] = p.get("jersey_number")
+        s["player_position"] = p.get("position")
+
+    match = await supabase.select_one("matches", match_id)
+    return {"match": match, "stats": stats}
+
+# ============================================
+# NOTIFICATIONS & STATS
+# ============================================
+
+@router.get("/notifications")
+async def get_notifications(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    try:
+        user_id = current_user["id"]
+        # Basic validation for UUID if using Postgres
+        import uuid
+        try:
+            uuid.UUID(str(user_id))
+        except ValueError:
+            # If not a UUID (like dev-id-...), return empty list instead of crashing Postgres
+            return []
+
+        notifs = await supabase.select("notifications", filters={"recipient_id": str(user_id)}, order_by="created_at")
+        return notifs
+    except Exception as e:
+        print(f"Error in get_notifications: {e}")
+        return [] # Return empty list on error to keep UI stable
+
+@router.post("/notifications")
+async def create_notification(
+    notif_data: NotificationCreate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    notif_dict = notif_data.model_dump()
+    notif_dict["id"] = str(uuid4())
+    saved = await supabase.insert("notifications", notif_dict)
+    return saved
+
+@router.put("/notifications/{notification_id}/mark-as-read")
+@router.put("/notifications/{notification_id}/read")
+async def mark_notification_read(
+    notification_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    updated = await supabase.update("notifications", notification_id, {"read": True})
+    return updated
+
+@router.put("/notifications/read-all")
+async def mark_all_notifications_read(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    # Mark all unread notifications for the current user as read
+    notifs = await supabase.select("notifications", filters={"recipient_id": current_user["id"], "read": False})
+    for n in notifs:
+         await supabase.update("notifications", n["id"], {"read": True})
+    return {"message": "All notifications marked as read"}
+
+@router.put("/notifications/{notification_id}")
+async def update_notification(
+    notification_id: str,
+    notification_data: NotificationCreate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    update_dict = notification_data.model_dump(exclude_unset=True)
+    updated = await supabase.update("notifications", notification_id, update_dict)
+    return updated
+
+@router.delete("/notifications/{notification_id}")
+async def delete_notification(
+    notification_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    await supabase.delete("notifications", notification_id)
+    return {"message": "Notification deleted"}
+
+
+@router.get("/stats")
+async def get_stats(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    # Mock aggregation or real counts
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if not orgs:
+            return {"players": 0, "matches": 0, "wins": 0}
+        org_id = orgs[0]["id"]
+    players = await supabase.select("players", filters={"organization_id": org_id})
+    matches = await supabase.select("matches", filters={"organization_id": org_id})
+    videos = await supabase.select("videos", filters={"organization_id": org_id})
+    
+    return {
+        "total_players": len(players),
+        "total_matches": len(matches),
+        "videos_analyzed": len(videos),
+        "upcoming_matches": len([m for m in matches if datetime.fromisoformat(m["date"].replace("Z", "+00:00")).replace(tzinfo=None) > datetime.utcnow()]),
+    }
+
+# ============================================
+# SECURITY & PROFILE 
+# ============================================
+
+@router.get("/profile")
+async def get_profile(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    # Just return user info plus org info
+    user_info = current_user
+    org_id = current_user.get("organization_id")
+    org = None
+    
+    if org_id:
+        org = await supabase.select_one("organizations", str(org_id))
+    elif current_user.get("account_type") == "team":
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org = orgs[0]
+            
+    return {"user": user_info, "organization": org}
+
+@router.put("/profile")
+async def update_profile(
+    profile_data: dict,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    # Update user or org
+    if "user" in profile_data:
+        user_payload = {}
+        for k, v in profile_data["user"].items():
+            if k in ["id", "created_at", "updated_at", "email", "account_type"]:
+                continue
+            user_payload[k] = v
+        if user_payload:
+            await supabase.update("users", current_user["id"], user_payload)
+    if "organization" in profile_data:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            # Avoid sending nested objects (which might not map to DB columns)
+            org_payload = {}
+            for k, v in (profile_data["organization"] or {}).items():
+                # Do not try to update primary key or generated fields
+                if k in ["id", "owner_id", "created_at", "updated_at"]:
+                    continue
+                org_payload[k] = v
+
+            if org_payload:
+                print(f"DEBUG update_profile: updating org {orgs[0]['id']} with payload: {org_payload}")
+                try:
+                    await supabase.update("organizations", orgs[0]["id"], org_payload)
+                    print("DEBUG update_profile: Supabase update successful")
+                except Exception as e:
+                    print(f"DEBUG update_profile: Supabase update failed: {e}")
+            
+    return {"message": "Profile updated"}
+
+@router.get("/security/settings")
+async def get_security_settings(current_user: dict = Depends(get_current_user)):
+    # Mock settings
+    return {"two_factor_enabled": False, "login_alerts": True}
+
+@router.put("/security/settings")
+async def update_security_settings(settings: dict, current_user: dict = Depends(get_current_user)):
+    # Mock update
+    return settings
+
+@router.get("/security/logs")
+async def get_security_logs(current_user: dict = Depends(get_current_user)):
+    # Mock logs
+    return [
+        {"id": 1, "action": "Login", "ip": "127.0.0.1", "timestamp": datetime.now().isoformat()},
+    ]
+
+# ============================================
+# OFFICIAL STATS IMPORT
+# ============================================
+
+@router.post("/matches/{match_id}/stats-upload")
+async def upload_match_stats(
+    match_id: str,
+    background_tasks: BackgroundTasks,
+    file: UploadFile = File(...),
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Upload a box score PDF or image, save to storage, schedule extraction."""
+    # 1. Verify match ownership
+    match = await supabase.select_one("matches", match_id)
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+            
+    if not match or match.get("organization_id") != org_id:
+        raise HTTPException(status_code=403, detail="Access denied")
+    
+    org_id = match["organization_id"]
+    upload_id = str(uuid4())
+    
+    # 2. Upload file to storage
+    file_bytes = await file.read()
+    is_pdf = file.content_type == "application/pdf"
+    file_ext = "pdf" if is_pdf else "jpg"
+    storage_path = f"org_{org_id}/match_{match_id}/{upload_id}.{file_ext}"
+    
+    try:
+        url = await supabase.upload_file("match-stats", storage_path, file_bytes, file.content_type)
+    except Exception as e:
+        print(f"Warning: file upload skip or error: {e}")
+        url = f"/local/{storage_path}"
+        
+    # 3. Create upload record
+    upload_data = {
+        "id": upload_id,
+        "match_id": match_id,
+        "organization_id": org_id,
+        "uploaded_by": current_user["id"],
+        "storage_path": storage_path,
+        "file_type": "pdf" if is_pdf else "image",
+        "extract_status": "queued",
+        "created_at": datetime.now().isoformat(),
+        "updated_at": datetime.now().isoformat()
+    }
+    await supabase.insert("match_stat_uploads", upload_data)
+    
+    # 4. Trigger extraction job
+    background_tasks.add_task(extract_stats_from_file_background, upload_id, org_id)
+    
+    return {"upload_id": upload_id, "status": "queued"}
+
+@router.get("/stats-upload/{upload_id}", response_model=MatchStatUploadResponse)
+async def get_stats_upload(
+    upload_id: str,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Poll for extraction status and JSON preview."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+
+    upload = await supabase.select_one("match_stat_uploads", upload_id)
+    if not upload or upload.get("organization_id") != org_id:
+        raise HTTPException(status_code=404, detail="Upload not found")
+        
+    return upload
+
+@router.post("/stats-upload/{upload_id}/confirm")
+async def confirm_stats_upload(
+    upload_id: str,
+    confirm_data: StatsConfirmRequest,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Confirm mapping and persist stats."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+
+    upload = await supabase.select_one("match_stat_uploads", upload_id)
+    if not upload or upload.get("organization_id") != org_id:
+        raise HTTPException(status_code=404, detail="Upload not found")
+        
+    org_id = upload["organization_id"]
+    match_id = upload["match_id"]
+    
+    confirmed_json = confirm_data.extracted_json
+    
+    # Update match score
+    if confirmed_json.final_score_for is not None:
+        await supabase.update("matches", match_id, {
+            "score_us": confirmed_json.final_score_for,
+            "score_them": confirmed_json.final_score_against
+        })
+    
+    # Persist the rows
+    stats_to_insert = []
+    
+    import re
+    from app.services.stats_utils import parse_made_attempted
+    
+    # 1. Collect all players (starters + bench)
+    all_players_to_save = []
+    if confirmed_json.starters:
+        for p in confirmed_json.starters:
+            p.is_starter = True
+            all_players_to_save.append(p)
+    if confirmed_json.bench:
+        for p in confirmed_json.bench:
+            p.is_starter = False
+            all_players_to_save.append(p)
+    
+    # Fallback if starters/bench were not populated but players was
+    if not all_players_to_save and confirmed_json.players:
+        all_players_to_save = confirmed_json.players
+
+    # 2. Prepare stat rows for database
+    stats_to_insert = []
+    for player_row in all_players_to_save:
+        if not player_row.linked_player_profile_id:
+            continue
+            
+        # Use already parsed values if available, otherwise try to parse from the ratio string
+        fg_m, fg_a = (player_row.fg_m, player_row.fg_a) if (player_row.fg_m or player_row.fg_a) else parse_made_attempted(player_row.fg)
+        tp_m, tp_a = (player_row.tp_m, player_row.tp_a) if (player_row.tp_m or player_row.tp_a) else parse_made_attempted(player_row.tp)
+        thp_m, thp_a = (player_row.thp_m, player_row.thp_a) if (player_row.thp_m or player_row.thp_a) else parse_made_attempted(player_row.thp)
+        ft_m, ft_a = (player_row.ft_m, player_row.ft_a) if (player_row.ft_m or player_row.ft_a) else parse_made_attempted(player_row.ft)
+        
+        stats_to_insert.append({
+            "id": str(uuid4()),
+            "match_id": match_id,
+            "organization_id": org_id,
+            "player_profile_id": str(player_row.linked_player_profile_id),
+            "source": "official_upload",
+            "mins": player_row.mins,
+            "pts": player_row.pts,
+            "fgm": fg_m,
+            "fga": fg_a,
+            "tp_m": tp_m,
+            "tp_a": tp_a,
+            "thp_m": thp_m,
+            "thp_a": thp_a,
+            "ft_m": ft_m,
+            "ft_a": ft_a,
+            "off_reb": player_row.off,
+            "def_reb": player_row.def_reb,
+            "reb": player_row.reb,
+            "ast": player_row.ast,
+            "to_cnt": player_row.to_cnt,
+            "stl": player_row.stl,
+            "blk": player_row.blk,
+            "blkr": player_row.blkr,
+            "pf": player_row.pf,
+            "fls_on": player_row.fls_on,
+            "plus_minus": player_row.plus_minus or 0,
+            "index_rating": player_row.index or 0,
+            "row_confidence": player_row.row_confidence or 1.0,
+            "is_starter": player_row.is_starter,
+            "created_at": datetime.now().isoformat()
+        })
+        
+    # 3. Bulk insert/update player stats
+    for stat in stats_to_insert:
+        try:
+            # Check for existing stat row for this player in this match
+            existing = await supabase.select("match_player_stats", filters={
+                "match_id": stat["match_id"],
+                "player_profile_id": stat["player_profile_id"]
+            })
+            if existing:
+                await supabase.update("match_player_stats", existing[0]["id"], stat)
+            else:
+                await supabase.insert("match_player_stats", stat)
+        except Exception as e:
+            print(f"Error persisting player stat row for {stat['player_profile_id']}: {e}")
+
+    # 4. Persist team statistics
+    if confirmed_json.team_statistics:
+        try:
+            team_stats = confirmed_json.team_statistics.model_dump()
+            team_stats["match_id"] = match_id
+            team_stats["organization_id"] = org_id
+            
+            existing_team = await supabase.select("match_team_stats", filters={"match_id": match_id})
+            if existing_team:
+                await supabase.update("match_team_stats", existing_team[0]["id"], team_stats)
+            else:
+                await supabase.insert("match_team_stats", team_stats)
+        except Exception as e:
+            print(f"Error persisting team stats: {e}")
+
+    # 5. Mark upload as confirmed
+    await supabase.update("match_stat_uploads", upload_id, {
+        "extract_status": "confirmed",
+        "extracted_json": confirmed_json.model_dump(by_alias=True)
+    })
+    
+    return {"message": "Stats confirmed and saved"}
+
+@router.post("/stats-upload/{upload_id}/retry")
+async def retry_stats_upload(
+    upload_id: str,
+    background_tasks: BackgroundTasks,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """Re-run extraction."""
+    org_id = current_user.get("organization_id")
+    if not org_id:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+
+    upload = await supabase.select_one("match_stat_uploads", upload_id)
+    if not upload or upload.get("organization_id") != org_id:
+        raise HTTPException(status_code=404, detail="Upload not found")
+        
+    await supabase.update("match_stat_uploads", upload_id, {"extract_status": "queued"})
+    background_tasks.add_task(extract_stats_from_file_background, upload_id, upload["organization_id"])
+    
+    return {"message": "Retry queued"}

app/api/advanced_analytics.py

@@ -0,0 +1,405 @@
+"""
+Advanced Analytics API endpoints.
+
+Provides access to advanced basketball analytics including spacing, defensive reactions,
+transition effort, decision quality, lineup impact, fatigue tracking, and auto-generated clips.
+"""
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException, status
+from uuid import UUID
+
+from app.dependencies import get_current_user, get_supabase
+from app.models.advanced_analytics import (
+    TeamAdvancedSummary,
+    PlayerAdvancedAnalysis,
+    LineupComparison,
+    ClipCatalog,
+    SpacingSummary,
+    DefensiveReactionSummary,
+    TransitionEffortSummary,
+    DecisionQualitySummary,
+    LineupImpactSummary,
+    FatigueSummary,
+    ClipSummary,
+    LineupMetric,
+    AutoClip,
+    DefensiveReaction,
+    TransitionEffort,
+    DecisionAnalysis,
+    FatigueIndex,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+
+def _hydrate_analysis_result(result: dict) -> dict:
+    """Extract summary stats from events JSONB if they exist and merge into top-level."""
+    if not result or "events" not in result:
+        return result
+        
+    events = result.get("events", [])
+    if not isinstance(events, list):
+        return result
+        
+    for event in events:
+        if isinstance(event, dict) and event.get("event_type") == "summary_stats":
+            details = event.get("details", {})
+            if isinstance(details, dict):
+                # Only fill if the main result field is missing or None
+                for key, value in details.items():
+                    if key not in result or result[key] is None or key == "advanced_analytics":
+                        result[key] = value
+            break
+    return result
+
+
+
+@router.get("/team-summary/{video_id}", response_model=TeamAdvancedSummary)
+async def get_team_advanced_summary(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get aggregated advanced analytics summary for a team game.
+    
+    Returns high-level statistics from all 7 analytics modules.
+    """
+    # Verify video access
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+    
+    # Get analysis results
+    analysis_results = await supabase.select(
+        "analysis_results",
+        filters={"video_id": video_id},
+        order_by="created_at",
+        ascending=False,
+        limit=1
+    )
+    
+    if not analysis_results:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No analysis results found for this video"
+        )
+    
+    analysis = analysis_results[0]
+    analysis = _hydrate_analysis_result(analysis)
+    advanced_analytics = analysis.get("advanced_analytics")
+    
+    if not advanced_analytics:
+        return TeamAdvancedSummary(
+            video_id=UUID(video_id),
+            spacing_summary=None,
+            defensive_summary=None,
+            transition_summary=None,
+            decision_summary=None,
+            lineup_summary=None,
+            fatigue_summary=None,
+            clip_summary=None,
+            modules_executed=[],
+            modules_failed=[]
+        )
+    
+    # Extract summaries from each module
+    spacing_summary = None
+    if "spacing" in advanced_analytics and advanced_analytics["spacing"].get("status") == "success":
+        spacing_summary = SpacingSummary(**advanced_analytics["spacing"]["summary"])
+    
+    defensive_summary = None
+    if "defensive_reactions" in advanced_analytics and advanced_analytics["defensive_reactions"].get("status") == "success":
+        defensive_summary = DefensiveReactionSummary(**advanced_analytics["defensive_reactions"]["summary"])
+    
+    transition_summary = None
+    if "transition_effort" in advanced_analytics and advanced_analytics["transition_effort"].get("status") == "success":
+        transition_summary = TransitionEffortSummary(**advanced_analytics["transition_effort"]["summary"])
+    
+    decision_summary = None
+    if "decision_quality" in advanced_analytics and advanced_analytics["decision_quality"].get("status") == "success":
+        decision_summary = DecisionQualitySummary(**advanced_analytics["decision_quality"]["summary"])
+    
+    lineup_summary = None
+    if "lineup_impact" in advanced_analytics and advanced_analytics["lineup_impact"].get("status") == "success":
+        lineup_summary = LineupImpactSummary(**advanced_analytics["lineup_impact"]["summary"])
+    
+    fatigue_summary = None
+    if "fatigue" in advanced_analytics and advanced_analytics["fatigue"].get("status") == "success":
+        fatigue_summary = FatigueSummary(**advanced_analytics["fatigue"]["summary"])
+    
+    clip_summary = None
+    if "clips" in advanced_analytics and advanced_analytics["clips"].get("status") == "success":
+        clip_summary = ClipSummary(**advanced_analytics["clips"]["summary"])
+    
+    return TeamAdvancedSummary(
+        video_id=UUID(video_id),
+        spacing_summary=spacing_summary,
+        defensive_summary=defensive_summary,
+        transition_summary=transition_summary,
+        decision_summary=decision_summary,
+        lineup_summary=lineup_summary,
+        fatigue_summary=fatigue_summary,
+        clip_summary=clip_summary,
+        modules_executed=advanced_analytics.get("modules_executed", []),
+        modules_failed=advanced_analytics.get("modules_failed", [])
+    )
+
+
+@router.get("/player/{video_id}/{player_track_id}", response_model=PlayerAdvancedAnalysis)
+async def get_player_advanced_analysis(
+    video_id: str,
+    player_track_id: int,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get advanced analytics for a specific player in a game.
+    
+    Returns player-specific metrics from all applicable modules.
+    """
+    # Verify video access
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+    
+    # Get analysis results
+    analysis_results = await supabase.select(
+        "analysis_results",
+        filters={"video_id": video_id},
+        order_by="created_at",
+        ascending=False,
+        limit=1
+    )
+    
+    if not analysis_results:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No analysis results found")
+    
+    analysis = analysis_results[0]
+    analysis = _hydrate_analysis_result(analysis)
+    advanced_analytics = analysis.get("advanced_analytics")
+    
+    if not advanced_analytics:
+        return PlayerAdvancedAnalysis(
+            player_track_id=player_track_id,
+            video_id=UUID(video_id),
+            spacing_involvement=0,
+            defensive_reactions=[],
+            transition_efforts=[],
+            decision_analyses=[],
+            fatigue_indices=[],
+            avg_effort_score=0.0,
+            avg_reaction_delay_ms=None,
+            fatigue_level="low"
+        )
+    
+    # Filter data for this specific player
+    player_defensive_reactions = []
+    if "defensive_reactions" in advanced_analytics:
+        all_reactions = advanced_analytics["defensive_reactions"].get("defensive_reactions", [])
+        player_defensive_reactions = [
+            DefensiveReaction(**r) for r in all_reactions
+            if r.get("defender_track_id") == player_track_id
+        ]
+    
+    player_transition_efforts = []
+    if "transition_effort" in advanced_analytics:
+        all_efforts = advanced_analytics["transition_effort"].get("transition_efforts", [])
+        player_transition_efforts = [
+            TransitionEffort(**e) for e in all_efforts
+            if e.get("player_track_id") == player_track_id
+        ]
+    
+    player_decision_analyses = []
+    if "decision_quality" in advanced_analytics:
+        all_decisions = advanced_analytics["decision_quality"].get("decision_analyses", [])
+        player_decision_analyses = [
+            DecisionAnalysis(**d) for d in all_decisions
+            if d.get("shooter_track_id") == player_track_id
+        ]
+    
+    player_fatigue_indices = []
+    if "fatigue" in advanced_analytics:
+        all_fatigue = advanced_analytics["fatigue"].get("fatigue_indices", [])
+        player_fatigue_indices = [
+            FatigueIndex(**f) for f in all_fatigue
+            if f.get("player_track_id") == player_track_id
+        ]
+    
+    # Calculate player-specific aggregates
+    spacing_involvement = 0
+    if "spacing" in advanced_analytics:
+        all_spacing = advanced_analytics["spacing"].get("spacing_metrics", [])
+        for metric in all_spacing:
+            player_positions = metric.get("player_positions", {})
+            if str(player_track_id) in player_positions:
+                spacing_involvement += 1
+    
+    avg_effort_score = 0.0
+    if player_transition_efforts:
+        avg_effort_score = sum(e.effort_score for e in player_transition_efforts) / len(player_transition_efforts)
+    
+    avg_reaction_delay_ms = None
+    if player_defensive_reactions:
+        valid_delays = [r.reaction_delay_ms for r in player_defensive_reactions if r.reaction_delay_ms is not None]
+        if valid_delays:
+            avg_reaction_delay_ms = sum(valid_delays) / len(valid_delays)
+    
+    fatigue_level = "low"
+    if player_fatigue_indices:
+        latest_fatigue = player_fatigue_indices[-1]
+        fatigue_level = latest_fatigue.fatigue_level
+    
+    return PlayerAdvancedAnalysis(
+        player_track_id=player_track_id,
+        video_id=UUID(video_id),
+        spacing_involvement=spacing_involvement,
+        defensive_reactions=player_defensive_reactions,
+        transition_efforts=player_transition_efforts,
+        decision_analyses=player_decision_analyses,
+        fatigue_indices=player_fatigue_indices,
+        avg_effort_score=avg_effort_score,
+        avg_reaction_delay_ms=avg_reaction_delay_ms,
+        fatigue_level=fatigue_level
+    )
+
+
+@router.get("/lineups/{video_id}", response_model=LineupComparison)
+async def get_lineup_comparison(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get lineup performance comparison for a game.
+    
+    Returns metrics for all 5-player combinations from both teams.
+    """
+    # Verify video access
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+    
+    # Get analysis results
+    analysis_results = await supabase.select(
+        "analysis_results",
+        filters={"video_id": video_id},
+        order_by="created_at",
+        ascending=False,
+        limit=1
+    )
+    
+    if not analysis_results:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No analysis results found")
+    
+    analysis = analysis_results[0]
+    analysis = _hydrate_analysis_result(analysis)
+    advanced_analytics = analysis.get("advanced_analytics")
+    
+    if not advanced_analytics or "lineup_impact" not in advanced_analytics:
+        return LineupComparison(
+            video_id=UUID(video_id),
+            team_1_lineups=[],
+            team_2_lineups=[],
+            best_overall_lineup=None,
+            worst_overall_lineup=None
+        )
+    
+    lineup_data = advanced_analytics["lineup_impact"]
+    all_lineups = lineup_data.get("lineup_metrics", [])
+    
+    team_1_lineups = [LineupMetric(**l) for l in all_lineups if l.get("team_id") == 1]
+    team_2_lineups = [LineupMetric(**l) for l in all_lineups if l.get("team_id") == 2]
+    
+    if not all_lineups:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No lineup data available"
+        )
+    
+    # Find best and worst lineups
+    best_lineup = max(all_lineups, key=lambda x: x.get("net_rating", 0))
+    worst_lineup = min(all_lineups, key=lambda x: x.get("net_rating", 0))
+    
+    return LineupComparison(
+        video_id=UUID(video_id),
+        team_1_lineups=team_1_lineups,
+        team_2_lineups=team_2_lineups,
+        best_overall_lineup=LineupMetric(**best_lineup),
+        worst_overall_lineup=LineupMetric(**worst_lineup)
+    )
+
+
+@router.get("/clips/{video_id}", response_model=ClipCatalog)
+async def get_coaching_clips(
+    video_id: str,
+    clip_type: str = None,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get automatically generated coaching clips for a game.
+    
+    Optionally filter by clip type (poor_spacing, late_rotation, etc.).
+    """
+    # Verify video access
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access denied")
+    
+    # Get analysis results
+    analysis_results = await supabase.select(
+        "analysis_results",
+        filters={"video_id": video_id},
+        order_by="created_at",
+        ascending=False,
+        limit=1
+    )
+    
+    if not analysis_results:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No analysis results found")
+    
+    analysis = analysis_results[0]
+    analysis = _hydrate_analysis_result(analysis)
+    advanced_analytics = analysis.get("advanced_analytics")
+    
+    if not advanced_analytics or "clips" not in advanced_analytics:
+        return ClipCatalog(
+            video_id=UUID(video_id),
+            clips=[],
+            summary=ClipSummary(
+                total_clips_generated=0,
+                clips_by_type={},
+                output_directory=""
+            )
+        )
+    
+    clip_data = advanced_analytics["clips"]
+    all_clips = clip_data.get("auto_clips", [])
+    
+    # Filter by clip type if specified
+    if clip_type:
+        all_clips = [c for c in all_clips if c.get("clip_type") == clip_type]
+    
+    clips = [AutoClip(**c) for c in all_clips]
+    summary = ClipSummary(**clip_data.get("summary", {}))
+    
+    return ClipCatalog(
+        video_id=UUID(video_id),
+        clips=clips,
+        summary=summary
+    )

app/api/analysis.py

@@ -0,0 +1,689 @@
+"""
+Analysis API endpoints for triggering and retrieving video analysis.
+"""
+import asyncio
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional, Union
+from fastapi import APIRouter, Depends, HTTPException, BackgroundTasks, status
+import anyio
+
+from app.dependencies import (
+    get_current_user,
+    require_team_account,
+    require_personal_account,
+    get_supabase,
+)
+from app.models.video import VideoStatus, AnalysisMode
+from app.models.analysis import (
+    AnalysisRequest,
+    AnalysisResult,
+    PersonalAnalysisResult,
+    Detection,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+
+def _run_dispatch_in_thread(video_path: str, mode: AnalysisMode, video_id: str, options: dict | None):
+    """Run async dispatch in a dedicated thread event loop."""
+    try:
+        from analysis.dispatcher import dispatch_analysis
+        return asyncio.run(dispatch_analysis(video_path, mode, options=options, video_id=video_id))
+    except ImportError:
+        print("⚠️ Analysis dispatcher not available (heavy dependencies missing)")
+        return {"status": "skipped", "reason": "heavy dependencies missing"}
+
+
+async def run_analysis_background(video_id: str, mode: str, supabase: SupabaseService, options: Optional[dict] = None):
+    """
+    Background task for running video analysis.
+    Wraps the template analysis pipeline for API use.
+    """
+    try:
+        # Update status to processing
+        await supabase.update("videos", video_id, {
+            "status": VideoStatus.PROCESSING.value,
+            "current_step": "Initializing analysis",
+            "progress_percent": 0,
+        })
+        
+        # Get video info
+        video = await supabase.select_one("videos", video_id)
+        if not video:
+            return
+
+        # Run analysis based on mode (offload CPU/GPU-heavy work to a thread)
+        result = await anyio.to_thread.run_sync(
+            _run_dispatch_in_thread,
+            video["storage_path"],
+            AnalysisMode(mode),
+            video_id,
+            options or {},
+        )
+
+        if result.get("status") == "failed":
+            raise Exception(result.get("error", "Analysis failed in dispatcher"))
+            
+        if result.get("total_frames", 0) == 0:
+            raise Exception("Analysis returned 0 frames. The process may have been killed due to lack of memory or encountered a fatal error.")
+
+        # Pull out large/extra payloads that should not be inserted into analysis_results
+        detections = result.pop("detections", None) or []
+        # This field is useful for UI but isn't part of the DB schema
+        result.pop("primary_player_frames", None)
+
+        # For PERSONAL mode, attach the user's player_id if available
+        player_id_for_analytics = None
+        if mode == AnalysisMode.PERSONAL.value:
+            players = await supabase.select("players", filters={"user_id": video["uploader_id"]})
+            if players:
+                player_id_for_analytics = players[0].get("id")
+        
+        # Store results (only columns that exist in analysis_results table)
+        allowed_fields = {
+            "total_frames",
+            "duration_seconds",
+            "players_detected",
+            "team_1_possession_percent",
+            "team_2_possession_percent",
+            "total_passes",
+            "team_1_passes",
+            "team_2_passes",
+            "total_interceptions",
+            "team_1_interceptions",
+            "team_2_interceptions",
+            "shot_attempts",
+            "shots_made",
+            "shots_missed",
+            "shooting_percentage",
+            "team_1_shot_attempts",
+            "team_1_shots_made",
+            "team_2_shot_attempts",
+            "team_2_shots_made",
+            "overall_shooting_percentage",
+            "defensive_actions",
+            "shot_form_consistency",
+            "dribble_count",
+            "dribble_frequency_per_minute",
+            "total_distance_meters",
+            "avg_speed_kmh",
+            "max_speed_kmh",
+            "fps",
+            "acceleration_events",
+            "avg_knee_bend_angle",
+            "avg_elbow_angle_shooting",
+            "training_load_score",
+            "events",
+            "processing_time_seconds",
+        }
+
+        def convert_numpy(obj):
+            import numpy as np
+            if isinstance(obj, (np.int64, np.int32, np.int16, np.int8)):
+                return int(obj)
+            if isinstance(obj, (np.float64, np.float32, np.float16)):
+                return float(obj)
+            if isinstance(obj, np.ndarray):
+                return obj.tolist()
+            if isinstance(obj, dict):
+                return {k: convert_numpy(v) for k, v in obj.items()}
+            if isinstance(obj, list):
+                return [convert_numpy(v) for v in obj]
+            return obj
+
+        result = convert_numpy(result)
+        detections = convert_numpy(detections)
+        
+        analysis_id = str(uuid4())
+        analysis_payload = {k: v for k, v in result.items() if k in allowed_fields}
+        
+        # Ensure required fields have values (not null)
+        required_fields = {
+            "total_frames": 0,
+            "duration_seconds": 0.0,
+            "players_detected": 0,
+            "team_1_possession_percent": 50.0,
+            "team_2_possession_percent": 50.0,
+            "total_passes": 0,
+            "total_interceptions": 0,
+            "shot_attempts": 0,
+            "processing_time_seconds": 0.0,
+        }
+        
+        for field, default_val in required_fields.items():
+            if field not in analysis_payload or analysis_payload[field] is None:
+                analysis_payload[field] = default_val
+        
+        # Capture extra metrics that might be missing from schema in the events JSONB
+        # This keeps the backend functional even if the DB hasn't been migrated yet.
+        extra_metrics = {
+            "defensive_actions": result.get("defensive_actions", 0),
+            "overall_shooting_percentage": result.get("overall_shooting_percentage", 0.0),
+            "total_distance_meters": result.get("total_distance_meters", 0.0),
+            "avg_speed_kmh": result.get("avg_speed_kmh", 0.0),
+            "max_speed_kmh": result.get("max_speed_kmh", 0.0),
+            "advanced_analytics": result.get("advanced_analytics"),
+            # Jersey colors — stored so the frontend can colour player markers by actual kit
+            "team_1_jersey": (options or {}).get("our_team_jersey", ""),
+            "team_2_jersey": (options or {}).get("opponent_jersey", ""),
+        }
+        
+        current_events = result.get("events", [])
+        if isinstance(current_events, list):
+            current_events.append({
+                "event_type": "summary_stats",
+                "frame": 0,
+                "timestamp_seconds": 0.0,
+                "details": extra_metrics
+            })
+            analysis_payload["events"] = current_events
+
+        analysis_record = {
+            "id": analysis_id,
+            "video_id": video_id,
+            **analysis_payload,
+            "created_at": datetime.utcnow().isoformat(),
+        }
+        
+        try:
+            await supabase.insert("analysis_results", analysis_record)
+        except Exception as e:
+            raise e
+
+        # Persist detections for overlay playback (always every frame for smoothness)
+        store_detections = True
+        detections_stride = 1
+        max_detections = 200_000
+        if options:
+            store_detections = bool(options.get("store_detections", True))
+            try:
+                detections_stride = int(options.get("detections_stride", detections_stride))
+            except Exception:
+                pass
+            try:
+                max_detections = int(options.get("max_detections", max_detections))
+            except Exception:
+                pass
+
+        if store_detections and detections:
+            await supabase.update("videos", video_id, {
+                "current_step": f"Saving {len(detections)} detection highlights",
+                "progress_percent": 99,
+            })
+
+            max_detections = max(1_000, max_detections)
+
+            rows = []
+            for d in detections:
+                bbox = d.get("bbox")
+                if not bbox or len(bbox) != 4:
+                    continue
+                obj_type = d.get("object_type")
+                # Map non-DB types to player/ball but keep real type in keypoints JSON
+                db_obj_type = "player"
+                if obj_type in ("ball", "basketball"):
+                    db_obj_type = "ball"
+                
+                # Store the original type and tactical coordinates in keypoints for the frontend
+                keypoints = d.get("keypoints") or {}
+                if not isinstance(keypoints, dict):
+                    keypoints = {"data": keypoints}
+                keypoints["real_type"] = obj_type
+                
+                # Store tactical coordinates if available
+                if "tactical_x" in d:
+                    keypoints["tactical_x"] = d["tactical_x"]
+                    keypoints["tactical_y"] = d["tactical_y"]
+
+                rows.append({
+                    "video_id": video_id,
+                    "frame": int(d.get("frame", 0)),
+                    "object_type": db_obj_type,
+                    "track_id": int(d.get("track_id", 0)) if isinstance(d.get("track_id"), (int, float)) else int(str(d.get("track_id", 0)).split('-')[0] if '-' in str(d.get("track_id", "")) else 0),
+                    "bbox": bbox,
+                    "confidence": float(d.get("confidence", 1.0)),
+                    "keypoints": keypoints,
+                    "team_id": d.get("team_id"),
+                    "has_ball": bool(d.get("has_ball", False)),
+                    "tactical_x": d.get("tactical_x"),
+                    "tactical_y": d.get("tactical_y"),
+                })
+                if len(rows) >= max_detections:
+                    break
+
+            # Replace old detections for this video (best-effort)
+            try:
+                await supabase.delete_where("detections", {"video_id": video_id})
+            except Exception:
+                pass
+
+            await supabase.insert_many("detections", rows, chunk_size=500)
+
+        # Persist PERSONAL analytics time-series (best-effort)
+        if mode == AnalysisMode.PERSONAL.value and player_id_for_analytics:
+            player_id = player_id_for_analytics
+            analytics_rows = []
+            if analysis_payload.get("total_distance_meters") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "distance_km",
+                    "value": float(analysis_payload["total_distance_meters"]) / 1000.0,
+                })
+            if analysis_payload.get("avg_speed_kmh") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "avg_speed_kmh",
+                    "value": float(analysis_payload["avg_speed_kmh"]),
+                })
+            if analysis_payload.get("max_speed_kmh") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "max_speed_kmh",
+                    "value": float(analysis_payload["max_speed_kmh"]),
+                })
+            if analysis_payload.get("dribble_count") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "dribble_count",
+                    "value": float(analysis_payload["dribble_count"]),
+                })
+            if analysis_payload.get("shot_attempts") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "shot_attempt",
+                    "value": float(analysis_payload["shot_attempts"]),
+                })
+            if analysis_payload.get("shot_form_consistency") is not None:
+                analytics_rows.append({
+                    "player_id": player_id,
+                    "video_id": video_id,
+                    "metric_type": "form_consistency",
+                    "value": float(analysis_payload["shot_form_consistency"]),
+                })
+
+            if analytics_rows:
+                try:
+                    await supabase.insert_many("analytics", analytics_rows, chunk_size=500)
+                except Exception:
+                    pass
+        
+        # ── Upload annotated video to Supabase Storage ────────────────────────
+        import os as _os
+        _ANNOTATED_BUCKET = "team-analysis-videos"
+        _annotated_local = _os.path.join("output_videos", "annotated", f"{video_id}.mp4")
+
+        if _os.path.exists(_annotated_local):
+            try:
+                _storage_path = f"{video.get('uploader_id', 'unknown')}/{video_id}_annotated.mp4"
+                await supabase.upload_file_from_path(
+                    bucket=_ANNOTATED_BUCKET,
+                    storage_path=_storage_path,
+                    local_path=_annotated_local,
+                    content_type="video/mp4",
+                )
+                _signed_url = await supabase.get_long_lived_url(
+                    bucket=_ANNOTATED_BUCKET,
+                    storage_path=_storage_path,
+                    expires_in=60 * 60 * 24 * 7,  # 7 days
+                )
+                if _signed_url:
+                    # Store signed URL in the videos record for direct playback
+                    await supabase.update("videos", video_id, {"annotated_url": _signed_url})
+                    # Clean up local annotated file
+                    try:
+                        _os.remove(_annotated_local)
+                    except Exception:
+                        pass
+            except Exception as _upload_err:
+                # Non-fatal — fallback to local FileResponse endpoint
+                print(f"[{video_id}] Supabase annotated upload failed (using local fallback): {_upload_err}")
+
+        # Update video status to COMPLETED
+        await supabase.update("videos", video_id, {
+            "status": VideoStatus.COMPLETED.value,
+            "progress_percent": 100,
+            "current_step": "Complete",
+            "completed_at": datetime.utcnow().isoformat(),
+            "has_annotated": True,
+        })
+        
+    except Exception as e:
+        # Update status on failure
+        await supabase.update("videos", video_id, {
+            "status": VideoStatus.FAILED.value,
+            "error_message": str(e),
+        })
+
+
+@router.post("/team", response_model=dict, status_code=status.HTTP_202_ACCEPTED)
+async def trigger_team_analysis(
+    request: AnalysisRequest,
+    background_tasks: BackgroundTasks,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Trigger team analysis on an uploaded video.
+    
+    **Requires TEAM account.**
+    
+    This is an async operation. Use GET /api/videos/{id}/status to check progress.
+    """
+    # Verify video exists and belongs to user
+    video = await supabase.select_one("videos", str(request.video_id))
+    
+    if not video:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Video not found"
+        )
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this video"
+        )
+    
+    if video["status"] == VideoStatus.PROCESSING.value:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Video is already being processed"
+        )
+    
+    # Build comprehensive options dict from request
+    options = request.options or {}
+    
+    # Add all detection and display parameters to options
+    if request.our_team_jersey:
+        options["our_team_jersey"] = request.our_team_jersey
+    if request.opponent_jersey:
+        options["opponent_jersey"] = request.opponent_jersey
+    if request.our_team_id:
+        options["our_team_id"] = request.our_team_id
+    
+    # Detection parameters
+    options["player_confidence"] = request.player_confidence or 0.3
+    options["ball_confidence"] = request.ball_confidence or 0.15
+    options["detection_batch_size"] = request.detection_batch_size or 10
+    options["image_size"] = request.image_size or 1080
+    options["max_players_on_court"] = request.max_players_on_court or 12
+    
+    # Analysis options
+    options["use_cached_detections"] = request.use_cached_detections or False
+    options["clear_cache_after"] = request.clear_cache_after if request.clear_cache_after is not None else True
+    options["save_annotated_video"] = request.save_annotated_video if request.save_annotated_video is not None else True
+    
+    # Display options
+    options["render_speed_text"] = request.render_speed_text if request.render_speed_text is not None else True
+    options["render_distance_text"] = request.render_distance_text if request.render_distance_text is not None else True
+    options["render_tactical_view"] = request.render_tactical_view if request.render_tactical_view is not None else True
+    options["render_court_keypoints"] = request.render_court_keypoints if request.render_court_keypoints is not None else True
+    
+    # Queue analysis
+    background_tasks.add_task(
+        run_analysis_background,
+        str(request.video_id),
+        AnalysisMode.TEAM.value,
+        supabase,
+        options,
+    )
+    
+    return {
+        "message": "Analysis queued",
+        "video_id": str(request.video_id),
+        "mode": "team",
+    }
+
+
+@router.post("/personal", response_model=dict, status_code=status.HTTP_202_ACCEPTED)
+async def trigger_personal_analysis(
+    request: AnalysisRequest,
+    background_tasks: BackgroundTasks,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Trigger personal analysis on an uploaded video.
+    
+    **Requires PERSONAL account.**
+    
+    This is an async operation. Use GET /api/videos/{id}/status to check progress.
+    """
+    video = await supabase.select_one("videos", str(request.video_id))
+    
+    if not video:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Video not found"
+        )
+    
+    if video["uploader_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this video"
+        )
+    
+    if video["status"] == VideoStatus.PROCESSING.value:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Video is already being processed"
+        )
+    
+    background_tasks.add_task(
+        run_analysis_background,
+        str(request.video_id),
+        AnalysisMode.PERSONAL.value,
+        supabase,
+        request.options or {},
+    )
+    
+    return {
+        "message": "Analysis queued",
+        "video_id": str(request.video_id),
+        "mode": "personal",
+    }
+
+
+def _hydrate_analysis_result(result: dict) -> dict:
+    """Extract summary stats from events JSONB if they exist and merge into top-level."""
+    if not result or "events" not in result:
+        return result
+        
+    events = result.get("events", [])
+    if not isinstance(events, list):
+        return result
+        
+    for event in events:
+        if isinstance(event, dict) and event.get("event_type") == "summary_stats":
+            details = event.get("details", {})
+            if isinstance(details, dict):
+                # Only fill if the main result field is missing or None
+                for key, value in details.items():
+                    # Only fill if the main result field is missing or None
+                    if key not in result or result[key] is None or key == "advanced_analytics":
+                        result[key] = value
+            break
+    return result
+
+
+@router.get("/by-video/{video_id}", response_model=Union[AnalysisResult, PersonalAnalysisResult])
+async def get_latest_analysis_for_video(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get the latest analysis result for a given video_id.
+    Useful for frontend: poll video status, then fetch latest analysis.
+    """
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    has_access = False
+    if video.get("uploader_id") == current_user["id"]:
+        has_access = True
+    elif video.get("analysis_mode") == AnalysisMode.TEAM.value:
+        org_id = current_user.get("organization_id")
+        if not org_id and current_user.get("account_type") == "team":
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs: org_id = orgs[0]["id"]
+        elif not org_id:
+            # Maybe they are a player linked to a team?
+            players = await supabase.select("players", filters={"user_id": current_user["id"]})
+            for p in players:
+                if p.get("organization_id"):
+                    org_id = p["organization_id"]
+                    break
+        
+        if org_id and str(video.get("organization_id")) == str(org_id):
+            has_access = True
+
+    if not has_access:
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="You don't have access to this video")
+
+    if video.get("analysis_mode") == AnalysisMode.PERSONAL.value:
+        results = await supabase.select(
+            "personal_analyses",
+            filters={"job_id": video_id},
+            order_by="created_at",
+            ascending=False,
+            limit=1,
+        )
+        if not results:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No analysis found for this video")
+        result = results[0]
+        # Map fields so it can be returned via PersonalAnalysisResult if needed
+        # Or return as is if the schema matches
+        result_json = result.get("results_json", {})
+        if isinstance(result_json, str):
+            import json
+            try: result_json = json.loads(result_json)
+            except: result_json = {}
+        
+        return PersonalAnalysisResult(**result)
+    else:
+        results = await supabase.select(
+            "analysis_results",
+            filters={"video_id": video_id},
+            order_by="created_at",
+            ascending=False,
+            limit=1,
+        )
+        if not results:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No analysis found for this video")
+    
+        result = results[0]
+        result = _hydrate_analysis_result(result)
+        return AnalysisResult(**result)
+
+
+@router.get("/{analysis_id}", response_model=Union[AnalysisResult, PersonalAnalysisResult])
+async def get_analysis_result(
+    analysis_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get analysis results by ID.
+    """
+    result = await supabase.select_one("analysis_results", analysis_id)
+    
+    if not result:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Analysis result not found"
+        )
+    
+    # Verify ownership via video
+    video = await supabase.select_one("videos", result["video_id"])
+    if not video:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Video not found"
+        )
+        
+    has_access = False
+    if video.get("uploader_id") == current_user["id"]:
+        has_access = True
+    elif video.get("analysis_mode") == AnalysisMode.TEAM.value:
+        org_id = current_user.get("organization_id")
+        if not org_id and current_user.get("account_type") == "team":
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs: org_id = orgs[0]["id"]
+        elif not org_id:
+            players = await supabase.select("players", filters={"user_id": current_user["id"]})
+            for p in players:
+                if p.get("organization_id"):
+                    org_id = p["organization_id"]
+                    break
+        
+        if org_id and str(video.get("organization_id")) == str(org_id):
+            has_access = True
+
+    if not has_access:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this analysis"
+        )
+
+    # Hydrate with extra metrics if stored in events
+    result = _hydrate_analysis_result(result)
+
+    # Return model based on video's analysis_mode
+    if video.get("analysis_mode") == AnalysisMode.PERSONAL.value:
+        return PersonalAnalysisResult(**result)
+
+    return AnalysisResult(**result)
+
+
+@router.get("/{analysis_id}/detections")
+async def get_analysis_detections(
+    analysis_id: str,
+    frame_start: Optional[int] = None,
+    frame_end: Optional[int] = None,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get frame-by-frame detections for an analysis.
+    
+    Optionally filter by frame range.
+    """
+    # Verify access
+    result = await supabase.select_one("analysis_results", analysis_id)
+    if not result:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Analysis result not found"
+        )
+    
+    video = await supabase.select_one("videos", result["video_id"])
+    if not video or video["uploader_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this analysis"
+        )
+    
+    # Get detections
+    filters = {"video_id": result["video_id"]}
+    detections = await supabase.select("detections", filters=filters, limit=100000)
+    
+    # Filter by frame range if specified
+    if frame_start is not None:
+        detections = [d for d in detections if d.get("frame", 0) >= frame_start]
+    if frame_end is not None:
+        detections = [d for d in detections if d.get("frame", 0) <= frame_end]
+    
+    return {
+        "analysis_id": analysis_id,
+        "total_detections": len(detections),
+        "detections": detections,
+    }

app/api/analytics.py

@@ -0,0 +1,402 @@
+"""
+Analytics and metrics API endpoints.
+"""
+from datetime import date, datetime, timedelta
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.dependencies import (
+    get_current_user,
+    require_team_account,
+    require_personal_account,
+    get_supabase,
+)
+from app.models.user import AccountType
+from app.models.analytics import (
+    PlayerAnalyticsSummary,
+    TeamAnalyticsSummary,
+    SkillSummary,
+    ProgressReport,
+    ProgressData,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+def _parse_ts(ts: Optional[str]) -> Optional[datetime]:
+    if not ts:
+        return None
+    try:
+        # Accept both "Z" and "+00:00" ISO formats
+        return datetime.fromisoformat(ts.replace("Z", "+00:00"))
+    except Exception:
+        return None
+
+
+@router.get("/player/{player_id}", response_model=PlayerAnalyticsSummary)
+async def get_player_analytics(
+    player_id: str,
+    period_days: int = Query(30, ge=1, le=365),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get aggregated analytics for a player over a time period.
+    """
+    # Verify player access
+    player = await supabase.select_one("players", player_id)
+    
+    if not player:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Player not found"
+        )
+    
+    # Check access based on account type
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if player.get("organization_id"):
+            org = await supabase.select_one("organizations", player["organization_id"])
+            has_access = org and org["owner_id"] == current_user["id"]
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        player_org = player.get("organization_id")
+        coach_org = current_user.get("organization_id")
+        has_access = player_org and coach_org and str(player_org) == str(coach_org)
+    else:
+        has_access = player.get("user_id") == current_user["id"]
+    
+    if not has_access:
+        raise HTTPException(status_code=403, detail="Access denied")
+    
+    # Calculate period
+    period_end = date.today()
+    period_start = period_end - timedelta(days=period_days)
+    period_start_dt = datetime.combine(period_start, datetime.min.time())
+    period_end_dt = datetime.combine(period_end, datetime.max.time())
+    
+    # Get analytics data
+    analytics = await supabase.select("analytics", filters={"player_id": player_id})
+    # Filter by period when timestamps exist
+    analytics = [
+        a for a in analytics
+        if (ts := _parse_ts(a.get("timestamp"))) is None or (period_start_dt <= ts <= period_end_dt)
+    ]
+    
+    # Aggregate metrics
+    def safe_float(v):
+        try:
+            return float(v) if v is not None else 0.0
+        except (ValueError, TypeError):
+            return 0.0
+
+    total_distance = sum(safe_float(a.get("value")) for a in analytics if a.get("metric_type") == "distance_km")
+    
+    speed_values = [safe_float(a.get("value")) for a in analytics if a.get("metric_type") == "avg_speed_kmh" and a.get("value") is not None]
+    max_speed_values = [safe_float(a.get("value")) for a in analytics if a.get("metric_type") == "max_speed_kmh" and a.get("value") is not None]
+    
+    shot_attempts = sum(
+        int(safe_float(a.get("value")))
+        for a in analytics
+        if a.get("metric_type") == "shot_attempt"
+    )
+    
+    form_scores = [safe_float(a.get("value")) for a in analytics if a.get("metric_type") == "form_consistency" and a.get("value") is not None]
+    
+    dribbles = sum(safe_float(a.get("value")) for a in analytics if a.get("metric_type") == "dribble_count")
+    
+    # Get unique video count
+    video_ids = set(str(a.get("video_id")) for a in analytics if a.get("video_id"))
+    
+    # Calculate training time from videos
+    training_minutes = 0.0
+    if video_ids:
+        try:
+            # Batch fetch video durations
+            vids = await supabase.select_in("videos", "id", list(video_ids), columns="id,duration_seconds")
+            for v in vids:
+                if v and v.get("duration_seconds") is not None:
+                    training_minutes += safe_float(v["duration_seconds"]) / 60
+        except Exception as e:
+            print(f"Background: Error batch fetching video durations: {e}")
+            for vid in video_ids:
+                try:
+                    video = await supabase.select_one("videos", vid)
+                    if video and video.get("duration_seconds") is not None:
+                        training_minutes += safe_float(video["duration_seconds"]) / 60
+                except Exception:
+                    continue
+    
+    return PlayerAnalyticsSummary(
+        player_id=player_id,
+        period_start=period_start,
+        period_end=period_end,
+        total_training_sessions=len(video_ids),
+        total_training_minutes=training_minutes,
+        total_videos_analyzed=len(video_ids),
+        total_distance_km=total_distance if total_distance > 0 else None,
+        avg_speed_kmh=sum(speed_values) / len(speed_values) if speed_values else None,
+        max_speed_kmh=max(max_speed_values) if max_speed_values else None,
+        total_shot_attempts=shot_attempts,
+        avg_shot_form_consistency=sum(form_scores) / len(form_scores) if form_scores else None,
+        total_dribbles=int(dribbles),
+    )
+
+
+@router.get("/team/{org_id}", response_model=TeamAnalyticsSummary)
+async def get_team_analytics(
+    org_id: str,
+    period_days: int = Query(30, ge=1, le=365),
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get aggregated team analytics over a time period.
+    
+    **Requires TEAM account.**
+    """
+    # Verify org access
+    org = await supabase.select_one("organizations", org_id)
+    
+    if not org:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Organization not found"
+        )
+    
+    # Verify access
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        has_access = org["owner_id"] == current_user["id"]
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        coach_org_id = current_user.get("organization_id")
+        has_access = coach_org_id and str(coach_org_id) == str(org_id)
+    
+    if not has_access:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Access denied"
+        )
+    
+    period_end = date.today()
+    period_start = period_end - timedelta(days=period_days)
+    period_start_dt = datetime.combine(period_start, datetime.min.time())
+    period_end_dt = datetime.combine(period_end, datetime.max.time())
+    
+    # Get team videos
+    videos = await supabase.select("videos", filters={"organization_id": org_id})
+    completed_videos = [v for v in videos if v.get("status") == "completed"]
+    
+    # Get analytics for team players
+    players = await supabase.select("players", filters={"organization_id": org_id})
+    player_ids = [p["id"] for p in players]
+    
+    all_analytics = []
+    for pid in player_ids:
+        analytics = await supabase.select("analytics", filters={"player_id": pid})
+        # Filter by period when timestamps exist
+        analytics = [
+            a for a in analytics
+            if (ts := _parse_ts(a.get("timestamp"))) is None or (period_start_dt <= ts <= period_end_dt)
+        ]
+        all_analytics.extend(analytics)
+    
+    # Aggregate team metrics
+    total_passes = sum(1 for a in all_analytics if a.get("metric_type") == "pass")
+    total_interceptions = sum(1 for a in all_analytics if a.get("metric_type") == "interception")
+    
+    return TeamAnalyticsSummary(
+        organization_id=org_id,
+        period_start=period_start,
+        period_end=period_end,
+        total_games_analyzed=len([v for v in completed_videos if v.get("analysis_mode") == "team"]),
+        total_training_sessions=len(completed_videos),
+        total_passes=total_passes,
+        avg_passes_per_game=total_passes / len(completed_videos) if completed_videos else None,
+        total_interceptions=total_interceptions,
+        avg_interceptions_per_game=total_interceptions / len(completed_videos) if completed_videos else None,
+    )
+
+
+@router.get("/skills/summary", response_model=SkillSummary)
+async def get_skill_summary(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get personal skill summary for dashboard display.
+    
+    **Requires PERSONAL account.**
+    """
+    # Get user's player profile
+    players = await supabase.select("players", filters={"user_id": current_user["id"]})
+    
+    if not players:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No player profile found. Create one first."
+        )
+    
+    player = players[0]
+    player_id = player["id"]
+    
+    # Get all analytics
+    analytics = await supabase.select("analytics", filters={"player_id": player_id})
+    
+    # Calculate scores (0-100 scale)
+    def calculate_score(values):
+        clean_values = [float(v) for v in values if v is not None]
+        if not clean_values:
+            return 50.0  # Neutral score if no data
+        avg = sum(clean_values) / len(clean_values)
+        return min(100.0, max(0.0, avg))
+    
+    # Extract metrics defensively
+    form_scores = [a.get("value") for a in analytics if a.get("metric_type") == "form_consistency"]
+    speed_scores = [a.get("value") for a in analytics if a.get("metric_type") == "movement_score"]
+    dribble_scores = [a.get("value") for a in analytics if a.get("metric_type") == "dribble_score"]
+    
+    shooting_score = calculate_score(form_scores)
+    movement_score = calculate_score(speed_scores)
+    dribbling_score = calculate_score(dribble_scores)
+    consistency_score = calculate_score([shooting_score, movement_score, dribbling_score])
+    overall_score = (shooting_score + movement_score + dribbling_score + consistency_score) / 4
+    
+    # Determine strengths and areas to improve
+    scores = {
+        "Shooting Form": shooting_score,
+        "Movement": movement_score,
+        "Ball Handling": dribbling_score,
+    }
+    
+    sorted_scores = sorted(scores.items(), key=lambda x: x[1], reverse=True)
+    strengths = [s[0] for s in sorted_scores if s[1] >= 70][:2]
+    areas_to_improve = [s[0] for s in sorted_scores if s[1] < 60][:2]
+    
+    # Generate recommendations
+    recommendations = []
+    if shooting_score < 60:
+        recommendations.append("Focus on shooting form consistency - practice elbow alignment")
+    if movement_score < 60:
+        recommendations.append("Work on lateral movement drills to improve court coverage")
+    if dribbling_score < 60:
+        recommendations.append("Practice dribbling with both hands to improve ball control")
+    
+    if not recommendations:
+        recommendations.append("Keep up the great work! Try advanced drills to maintain progress")
+    
+    return SkillSummary(
+        player_id=player_id,
+        last_updated=datetime.utcnow(),
+        overall_score=overall_score,
+        shooting_score=shooting_score,
+        dribbling_score=dribbling_score,
+        movement_score=movement_score,
+        consistency_score=consistency_score,
+        strengths=strengths,
+        areas_to_improve=areas_to_improve,
+        recommendations=recommendations[:3],
+    )
+
+
+@router.get("/progress/{player_id}", response_model=ProgressReport)
+async def get_player_progress(
+    player_id: str,
+    metric_type: str = Query(..., description="Metric to track: 'speed', 'form', 'distance'"),
+    period_days: int = Query(30, ge=7, le=365),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get progress report for a specific metric over time.
+    """
+    # Verify access (same as player analytics)
+    player = await supabase.select_one("players", player_id)
+    
+    if not player:
+        raise HTTPException(status_code=404, detail="Player not found")
+    
+    # Check access
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if player.get("organization_id"):
+            org = await supabase.select_one("organizations", player["organization_id"])
+            has_access = org and org["owner_id"] == current_user["id"]
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        player_org = player.get("organization_id")
+        coach_org = current_user.get("organization_id")
+        has_access = player_org and coach_org and str(player_org) == str(coach_org)
+    else:
+        has_access = player.get("user_id") == current_user["id"]
+    
+    if not has_access:
+        raise HTTPException(status_code=403, detail="Access denied")
+    
+    period_end = date.today()
+    period_start = period_end - timedelta(days=period_days)
+    period_start_dt = datetime.combine(period_start, datetime.min.time())
+    period_end_dt = datetime.combine(period_end, datetime.max.time())
+    
+    # Map user-friendly names to internal metric types
+    metric_map = {
+        "speed": "avg_speed_kmh",
+        "form": "form_consistency",
+        "distance": "distance_km",
+    }
+    
+    internal_metric = metric_map.get(metric_type, metric_type)
+    
+    # Get analytics data
+    analytics = await supabase.select("analytics", filters={"player_id": player_id})
+    metric_data = [a for a in analytics if a.get("metric_type") == internal_metric]
+    metric_data = [
+        a for a in metric_data
+        if (ts := _parse_ts(a.get("timestamp"))) is None or (period_start_dt <= ts <= period_end_dt)
+    ]
+    
+    # Build data points (mock aggregation by date)
+    data_points = []
+    for a in metric_data:
+        timestamp = a.get("timestamp")
+        value = a.get("value")
+        if timestamp and value is not None:
+            try:
+                dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+                data_points.append(ProgressData(
+                    date=dt.date(),
+                    value=float(value),
+                    metric_type=metric_type,
+                ))
+            except (ValueError, TypeError):
+                pass
+    
+    # Calculate trend
+    if len(data_points) >= 2:
+        sorted_points = sorted(data_points, key=lambda x: x.date)
+        first_value = sorted_points[0].value
+        last_value = sorted_points[-1].value
+        
+        if first_value > 0:
+            percent_change = ((last_value - first_value) / first_value) * 100
+        else:
+            percent_change = 0
+        
+        if percent_change > 5:
+            trend = "improving"
+        elif percent_change < -5:
+            trend = "declining"
+        else:
+            trend = "stable"
+    else:
+        trend = "stable"
+        percent_change = 0
+    
+    return ProgressReport(
+        player_id=player_id,
+        metric_type=metric_type,
+        period_start=period_start,
+        period_end=period_end,
+        data_points=data_points,
+        trend=trend,
+        percent_change=percent_change,
+    )

app/api/auth.py

@@ -0,0 +1,382 @@
+"""
+Authentication API endpoints.
+"""
+from datetime import datetime, timedelta
+import os
+from uuid import uuid4
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from app.config import get_settings
+from app.core.security import (
+    create_access_token,
+    create_refresh_token,
+    get_password_hash,
+    verify_password,
+    decode_access_token,
+)
+from app.dependencies import get_current_user, get_supabase
+from app.models.user import (
+    UserCreate,
+    UserLogin,
+    UserUpdate,
+    User,
+    TokenResponse,
+    RefreshTokenRequest,
+    AccountType,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+
+def _get_limiter(request: Request) -> Limiter:
+    # Helper to get the global limiter attached in app.main
+    return request.app.state.limiter
+
+
+@router.post(
+    "/register",
+    response_model=TokenResponse,
+    status_code=status.HTTP_201_CREATED,
+)
+async def register(
+    user_data: UserCreate,
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Register a new user account.
+    
+    - **email**: Valid email address
+    - **password**: Minimum 8 characters
+    - **account_type**: 'team' or 'personal'
+    """
+    settings = get_settings()
+    
+    # Check if user already exists
+    existing = await supabase.select("users", filters={"email": user_data.email})
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Email already registered"
+        )
+    
+    # Create user
+    user_id = str(uuid4())
+    hashed_password = get_password_hash(user_data.password)
+    
+    user_record = {
+        "id": user_id,
+        "email": user_data.email,
+        "hashed_password": hashed_password,
+        "account_type": user_data.account_type.value,
+        "full_name": user_data.full_name,
+    }
+    
+    await supabase.insert("users", user_record)
+    
+    # If team account, check for org or create one?
+    # Schema says organizations(owner_id).
+    org_id = None
+    if user_data.account_type == AccountType.TEAM:
+        org_id = str(uuid4())
+        await supabase.insert("organizations", {
+            "id": org_id,
+            "name": f"{user_data.full_name or user_id}'s Team",
+            "owner_id": user_id
+        })
+        # Link org back to user record
+        await supabase.update("users", user_id, {"organization_id": org_id})
+
+    # Create tokens
+    token_data = {
+        "sub": user_id,
+        "email": user_data.email,
+        "account_type": user_data.account_type.value,
+        "organization_id": org_id
+    }
+    
+    access_token = create_access_token(token_data)
+    refresh_token = create_refresh_token(user_id)
+    
+    user = User(
+        id=user_id,
+        email=user_data.email,
+        account_type=user_data.account_type,
+        full_name=user_data.full_name,
+        organization_id=org_id,
+        created_at=datetime.now()
+    )
+    
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token,
+        expires_in=settings.jwt_expiration_minutes * 60,
+        user=user
+    )
+
+
+@router.post("/login", response_model=TokenResponse)
+async def login(
+    request: Request,
+    credentials: UserLogin,
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Authenticate and get access tokens.
+    """
+    settings = get_settings()
+
+    # Apply a stricter rate limit on login to protect against brute force.
+    limiter = _get_limiter(request)
+    # The decorated function must accept a 'request' argument for slowapi inspection
+    limiter.limit("60/minute")(lambda request: None)(request)
+    
+    # Find user
+    users = await supabase.select("users", filters={"email": credentials.email})
+    if not users:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials"
+        )
+    
+    user = users[0]
+    
+    # Verify password
+    if not verify_password(credentials.password, user.get("hashed_password", "")):
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid credentials"
+        )
+    
+    # Fetch organization_id if applicable
+    org_id = user.get("organization_id")
+    if not org_id and user["account_type"] == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+    elif not org_id and user["account_type"] == AccountType.COACH.value:
+        # For coaches, we expect organization_id to be set in users table already via linking
+        pass
+            
+    # Create tokens
+    token_data = {
+        "sub": user["id"],
+        "email": user["email"],
+        "account_type": user["account_type"],
+        "organization_id": org_id
+    }
+    
+    access_token = create_access_token(token_data)
+    refresh_token = create_refresh_token(user["id"])
+    
+    return TokenResponse(
+        access_token=access_token,
+        refresh_token=refresh_token,
+        expires_in=settings.jwt_expiration_minutes * 60,
+        user=User(
+            id=user["id"],
+            email=user["email"],
+            account_type=AccountType(user["account_type"]),
+            full_name=user.get("full_name"),
+            organization_id=org_id,
+            created_at=user.get("created_at") or datetime.now()
+        )
+    )
+
+
+@router.post("/refresh", response_model=TokenResponse)
+async def refresh_token(
+    body: RefreshTokenRequest,
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Refresh access token using a valid refresh token.
+    """
+    settings = get_settings()
+    
+    payload = decode_access_token(body.refresh_token)
+    if not payload or payload.get("type") != "refresh":
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid refresh token"
+        )
+    
+    user_id = payload.get("sub")
+    user = await supabase.select_one("users", user_id)
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="User not found"
+        )
+    
+    token_data = {
+        "sub": user["id"],
+        "email": user["email"],
+        "account_type": user["account_type"],
+    }
+    
+    new_access_token = create_access_token(token_data)
+    new_refresh_token = create_refresh_token(user["id"])
+    
+    return TokenResponse(
+        access_token=new_access_token,
+        refresh_token=new_refresh_token,
+        expires_in=settings.jwt_expiration_minutes * 60,
+    )
+
+
+@router.post("/refresh-token", response_model=TokenResponse)
+async def refresh_token_alias(
+    body: RefreshTokenRequest,
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Alias for /refresh to support frontend expectations.
+    """
+    return await refresh_token(body, supabase)
+
+
+@router.get("/me", response_model=User)
+async def get_current_user_profile(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get the currently authenticated user's profile.
+    """
+    user = await supabase.select_one("users", current_user["id"])
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="User not found"
+        )
+
+    # Fetch org info
+    org_id = user.get("organization_id")
+    if not org_id and user["account_type"] == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": user["id"]})
+        if orgs:
+            org_id = orgs[0]["id"]
+    elif not org_id and user["account_type"] == AccountType.COACH.value:
+        pass
+            
+    return User(
+        id=user["id"],
+        email=user["email"],
+        account_type=AccountType(user["account_type"]),
+        full_name=user.get("full_name"),
+        avatar_url=user.get("avatar_url"),
+        organization_id=org_id,
+        created_at=user.get("created_at"),
+        updated_at=user.get("updated_at"),
+    )
+
+
+@router.put("/me", response_model=User)
+async def update_current_user_profile(
+    update_data: UserUpdate,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update the currently authenticated user's profile.
+    """
+    update_dict = update_data.model_dump(exclude_unset=True)
+    
+    if not update_dict:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No fields to update"
+        )
+    
+    updated = await supabase.update("users", current_user["id"], update_dict)
+    
+    return User(
+        id=updated["id"],
+        email=updated["email"],
+        account_type=AccountType(updated["account_type"]),
+        full_name=updated.get("full_name"),
+        avatar_url=updated.get("avatar_url"),
+        created_at=updated.get("created_at"),
+        updated_at=updated.get("updated_at"),
+    )
+
+
+@router.post("/logout")
+async def logout():
+    """
+    Log out the current user.
+    Since we use stateless JWT, this is primarily for client-side cleanup.
+    """
+    return {"message": "Successfully logged out"}
+
+
+@router.delete("/account", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_current_user_account(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Permanently delete the current user's account and all associated data.
+    """
+    user_id = current_user["id"]
+    
+    # 1. Cleanup Videos and physical files
+    # Get all videos uploaded by this user
+    videos = await supabase.select("videos", filters={"uploader_id": user_id})
+    
+    for video in videos:
+        video_id = str(video.get("id"))
+        storage_path = video.get("storage_path")
+        
+        # Delete physical file
+        if storage_path and os.path.exists(storage_path):
+            try:
+                os.remove(storage_path)
+            except Exception as e:
+                print(f"Error removing file {storage_path}: {e}")
+                
+        # Also check for annotated video
+        annotated_path = os.path.join(
+            os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))),
+            "output_videos", "annotated", f"{video_id}.mp4"
+        )
+        if os.path.exists(annotated_path):
+            try:
+                os.remove(annotated_path)
+            except Exception:
+                pass
+
+        # Cleanup related DB records (best effort)
+        for table in ["analysis_results", "detections", "analytics", "clips"]:
+            try:
+                await supabase.delete_where(table, {"video_id": video_id})
+            except Exception:
+                pass
+                
+        # Delete video record
+        await supabase.delete("videos", video_id)
+
+    # 2. Cleanup Organization if Owner
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": user_id})
+        for org in orgs:
+            org_id = str(org.get("id"))
+            # Unlink staff/players or delete them? 
+            # For now, let's just delete the organization. 
+            await supabase.delete("organizations", org_id)
+
+    # 3. Delete Profile (from users table)
+    await supabase.delete("users", user_id)
+    
+    # 4. Delete from Supabase Auth
+    success = await supabase.delete_user_auth(user_id)
+    if not success:
+        print(f"CRITICAL: Failed to delete user {user_id} from Supabase Auth")
+
+    return None

app/api/communications.py

@@ -0,0 +1,147 @@
+from uuid import uuid4
+from datetime import datetime
+from typing import List
+from fastapi import APIRouter, Depends, HTTPException, status
+
+from app.dependencies import (
+    get_supabase, 
+    get_current_user,
+    require_team_account,
+    require_staff_member,
+    require_linked_account
+)
+from app.services.supabase_client import SupabaseService
+from app.models.communication import Announcement, AnnouncementCreate, AnnouncementListResponse
+
+router = APIRouter()
+
+@router.get("/announcements", response_model=AnnouncementListResponse)
+async def get_announcements(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get all announcements for the user's organization.
+    Accessible by Team Owners, Coaches, and Linked Players.
+    """
+    org_id = current_user.get("organization_id")
+    user_id = current_user["id"]
+    account_type = current_user.get("account_type", "")
+
+    # --- Resolve org_id if not in token ---
+    if not org_id:
+        if account_type == "team":
+            # Team owner: look up via organizations table
+            orgs = await supabase.select("organizations", filters={"owner_id": user_id})
+            if orgs:
+                org_id = orgs[0]["id"]
+        else:
+            # Player/coach: check users table first
+            user_record = await supabase.select_one("users", user_id)
+            if user_record and user_record.get("organization_id"):
+                org_id = user_record["organization_id"]
+            else:
+                # Personal players linked to a team via players table
+                player_rows = await supabase.select("players", filters={"user_id": user_id})
+                linked = [p for p in player_rows if p.get("organization_id")]
+                if linked:
+                    org_id = linked[0]["organization_id"]
+
+    if not org_id:
+        return AnnouncementListResponse(announcements=[], total=0)
+
+    announcements_data = await supabase.select(
+        "announcements",
+        filters={"organization_id": str(org_id)},
+        order_by="created_at",
+        ascending=False
+    )
+
+    announcements = []
+    for item in announcements_data:
+        announcement = Announcement(**item)
+        try:
+            author = await supabase.select_one("users", str(item["author_id"]))
+            if author:
+                announcement.author_name = author.get("full_name") or author.get("email")
+        except Exception:
+            pass
+        announcements.append(announcement)
+
+    return AnnouncementListResponse(announcements=announcements, total=len(announcements))
+
+@router.post("/announcements", response_model=Announcement, status_code=status.HTTP_201_CREATED)
+async def create_announcement(
+    data: AnnouncementCreate,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Create a new announcement for the organization.
+    Restricted to Coaching Staff and Team Owners.
+    """
+    org_id = current_user.get("organization_id")
+
+    # Team owners may not have org_id in token — resolve from DB
+    if not org_id:
+        if current_user.get("account_type") == "team":
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs:
+                org_id = orgs[0]["id"]
+
+    if not org_id:
+        raise HTTPException(status_code=403, detail="You must be linked to an organization to post announcements")
+
+    announcement_id = str(uuid4())
+    record = {
+        "id": announcement_id,
+        "organization_id": str(org_id),
+        "author_id": current_user["id"],
+        "title": data.title,
+        "content": data.content,
+        "created_at": datetime.now().isoformat(),
+        "updated_at": datetime.now().isoformat()
+    }
+
+    saved = await supabase.insert("announcements", record)
+
+    # Notify all players in the org roster
+    try:
+        players = await supabase.select("players", filters={"organization_id": str(org_id)})
+        for player in players:
+            if player.get("user_id"):
+                await supabase.insert("notifications", {
+                    "id": str(uuid4()),
+                    "recipient_id": player["user_id"],
+                    "title": f"New Announcement: {data.title}",
+                    "message": f"{current_user.get('email')} posted a new announcement.",
+                    "type": "announcement",
+                    "read": False,
+                    "created_at": datetime.now().isoformat()
+                })
+    except Exception as e:
+        print(f"Warning: Failed to send announcement notifications: {e}")
+
+    return Announcement(**saved)
+
+@router.delete("/announcements/{announcement_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_announcement(
+    announcement_id: str,
+    current_user: dict = Depends(require_staff_member),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Delete an announcement.
+    Restricted to Coaches.
+    """
+    org_id = current_user.get("organization_id")
+    announcement = await supabase.select_one("announcements", announcement_id)
+    
+    if not announcement:
+        raise HTTPException(status_code=404, detail="Announcement not found")
+    
+    if str(announcement["organization_id"]) != str(org_id):
+        raise HTTPException(status_code=403, detail="Access denied")
+        
+    await supabase.delete("announcements", announcement_id)
+    return None

app/api/personal_analysis.py

@@ -0,0 +1,343 @@
+"""
+Personal Analysis API endpoints.
+
+Handles video upload + triggering the swiss basketball shot analysis pipeline
+for individual (personal account) players.
+
+Does NOT touch or interfere with the team analysis pipeline.
+"""
+import os
+import uuid
+import logging
+from typing import Optional
+from datetime import datetime
+from fastapi import APIRouter, Depends, HTTPException, status, UploadFile, File, BackgroundTasks
+from fastapi.responses import JSONResponse
+
+from app.dependencies import require_personal_account, get_supabase
+from app.services.supabase_client import SupabaseService
+from app.models.video import VideoStatus, AnalysisMode
+
+logger = logging.getLogger("personal_analysis_api")
+
+router = APIRouter()
+
+# Where processed output videos are stored and served
+_BASE_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+PERSONAL_OUTPUT_DIR = os.path.join(_BASE_DIR, "uploads", "personal_output")
+os.makedirs(PERSONAL_OUTPUT_DIR, exist_ok=True)
+
+# In-memory job status store (simple; survives server restart via DB)
+_job_cache: dict = {}
+
+
+async def _save_job_to_db(supabase: SupabaseService, job: dict):
+    """Persist the job record to Supabase. Best-effort only."""
+    try:
+        existing = await supabase.select("personal_analyses", filters={"job_id": job["job_id"]})
+        if existing:
+            await supabase.update("personal_analyses", existing[0]["id"], job)
+        else:
+            await supabase.insert("personal_analyses", {**job, "id": str(uuid.uuid4())})
+    except Exception as e:
+        logger.warning(f"Could not save job to DB: {e}")
+
+
+async def _run_and_update(job_id: str, video_path: str, user_id: str, supabase: SupabaseService, shooting_arm: str = "right"):
+    """Background task that runs the pipeline and updates the DB."""
+    from personal_analysis.pipeline import run_personal_analysis
+
+    BUCKET = "personal-analysis-videos"
+
+    _job_cache[job_id] = {"job_id": job_id, "status": "processing", "user_id": user_id}
+
+    result = await run_personal_analysis(
+        video_path=video_path,
+        output_dir=PERSONAL_OUTPUT_DIR,
+        job_id=job_id,
+        shooting_arm=shooting_arm,
+    )
+
+    # ── Upload annotated video to Supabase Storage ────────────────────────────
+    if result.get("status") == "completed":
+        local_output = os.path.join(PERSONAL_OUTPUT_DIR, f"{job_id}_output.mp4")
+        if os.path.exists(local_output):
+            try:
+                storage_path = f"{user_id}/{job_id}_output.mp4"
+                await supabase.upload_file_from_path(
+                    bucket=BUCKET,
+                    storage_path=storage_path,
+                    local_path=local_output,
+                    content_type="video/mp4",
+                )
+                signed_url = await supabase.get_long_lived_url(
+                    bucket=BUCKET,
+                    storage_path=storage_path,
+                    expires_in=60 * 60 * 24 * 7,  # 7 days
+                )
+                if signed_url:
+                    result["annotated_video_url"] = signed_url
+                    logger.info(f"[{job_id}] Uploaded to Supabase Storage → {storage_path}")
+                    # Clean up local file after successful upload
+                    try:
+                        os.remove(local_output)
+                        # Remove tmp file if it still exists
+                        tmp = local_output.replace("_output.mp4", "_output_tmp.mp4")
+                        if os.path.exists(tmp):
+                            os.remove(tmp)
+                    except Exception:
+                        pass
+            except Exception as upload_err:
+                # Upload failed — fall back to local URL so results still work
+                logger.warning(f"[{job_id}] Supabase upload failed, using local URL: {upload_err}")
+                result["annotated_video_url"] = f"/personal-output/{job_id}_output.mp4"
+
+    _job_cache[job_id] = {**result, "user_id": user_id}
+
+    # Persist to DB (personal_analyses table)
+    await _save_job_to_db(supabase, {
+        "job_id": job_id,
+        "user_id": user_id,
+        "status": result.get("status", "completed"),
+        "results_json": result,
+        "created_at": datetime.utcnow().isoformat(),
+    })
+
+    # ── Push to global analytics table ────────────────────────────────────────
+    if result.get("status") == "completed":
+        try:
+            # Get player_id (personal users have 1 player record)
+            p_rows = await supabase.select("players", filters={"user_id": user_id})
+            if p_rows:
+                player_id = p_rows[0]["id"]
+                ts = datetime.utcnow().isoformat()
+                
+                metrics_to_save = [
+                    ("shot_attempt", result.get("shots_total", 0)),
+                    ("shot_made", result.get("shots_made", 0)),
+                    ("distance_km", float(result.get("total_distance_meters", 0) or 0) / 1000.0),
+                    ("avg_speed_kmh", result.get("avg_speed_kmh", 0)),
+                    ("max_speed_kmh", result.get("max_speed_kmh", 0)),
+                    ("dribble_count", result.get("dribble_count", 0)),
+                    ("form_consistency", 100 if result.get("overall_verdict") == "GOOD FORM" else 60),
+                ]
+                
+                for m_type, val in metrics_to_save:
+                    if val is not None:
+                        await supabase.insert("analytics", {
+                            "id": str(uuid.uuid4()),
+                            "player_id": player_id,
+                            "metric_type": m_type,
+                            "value": float(val),
+                            "timestamp": ts,
+                            "video_id": job_id
+                        })
+        except Exception as ae:
+            logger.warning(f"Could not push to analytics table: {ae}")
+
+    # Update global videos table status
+    try:
+        final_video_status = VideoStatus.COMPLETED.value if result.get("status") == "completed" else VideoStatus.FAILED.value
+        
+        update_payload = {
+            "status": final_video_status,
+            "progress_percent": 100 if final_video_status == VideoStatus.COMPLETED.value else 0,
+            "has_annotated": final_video_status == VideoStatus.COMPLETED.value,
+        }
+        
+        if result.get("annotated_video_url"):
+            update_payload["annotated_url"] = result.get("annotated_video_url")
+            
+        await supabase.update("videos", job_id, update_payload)
+    except Exception as e:
+        logger.warning(f"Could not update videos table status: {e}")
+
+    # Clean up the raw upload to save disk space
+    try:
+        if os.path.exists(video_path):
+            os.remove(video_path)
+    except Exception:
+        pass
+
+
+@router.post("/analysis/trigger")
+async def trigger_analysis(
+    background_tasks: BackgroundTasks,
+    video: UploadFile = File(...),
+    shooting_arm: str = "right",
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Upload a personal training video and start shot analysis.
+    Returns a job_id immediately — poll /analysis/{job_id} for results.
+    """
+    # Validate file type
+    allowed_ext = {".mp4", ".avi", ".mov", ".mkv"}
+    _, ext = os.path.splitext(video.filename or "video.mp4")
+    if ext.lower() not in allowed_ext:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Unsupported video format '{ext}'. Allowed: {', '.join(allowed_ext)}"
+        )
+
+    # Save to temporary upload path
+    job_id = str(uuid.uuid4())
+    upload_path = os.path.join(PERSONAL_OUTPUT_DIR, f"{job_id}_input{ext}")
+
+    content = await video.read()
+    if len(content) > 500 * 1024 * 1024:  # 500 MB limit
+        raise HTTPException(status_code=413, detail="Video file too large (max 500 MB)")
+
+    with open(upload_path, "wb") as f:
+        f.write(content)
+
+    # 1. Register in the global videos table so it shows up in general lists
+    try:
+        # Get basic video info for the record
+        # In a real app we'd use cv2 here, but for personal portal we can use defaults
+        video_record = {
+            "id": job_id,
+            "uploader_id": current_user["id"],
+            "title": video.filename or f"Analysis {datetime.utcnow().strftime('%Y-%m-%d %H:%M')}",
+            "description": f"Personal shot analysis (hand: {shooting_arm})",
+            "analysis_mode": AnalysisMode.PERSONAL.value,
+            "status": VideoStatus.PROCESSING.value,
+            "storage_path": upload_path,
+            "file_size_bytes": len(content),
+            "created_at": datetime.utcnow().isoformat(),
+        }
+        await supabase.insert("videos", video_record)
+    except Exception as e:
+        logger.warning(f"Could not insert into videos table: {e}")
+
+    user_id = current_user["id"]
+    _job_cache[job_id] = {"job_id": job_id, "status": "processing", "user_id": user_id}
+
+    # Fire and forget — analysis runs in background
+    background_tasks.add_task(
+        _run_and_update, job_id, upload_path, user_id, supabase, shooting_arm
+    )
+
+    return {
+        "job_id": job_id,
+        "status": "processing",
+        "message": "Analysis started. Poll /player/analysis/${job_id} for results.",
+    }
+
+
+@router.get("/analysis/{job_id}")
+async def get_analysis_result(
+    job_id: str,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Poll the status / results of a personal analysis job.
+    Returns 'processing' until done, then the full results.
+    """
+    # Check in-memory cache first
+    if job_id in _job_cache:
+        job = _job_cache[job_id]
+        if job.get("user_id") != current_user["id"]:
+            raise HTTPException(status_code=403, detail="Access denied")
+        return job
+
+    # Fall back to DB
+    try:
+        rows = await supabase.select("personal_analyses", filters={"job_id": job_id})
+        if rows:
+            record = rows[0]
+            if record.get("user_id") != current_user["id"]:
+                raise HTTPException(status_code=403, detail="Access denied")
+
+            # results_json holds the full pipeline output dict.
+            # Merge it with the top-level DB record so callers always see
+            # shots_total, made_percentage, annotated_video_url etc. at the
+            # root level (not buried inside a nested "results_json" key).
+            results_json = record.get("results_json") or {}
+            if isinstance(results_json, str):
+                import json as _json
+                try:
+                    results_json = _json.loads(results_json)
+                except Exception:
+                    results_json = {}
+
+            merged = {**record, **results_json}
+            return merged
+    except HTTPException:
+        raise
+    except Exception:
+        pass
+
+    raise HTTPException(status_code=404, detail="Analysis job not found")
+
+
+@router.get("/analysis")
+async def list_my_analyses(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    List all past personal analysis jobs for the current player.
+    """
+    try:
+        rows = await supabase.select(
+            "personal_analyses",
+            filters={"user_id": current_user["id"]},
+            order_by="created_at",
+            ascending=False
+        )
+        return rows or []
+    except Exception as e:
+        logger.warning(f"Could not fetch analyses: {e}")
+        return []
+
+
+@router.delete("/analysis/{job_id}", status_code=200)
+async def delete_analysis(
+    job_id: str,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Delete a personal analysis job and its output files.
+    """
+    # Verify ownership
+    try:
+        rows = await supabase.select("personal_analyses", filters={"job_id": job_id})
+    except Exception:
+        rows = []
+
+    if not rows:
+        raise HTTPException(status_code=404, detail="Analysis not found")
+
+    record = rows[0]
+    if record.get("user_id") != current_user["id"]:
+        raise HTTPException(status_code=403, detail="Access denied")
+
+    # Delete from DB
+    try:
+        await supabase.delete("personal_analyses", record["id"])
+    except Exception as e:
+        logger.warning(f"Could not delete personal_analyses record: {e}")
+
+    # Delete from videos table too
+    try:
+        await supabase.delete("videos", job_id)
+    except Exception:
+        pass
+
+    # Remove output files from disk
+    for suffix in ["_output.mp4", "_output.avi", "_report.txt"]:
+        fpath = os.path.join(PERSONAL_OUTPUT_DIR, f"{job_id}{suffix}")
+        try:
+            if os.path.exists(fpath):
+                os.remove(fpath)
+        except Exception:
+            pass
+
+    # Remove from in-memory cache
+    _job_cache.pop(job_id, None)
+
+    return {"message": "Analysis deleted successfully"}

app/api/player_routes.py

@@ -0,0 +1,679 @@
+"""
+Player Portal API endpoints (for Personal/Individual Player Users).
+"""
+import os
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional, List
+from fastapi import APIRouter, Depends, HTTPException, Query, status, UploadFile, File
+from fastapi.responses import JSONResponse
+
+from ..dependencies import require_personal_account, get_supabase, get_current_user
+from ..services.supabase_client import SupabaseService
+from ..models.player import Player, PlayerCreate, PlayerUpdate
+from ..models.schedule import Schedule
+from ..models.notification import Notification
+
+router = APIRouter()
+
+@router.get("/debug-portal")
+async def debug_portal():
+    return {"status": "portal-registered"}
+
+@router.get("/players")
+async def get_my_player(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get the current user's player profile.
+    """
+    players = await supabase.select("players", filters={"user_id": current_user["id"]})
+    if not players:
+        return [] # Or raise 404? Frontend expects list?
+    return players
+
+@router.get("/players/{player_id}")
+async def get_player_by_id(
+    player_id: str,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get generic player information.
+    Currently used in personal dashboard too.
+    """
+    player = await supabase.select_one("players", player_id)
+    if not player:
+        raise HTTPException(status_code=404, detail="Player not found")
+        
+    # Security check: must be the user's player
+    if player.get("user_id") != current_user["id"]:
+         raise HTTPException(status_code=403, detail="Access denied")
+         
+    return player
+
+@router.post("/players/{player_id}/activities")
+async def add_player_activity(
+    player_id: str,
+    activity_data: dict, # Using dict for flexibility or could use Pydantic model
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    player = await supabase.select_one("players", player_id)
+    if not player or player.get("user_id") != current_user["id"]:
+        raise HTTPException(status_code=403, detail="Access denied")
+        
+    activity_record = activity_data.copy()
+    activity_record["player_id"] = player_id
+    activity_record["id"] = str(uuid4())
+    if "date" not in activity_record:
+        activity_record["date"] = datetime.utcnow().isoformat()
+        
+    saved = await supabase.insert("activities", activity_record)
+    return saved
+
+@router.get("/players/{player_id}/activities")
+async def get_player_activities(
+    player_id: str,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    player = await supabase.select_one("players", player_id)
+    if not player or player.get("user_id") != current_user["id"]:
+        raise HTTPException(status_code=403, detail="Access denied")
+        
+    activities = await supabase.select("activities", filters={"player_id": player_id}, order_by="date", ascending=False)
+    return activities
+
+@router.get("/schedule")
+async def get_schedule(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get schedule for the player.
+    Includes personal events + team events if they belong to a team.
+    Always prefers the player record that has an organization_id.
+    """
+    players = await supabase.select("players", filters={"user_id": current_user["id"]})
+    if not players:
+        return []
+
+    # If multiple player records exist, prefer the one with an organization_id
+    linked = [p for p in players if p.get("organization_id")]
+    player = linked[0] if linked else players[0]
+
+    org_id = player.get("organization_id")
+
+    if org_id:
+        schedule = await supabase.select("schedules", filters={"organization_id": org_id})
+    else:
+        schedule = []
+
+    return schedule or []
+
+@router.get("/training")
+async def get_training_sessions(
+    date: Optional[str] = None,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get training sessions (videos) for a specific date or all.
+    """
+    filters = {"uploader_id": current_user["id"]}
+    # If date provided, filter by created_at range
+    
+    videos = await supabase.select("videos", filters=filters)
+    
+    if date:
+        try:
+            target_date = datetime.strptime(date, "%Y-%m-%d").date()
+            videos = [v for v in videos if datetime.fromisoformat(v["created_at"].replace("Z", "+00:00")).date() == target_date]
+        except ValueError:
+            pass # Ignore invalid date
+            
+    return videos
+
+
+@router.get("/training-videos")
+async def get_training_videos(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Alias for /training to satisfy frontend PlayerDashboard.
+    """
+    try:
+        videos = await supabase.select("videos", filters={"uploader_id": current_user["id"]})
+        return videos or []
+    except Exception as e:
+        print(f"Error fetching training videos: {e}")
+        return []
+
+
+@router.get("/training-history")
+async def get_training_history(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get training history for the player including activities and personal analyses.
+    """
+    try:
+        players = await supabase.select("players", filters={"user_id": current_user["id"]})
+        player_id = players[0]["id"] if players else None
+        
+        history = []
+        
+        # 1. Fetch manual activities
+        if player_id:
+            activities = await supabase.select("activities", filters={"player_id": player_id})
+            for act in activities:
+                history.append({
+                    "id": act.get("id"),
+                    "type": act.get("type", "training"),
+                    "title": act.get("title", "Practice Session"),
+                    "date": act.get("date"),
+                    "duration": act.get("duration"),
+                    "category": "Manual"
+                })
+        
+        # 2. Fetch personal analyses
+        analyses = await supabase.select("personal_analyses", filters={"user_id": current_user["id"]})
+        for row in analyses:
+            results = row.get("results_json") or {}
+            if isinstance(results, str):
+                try: import json; results = json.loads(results);
+                except: results = {}
+            
+            history.append({
+                "id": row.get("id"),
+                "type": "shooting",
+                "title": f"Shot Analysis: {results.get('shots_made', 0)}/{results.get('shots_total', 0)}",
+                "date": row.get("created_at"),
+                "duration": "15 min", # Estimated
+                "category": "AI Analysis",
+                "outcome": results.get("made_percentage")
+            })
+            
+        # Sort by date descending
+        history.sort(key=lambda x: x["date"] or "", reverse=True)
+        return history
+    except Exception as e:
+        print(f"Error fetching training history: {e}")
+        return []
+
+@router.post("/training")
+async def log_training(
+    training_data: dict, 
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Log a manual training session.
+    (Currently just a placeholder or could store in a separate table or events)
+    """
+    # For now, maybe just return success mock
+    return {"message": "Training logged", "id": str(uuid4())}
+
+@router.get("/notifications")
+async def get_notifications(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    notifs = await supabase.select("notifications", filters={"recipient_id": current_user["id"]}, order_by="created_at", ascending=False)
+    return notifs
+
+@router.put("/notifications/{notification_id}/read")
+async def mark_notification(
+    notification_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    await supabase.update("notifications", notification_id, {"read": True})
+    return {"message": "Marked as read"}
+
+@router.put("/notifications/read-all")
+async def mark_all_read(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    # This might need a custom query or loop
+    notifs = await supabase.select("notifications", filters={"recipient_id": current_user["id"], "read": False})
+    for n in notifs:
+         await supabase.update("notifications", n["id"], {"read": True})
+    return {"message": "All marked as read"}
+
+@router.delete("/notifications/{notification_id}")
+async def delete_notification(
+    notification_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    await supabase.delete("notifications", notification_id)
+    return {"message": "Deleted"}
+
+
+@router.get("/performance-metrics")
+async def get_performance_metrics(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get real performance metrics aggregated from personal analyses and activities.
+    """
+    try:
+        analyses = await supabase.select("personal_analyses", filters={"user_id": current_user["id"]})
+        activities = await supabase.select("activities", filters={"player_id": current_user["id"]}) # Assuming player_id is user_id in some contexts, adjust if needed
+        
+        # Pull basic player info to get session count if activities are stored elsewhere
+        players = await supabase.select("players", filters={"user_id": current_user["id"]})
+        player_id = players[0]["id"] if players else None
+        
+        if player_id:
+            activities = await supabase.select("activities", filters={"player_id": player_id})
+        
+        total_shots = 0
+        total_made = 0
+        total_form_score = 0
+        total_distance = 0.0
+        total_minutes = 0.0
+        completed_analyses = 0
+        
+        for row in analyses:
+            results = row.get("results_json") or {}
+            # Handle if nested string
+            if isinstance(results, str):
+                try: import json; results = json.loads(results)
+                except: results = {}
+            
+            if results.get("status") == "completed":
+                # Real stats from AI pipeline
+                total_shots += int(results.get("shots_total", 0) or 0)
+                total_made += int(results.get("shots_made", 0) or 0)
+                total_distance += float(results.get("total_distance_meters", 0) or 0) / 1000.0 # Convert to km
+                total_minutes += float(results.get("duration_seconds", 0) or 0) / 60.0
+                
+                # Simple form score: 100 for GOOD FORM, 60 for NEEDS WORK
+                reports = results.get("shot_reports", [])
+                if reports and isinstance(reports, list):
+                    score = sum(100 if r.get("verdict") == "GOOD FORM" else 60 for r in reports) / len(reports)
+                    total_form_score += score
+                    completed_analyses += 1
+
+        accuracy = float(total_made / total_shots * 100) if total_shots > 0 else 0.0
+        overall_rating = float(total_form_score / completed_analyses) if completed_analyses > 0 else 0.0
+        
+        # Merge manual activities for session counts
+        total_sessions = len(activities) + len(analyses)
+        
+        return {
+            "shootingAccuracy": round(accuracy, 1),
+            "overallRating": round(overall_rating, 1),
+            "weeklyStats": {
+                "sessionsCompleted": total_sessions,
+                "training_sessions": total_sessions,
+                "minutesTrained": round(total_minutes, 1),
+                "training_minutes": round(total_minutes, 1),
+                "distance": round(total_distance, 2),
+                "shotsAttempted": total_shots,
+                "shotsMade": total_made
+            }
+        }
+    except Exception as e:
+        import traceback
+        print(f"CRITICAL ERROR aggregating performance metrics: {e}")
+        print(traceback.format_exc())
+        return {
+            "shootingAccuracy": 0, "overallRating": 0,
+            "weeklyStats": {"sessionsCompleted": 0, "minutesTrained": 0, "shotsAttempted": 0, "shotsMade": 0}
+        }
+
+
+@router.get("/skill-trends")
+async def get_skill_trends(
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get actual skill improvement trends from historical analysis data.
+    """
+    try:
+        analyses = await supabase.select("personal_analyses", filters={"user_id": current_user["id"]})
+        
+        shooting_points = []
+        for row in sorted(analyses, key=lambda x: x["created_at"]):
+            results = row.get("results_json") or {}
+            if isinstance(results, str):
+                try: import json; results = json.loads(results);
+                except: results = {}
+            
+            if results.get("status") == "completed":
+                shooting_points.append(results.get("made_percentage", 0))
+                
+        # If we have too many points, sample or slice
+        recent_points: List[float] = []
+        for p in shooting_points[-12:]:
+            recent_points.append(p)
+        
+        # If we have no data, return empty or mock if requested (usually empty is better for "Real Data")
+        return {
+            "shooting": recent_points,
+            "dribbling": [],
+            "defense": [],
+            "fitness": []
+        }
+    except Exception as e:
+        print(f"Error fetching trends: {e}")
+        return {"shooting": [], "dribbling": [], "defense": [], "fitness": []}
+
+
+@router.get("/skills")
+async def get_skills_analytics(
+    startDate: Optional[str] = Query(None),
+    endDate: Optional[str] = Query(None),
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get detailed skill analytics based on real personal analysis reports.
+    """
+    try:
+        analyses = await supabase.select("personal_analyses", filters={"user_id": current_user["id"]})
+        
+        skills_data = []
+        shooting_scores = []
+        
+        # Use latest analyses to build the report
+        for row in analyses[-10:]: # Look at last 10
+            results = row.get("results_json") or {}
+            if isinstance(results, str):
+                try: import json; results = json.loads(results)
+                except: results = {}
+            
+            if results.get("status") == "completed":
+                accuracy = float(results.get("made_percentage", 0) or 0)
+                shooting_scores.append(accuracy)
+                
+                reports = results.get("shot_reports", [])
+                if isinstance(reports, list):
+                    for r in reports:
+                        if not isinstance(r, dict): continue
+                        metrics = r.get("metrics", {}) if isinstance(r.get("metrics"), dict) else {}
+                        
+                        mapped_shot_details = [{
+                            "outcome": "made" if r.get("verdict") == "GOOD FORM" else "missed",
+                            "faults": r.get("issues", []) if isinstance(r.get("issues"), list) else [],
+                            "feedback": "\n".join(r.get("issues", ["Form looking solid"])) if isinstance(r.get("issues"), list) else "Form looking solid",
+                            "biometrics": {
+                                "shoulder_angle": float(metrics.get("shoulder_angle", 0) or 0),
+                                "elbow_angle": float(metrics.get("elbow_angle", 0) or 0),
+                                "knee_angle": float(metrics.get("knee_angle", 0) or 0),
+                                "hip_angle": float(metrics.get("hip_angle", 0) or 0),
+                            }
+                        }]
+                        
+                        issues_list = r.get("issues", []) if isinstance(r.get("issues"), list) else []
+                        if not issues_list or r.get("verdict") == "GOOD FORM":
+                            dynamic_feedback = "Perfect execution on this shot! Mechanics look solid and fluid. Keep up the consistency."
+                        else:
+                            issues_str = " ".join(str(i) for i in issues_list)
+                            dynamic_feedback = f"Focus areas for this attempt: {issues_str} Maintaining proper alignment will improve your accuracy."
+
+                        skills_data.append({
+                            "id": f"shot-{row.get('id', '')}-{r.get('shot_number', 0)}",
+                            "name": f"Shot {r.get('shot_number', 0)}",
+                            "category": "Shooting",
+                            "score": 100 if r.get("verdict") == "GOOD FORM" else 60,
+                            "feedback": issues_list,
+                            "date": str(row.get("created_at", "")),
+                            "videoUrl": str(results.get("annotated_video_url", "")),
+                            "analysisData": {
+                                "feedback": str(results.get("overall_feedback", dynamic_feedback)),
+                                "shot_details": mapped_shot_details
+                            }
+                        })
+
+        avg_shooting = float(sum(shooting_scores) / len(shooting_scores)) if shooting_scores else 0.0
+        
+        # Calculate real volume metrics
+        total_dist_km = 0.0
+        total_dur_mins = 0.0
+        for row in analyses:
+            res = row.get("results_json") or {}
+            if isinstance(res, str):
+                try: import json; res = json.loads(res)
+                except: res = {}
+            if res.get("status") == "completed":
+                total_dist_km += float(res.get("total_distance_meters", 0) or 0) / 1000.0
+                total_dur_mins += float(res.get("duration_seconds", 0) or 0) / 60.0
+
+        return {
+            "skills": skills_data,
+            "summary": {
+                "overall": round(avg_shooting, 1),
+                "shooting": round(avg_shooting, 1),
+                "defense": 0.0,
+                "training_sessions": len(analyses),
+                "training_minutes": round(total_dur_mins, 1),
+                "distance": round(total_dist_km, 2)
+            }
+        }
+    except Exception as e:
+        import traceback
+        print(f"CRITICAL ERROR fetching real skills: {e}")
+        print(traceback.format_exc())
+        return {"skills": [], "summary": {"overall": 0, "shooting": 0, "defense": 0}}
+
+
+@router.delete("/skills/{skill_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_skill_analysis(
+    skill_id: str,
+    current_user: dict = Depends(require_personal_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Delete a personal analysis record.
+    The frontend ID format: shot-{db_id}-{shot_number}
+    """
+    # Extract the actual analysis ID
+    db_id = skill_id
+    if skill_id.startswith("shot-"):
+        parts = skill_id.split("-")
+        if len(parts) >= 2:
+            db_id = "-".join(parts[1:-1]) if len(parts) > 2 else parts[1]
+
+    analysis = await supabase.select_one("personal_analyses", db_id)
+    if not analysis:
+        raise HTTPException(status_code=404, detail="Analysis not found")
+        
+    if analysis.get("user_id") != current_user["id"]:
+        raise HTTPException(status_code=403, detail="Not authorized to delete this analysis")
+
+    # If you want to delete the file from Supabase as well:
+    results = analysis.get("results_json") or {}
+    if isinstance(results, str):
+        try: 
+            import json
+            results = json.loads(results)
+        except: 
+            results = {}
+            
+    # NOTE: Optional - delete from Supabase block
+    # annotated_url = results.get("annotated_video_url")
+    # if annotated_url and "personal-analysis-videos" in annotated_url:
+    #     try:
+    #         # Need a way to extract the path from the signed URL or derive it
+    #         # For safety, we just delete the DB record.
+    #     except Exception:
+    #         pass
+
+    await supabase.delete("personal_analyses", db_id)
+    return None
+
+@router.post("/profile/image")
+async def upload_profile_image(
+    image: UploadFile = File(...),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Upload a profile picture for the current user/player.
+    Saves the file locally and returns the public URL.
+    """
+    # Validate file type
+    valid_types = ["image/jpeg", "image/jpg", "image/png", "image/gif", "image/webp"]
+    if image.content_type not in valid_types:
+        raise HTTPException(status_code=400, detail="Only image files (JPG, PNG, GIF, WEBP) are allowed")
+    
+    # Read file content
+    content = await image.read()
+    if len(content) > 5 * 1024 * 1024:  # 5MB limit
+        raise HTTPException(status_code=400, detail="Image size must be less than 5MB")
+    
+    # Build a safe filename and storage path
+    ext = os.path.splitext(image.filename or "avatar.jpg")[1] or ".jpg"
+    safe_filename = f"{current_user['id']}_avatar{ext}"
+    avatars_dir = os.path.join("./uploads", "avatars")
+    os.makedirs(avatars_dir, exist_ok=True)
+    file_path = os.path.join(avatars_dir, safe_filename)
+    
+    # Write the file to disk
+    with open(file_path, "wb") as f:
+        f.write(content)
+    
+    # The public URL served by the backend static file server
+    image_url = f"/uploads/avatars/{safe_filename}"
+    
+    # Update user avatar_url
+    try:
+        await supabase.update("users", current_user["id"], {"avatar_url": image_url})
+    except Exception as e:
+        print(f"Warning: Failed to update user avatar_url: {e}")
+    
+    # If the user has a player profile, update that too
+    try:
+        players = await supabase.select("players", filters={"user_id": current_user["id"]})
+        for player in players:
+            await supabase.update("players", player["id"], {"avatar_url": image_url})
+    except Exception as e:
+        print(f"Warning: Failed to update player avatar_url: {e}")
+    
+    return {"imageUrl": image_url}
+
+
+@router.get("/profile")
+async def get_profile(
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get the current user's profile, merging user and player table data.
+    Auto-creates player record if missing.
+    """
+    try:
+        user = await supabase.select_one("users", current_user["id"])
+        if not user:
+            # Fallback to current_user info if no record in users table yet
+            user = {
+                "id": current_user["id"],
+                "email": current_user["email"],
+                "full_name": current_user.get("full_name", "Athlete")
+            }
+        
+        # Ensure full_name is present (might be fullName in some DB views)
+        if isinstance(user, dict) and "fullName" in user and "full_name" not in user:
+            user["full_name"] = user["fullName"]
+
+        players = await supabase.select("players", filters={"user_id": current_user["id"]})
+        player = players[0] if players else None
+        
+        if not player:
+            # Auto-create basic player record if missing
+            new_player = {
+                "user_id": current_user["id"],
+                "name": user.get("full_name") or user.get("fullName") or "New Athlete",
+                "email": user.get("email"),
+                "status": "active",
+                "created_at": datetime.utcnow().isoformat()
+            }
+            try:
+                player = await supabase.insert("players", new_player)
+            except Exception as pe:
+                print(f"Failed to auto-create player record: {pe}")
+        
+        return {"user": user, "player": player}
+    except Exception as e:
+        import traceback
+        print(f"Error in get_profile: {e}")
+        print(traceback.format_exc())
+        return {"user": None, "player": None}
+
+@router.put("/profile")
+async def update_profile(
+    profile_data: dict,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update the current user's profile (both users table and players table).
+    Accepts { user: {...}, player: {...} } structure.
+    """
+    import traceback
+    updated_user = None
+    updated_player = None
+    errors = []
+
+    if "user" in profile_data and profile_data["user"]:
+        # Strip read-only / primary-key fields before sending to Supabase
+        user_payload = {
+            k: v for k, v in profile_data["user"].items()
+            if k not in ("id", "created_at", "account_type")
+        }
+        user_payload["updated_at"] = datetime.utcnow().isoformat()
+        try:
+            updated_user = await supabase.update("users", current_user["id"], user_payload)
+            print(f"[profile] users updated OK for {current_user['id']}: {list(user_payload.keys())}")
+        except Exception as e:
+            err_msg = f"users update failed: {e}"
+            print(f"[profile] ERROR {err_msg}")
+            print(traceback.format_exc())
+            errors.append(err_msg)
+
+    if "player" in profile_data and profile_data["player"]:
+        player_payload = {
+            k: v for k, v in profile_data["player"].items()
+            if k not in ("id", "created_at", "user_id", "organization_id")
+        }
+        player_payload["updated_at"] = datetime.utcnow().isoformat()
+        try:
+            players = await supabase.select("players", filters={"user_id": current_user["id"]})
+            if players:
+                updated_player = await supabase.update("players", players[0]["id"], player_payload)
+                print(f"[profile] players updated OK for player {players[0]['id']}: {list(player_payload.keys())}")
+            else:
+                # Auto-create if missing
+                new_player = {
+                    "id": str(uuid4()),
+                    "user_id": current_user["id"],
+                    "status": "active",
+                    "created_at": datetime.utcnow().isoformat(),
+                    **player_payload
+                }
+                updated_player = await supabase.insert("players", new_player)
+                print(f"[profile] player auto-created for user {current_user['id']}")
+        except Exception as e:
+            err_msg = f"players update failed: {e}"
+            print(f"[profile] ERROR {err_msg}")
+            print(traceback.format_exc())
+            errors.append(err_msg)
+
+    if errors:
+        return JSONResponse(
+            status_code=207,
+            content={"message": "Partial update", "errors": errors}
+        )
+
+    return {"message": "Profile updated successfully"}

app/api/players.py

@@ -0,0 +1,279 @@
+"""
+Player management API endpoints.
+"""
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.dependencies import get_current_user, get_supabase
+from app.models.user import AccountType
+from app.models.player import (
+    PlayerCreate,
+    PlayerUpdate,
+    Player,
+    PlayerWithStats,
+    PlayerListResponse,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+
+@router.post("", response_model=Player, status_code=status.HTTP_201_CREATED)
+async def create_player(
+    player_data: PlayerCreate,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Create a new player profile.
+    
+    - **TEAM accounts**: Must provide organization_id
+    - **PERSONAL accounts**: Player is linked to user account
+    """
+    player_id = str(uuid4())
+    
+    player_record = {
+        "id": player_id,
+        "name": player_data.name,
+        "jersey_number": player_data.jersey_number,
+        "position": player_data.position,
+        "height_cm": player_data.height_cm,
+        "weight_kg": player_data.weight_kg,
+        "date_of_birth": str(player_data.date_of_birth) if player_data.date_of_birth else None,
+    }
+    
+    # Handle based on account type
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if not player_data.organization_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="organization_id is required for TEAM accounts"
+            )
+        
+        # Verify org ownership
+        org = await supabase.select_one("organizations", str(player_data.organization_id))
+        if not org or org["owner_id"] != current_user["id"]:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You don't have access to this organization"
+            )
+        
+        player_record["organization_id"] = str(player_data.organization_id)
+    else:
+        # PERSONAL account - link to user
+        player_record["user_id"] = current_user["id"]
+    
+    await supabase.insert("players", player_record)
+    
+    return Player(**player_record, created_at=datetime.utcnow())
+
+
+@router.get("", response_model=PlayerListResponse)
+async def list_players(
+    organization_id: Optional[str] = Query(None),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    List players.
+    
+    - **TEAM accounts**: Filter by organization_id
+    - **PERSONAL accounts**: Returns the user's player profile
+    """
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if not organization_id:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="organization_id query parameter is required for TEAM accounts"
+            )
+        
+        # Verify org ownership
+        org = await supabase.select_one("organizations", organization_id)
+        if not org or org["owner_id"] != current_user["id"]:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You don't have access to this organization"
+            )
+        
+        players = await supabase.select(
+            "players",
+            filters={"organization_id": organization_id},
+            order_by="name",
+        )
+    else:
+        # PERSONAL account
+        players = await supabase.select(
+            "players",
+            filters={"user_id": current_user["id"]},
+        )
+    
+    return PlayerListResponse(
+        players=[Player(**p) for p in players],
+        total=len(players),
+    )
+
+
+@router.get("/{player_id}", response_model=PlayerWithStats)
+async def get_player(
+    player_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get player details with statistics.
+    """
+    player = await supabase.select_one("players", player_id)
+    
+    if not player:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Player not found"
+        )
+    
+    # Verify access
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if player.get("organization_id"):
+            org = await supabase.select_one("organizations", str(player["organization_id"]))
+            has_access = org and str(org.get("owner_id")) == str(current_user["id"])
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        player_org = player.get("organization_id")
+        coach_org = current_user.get("organization_id")
+        has_access = player_org and coach_org and str(player_org) == str(coach_org)
+    else:
+        has_access = player.get("user_id") == current_user["id"]
+    
+    if not has_access:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this player"
+        )
+    
+    # Data Fallback: If this is an organization-linked record, try to fill missing fields from personal profile
+    if player.get("organization_id") and player.get("user_id"):
+        try:
+            # Get all profiles for this user
+            all_user_profiles = await supabase.select("players", filters={"user_id": str(player["user_id"])})
+            # Find the personal one (no organization_id)
+            personal = next((p for p in all_user_profiles if not p.get("organization_id")), None)
+            
+            if personal:
+                # Fields to potentially fallback to
+                fallback_fields = [
+                    "jersey_number", "position", "height_cm", "weight_kg", 
+                    "date_of_birth", "avatar_url", "phone", "address", 
+                    "experience_years", "bio", "status"
+                ]
+                for field in fallback_fields:
+                    # Use personal data if team-specific data is missing or empty
+                    val = player.get(field)
+                    pers_val = personal.get(field)
+                    if (val is None or val == "") and (pers_val is not None and pers_val != ""):
+                        player[field] = pers_val
+        except Exception as e:
+            print(f"Warning: Failed to fetch personal profile fallback for player {player_id}: {e}")
+            
+    # Ensure ppg exists and is a float
+    p_ppg = player.get("ppg")
+    player["ppg"] = float(p_ppg) if p_ppg is not None and p_ppg != "" else 0.0
+    
+    # Coerce string fields that might have been stored as numbers in the DB
+    if player.get("experience_years") is not None:
+        player["experience_years"] = str(player["experience_years"])
+    
+    # Fetch email if linked to a user
+    email = None
+    if player.get("user_id"):
+        user = await supabase.select_one("users", str(player["user_id"]))
+        if user:
+            email = user.get("email")
+    
+    # Get stats from analytics (video-based tracked metrics)
+    analytics_data = await supabase.select("analytics", filters={"player_id": player_id})
+    
+    video_dist = sum(a.get("value", 0) for a in analytics_data if a.get("metric_type") == "distance_km")
+    speed_values = [a.get("value", 0) for a in analytics_data if a.get("metric_type") == "avg_speed_kmh"]
+    avg_speed = sum(speed_values) / len(speed_values) if speed_values else None
+    
+    # Calculate unique videos from tracking
+    tracking_video_ids = set(a.get("video_id") for a in analytics_data if a.get("video_id"))
+    
+    # NEW: Fetch official match stats (linked from box score uploads)
+    match_stats = await supabase.select("match_player_stats", filters={"player_profile_id": player_id})
+    
+    total_pts = sum(s.get("pts", 0) for s in match_stats)
+    total_matches = len(match_stats)
+    
+    # Calculate PPG based on official match stats if available, otherwise fallback to existing
+    if total_matches > 0:
+        player["ppg"] = round(total_pts / total_matches, 1)
+        # We can also add more aggregated stats to the model if needed in the future
+    
+    # Combine unique videos from both sources
+    match_video_ids = set(s.get("match_id") for s in match_stats if s.get("match_id"))
+    total_unique_videos = len(tracking_video_ids.union(match_video_ids))
+
+    # Build the final response dict
+    player["email"] = email
+    player["total_videos"] = total_unique_videos
+    player["total_training_minutes"] = total_unique_videos * 40.0 # Estimate 40m per game/video
+    player["total_distance_km"] = video_dist if video_dist > 0 else None
+    player["avg_speed_kmh"] = avg_speed
+    
+    return PlayerWithStats(**player)
+
+
+@router.put("/{player_id}", response_model=Player)
+async def update_player(
+    player_id: str,
+    update_data: PlayerUpdate,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update player profile.
+    """
+    player = await supabase.select_one("players", player_id)
+    
+    if not player:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Player not found"
+        )
+    
+    # Verify access
+    has_access = False
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        if player.get("organization_id"):
+            org = await supabase.select_one("organizations", player["organization_id"])
+            has_access = org and org["owner_id"] == current_user["id"]
+    elif current_user.get("account_type") == AccountType.COACH.value:
+        player_org = player.get("organization_id")
+        coach_org = current_user.get("organization_id")
+        has_access = player_org and coach_org and str(player_org) == str(coach_org)
+    else:
+        has_access = player.get("user_id") == current_user["id"]
+    
+    if not has_access:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have permission to update this player"
+        )
+    
+    update_dict = update_data.model_dump(exclude_unset=True)
+    
+    if "date_of_birth" in update_dict and update_dict["date_of_birth"]:
+        update_dict["date_of_birth"] = str(update_dict["date_of_birth"])
+    
+    if not update_dict:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No fields to update"
+        )
+    
+    updated = await supabase.update("players", player_id, update_dict)
+    
+    return Player(**updated)

app/api/stat_import.py

@@ -0,0 +1,77 @@
+from fastapi import APIRouter, Form, UploadFile, File, Depends, HTTPException
+from typing import Optional
+from uuid import UUID
+from datetime import date
+
+from app.dependencies import require_linked_account
+from app.stat_import.schemas import StatImportJobResponse, ImportReviewSchema, FinalizeImportRequest
+
+router = APIRouter()
+
+@router.post("/upload", response_model=StatImportJobResponse, summary="Upload a stat sheet (PDF/Image)")
+async def upload_stat_sheet(
+    team_id: UUID = Form(...),
+    game_date: Optional[date] = Form(None),
+    opponent_name: Optional[str] = Form(None),
+    notes: Optional[str] = Form(None),
+    file: UploadFile = File(...),
+    account_info: dict = Depends(require_linked_account)
+):
+    """
+    Coach uploads a PDF/image stat sheet. 
+    System stores it in Supabase Storage and creates an import job.
+    """
+    # TODO: Validate user is in team `team_id`
+    # TODO: Push to supabase storage
+    # TODO: Insert to `stat_import_jobs` table
+    raise HTTPException(status_code=501, detail="Not Implemented")
+
+
+@router.post("/process/{import_job_id}", summary="Process an uploaded stat sheet")
+async def process_stat_sheet(import_job_id: UUID, account_info: dict = Depends(require_linked_account)):
+    """
+    Trigger the asynchronous or synchronous OCR parsing pipeline for this upload.
+    Classification -> Extraction -> Parsing -> Matching -> Validation.
+    """
+    # TODO: Service layer to run the layout parser / paddleOCR logic
+    raise HTTPException(status_code=501, detail="Not Implemented")
+
+
+@router.get("/{import_job_id}", summary="Get import job details")
+async def get_import_job(import_job_id: UUID, account_info: dict = Depends(require_linked_account)):
+    """
+    Fetches the result of the pipeline: parsed data, status, etc.
+    """
+    raise HTTPException(status_code=501, detail="Not Implemented")
+
+
+@router.post("/{import_job_id}/confirm", summary="Acknowledge overrides on review flow")
+async def confirm_review_edits(import_job_id: UUID, account_info: dict = Depends(require_linked_account)):
+    """
+    Called periodically or as checkpoints when resolving unmatched players manually.
+    """
+    raise HTTPException(status_code=501, detail="Not Implemented")
+
+
+@router.get("/{import_job_id}/issues", response_model=ImportReviewSchema, summary="Get extraction or validation issues")
+async def get_import_issues(import_job_id: UUID, account_info: dict = Depends(require_linked_account)):
+    """
+    Return all validation and matching errors flagged during processing.
+    """
+    raise HTTPException(status_code=501, detail="Not Implemented")
+
+
+@router.post("/{import_job_id}/finalize", summary="Commit the checked stat sheet to the database")
+async def finalize_stat_import(
+    import_job_id: UUID, 
+    payload: FinalizeImportRequest, 
+    account_info: dict = Depends(require_linked_account)
+):
+    """
+    Saves final JSON mapped data into games, game_player_stats, game_team_totals tables.
+    Also triggers analytics event generation.
+    """
+    # TODO: Check if ALL blockers are resolved
+    # TODO: Open transaction and dump to relational schema
+    # TODO: Mark import job as finalized
+    raise HTTPException(status_code=501, detail="Not Implemented")

app/api/teams.py

@@ -0,0 +1,211 @@
+"""
+Team management API endpoints (TEAM accounts only).
+"""
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.dependencies import require_team_account, get_supabase
+from app.models.team import (
+    OrganizationCreate,
+    OrganizationUpdate,
+    Organization,
+    OrganizationWithStats,
+    OrganizationListResponse,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+
+@router.post("", response_model=Organization, status_code=status.HTTP_201_CREATED)
+async def create_organization(
+    org_data: OrganizationCreate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Create a new organization (team).
+    
+    **Requires TEAM account.**
+    """
+    org_id = str(uuid4())
+    
+    org_record = {
+        "id": org_id,
+        "name": org_data.name,
+        "description": org_data.description,
+        "logo_url": org_data.logo_url,
+        "owner_id": current_user["id"],
+    }
+    
+    await supabase.insert("organizations", org_record)
+    
+    return Organization(**org_record, created_at=datetime.utcnow())
+
+
+@router.get("", response_model=OrganizationListResponse)
+async def list_organizations(
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    List organizations owned by the current user.
+    
+    **Requires TEAM account.**
+    """
+    orgs = await supabase.select(
+        "organizations",
+        filters={"owner_id": current_user["id"]},
+        order_by="created_at",
+        ascending=False,
+    )
+    
+    return OrganizationListResponse(
+        organizations=[Organization(**o) for o in orgs],
+        total=len(orgs),
+    )
+
+
+@router.get("/{org_id}", response_model=OrganizationWithStats)
+async def get_organization(
+    org_id: str,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get organization details with statistics.
+    
+    **Requires TEAM account.**
+    """
+    org = await supabase.select_one("organizations", org_id)
+    
+    if not org:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Organization not found"
+        )
+    
+    if org["owner_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this organization"
+        )
+    
+    # Get stats
+    players = await supabase.select("players", filters={"organization_id": org_id})
+    videos = await supabase.select("videos", filters={"organization_id": org_id})
+    
+    return OrganizationWithStats(
+        **org,
+        player_count=len(players),
+        video_count=len(videos),
+        total_analysis_count=len([v for v in videos if v.get("status") == "completed"]),
+    )
+
+
+@router.put("/{org_id}", response_model=Organization)
+async def update_organization(
+    org_id: str,
+    update_data: OrganizationUpdate,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Update organization details.
+    
+    **Requires TEAM account.**
+    """
+    org = await supabase.select_one("organizations", org_id)
+    
+    if not org:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Organization not found"
+        )
+    
+    if org["owner_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have permission to update this organization"
+        )
+    
+    update_dict = update_data.model_dump(exclude_unset=True)
+    
+    if not update_dict:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="No fields to update"
+        )
+    
+    updated = await supabase.update("organizations", org_id, update_dict)
+    
+    return Organization(**updated)
+
+
+@router.delete("/{org_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_organization(
+    org_id: str,
+    current_user: dict = Depends(require_team_account),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Delete an organization and all associated data.
+    
+    **Requires TEAM account.**
+    """
+    org = await supabase.select_one("organizations", org_id)
+    
+    if not org:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Organization not found"
+        )
+    
+    if org["owner_id"] != current_user["id"]:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have permission to delete this organization"
+        )
+    
+    # Best-effort cascade delete associated data
+    videos = await supabase.select("videos", filters={"organization_id": org_id})
+    video_ids = [v.get("id") for v in videos if v.get("id")]
+
+    # Delete analysis/detections/analytics linked to videos
+    for vid in video_ids:
+        try:
+            await supabase.delete_where("analysis_results", {"video_id": vid})
+        except Exception:
+            pass
+        try:
+            await supabase.delete_where("detections", {"video_id": vid})
+        except Exception:
+            pass
+        try:
+            await supabase.delete_where("analytics", {"video_id": vid})
+        except Exception:
+            pass
+        try:
+            await supabase.delete("videos", vid)
+        except Exception:
+            pass
+
+    # Delete players for the org
+    players = await supabase.select("players", filters={"organization_id": org_id})
+    player_ids = [p.get("id") for p in players if p.get("id")]
+    for pid in player_ids:
+        try:
+            await supabase.delete_where("analytics", {"player_id": pid})
+        except Exception:
+            pass
+        try:
+            await supabase.delete("players", pid)
+        except Exception:
+            pass
+
+    await supabase.delete("organizations", org_id)
+    
+    return None

app/api/videos.py

@@ -0,0 +1,614 @@
+"""
+Video management API endpoints.
+"""
+import os
+import shutil
+from uuid import uuid4
+from datetime import datetime
+from typing import Optional
+from urllib.parse import quote
+
+from fastapi import (
+    APIRouter,
+    Depends,
+    HTTPException,
+    Request,
+    UploadFile,
+    File,
+    Form,
+    Query,
+    status,
+)
+from fastapi.responses import FileResponse
+
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+from app.config import get_settings
+from app.dependencies import get_current_user, get_supabase
+from app.models.user import AccountType
+from app.models.video import (
+    VideoUpload,
+    Video,
+    VideoStatus,
+    AnalysisMode,
+    VideoStatusResponse,
+    VideoListResponse,
+)
+from app.services.supabase_client import SupabaseService
+
+
+router = APIRouter()
+
+def _annotated_video_path(video_id: str) -> str:
+    # Produced by analysis pipelines (e.g. analysis/team_analysis.py)
+    return os.path.join("output_videos", "annotated", f"{video_id}.mp4")
+
+
+def _get_limiter(request: Request) -> Limiter:
+    return request.app.state.limiter
+
+
+def get_video_info(file_path: str) -> dict:
+    """Extract video metadata using OpenCV."""
+    try:
+        import cv2
+        cap = cv2.VideoCapture(file_path)
+    except ImportError:
+        print("⚠️ OpenCV not installed, skipping video metadata extraction")
+        return {
+            "fps": 30.0,
+            "frame_count": 0,
+            "width": 1920,
+            "height": 1080,
+            "duration_seconds": 0,
+        }
+    
+    try:
+        if not cap.isOpened():
+            return {}
+        
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        
+        duration = frame_count / fps if fps > 0 else 0
+        
+        cap.release()
+        
+        return {
+            "fps": fps,
+            "frame_count": frame_count,
+            "width": width,
+            "height": height,
+            "duration_seconds": duration,
+        }
+    except Exception:
+        return {}
+    finally:
+        try:
+            cap.release()
+        except Exception:
+            pass
+
+
+@router.post("/upload", response_model=Video, status_code=status.HTTP_201_CREATED)
+async def upload_video(
+    request: Request,
+    file: UploadFile = File(...),
+    title: Optional[str] = Form(None, max_length=200),
+    description: Optional[str] = Form(None, max_length=1000),
+    analysis_mode: AnalysisMode = Form(...),
+    organization_id: Optional[str] = Form(None),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Upload a video for analysis.
+    
+    - **file**: Video file (mp4, avi, mov, mkv)
+    - **analysis_mode**: 'team' or 'personal'
+    - **organization_id**: Required for TEAM analysis
+    """
+    settings = get_settings()
+
+    # Apply a modest rate limit to uploads to avoid resource exhaustion.
+    limiter = _get_limiter(request)
+    limiter.limit("10/hour")(lambda request: None)(request)
+    
+    # Validate file extension
+    if not file.filename:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Missing filename"
+        )
+
+    _, ext = os.path.splitext(file.filename)
+    ext = ext.lstrip(".").lower()
+    if ext not in settings.allowed_extensions_list:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"Invalid file type. Allowed: {settings.allowed_video_extensions}"
+        )
+    
+    # Basic content-type validation (defence-in-depth – still rely on OpenCV check later)
+    allowed_mime_types = {
+        "video/mp4",
+        "video/x-msvideo",
+        "video/quicktime",
+        "video/x-matroska",
+    }
+    if file.content_type and file.content_type.lower() not in allowed_mime_types:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Invalid content type for video upload",
+        )
+
+    # Validate file size
+    file.file.seek(0, 2)  # Seek to end
+    file_size = file.file.tell()
+    file.file.seek(0)  # Reset
+    
+    if file_size > settings.max_upload_size_bytes:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"File too large. Maximum: {settings.max_upload_size_mb}MB"
+        )
+    
+    # Validate team analysis requirements
+    if analysis_mode == AnalysisMode.TEAM:
+        allowed_types = [AccountType.TEAM.value, AccountType.COACH.value]
+        if current_user.get("account_type") not in allowed_types:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Team analysis requires a TEAM or COACH account"
+            )
+        
+        # Determine the user's organization context
+        user_org_id = current_user.get("organization_id")
+        if user_org_id in ("null", "undefined", ""):
+            user_org_id = None
+        
+        # If the user is a team manager but organization_id isn't in token (unlikely but safe check)
+        if not user_org_id and current_user.get("account_type") == AccountType.TEAM.value:
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs:
+                user_org_id = str(orgs[0]["id"])
+
+        if organization_id in ("null", "undefined", ""):
+            organization_id = None
+
+        if not organization_id:
+            organization_id = user_org_id
+
+        # Determine if we should allow null organization_id
+        # We allow it for individual coaches who aren't linked yet.
+        is_coach = current_user.get("account_type") == AccountType.COACH.value
+        
+        if not organization_id and not is_coach:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="organization_id is required and you are not linked to any organization"
+            )
+            
+        # Verify org access if an organization_id is provided or found
+        if organization_id and str(organization_id) != str(user_org_id):
+            # For robustness, if it's a team account, double check org ownership if the ID doesn't match token
+            if current_user.get("account_type") == AccountType.TEAM.value:
+                org = await supabase.select_one("organizations", str(organization_id))
+                if not org or org.get("owner_id") != current_user["id"]:
+                    raise HTTPException(status_code= status.HTTP_403_FORBIDDEN, detail="Access denied to this organization")
+            else:
+                 raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="You can only upload to your linked organization")
+    
+    # Generate unique filename and save. We never trust the original name for paths.
+    video_id = str(uuid4())
+    filename = f"{video_id}.{ext}"
+    # Ensure uploader id does not introduce path traversal
+    safe_uploader_id = str(current_user["id"]).replace("/", "_").replace("\\", "_")
+    storage_path = os.path.join(settings.upload_dir, safe_uploader_id, filename)
+    
+    os.makedirs(os.path.dirname(storage_path), exist_ok=True)
+    
+    with open(storage_path, "wb") as buffer:
+        shutil.copyfileobj(file.file, buffer)
+    
+    # Get video metadata
+    video_info = get_video_info(storage_path)
+    if not video_info or not video_info.get("frame_count"):
+        # Reject unreadable / non-video uploads
+        try:
+            os.remove(storage_path)
+        except Exception:
+            pass
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Uploaded file is not a readable video"
+        )
+    
+    # Create database record
+    video_record = {
+        "id": video_id,
+        "uploader_id": current_user["id"],
+        "title": title or file.filename,
+        "description": description,
+        "analysis_mode": analysis_mode.value,
+        "status": VideoStatus.PENDING.value,
+        "storage_path": storage_path,
+        "file_size_bytes": file_size,
+        "organization_id": organization_id,
+        **video_info,
+    }
+    
+    await supabase.insert("videos", video_record)
+    
+    return Video(
+        **video_record,
+        created_at=datetime.utcnow(),
+        download_url=f"/api/videos/{video_id}/download",
+        annotated_download_url=f"/api/videos/{video_id}/annotated",
+        has_annotated=os.path.exists(_annotated_video_path(video_id)),
+    )
+
+
+@router.get("", response_model=VideoListResponse)
+async def list_videos(
+    page: int = Query(1, ge=1),
+    page_size: int = Query(20, ge=1, le=100),
+    status_filter: Optional[VideoStatus] = Query(None),
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    List videos uploaded by the current user.
+    """
+    # If TEAM account, filter by organization_id by default if possible
+    filters = {}
+    or_filter = None
+    if current_user.get("account_type") == AccountType.TEAM.value:
+        orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+        if orgs:
+            filters["organization_id"] = orgs[0]["id"]
+        else:
+            filters["uploader_id"] = current_user["id"]
+    else:
+        # Player account
+        if current_user.get("organization_id"):
+            uid = current_user["id"]
+            oid = current_user["organization_id"]
+            or_filter = f"uploader_id.eq.{uid},and(organization_id.eq.{oid},analysis_mode.eq.team)"
+        else:
+            filters["uploader_id"] = current_user["id"]
+        
+    if status_filter:
+        filters["status"] = status_filter.value
+    
+    videos = await supabase.select(
+        "videos",
+        filters=filters,
+        order_by="created_at",
+        ascending=False,
+        or_filter=or_filter,
+    )
+    
+    # Paginate
+    total = len(videos)
+    start = (page - 1) * page_size
+    end = start + page_size
+    paginated = videos[start:end]
+    
+    return VideoListResponse(
+        videos=[
+            Video(
+                **{
+                    **v,
+                    "download_url": f"/api/videos/{v.get('id')}/download",
+                    "annotated_download_url": f"/api/videos/{v.get('id')}/annotated",
+                    "has_annotated": bool(v.get("annotated_url")) or os.path.exists(_annotated_video_path(str(v.get('id')))),
+                }
+            )
+            for v in paginated
+        ],
+        total=total,
+        page=page,
+        page_size=page_size,
+    )
+
+
+@router.get("/{video_id}", response_model=Video)
+async def get_video(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get video details by ID.
+    """
+    video = await supabase.select_one("videos", video_id)
+    
+    if not video:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Video not found"
+        )
+    
+    # Check ownership
+    is_owner = str(video["uploader_id"]) == str(current_user["id"])
+    is_org_member = False
+    if not is_owner and video.get("organization_id") and current_user.get("organization_id"):
+        if str(video["organization_id"]) == str(current_user["organization_id"]):
+            is_org_member = True
+            
+    if not is_owner and not is_org_member:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have access to this video"
+        )
+    
+    return Video(
+        **{
+            **video,
+            "download_url": f"/api/videos/{video_id}/download",
+            "annotated_download_url": f"/api/videos/{video_id}/annotated",
+            "has_annotated": bool(video.get("annotated_url")) or os.path.exists(_annotated_video_path(video_id)),
+        }
+    )
+
+
+@router.get("/{video_id}/download")
+async def download_video(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Download a previously uploaded video.
+    Authenticated and ownership-checked.
+    """
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+
+    if video.get("uploader_id") != current_user["id"]:
+        is_org_member = False
+        if video.get("organization_id") and current_user.get("organization_id"):
+            if str(video["organization_id"]) == str(current_user["organization_id"]):
+                is_org_member = True
+                
+        # Also check if it's the TEAM owner
+        if current_user.get("account_type") == AccountType.TEAM.value:
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs and str(video.get("organization_id")) == str(orgs[0]["id"]):
+                is_org_member = True
+                
+        if not is_org_member:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="You don't have access to this video")
+
+    storage_path = video.get("storage_path")
+    if not storage_path or not os.path.exists(storage_path):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video file not found on server")
+
+    # Prefer the original filename for download if available
+    original_title = (video.get("title") or f"{video_id}").strip()
+    safe_name = quote(original_title.replace("/", "_").replace("\\", "_"))
+    _, ext = os.path.splitext(storage_path)
+    ext = ext if ext else ".mp4"
+    
+    # Guess media type based on extension
+    media_types = {
+        ".mp4": "video/mp4",
+        ".webm": "video/webm",
+        ".avi": "video/x-msvideo",
+        ".mov": "video/quicktime",
+        ".mkv": "video/x-matroska",
+    }
+    media_type = media_types.get(ext.lower(), "video/mp4")
+
+    return FileResponse(
+        path=storage_path,
+        filename=f"{safe_name}{ext}",
+        media_type=media_type,
+        content_disposition_type="inline"
+    )
+
+
+@router.get("/{video_id}/annotated")
+async def download_annotated_video(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Download the annotated output video (if available).
+    Redirects to Supabase signed URL when stored in cloud, otherwise streams from disk.
+    Ownership-checked via the uploaded video record.
+    """
+    from fastapi.responses import RedirectResponse
+
+    video = await supabase.select_one("videos", video_id)
+    if not video:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Video not found")
+    if video.get("uploader_id") != current_user["id"]:
+        is_org_member = False
+        if video.get("organization_id") and current_user.get("organization_id"):
+            if str(video["organization_id"]) == str(current_user["organization_id"]):
+                is_org_member = True
+                
+        # Also check if it's the TEAM owner
+        if current_user.get("account_type") == AccountType.TEAM.value:
+            orgs = await supabase.select("organizations", filters={"owner_id": current_user["id"]})
+            if orgs and str(video.get("organization_id")) == str(orgs[0]["id"]):
+                is_org_member = True
+                
+        if not is_org_member:
+            raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="You don't have access to this video")
+
+    # Prefer Supabase signed URL (cloud storage) — redirect the client directly
+    annotated_url = video.get("annotated_url")
+    if annotated_url and annotated_url.startswith("https"):
+        return RedirectResponse(url=annotated_url, status_code=302)
+
+    # Fallback: serve from local disk
+    annotated_path = _annotated_video_path(video_id)
+    if not os.path.exists(annotated_path):
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Annotated video not available yet")
+
+    original_title = (video.get("title") or f"{video_id}").strip()
+    safe_name = quote(original_title.replace("/", "_").replace("\\", "_"))
+    return FileResponse(
+        path=annotated_path,
+        filename=f"{safe_name}-annotated.mp4",
+        media_type="video/mp4",
+        content_disposition_type="inline"
+    )
+
+
+@router.get("/{video_id}/status", response_model=VideoStatusResponse)
+async def get_video_status(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Get video processing status with robust error handling for network issues.
+    """
+    try:
+        video = await supabase.select_one("videos", video_id)
+        
+        if not video:
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail="Video not found"
+            )
+        
+        # Security: Only owner or team members can see status
+        is_owner = str(video["uploader_id"]) == str(current_user["id"])
+        
+        # Check org access if uploader is different
+        is_org_member = False
+        if not is_owner and video.get("organization_id") and current_user.get("organization_id"):
+            if str(video["organization_id"]) == str(current_user["organization_id"]):
+                is_org_member = True
+        
+        if not is_owner and not is_org_member:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You don't have access to this video status"
+            )
+        
+        # HEAL: If status is failed but an analysis result was actually written, 
+        # then the process likely finished but the final status update was interrupted.
+        if video["status"] == VideoStatus.FAILED.value:
+            try:
+                results = await supabase.select("analysis_results", filters={"video_id": video_id}, limit=1)
+                if results:
+                    video["status"] = VideoStatus.COMPLETED.value
+                    video["progress_percent"] = 100
+                    video["current_step"] = "Complete (Auto-Recovered)"
+                    # Apply heal to DB so it doesn't repeat
+                    await supabase.update("videos", video_id, {
+                        "status": VideoStatus.COMPLETED.value,
+                        "progress_percent": 100,
+                        "current_step": "Complete (Auto-Recovered)"
+                    })
+            except Exception as e:
+                print(f"⚠️  Auto-heal check failed for video {video_id}: {e}")
+        
+        return VideoStatusResponse(
+            id=video["id"],
+            status=VideoStatus(video["status"]),
+            progress_percent=video.get("progress_percent") or 0,
+            current_step=video.get("current_step") or "Initializing",
+            error_message=video.get("error_message"),
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        print(f"❌ Error fetching video status for {video_id}: {e}")
+        # Return 503 instead of 500 for network/database connection errors
+        raise HTTPException(
+            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+            detail="Temporary database connection error. Please try again in a few moments."
+        )
+
+
+@router.delete("/{video_id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_video(
+    video_id: str,
+    current_user: dict = Depends(get_current_user),
+    supabase: SupabaseService = Depends(get_supabase),
+):
+    """
+    Delete a video and associated data.
+    Allows uploader, team owner, or coach (if in same org) to delete.
+    """
+    video = await supabase.select_one("videos", video_id)
+    
+    if not video:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Video not found"
+        )
+    
+    # Permission Check: Uploader can always delete
+    is_owner = str(video["uploader_id"]) == str(current_user["id"])
+    
+    # Organization Check: Team Owner or Coach can delete team videos
+    is_org_authorized = False
+    if video.get("organization_id") and current_user.get("organization_id"):
+        if str(video["organization_id"]) == str(current_user["organization_id"]):
+            if current_user.get("account_type") in [AccountType.TEAM.value, AccountType.COACH.value]:
+                is_org_authorized = True
+
+    if not is_owner and not is_org_authorized:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="You don't have permission to delete this video"
+        )
+    
+    # 1. Delete original file
+    if video.get("storage_path") and os.path.exists(video["storage_path"]):
+        try:
+            os.remove(video["storage_path"])
+        except Exception as e:
+            print(f"Error removing original video: {e}")
+
+    # 2. Delete annotated video (if any)
+    annotated_path = _annotated_video_path(video_id)
+    if os.path.exists(annotated_path):
+        try:
+            os.remove(annotated_path)
+        except Exception as e:
+            print(f"Error removing annotated video: {e}")
+
+    # 3. Clean up personal analysis outputs (if any)
+    # Personal analysis uses a different naming convention: {video_id}_output.mp4 etc.
+    from app.api.personal_analysis import PERSONAL_OUTPUT_DIR
+    for suffix in ["_output.mp4", "_output.avi", "_report.txt", "_input.mp4", "_input.avi"]:
+        personal_path = os.path.join(PERSONAL_OUTPUT_DIR, f"{video_id}{suffix}")
+        if os.path.exists(personal_path):
+            try:
+                os.remove(personal_path)
+            except Exception:
+                pass
+
+    # 4. Best-effort cascade delete related rows
+    for table in ["analysis_results", "detections", "analytics", "personal_analyses", "clips"]:
+        try:
+            await supabase.delete_where(table, {"video_id": video_id})
+        except Exception:
+            # Fallback for tables that might use different columns or not exist
+            try:
+                if table == "personal_analyses":
+                    await supabase.delete_where(table, {"job_id": video_id})
+                elif table == "clips":
+                    # Advanced analytics clips usually linked via video_id
+                    await supabase.delete_where(table, {"video_id": video_id})
+            except Exception:
+                pass
+    
+    # 5. Delete database record
+    await supabase.delete("videos", video_id)
+    
+    return None

app/config.py

@@ -0,0 +1,94 @@
+"""
+Configuration settings for the Basketball Analysis API.
+
+Uses Pydantic Settings for environment variable management with type validation.
+"""
+from functools import lru_cache
+from typing import Optional
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application configuration loaded from environment variables."""
+    
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore"
+    )
+    
+    # Application settings
+    app_name: str = "Basketball Analysis API"
+    app_version: str = "1.0.0"
+    debug: bool = False
+    default_rate_limit: str = "100 per minute"
+    
+    # Server settings
+    host: str = "0.0.0.0"
+    port: int = 8000
+    request_timeout_seconds: int = 120
+    
+    # Supabase configuration
+    supabase_url: Optional[str] = None
+    supabase_key: Optional[str] = None
+    supabase_service_key: Optional[str] = None
+    
+    # JWT settings
+    jwt_secret: str = "your-super-secret-key-change-in-production"
+    jwt_algorithm: str = "HS256"
+    jwt_expiration_minutes: int = 60 * 24  # 24 hours
+
+    # CORS (comma-separated list). Example: "http://localhost:5173,https://yourapp.com"
+    cors_origins: str = ""
+    
+    # File storage
+    upload_dir: str = "./uploads"
+    max_upload_size_mb: int = 500
+    allowed_video_extensions: str = "mp4,avi,mov,mkv"
+    serve_uploads_in_debug: bool = True
+    
+    # GPU settings
+    gpu_enabled: bool = True
+    cuda_device: int = 0
+    
+    # Model paths (relative to backend root)
+    team_model_path: str = "models/player_detector.pt"
+    personal_model_path: str = "models/player_detector.pt"
+    
+    # Independent detector models trained on NBL dataset
+    player_detector_path: str = "models/player_detector.pt"
+    ball_detector_path: str = "models/ball_detector.pt"
+    court_keypoint_detector_path: str = "models/court_keypoint_detector.pt"
+    pose_model_path: str = "models/yolov8n-pose.pt"
+    
+    # Swish-Vision specific models
+    swish_ball_rim_model: str = "models/swish_ball_rim.pt"
+    swish_pose_model: str = "models/swish_pose.pt"
+    
+    # Processing settings
+    batch_size: int = 20
+    detection_confidence: float = 0.5
+    
+    @property
+    def allowed_extensions_list(self) -> list[str]:
+        """Get allowed video extensions as a list."""
+        return [ext.strip().lower() for ext in self.allowed_video_extensions.split(",")]
+    
+    @property
+    def cors_origins_list(self) -> list[str]:
+        """Get CORS origins as a list."""
+        if not self.cors_origins:
+            return []
+        return [o.strip() for o in self.cors_origins.split(",") if o.strip()]
+
+    @property
+    def max_upload_size_bytes(self) -> int:
+        """Get max upload size in bytes."""
+        return self.max_upload_size_mb * 1024 * 1024
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Get cached settings instance."""
+    return Settings()

app/core/__init__.py

@@ -0,0 +1,78 @@
+"""
+Custom exceptions for the Basketball Analysis API.
+"""
+from typing import Optional, Dict, Any
+
+
+class BasketballAPIException(Exception):
+    """Base exception for all API errors."""
+    
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        details: Optional[Dict[str, Any]] = None
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class AuthenticationError(BasketballAPIException):
+    """Raised when authentication fails."""
+    
+    def __init__(self, message: str = "Authentication failed", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=401, details=details)
+
+
+class AuthorizationError(BasketballAPIException):
+    """Raised when user lacks permission for an action."""
+    
+    def __init__(self, message: str = "Access denied", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=403, details=details)
+
+
+class NotFoundError(BasketballAPIException):
+    """Raised when a resource is not found."""
+    
+    def __init__(self, resource: str = "Resource", resource_id: Optional[str] = None):
+        message = f"{resource} not found"
+        if resource_id:
+            message = f"{resource} with id '{resource_id}' not found"
+        super().__init__(message, status_code=404)
+
+
+class ValidationError(BasketballAPIException):
+    """Raised when request validation fails."""
+    
+    def __init__(self, message: str = "Validation error", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=422, details=details)
+
+
+class VideoProcessingError(BasketballAPIException):
+    """Raised when video processing fails."""
+    
+    def __init__(self, message: str = "Video processing failed", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=500, details=details)
+
+
+class StorageError(BasketballAPIException):
+    """Raised when file storage operations fail."""
+    
+    def __init__(self, message: str = "Storage operation failed", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=500, details=details)
+
+
+class SupabaseError(BasketballAPIException):
+    """Raised when Supabase operations fail."""
+    
+    def __init__(self, message: str = "Database operation failed", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=500, details=details)
+
+
+class AnalysisError(BasketballAPIException):
+    """Raised when video analysis fails."""
+    
+    def __init__(self, message: str = "Analysis failed", details: Optional[Dict[str, Any]] = None):
+        super().__init__(message, status_code=500, details=details)

app/core/security.py

@@ -0,0 +1,106 @@
+"""
+Security utilities for JWT token handling and password hashing.
+"""
+from datetime import datetime, timedelta, timezone
+from typing import Optional, Dict, Any
+from jose import jwt, JWTError
+import bcrypt
+from app.config import get_settings
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verify a password against its hash."""
+    try:
+        password_bytes = plain_password.encode('utf-8')
+        hash_bytes = hashed_password.encode('utf-8')
+        return bcrypt.checkpw(password_bytes, hash_bytes)
+    except Exception as e:
+        print(f"Error verifying password: {e}")
+        return False
+
+
+def get_password_hash(password: str) -> str:
+    """Generate a password hash."""
+    password_bytes = password.encode('utf-8')
+    salt = bcrypt.gensalt()
+    hashed = bcrypt.hashpw(password_bytes, salt)
+    return hashed.decode('utf-8')
+
+
+def create_access_token(
+    data: Dict[str, Any],
+    expires_delta: Optional[timedelta] = None
+) -> str:
+    """
+    Create a JWT access token.
+    
+    Args:
+        data: Payload data to encode in the token
+        expires_delta: Optional custom expiration time
+        
+    Returns:
+        Encoded JWT token string
+    """
+    settings = get_settings()
+    to_encode = data.copy()
+    
+    if expires_delta:
+        expire = datetime.now(timezone.utc) + expires_delta
+    else:
+        expire = datetime.now(timezone.utc) + timedelta(minutes=settings.jwt_expiration_minutes)
+    
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(
+        to_encode,
+        settings.jwt_secret,
+        algorithm=settings.jwt_algorithm
+    )
+    return encoded_jwt
+
+
+def decode_access_token(token: str) -> Optional[Dict[str, Any]]:
+    """
+    Decode and validate a JWT access token.
+    
+    Args:
+        token: JWT token string
+        
+    Returns:
+        Decoded payload if valid, None otherwise
+    """
+    settings = get_settings()
+    try:
+        payload = jwt.decode(
+            token,
+            settings.jwt_secret,
+            algorithms=[settings.jwt_algorithm]
+        )
+        return payload
+    except JWTError:
+        return None
+
+
+def create_refresh_token(user_id: str) -> str:
+    """
+    Create a refresh token with extended expiration.
+    
+    Args:
+        user_id: User ID to encode in the token
+        
+    Returns:
+        Encoded JWT refresh token
+    """
+    settings = get_settings()
+    expire = datetime.now(timezone.utc) + timedelta(days=7)  # 7 days for refresh token
+    
+    to_encode = {
+        "sub": user_id,
+        "type": "refresh",
+        "exp": expire
+    }
+    
+    return jwt.encode(
+        to_encode,
+        settings.jwt_secret,
+        algorithm=settings.jwt_algorithm
+    )

app/dependencies.py

@@ -0,0 +1,202 @@
+"""
+FastAPI dependency injection functions.
+
+Provides common dependencies for authentication, authorization, 
+and service access across all API endpoints.
+"""
+from typing import Optional
+from fastapi import Depends, HTTPException, status, Query
+from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
+
+from app.config import get_settings, Settings
+from app.core.security import decode_access_token
+from app.core import AuthenticationError, AuthorizationError
+from app.models.user import AccountType, TokenPayload
+from app.services.supabase_client import SupabaseService, get_supabase_service
+
+
+# OAuth2 bearer scheme for JWT tokens
+security = HTTPBearer(auto_error=False)
+
+
+async def get_settings_dep() -> Settings:
+    """Dependency to get application settings."""
+    return get_settings()
+
+
+async def get_supabase(
+    settings: Settings = Depends(get_settings_dep)
+) -> SupabaseService:
+    """Dependency to get Supabase service instance."""
+    return get_supabase_service()
+
+
+async def get_current_user_optional(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+) -> Optional[dict]:
+    """
+    Get current user from JWT token if present.
+    Returns None if no token provided (for public endpoints).
+    """
+    if not credentials:
+        return None
+    
+    token = credentials.credentials
+    payload = decode_access_token(token)
+    
+    if not payload:
+        return None
+    
+    return {
+        "id": payload.get("sub"),
+        "email": payload.get("email"),
+        "account_type": payload.get("account_type"),
+        "organization_id": payload.get("organization_id")
+    }
+
+
+
+
+async def get_current_user(
+    credentials: Optional[HTTPAuthorizationCredentials] = Depends(security),
+    token_query: Optional[str] = Query(None, alias="token")
+) -> dict:
+    """
+    Get current authenticated user from JWT token (Header or Query param).
+    Raises HTTPException if not authenticated.
+    """
+    token = None
+    if credentials:
+        token = credentials.credentials
+    elif token_query:
+        token = token_query
+        
+    if not token:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Not authenticated",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    payload = decode_access_token(token)
+    
+    if not payload:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Invalid or expired token",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    
+    return {
+        "id": payload.get("sub"),
+        "email": payload.get("email"),
+        "account_type": payload.get("account_type"),
+        "organization_id": payload.get("organization_id")
+    }
+
+
+async def require_team_account(
+    current_user: dict = Depends(get_current_user),
+) -> dict:
+    """
+    Dependency that requires a TEAM or COACH account type.
+    Use for team-only endpoints.
+    """
+    allowed_types = [AccountType.TEAM.value, AccountType.COACH.value]
+    if current_user.get("account_type") not in allowed_types:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This endpoint requires a TEAM or COACH account",
+        )
+    return current_user
+
+
+async def require_organization_admin(
+    current_user: dict = Depends(get_current_user),
+) -> dict:
+    """
+    Dependency that requires a TEAM account type (Organization Owner).
+    Use for critical administrative tasks like staff linking and settings.
+    """
+    if current_user.get("account_type") != AccountType.TEAM.value:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This operation requires organization owner administrative privileges",
+        )
+    return current_user
+
+async def require_personal_account(
+    current_user: dict = Depends(get_current_user),
+) -> dict:
+    """
+    Dependency that requires a PERSONAL account type.
+    Use for personal-only endpoints.
+    """
+    if current_user.get("account_type") != AccountType.PERSONAL.value:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This endpoint requires a PERSONAL account",
+        )
+    return current_user
+
+
+async def require_linked_account(
+    current_user: dict = Depends(get_current_user),
+) -> dict:
+    """
+    Dependency that requires the user to be linked to an organization.
+    """
+    if not current_user.get("organization_id"):
+        # For TEAM accounts, they might not have organization_id in token yet if just created,
+        # but for players/coaches, they MUST be linked.
+        if current_user.get("account_type") != AccountType.TEAM.value:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You must be linked to a team to access this feature",
+            )
+    return current_user
+
+
+async def require_staff_member(
+    current_user: dict = Depends(require_team_account),
+) -> dict:
+    """
+    Dependency that requires the user to be a COACH or TEAM owner who is linked to an organization.
+    Used for features delegated to coaching staff (match upload, scheduling, stats).
+    """
+    allowed_types = [AccountType.COACH.value, AccountType.TEAM.value]
+    if current_user.get("account_type") not in allowed_types:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This feature is managed by the Team Owner or Coaching Staff",
+        )
+    if not current_user.get("organization_id"):
+        # For TEAM accounts, we might need to fetch the org_id if not in token
+        # but the check below is a safe guard.
+        if current_user.get("account_type") != AccountType.TEAM.value:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Your account has not been linked to a team yet.",
+            )
+    return current_user
+
+def require_owner_or_admin(resource_owner_id: str):
+    """
+    Factory for dependency that checks if user owns a resource.
+    
+    Usage:
+        @router.delete("/items/{item_id}")
+        async def delete_item(
+            item_id: str,
+            _: dict = Depends(require_owner_or_admin(item.owner_id))
+        ):
+            ...
+    """
+    async def dependency(current_user: dict = Depends(get_current_user)) -> dict:
+        if current_user.get("id") != resource_owner_id:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="You don't have permission to access this resource",
+            )
+        return current_user
+    return dependency

app/main.py

@@ -0,0 +1,272 @@
+"""
+Basketball Analysis API - Main FastAPI Application
+
+This module sets up the FastAPI application with all routes, middleware,
+and exception handlers for the basketball performance analysis platform.
+"""
+import os
+from contextlib import asynccontextmanager
+from typing import Dict, Any
+
+from fastapi import FastAPI, Request, status
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+
+from app.config import get_settings
+from app.core import BasketballAPIException
+from app.api import (
+    auth, 
+    videos, 
+    analysis, 
+    teams, 
+    players, 
+    analytics, 
+    admin, 
+    player_routes, 
+    advanced_analytics,
+    communications,
+    personal_analysis,
+    stat_import
+)
+from app.middleware.timeout import TimeoutMiddleware
+
+# Basic rate limiting for abuse protection
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from slowapi.errors import RateLimitExceeded
+from slowapi.middleware import SlowAPIMiddleware
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan handler for startup and shutdown events.
+    """
+    # Startup
+    settings = get_settings()
+    print(f"🏀 Starting {settings.app_name} v{settings.app_version}")
+
+    # Basic production hardening
+    if not settings.debug and settings.jwt_secret == "your-super-secret-key-change-in-production":
+        raise ValueError("JWT_SECRET must be set in production (refusing to start with default secret).")
+    
+    # Ensure upload directory exists
+    os.makedirs(settings.upload_dir, exist_ok=True)
+    
+    # Check GPU availability
+    if settings.gpu_enabled:
+        try:
+            import torch
+            if torch.cuda.is_available():
+                print(f"✅ GPU acceleration enabled: {torch.cuda.get_device_name(settings.cuda_device)}")
+            else:
+                print("⚠️ GPU requested but CUDA not available, falling back to CPU")
+        except ImportError:
+            print("⚠️ PyTorch not installed, running without GPU check")
+    
+    yield
+    
+    # Shutdown
+    print("🛑 Shutting down application")
+
+
+def create_app() -> FastAPI:
+    """
+    Application factory for creating the FastAPI instance.
+    """
+    settings = get_settings()
+    
+    app = FastAPI(
+        title=settings.app_name,
+        version=settings.app_version,
+        description="""
+        AI-driven basketball performance analysis platform.
+        
+        ## Features
+        - **Video Analysis**: Upload and analyze basketball footage
+        - **Team Analysis**: Multi-player tracking, passes, interceptions  
+        - **Personal Analysis**: Individual skill metrics and pose analysis
+        - **Progress Tracking**: Monitor improvement over time
+        
+        ## Account Types
+        - **TEAM**: Manage organizations, players, and team analytics
+        - **PERSONAL**: Focus on individual training and skill development
+        """,
+        docs_url="/docs",
+        redoc_url="/redoc",
+        openapi_url="/api/openapi.json",
+        lifespan=lifespan,
+    )
+
+    # Attach a rate limiter to the app. We keep limits conservative but safe by default.
+    limiter = Limiter(key_func=get_remote_address, default_limits=[settings.default_rate_limit])
+    app.state.limiter = limiter
+    app.add_middleware(SlowAPIMiddleware)
+
+    # Configure CORS
+    # - In production, require explicit origins (settings.cors_origins)
+    # - In debug, allow "*" but disable credentials to avoid insecure/invalid combo
+    cors_origins = settings.cors_origins_list
+    if settings.debug and not cors_origins:
+        allow_origins = ["*"]
+        allow_credentials = False
+    else:
+        allow_origins = cors_origins
+        allow_credentials = True
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=allow_origins,
+        allow_credentials=allow_credentials,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    # Request timeout (avoid resource exhaustion)
+    app.add_middleware(TimeoutMiddleware, timeout_seconds=settings.request_timeout_seconds)
+    
+    # Register exception handlers
+    register_exception_handlers(app)
+    
+    # Register API routes
+    register_routes(app)
+    
+    # Static files for uploads (debug/dev only). In production, use authenticated download endpoints
+    # or signed object storage URLs instead of exposing a filesystem-backed directory.
+    # Anchor all static dirs to the backend root (derived from __file__) so they
+    # resolve correctly even when CWD is mangled (apostrophe-stripped shell).
+    _app_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+    if settings.serve_uploads_in_debug and os.path.exists(settings.upload_dir):
+        app.mount("/uploads", StaticFiles(directory=settings.upload_dir), name="uploads")
+    
+    # Serve generated clips (highlights)
+    clips_dir = os.path.join(_app_dir, "output_videos", "clips")
+    os.makedirs(clips_dir, exist_ok=True)
+    app.mount("/clips", StaticFiles(directory=clips_dir), name="clips")
+    
+    # Serve personal analysis output videos — always mounted so results are
+    # accessible regardless of the DEBUG flag.
+    personal_out_dir = os.path.join(_app_dir, "uploads", "personal_output")
+    os.makedirs(personal_out_dir, exist_ok=True)
+    app.mount("/personal-output", StaticFiles(directory=personal_out_dir), name="personal-output")
+
+    return app
+
+
+def register_exception_handlers(app: FastAPI) -> None:
+    """Register custom exception handlers."""
+    
+    @app.exception_handler(BasketballAPIException)
+    async def basketball_exception_handler(
+        request: Request, exc: BasketballAPIException
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": exc.message,
+                "details": exc.details,
+            },
+        )
+    
+    from fastapi.exceptions import RequestValidationError
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError):
+        print(f"Validation Error: {exc.errors()}")
+        return JSONResponse(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            content={"detail": exc.errors()},
+        )
+    
+    @app.exception_handler(RateLimitExceeded)
+    async def rate_limit_handler(
+        request: Request, exc: RateLimitExceeded
+    ) -> JSONResponse:
+        return JSONResponse(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            content={
+                "error": "Too many requests",
+                "details": {"message": str(exc)},
+            },
+        )
+
+    @app.exception_handler(Exception)
+    async def general_exception_handler(
+        request: Request, exc: Exception
+    ) -> JSONResponse:
+        # Log the error without leaking internals to clients
+        settings = get_settings()
+        # Use standard logging so deployments can aggregate logs
+        import logging
+
+        logger = logging.getLogger("basketball_api")
+        logger.exception("Unhandled error", exc_info=exc)
+
+        return JSONResponse(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            content={
+                "error": "An unexpected error occurred",
+                # Only expose minimal type information; no stack traces or messages.
+                "details": {"type": type(exc).__name__} if settings.debug else {},
+            },
+        )
+
+
+def register_routes(app: FastAPI) -> None:
+    """Register all API routers."""
+    
+    # Health check endpoint
+    @app.get("/api/health", tags=["Health"])
+    async def health_check() -> Dict[str, Any]:
+        """Check API health status."""
+        settings = get_settings()
+        return {
+            "status": "healthy",
+            "version": settings.app_version,
+            "gpu_enabled": settings.gpu_enabled,
+        }
+    
+    # Root endpoint
+    @app.get("/", tags=["Root"])
+    async def root() -> Dict[str, str]:
+        """API root endpoint."""
+        settings = get_settings()
+        return {
+            "message": f"Welcome to {settings.app_name}",
+            "docs": "/docs",
+            "health": "/api/health",
+        }
+
+    @app.get("/api/test-proxy")
+    async def test_proxy():
+        return {"status": "proxy-ok"}
+    
+    # Register API routers
+    app.include_router(auth.router, prefix="/api/auth", tags=["Authentication"])
+    app.include_router(videos.router, prefix="/api/videos", tags=["Videos"])
+    app.include_router(analysis.router, prefix="/api/analysis", tags=["Analysis"])
+    app.include_router(teams.router, prefix="/api/teams", tags=["Teams"])
+    app.include_router(players.router, prefix="/api/players", tags=["Players"])
+    app.include_router(analytics.router, prefix="/api/analytics", tags=["Analytics"])
+    app.include_router(advanced_analytics.router, prefix="/api/analytics/advanced", tags=["Advanced Analytics"])
+    app.include_router(admin.router, prefix="/api/admin", tags=["Admin"])
+    app.include_router(player_routes.router, prefix="/api/player", tags=["Player Portal"])
+    app.include_router(personal_analysis.router, prefix="/api/player", tags=["Personal Analysis"])
+    app.include_router(communications.router, prefix="/api/communications", tags=["Communication"])
+    app.include_router(stat_import.router, prefix="/api/stat-import", tags=["Stat Sheet Import"])
+
+
+# Create the application instance
+app = create_app()
+
+
+if __name__ == "__main__":
+    import uvicorn
+    settings = get_settings()
+    uvicorn.run(
+        "app.main:app",
+        host=settings.host,
+        port=settings.port,
+        reload=settings.debug,
+    )

app/middleware/__init__.py

@@ -0,0 +1 @@
+

app/middleware/timeout.py

@@ -0,0 +1,20 @@
+import anyio
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+
+
+class TimeoutMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app, timeout_seconds: int):
+        super().__init__(app)
+        self.timeout_seconds = timeout_seconds
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        try:
+            with anyio.fail_after(self.timeout_seconds):
+                return await call_next(request)
+        except TimeoutError:
+            return JSONResponse(
+                status_code=504,
+                content={"error": "Request timed out", "details": {"timeout_seconds": self.timeout_seconds}},
+            )

app/models/__init__.py

@@ -0,0 +1,105 @@
+"""
+Pydantic models package.
+"""
+from app.models.user import (
+    AccountType,
+    UserCreate,
+    UserLogin,
+    UserUpdate,
+    User,
+    UserInDB,
+    TokenResponse,
+    TokenPayload,
+)
+from app.models.video import (
+    VideoStatus,
+    AnalysisMode,
+    VideoUpload,
+    Video,
+    VideoStatusResponse,
+    VideoListResponse,
+)
+from app.models.team import (
+    OrganizationCreate,
+    OrganizationUpdate,
+    Organization,
+    OrganizationWithStats,
+    OrganizationListResponse,
+)
+from app.models.player import (
+    PlayerCreate,
+    PlayerUpdate,
+    Player,
+    PlayerWithStats,
+    PlayerListResponse,
+)
+from app.models.analysis import (
+    Detection,
+    DetectionBatch,
+    AnalysisRequest,
+    AnalysisEvent,
+    AnalysisResult,
+    PersonalAnalysisResult,
+)
+from app.models.analytics import (
+    PlayerMetric,
+    PlayerAnalyticsSummary,
+    TeamAnalyticsSummary,
+    SkillSummary,
+    ProgressData,
+    ProgressReport,
+)
+from app.models.communication import (
+    AnnouncementCreate,
+    Announcement,
+    AnnouncementListResponse,
+)
+
+__all__ = [
+    # User models
+    "AccountType",
+    "UserCreate",
+    "UserLogin",
+    "UserUpdate",
+    "User",
+    "UserInDB",
+    "TokenResponse",
+    "TokenPayload",
+    # Video models
+    "VideoStatus",
+    "AnalysisMode",
+    "VideoUpload",
+    "Video",
+    "VideoStatusResponse",
+    "VideoListResponse",
+    # Team models
+    "OrganizationCreate",
+    "OrganizationUpdate",
+    "Organization",
+    "OrganizationWithStats",
+    "OrganizationListResponse",
+    # Player models
+    "PlayerCreate",
+    "PlayerUpdate",
+    "Player",
+    "PlayerWithStats",
+    "PlayerListResponse",
+    # Analysis models
+    "Detection",
+    "DetectionBatch",
+    "AnalysisRequest",
+    "AnalysisEvent",
+    "AnalysisResult",
+    "PersonalAnalysisResult",
+    # Analytics models
+    "PlayerMetric",
+    "PlayerAnalyticsSummary",
+    "TeamAnalyticsSummary",
+    "SkillSummary",
+    "ProgressData",
+    "ProgressReport",
+    # Communication models
+    "AnnouncementCreate",
+    "Announcement",
+    "AnnouncementListResponse",
+]