# Handicap Engine

WHS-compliant golf handicap calculation platform for golfers and developers.

## What this platform does

Handicap Engine calculates golf Handicap Indexes according to the World Handicap System (WHS) Rules of Handicapping as published by R&A and USGA. It implements:

- Score Differential calculation: `(Score − Course Rating) × 113 / Slope Rating`
- Handicap Index calculation: arithmetic mean of the best 8 Score Differentials from the most recent 20 rounds, multiplied by 0.96
- Course Handicap: `ROUND(Handicap Index × (Slope Rating / 113) + (Course Rating − Par))`
- Playing Handicap, Exceptional Score Reduction (ESR, WHS §5.9), soft and hard caps
- 9-hole round support with Expected Score normalization (WHS §3.1)

## Key URLs

- Landing page: /
- Guest calculator (no registration required): /rechner/
- Authenticated app: /app/
- REST API documentation (human-readable): /api/
- Interactive API explorer: /api/docs/
- OpenAPI specification (machine-readable): /api/openapi.yaml

## REST API summary

The API is versioned at /v1/. Key public endpoints (no authentication):
- GET /v1/courses?q={search_term} — search golf courses with Course Rating and Slope Rating data
- GET /v1/courses/{courseId} — retrieve full course details including tee sets and ratings
- GET /v1/health — service health status

Authenticated endpoints require a Bearer JWT token from POST /v1/auth/login.

## WHS terminology reference

| Term | German | Formula |
|---|---|---|
| Handicap Index | Handicap Index | best 8 of 20 differentials × 0.96 |
| Score Differential | Score Differential | (AGS − CR) × 113 / SR |
| Adjusted Gross Score | Adjusted Gross Score (AGS) | gross score with Net Double Bogey cap |
| Course Rating | Course Rating | expected score for scratch golfer |
| Slope Rating | Slope Rating | relative difficulty vs. scratch (113 = standard) |
| Course Handicap | Course Handicap | HI × (SR / 113) + (CR − Par) |

## Standards compliance

- World Handicap System (WHS) Rules of Handicapping, effective 2024
- R&A / USGA joint governance