116 lines
6.7 KiB
Markdown
116 lines
6.7 KiB
Markdown
# ⛳ 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).
|