PickleBALLER/README.md

# 🏓 Pickleball ELO Tracker

> A powerful, modern web application for tracking pickleball player ratings using the **Glicko-2** rating system with separate rankings for singles and doubles play.

## 📋 Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Installation](#installation)
- [Usage](#usage)
- [API Endpoints](#api-endpoints)
- [Rating System](#rating-system)
- [License](#license)

---

## 🎯 Overview

The **Pickleball ELO Tracker** is a sophisticated rating management system designed specifically for pickleball communities. It leverages the **Glicko-2 rating algorithm** to provide accurate, dynamic player ratings that account for rating uncertainty and rating volatility. The system supports both singles and doubles matches, with separate rating tracks for each format.

Perfect for:
- 🏓 League organizers and tournament directors
- 👥 Recreational pickleball groups and clubs
- 📊 Player skill progression tracking
- ⚖️ Fair team composition and matchmaking

---

## ✨ Features

### 🎮 Player Management
- ➕ Add new players with names and email addresses
- ✏️ Edit player profiles and ratings
- 📊 View individual player statistics and match history
- 🗑️ Delete players and associated records

### 🏆 Match Recording
- 📝 Record singles and doubles matches
- 🎯 Automatic rating updates using Glicko-2 algorithm
- 🔍 View complete match history with details
- 🗑️ Delete matches with automatic rating recalculation
- 📈 Transparent rating change calculations

### 📋 Leaderboards
- 🥇 Separate rankings for singles and doubles
- 📊 Display player ratings, RD (rating deviation), and volatility
- 🔄 Real-time updates after each match
- 🌐 Both HTML and JSON API endpoints

### ⚙️ Team Balancer
- 🤝 Suggest balanced team compositions from available players
- 💡 Intelligent pairing based on player ratings
- 📊 Predict match outcomes with win probability
- 🎯 Perfect for tournament or session planning

### 📧 Session Management
- 📧 Create and manage pickleball sessions
- 👥 Assign players to sessions
- 📊 Preview session results and standings
- 💌 Send session summary emails to participants
- 📄 Email templating with detailed match statistics

### 📱 User Interface
- 🎨 Modern, responsive web interface
- 🌈 Beautiful gradient designs and intuitive navigation
- 📊 Data visualization with tables and statistics cards
- 🖱️ Seamless forms for all operations

---

## 🛠️ Tech Stack

| Component | Technology | Version |
|-----------|-----------|---------|
| **Language** | Rust | 2021 Edition |
| **Web Framework** | Axum | 0.7 |
| **Async Runtime** | Tokio | 1.x (full features) |
| **Database** | SQLite | Via sqlx 0.7 |
| **Templating** | Askama | 0.12 |
| **Serialization** | Serde | 1.0 |
| **Email** | Lettre | 0.11 |
| **CLI** | Clap | 4.0 |
| **Logging** | Tracing | 0.1 |

### Key Dependencies
- **tower** - Middleware and utilities
- **tower-http** - HTTP-specific middleware
- **chrono** - Date/time handling
- **anyhow** & **thiserror** - Error handling

---

## 📦 Installation

### Prerequisites
- **Rust** 1.70 or later ([Install Rust](https://www.rust-lang.org/tools/install))
- **SQLite** 3.x (usually pre-installed on macOS/Linux)
- **Cargo** (included with Rust)

### Clone the Repository

```bash
git clone https://github.com/yourusername/pickleball-elo.git
cd pickleball-elo
```

### Build from Source

#### Development Build
```bash
cargo build
```

#### Release Build (Recommended)
```bash
cargo build --release
```

The compiled binary will be located at:
- **Debug**: `target/debug/pickleball-elo`
- **Release**: `target/release/pickleball-elo`

### Database Setup

The application automatically initializes the SQLite database on first run:

```bash
# The database will be created at:
# /Users/split/Projects/pickleball-elo/pickleball.db
```

---

## 🚀 Usage

### Running the Server

```bash
# Development mode (debug build)
cargo run

# Release mode (optimized)
cargo run --release
```

### Default Configuration

- **URL**: `http://localhost:3000`
- **Port**: `3000`
- **Database**: `pickleball.db` (in project root)

### Running the Demo

To see a live demo with sample data:

```bash
cargo run --bin pickleball-elo -- --demo
```

This will populate the database with sample players and matches.

### Web Interface

Once the server is running, open your browser to:

```
http://localhost:3000
```

You'll see:
- 🏠 Dashboard with latest matches and stats
- 👥 Players list with all registered players
- 🏆 Leaderboards (singles & doubles)
- 🏓 Match history with full details
- ⚙️ Team balancer tool
- 📧 Session manager for tournaments/events

---

## 🔌 API Endpoints

All routes support both HTML (for web UI) and JSON (for API clients).

### Web Routes (HTML)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/` | Dashboard/home page |
| `GET` | `/leaderboard` | Leaderboard view (singles & doubles) |
| `GET` | `/players` | List all players |
| `GET` | `/players/new` | New player form |
| `POST` | `/players/new` | Create new player |
| `GET` | `/players/:id` | Player profile and stats |
| `GET` | `/players/:id/edit` | Edit player form |
| `POST` | `/players/:id/edit` | Update player details |
| `GET` | `/matches` | Match history view |
| `GET` | `/matches/new` | New match form |
| `POST` | `/matches/new` | Record new match |
| `POST` | `/matches/:id/delete` | Delete match |
| `GET` | `/balance` | Team balancer tool |
| `GET` | `/sessions` | Sessions list |
| `GET` | `/sessions/:id/preview` | Session preview |
| `POST` | `/sessions/:id/send` | Send session email |

### API Routes (JSON)

| Method | Endpoint | Description | Response |
|--------|----------|-------------|----------|
| `GET` | `/api/leaderboard` | Leaderboard data | JSON array of players with ratings |
| `GET` | `/api/players` | Players list | JSON array of all players |

### Response Examples

**GET /api/leaderboard**
```json
[
  {
    "id": 1,
    "name": "Alice Chen",
    "singles_rating": 1650.5,
    "singles_rd": 45.2,
    "singles_volatility": 0.062,
    "doubles_rating": 1580.3,
    "doubles_rd": 52.1,
    "doubles_volatility": 0.075,
    "matches_played": 24
  },
  ...
]
```

**GET /api/players**
```json
[
  {
    "id": 1,
    "name": "Alice Chen",
    "singles_rating": 1650.5,
    "doubles_rating": 1580.3
  },
  ...
]
```

---

## 🧮 Rating System

### Glicko-2 Overview

The **Glicko-2 rating system** is an advanced evolution of the Elo rating system that addresses several limitations:

- **Rating Deviation (RD)**: Measures the uncertainty in a player's rating
  - Low RD = High confidence in the rating
  - High RD = More uncertainty (needs more matches to stabilize)

- **Rating Volatility**: Measures how much a player's rating changes over time
  - High volatility = Inconsistent performer
  - Low volatility = Consistent performer

- **Automatic Decay**: If a player doesn't play for extended periods, their RD increases, reflecting the decay in confidence about their true skill level

### Separate Ratings

This tracker maintains **two independent rating tracks** per player:

#### 🎯 Singles Ratings
- Tracks performance in 1v1 matches
- Separate rating, RD, and volatility
- Useful for evaluating individual skill

#### 👥 Doubles Ratings
- Tracks performance in 2v2 matches
- Separate rating, RD, and volatility
- Accounts for team synergy and partner chemistry

### How Ratings Are Calculated

When a match is recorded:

1. **Match Outcome** is recorded (winner and loser)
2. **Glicko-2 Algorithm** processes:
   - Pre-match ratings and rating deviations
   - Expected outcome probability (based on pre-match ratings)
   - Actual outcome
   - Time since last match
3. **New Ratings** are calculated for all participants
4. **RD and Volatility** are updated to reflect the new certainty level

### Rating Changes

- **Large upset wins** → Bigger rating gain
- **Expected wins** → Smaller rating gain
- **Close matches** → Larger RD reduction (more certainty)
- **Inactive players** → RD increases (less certainty)

### Initial Ratings

New players start with:
- **Initial Rating**: 1500
- **Initial RD**: 350
- **Initial Volatility**: 0.06

These stabilize after the first several matches.

---

## 📧 Session & Email Features

### Creating Sessions

Sessions allow you to:
- 📅 Organize tournaments or regular play events
- 🎯 Assign specific players to the session
- 📊 Track results and generate leaderboards
- 💌 Email results to participants

### Email Templates

Session emails include:
- 📋 Complete match results
- 🏆 Final standings/leaderboard
- 📈 Rating changes for each player
- 👥 Player statistics

---

## 🐛 Development

### Project Structure

```
pickleball-elo/
├── src/
│   ├── main.rs              # Server & routes
│   ├── lib.rs               # Library exports
│   ├── db/                  # Database operations
│   ├── models/              # Data structures
│   ├── glicko/              # Glicko-2 implementation
│   │   ├── mod.rs
│   │   ├── calculator.rs    # Rating calculations
│   │   ├── rating.rs        # Rating structures
│   │   ├── doubles.rs       # Doubles-specific logic
│   │   └── score_weight.rs  # Scoring weights
│   ├── email/               # Email templates and sending
│   ├── handlers/            # Request handlers
│   ├── utils/               # Utility functions
│   └── bin/                 # Binary targets
├── Cargo.toml               # Project manifest
├── Cargo.lock               # Dependency lock file
└── pickleball.db            # SQLite database (auto-created)
```

### Running Tests

```bash
cargo test
```

### Building Documentation

```bash
cargo doc --open
```

---

## 📄 License

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

### MIT License Summary

You are free to:
- ✅ Use commercially
- ✅ Modify the source code
- ✅ Distribute the software
- ✅ Include it in private use

Conditions:
- 📋 Include the original copyright and license notice
- 📝 Document significant changes

---

## 🤝 Contributing

Contributions are welcome! To contribute:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📞 Support

For issues, questions, or feature requests, please open an issue on the repository.

---

## 🎉 Acknowledgments

- **Glicko-2 Algorithm**: Based on the work by [Mark Glickman](http://glicko.net/)
- **Axum Web Framework**: Ergonomic and modular web framework
- **SQLite**: Reliable, zero-configuration database

---

**Built with ❤️ for the pickleball community**