admin/PinPoint-Golf
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity
Files
3ec61915f72eac5d87f22ed2bb5f82016420bf2f
PinPoint-Golf/README.md
T

6.7 KiB
Raw Blame History

⛳ 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

git clone <repository-url>
cd pinpoint-golf
npm install

2. Configure Environment Variables

Copy .env.example to .env:

cp .env.example .env

Add your Google Maps API key and optional OAuth credentials:

VITE_GOOGLE_MAPS_API_KEY="AIzaSy..."
JWT_SECRET="your_secret_key"

3. Start Full-Stack Dev Server

npm run dev

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

    docker compose up -d --build

  2. Access the application at http://localhost:3000.

  3. Verify health status:

    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.

Reference in new issue View Git Blame Copy Permalink