# ⛳ PinPoint Golf: Smart Scorecard, GPS Rangefinder & Shot Tracker

A modern, tournament-grade golf scorecard and performance tracking web application built with **React 19**, **TypeScript**, **Tailwind CSS v4**, **Node.js Express**, and **Google Maps Platform**.

PinPoint Golf goes far beyond basic stroke scoring, providing granular stats tracking, GPS-assisted green rangefinding, worldwide course discovery via public APIs, custom course building, career achievements, and **user authentication with community benchmark analytics**.

---

## ✨ Features Overview

### 1. 👤 User Authentication & Cloud Synchronization
- **Local Authentication**: Register and log in with email, username, and secure password hashing (`bcryptjs`).
- **OAuth & Single Sign-On (SSO)**:
  - **Google Login**: Google OAuth 2.0 integration.
  - **Authentik (OIDC)**: Direct support for homelab setups, enterprise IdPs, and Keycloak via OIDC.
  - **GitHub**: One-click developer OAuth sign in.
- **Persistent Cloud Database**: All rounds, customized tracking settings, and custom courses are saved in a durable database (`pinpoint_db.json`) tied to the golfer's user account.
- **Offline-First & Auto-Sync**: Continue playing offline seamlessly; when connected or logging in, offline rounds automatically sync to your cloud account.

### 2. 🌍 Community Benchmark & Public Leaderboard
- **Public vs. Private Privacy Control**: Easily toggle your scorecard visibility in your profile.
- **Head-to-Head Comparison Matrix**: Compare your **Scoring Average**, **FIR %**, **GIR %**, **Putts Per Round**, **Scrambling %**, **Sand Saves**, and **Penalty Strokes** against:
  - Global Community Averages across thousands of recorded rounds.
  - Your specific Handicap Bracket (**Scratch < 5**, **Mid-Cap 5–15**, **High-Cap > 15**).
  - Calculated **Percentile Rankings (0–100%)** with automated coaching insights highlighting your best scoring leverage areas.
- **Public Golfers Leaderboard**: Global leaderboard filtered by handicap division, displaying verified rounds, lowest gross scores, and key stats.

### 3. 📊 Deep Stats & Scoring Engine
- **Customizable Stat Switchboard**: Turn any stat on or off anytime with instant UI adaptation.
- **Fairway in Regulation (FIR)**: Center Hit, Miss Left ⬅, Miss Right ➡, Miss Short ⬇ (automatically marked N/A on Par 3s).
- **Green in Regulation (GIR)**: Green Hit vs Missed, with approach miss direction dispersal (Short, Long, Left, Right).
- **Official Putts (On Green)**: Fast touch steppers for putts taken on the putting green surface.
- **Foregreen / Fringe Putts (Off Green)**: Tracks putter strokes taken from the collar/fringe separately from official green putts (in compliance with USGA/R&A rules).
- **Bunker Encounters**: Distinguishes **Fairway Bunkers** from **Greenside Bunkers** and tracks **Sand Save** conversion.
- **Detailed Penalties**: Categorizes penalty strokes into **Water/Hazard 💧**, **Out of Bounds (OB) ⚪**, **Lost Ball 🔍**, and **Unplayable Lie ⚠️**.
- **Scrambling & Up & Down**: Automatically tracks par saves following missed greens in regulation.
- **Metric by Default**: Distances in **Meters**, putts in **Meters**, temperatures in **Celsius**, and wind in **km/h** (toggleable to Imperial yards/feet in settings).

### 4. ⛅ Real-Time Weather Forecast (Open Weather API)
- **Live GPS Meteorological Conditions**: Before starting a round, retrieves current conditions using the open-source Open-Meteo meteorological API based on the golfer's live GPS coordinates.
- **Key Golf Weather Metrics**:
  - **Temperature**: Displayed in Celsius (°C) and Fahrenheit (°F) with apparent feels-like temperature.
  - **Wind Speed & Direction**: Real-time wind speed in **km/h**, 16-point directional compass heading (e.g. `SW 230°`), and automatic classification (`Calm`, `Breezy`, `Strong`, `Gusty`).
  - **Precipitation Probability**: Hourly rain probability percentage with a visual risk bar (low, moderate, high chance).
  - **Dual Source Mode**: Toggle between **My GPS** and **Course GPS** with a 1-click refresh.
- **Round Snapshot**: Conditions are saved directly with the scorecard and displayed on the digital scorecard and history logs.

### 5. 🛰️ Google Maps Satellite & GPS Rangefinder
- **Live GPS Green Distance**: Real-time high-accuracy distance to the **Front Edge**, **Center / Pin Flag**, and **Back Edge** of the green.
- **High-Contrast Digital HUD**: Sunlight-legible Bushnell/Garmin-style readout.
- **Automatic Hole Detection**: Detects which hole you are standing on based on GPS coordinates and fairway corridor proximity.
- **Shot Distance Measurement**: Mark your ball's origin at the tee and walk to measure your exact drive distance in meters.
- **Demo / Simulation Mode**: Built-in simulator allows testing green distances and hole transitions indoors or on desktop.

### 6. 🗺️ Worldwide Golf Course Directory & Custom Course Builder
- **OpenGolfAPI Integration**: Search and import official scorecards and pars from a directory of **32,000+ golf courses worldwide**.
- **Custom Course Creator**: Build any 9 or 18-hole course with custom Pars, Yardages/Meters, and Handicap indices.
- **Duplicate & Modify**: 1-click clone and modify any existing or imported course to match your local club's current tee setup.

### 7. 🏆 Career Trophies & Achievements
- **Automated Milestone Engine**: Automatically evaluates all played rounds to unlock 23 achievements across 4 tiers (Bronze, Silver, Gold, Platinum), from *Century Broken (Break 100)* to *Ace in the Hole (Hole-in-One)* and *Drove the Green*.

---

## 🚀 Quick Start (Local Development)

### 1. Clone & Install Dependencies
```bash
git clone <repository-url>
cd pinpoint-golf
npm install
```

### 2. Configure Environment Variables
Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```
Add your Google Maps API key and optional OAuth credentials:
```env
VITE_GOOGLE_MAPS_API_KEY="AIzaSy..."
JWT_SECRET="your_secret_key"
```

### 3. Start Full-Stack Dev Server
```bash
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) in your browser.

---

## 🐳 Docker Deployment

The application includes an optimized multi-stage `Dockerfile` and `docker-compose.yaml` configured with persistent volume storage for the database.

### Using Docker Compose (Recommended)

1. Build and launch the container:
   ```bash
   docker compose up -d --build
   ```

2. Access the application at [http://localhost:3000](http://localhost:3000).

3. Verify health status:
   ```bash
   curl http://localhost:3000/healthz
   # Output: healthy
   ```

---

## 📖 Further Development & Future Roadmap
For complete architecture specifications and the future roadmap (Strokes Gained, WHS Handicap Calculator, Live Matchplay), see the [Developer Guide](DEVELOPER_GUIDE.md).