🏀 Valley Catholic Basketball Stats

A comprehensive basketball statistics platform with AI-powered analysis for Valley Catholic High School's varsity team.

📋 Table of Contents

• Features
• Demo
• Quick Start
• Installation
• Configuration
• Usage
• API Documentation
• Project Structure
• Advanced Metrics
• AI Analysis System
• Deployment
• Contributing
• Troubleshooting
• License

✨ Features

• 📊 Advanced Stats: eFG%, TS%, PPP, shot analytics, win/loss patterns, and consistency metrics
• 🤖 AI Analysis: Powered by OpenAI GPT models for player evaluation, game breakdowns, and diagnostic insights
• 📱 Responsive Design: Six fully responsive pages optimized for desktop and mobile
• 🎨 Modern UI: Dark theme with Valley Catholic school colors (Royal Blue)
• ⚡ High Performance: Backend caching with LRU cache and Service Worker for offline support
• 📈 Interactive Charts: Real-time data visualization with Chart.js
• 🔒 Secure: Environment-based configuration with no hardcoded credentials
• 🚀 Production Ready: Deploy to Railway, Heroku, or any platform with one click

🎥 Demo

Visit the live application: Your-App.railway.app (Update with your actual URL)

Screenshots

Dashboard	Players	Trends
Season overview with AI insights	Player profiles & game logs	Interactive performance charts

🚀 Quick Start

# Clone the repository
git clone https://github.com/yourusername/vc-basketball-stats.git
cd vc-basketball-stats

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

# Run the application
python main.py

# Visit http://localhost:5000

📦 Installation

Prerequisites

• Python 3.11+ - Download
• pip - Comes with Python
• OpenAI API Key - Get one here

Step-by-Step Installation

1. Clone the repository:

   git clone https://github.com/yourusername/vc-basketball-stats.git
   cd vc-basketball-stats

2. Create a virtual environment:

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # macOS/Linux
   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables:

   cp .env.example .env

   Edit .env and add your API keys:

   OPENAI_API_KEY=your_openai_api_key_here
   DATABASE_URL=postgresql://user:pass@host:port/db  # Optional for production

5. Run the application:

   python main.py

6. Access the application: Open your browser and navigate to http://localhost:5000

⚙️ Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

Variable	Description	Required	Default
OPENAI_API_KEY	Your OpenAI API key for AI analysis	Yes	-
DATABASE_URL	PostgreSQL connection string (production)	No	SQLite (local)
FLASK_DEBUG	Enable Flask debug mode	No	False
PORT	Port to run the application	No	5000

Database Configuration

• Development: Uses SQLite by default (basketball_stats.db)
• Production: Set DATABASE_URL for PostgreSQL (recommended for Railway/Heroku)

OpenAI Model Configuration

The application intelligently selects models based on task complexity:

• GPT-4o-mini: Quick insights, UI text generation
• GPT-4o: Main analysis, player diagnostics, game recaps
• GPT-4: Season-wide processing (long context)

📖 Usage

Available Pages

1. Dashboard (/) - Season overview with advanced metrics and AI insights
2. Games (/games) - Complete box scores for all games with search and filter
3. Players (/players) - Player profiles with advanced stats and game logs
4. Trends (/trends) - Interactive charts showing team and player performance
5. Analysis (/analysis) - AI-generated comprehensive season analysis
6. AI Coach (/ai-insights) - Custom AI-powered queries and diagnostics

Using the AI Coach

Navigate to the AI Insights page and enter queries like:

• "Analyze Gavin's shooting efficiency trends"
• "What are our main weaknesses in losses?"
• "Compare our performance in first vs second half"
• "Which players have the most consistent scoring?"

🔌 API Endpoints

Advanced Stats Endpoints

GET /api/advanced/team          # Team advanced statistics
GET /api/advanced/player/<name> # Player advanced statistics
GET /api/advanced/patterns      # Win/loss patterns
GET /api/advanced/volatility    # Consistency metrics
GET /api/advanced/insights      # Auto-generated insights
GET /api/advanced/all           # All advanced stats in one call

Team & Player Endpoints

GET /api/team-stats             # Overall team statistics
GET /api/team-trends            # Team performance trends
GET /api/roster                 # Current roster
GET /api/players/<name>         # Individual player stats

Game Endpoints

GET /api/games                  # All games
GET /api/games/<id>             # Specific game details

AI Analysis Endpoints

POST /api/ai/analyze            # Custom AI analysis
GET /api/ai/player-insights/<name>  # Player diagnostic analysis
GET /api/ai/game-analysis/<id>      # Game breakdown
GET /api/ai/team-summary            # Season performance diagnosis

Example API Call

curl http://localhost:5000/api/advanced/team

Response:

{
  "eFG": 45.2,
  "TS": 47.8,
  "PPP": 0.92,
  "games_played": 9,
  "record": "4-5"
}

📁 Project Structure

