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
• Features
• Tech Stack
• Installation
• Usage
• API Endpoints
• Rating System
• 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)
• SQLite 3.x (usually pre-installed on macOS/Linux)
• Cargo (included with Rust)

Clone the Repository

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

Build from Source

Development Build

cargo build

Release Build (Recommended)

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:

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

---

🚀 Usage

Running the Server

# 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:

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

[
  {
    "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

[
  {
    "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

cargo test

Building Documentation

cargo doc --open

---

📄 License

This project is licensed under the MIT License - see the 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
• Axum Web Framework: Ergonomic and modular web framework
• SQLite: Reliable, zero-configuration database

---

Built with ❤️ for the pickleball community