golf-score/docs/design.md

Golf Score Card App — Design Document

Overview

Single-page application (SPA) for tracking golf rounds with advanced statistics beyond basic score.

User Flow

1. Entry: User enters name and handicap (hcp). Authentication and user accounts will be added later.
2. Setup: Select golf course and tee box.
3. Round Start: Begin round; presented with Hole 1.
4. Hole Play: Record score and detailed stats per hole. User can skip a hole and return to complete it later.
5. Completion: Finish round and view summary statistics.

Core Features

• Basic Scoring: Strokes per hole, total score, relation to par.
• Hole Navigation: Skip holes; resume unfinished holes at any time during the round.
• Penalty Tracking: Record penalties with type:
  • Water
  • Out of Bounds (OB)
  • Lost ball
• Bunker Tracking: Record bunker shots with location:
  • Greenside
  • Fairway
• Advanced Putting Stats:
  • Count putts from green, foregreen, fringe, or other areas.
  • Prevent false "Green in Regulation" (GIR) calculations: if a player has one putt from off-green and one on-green, it should not count as GIR.
• Statistics Dashboard (post-round / live):
  • Fairways hit
  • Greens in Regulation (accurate, using putt location data)
  • Putts per round / per green
  • Penalty breakdown by type
  • Bunker saves / bunker shots by location
  • Scrambling stats

Additional Proposed Features

• Course Database: Pre-loaded courses with hole layouts, par, yardage, handicap ratings per tee.
• Live Round View: Current hole, running total, stats for holes played so far.
• Round History: Save completed rounds; compare stats over time.
• Export / Share: Export scorecard as image or PDF.
• Offline Support: Cache round data locally; sync when online.
• Future Auth: User login, handicap tracking, leaderboards.

Technology Stack

• Backend: Python (FastAPI or Flask) — REST API for courses, rounds, stats, and future authentication.
• Frontend: Lightweight vanilla JavaScript (or minimal framework like Alpine.js / Preact) — single HTML page with dynamic updates, no heavy build step required.
• Database: PostgreSQL or SQLite (for simplicity initially).
• Deployment: Containerized Python backend; static frontend served via CDN or same server.

Data Model (High Level)

• User (name, hcp — auth later)
• Course (name, location, holes[])
• TeeBox (course_id, name, rating, slope)
• Round (user_id, course_id, teebox_id, date, status)
• HoleScore (round_id, hole_number, strokes, skipped, completed)
• Penalty (hole_score_id, type: water/ob/lost)
• Bunker (hole_score_id, location: greenside/fairway)
• Putt (hole_score_id, location: green/foregreen/fringe/other)

Notes

• Keep frontend lightweight; avoid large frameworks.
• Design API endpoints to support partial hole updates (skip/resume).
• Ensure statistics calculations account for putt location to maintain accurate GIR logic.