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