diff --git a/No existing repo files need editing.docs/design.md b/No existing repo files need editing.docs/design.md
new file mode 100644
index 0000000..cfe064d
--- /dev/null
+++ b/No existing repo files need editing.docs/design.md	
@@ -0,0 +1,61 @@
+# 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.