vc-basketball-stats/ ├── src/ # Application source code │ ├── app.py # Flask application and routes │ ├── config.py # Configuration management │ ├── data_manager.py # Data loading and caching │ ├── ai_service.py # OpenAI API integration │ ├── advanced_stats.py # Statistics calculations │ └── models.py # Database models (SQLAlchemy) ├── data/ # JSON data files │ ├── parsed_games.json # Processed game data │ ├── roster.json # Team roster │ └── season_analysis.json # Season statistics ├── static/ # Frontend assets │ ├── style.css # Application styles │ ├── dashboard.js # Dashboard functionality │ ├── games.js # Games page logic │ ├── players.js # Players page logic │ ├── trends.js # Charts and visualizations │ ├── ai-insights.js # AI Coach interface │ └── service-worker.js # Offline support ├── templates/ # Jinja2 HTML templates │ ├── base.html # Base template │ ├── dashboard.html # Dashboard page │ ├── games.html # Games page │ ├── players.html # Players page │ ├── trends.html # Trends page │ ├── analysis.html # Analysis page │ └── ai-insights.html # AI Coach page ├── scripts/ # Utility scripts │ ├── database_setup.py # Database initialization │ ├── migrate_to_db.py # Data migration │ └── test_api.py # API testing ├── tests/ # Test suite │ └── test_*.py # Unit tests ├── docs/ # Documentation ├── main.py # Application entry point ├── requirements.txt # Python dependencies ├── .env.example # Environment template ├── .gitignore # Git ignore rules ├── Procfile # Railway/Heroku config ├── nixpacks.toml # Nixpacks configuration └── README.md # This file

## 🧮 Advanced Metrics Explained

### Shooting Efficiency

**eFG% (Effective Field Goal Percentage)**

eFG% = (FGM + 0.5 × 3PM) / FGA × 100

Accounts for the added value of three-point shots. League average is ~50%.

**TS% (True Shooting Percentage)**

TS% = PTS / (2 × (FGA + 0.44 × FTA)) × 100

Most comprehensive shooting metric, includes free throws. Elite shooters are above 60%.

**PPP (Points Per Possession)**

PPP = PTS / Estimated Possessions

Measures offensive efficiency. Above 1.0 is good, above 1.1 is excellent.

### Usage & Role Metrics

**Usage Proxy**

Usage% = (FGA + 0.44 × FTA + TO) / Team Total × 100

Estimates percentage of team possessions used by a player.

**Scoring Share**

Scoring Share% = Player PTS / Team PTS × 100

Percentage of team scoring contributed by a player.

**Player Roles** (Auto-classified):
- 🌟 **Primary Scorer**: Usage >20%, Scoring Share >20%
- ⚙️ **Role Player**: Usage 15-20%
- 🔧 **Supporting Role**: Usage <15%

### Consistency Metrics

**Volatility Measures**:
- PPG Range: Difference between highest and lowest scoring games
- FG% Standard Deviation: Shooting consistency
- TO Standard Deviation: Turnover consistency

Lower volatility = more consistent performance.

### Win Condition Analysis

Identifies statistical thresholds for wins:
- "Team is 7-0 when TO ≤ 13"
- "Team is 4-1 when scoring 50+ points"
- Compares averages in wins vs losses

## 🤖 AI Analysis System

### Capabilities

The AI system provides data-driven insights using OpenAI's GPT models:

- **Player Performance Diagnosis**: Identifies trends, strengths, and areas for improvement
- **Game Root Cause Analysis**: Explains what led to wins or losses
- **Season Pattern Detection**: Finds statistical trends and correlations
- **Win Condition Identification**: Determines what the team needs to do to win
- **Tactical Recommendations**: Suggests adjustments based on data

### Design Philosophy

✅ **Data-Driven**: All insights derived from box score statistics
✅ **Transparent**: Shows which stats inform each conclusion
✅ **Honest**: Acknowledges limitations and data gaps
✅ **Actionable**: Provides specific, measurable recommendations

❌ **No Speculation**: Won't infer things not in the data
❌ **No Assumptions**: Won't guess about player effort, coaching decisions, or momentum
❌ **No Overreach**: Won't claim to know defensive matchups or shot locations beyond stats

### AI Model Selection

| Task | Model | Reason |
|------|-------|--------|
| Season summaries | GPT-4o | Long context, comprehensive analysis |
| Player diagnostics | GPT-4o | Detailed evaluation with nuance |
| Game recaps | GPT-4o | Balanced quality and speed |
| Quick insights | GPT-4o-mini | Fast, cost-effective for short text |

### Example AI Insights

```json
{
  "insight": "Team struggles with turnovers in close games (avg 16.2 in losses vs 11.4 in wins)",
  "supporting_data": {
    "avg_to_losses": 16.2,
    "avg_to_wins": 11.4,
    "correlation": -0.72
  },
  "recommendation": "Focus on ball security in high-pressure situations"
}

🚀 Deployment

Deploy to Railway

1. Push code to GitHub

   git add .
   git commit -m "Initial commit"
   git push origin main

2. Create Railway project

   • Visit railway.app
   • Click "New Project" → "Deploy from GitHub repo"
   • Select your repository

3. Configure environment variables

   • Go to project settings → Variables
   • Add OPENAI_API_KEY
   • Optionally add DATABASE_URL for PostgreSQL

4. Deploy

   • Railway will automatically detect your app and deploy
   • Your app will be live at your-app.railway.app

Deploy to Heroku

# Login to Heroku
heroku login

# Create app
heroku create your-app-name

# Set environment variables
heroku config:set OPENAI_API_KEY=your_key_here

# Deploy
git push heroku main

# Open app
heroku open

Environment Variables for Production

Ensure these are set in your deployment platform:

OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://...
FLASK_DEBUG=False
PORT=5000

For detailed deployment instructions, see DEPLOYMENT.md.

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on:

• Code of Conduct
• Development setup
• Coding standards
• Pull request process
• Testing guidelines

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and test thoroughly
4. Commit: git commit -m 'Add amazing feature'
5. Push: git push origin feature/amazing-feature
6. Open a Pull Request

🔧 Development

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test file
python -m pytest tests/test_advanced_stats.py

# Run with coverage
python -m pytest --cov=src tests/

Code Quality

# Format code
black src/ tests/

# Lint code
flake8 src/ tests/

# Type checking
mypy src/

🐛 Troubleshooting

Common Issues

❌ "Address already in use" Error

# Windows
netstat -ano | findstr :5000
taskkill /PID <PID> /F

# macOS/Linux
lsof -ti:5000 | xargs kill -9

❌ OpenAI API Errors

• Check that OPENAI_API_KEY is set correctly in .env
• Verify API key is active at OpenAI Platform
• Check rate limits and billing status

❌ Stats Not Updating

• Clear browser cache (Ctrl+Shift+Delete)
• Restart the Flask application
• Check data/ directory for updated JSON files

❌ Database Connection Issues

• Verify DATABASE_URL format: postgresql://user:pass@host:port/db
• Check network connectivity to database
• Ensure database exists and user has permissions

❌ Charts Not Displaying

• Check browser console (F12) for JavaScript errors
• Verify internet connection (Chart.js loads from CDN)
• Try a different browser

❌ Import Errors

# Reinstall dependencies
pip install --upgrade -r requirements.txt

# Verify Python version
python --version  # Should be 3.11+

For more issues, check DATABASE_TROUBLESHOOTING.md or open an issue.

📚 Documentation

Additional documentation is available in the docs/ directory:

• DEPLOYMENT.md - Detailed deployment instructions
• CODE_REVIEW.md - Code review guidelines
• OUTPUT_STRUCTURE.md - Data structure documentation
• ADVANCED_STATS_API.txt - API reference
• AI_PROMPTS.txt - AI prompt engineering
• DATABASE_TROUBLESHOOTING.md - Database issues
• TESTING_GUIDE.md - Testing procedures

🛠️ Tech Stack

Layer	Technology	Purpose
Backend	Flask 3.1.2	Web framework
Language	Python 3.11+	Core application
Database	PostgreSQL / SQLite	Data persistence
ORM	SQLAlchemy 3.1.1	Database abstraction
AI	OpenAI GPT-4o/mini	Analysis engine
Frontend	Vanilla JavaScript	Interactive UI
Charts	Chart.js	Data visualization
Server	Gunicorn	Production WSGI server
Deployment	Railway / Heroku	Cloud hosting
Caching	LRU Cache	Performance optimization

📊 Performance Metrics

• First Page Load: ~1.2s (uncached)
• Cached Load: ~150ms (90% faster)
• API Response Time: <100ms (cached endpoints)
• AI Analysis: 2-5s (depends on query complexity)
• Database Queries: <50ms average

🔒 Security & Privacy

• ✅ Environment variables for all sensitive data
• ✅ No credentials in code or Git history
• ✅ Input sanitization on all user inputs
• ✅ SQL injection protection via SQLAlchemy ORM
• ✅ HTTPS enforced in production
• ✅ Rate limiting on AI endpoints
• ✅ Error messages don't expose system details

📈 Roadmap

• Add real-time game tracking
• Implement user authentication
• Export reports to PDF
• Mobile app (React Native)
• Multi-season comparison
• Video highlights integration
• Shot chart visualization
• Advanced defensive metrics

👥 Team

Built for Valley Catholic High School Basketball Team - 2025-2026 Season

🙏 Acknowledgments

• Valley Catholic High School for supporting the project
• OpenAI for providing AI analysis capabilities
• The Python and Flask communities
• All contributors and testers

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

📞 Support

• 📧 Email: your-email@example.com
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ for Valley Catholic Basketball

⬆ Back to Top