# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Is

Skins&Pins is a social golf score tracking PWA. Multiple players in a group track scores per hole in real-time. Anyone in a group can enter or edit scores for any player. Built as a self-hosted Python app running in Docker Compose with a single SQLite database and traefik as a Proxy. The PWA has optimizations for Mobile use.

## Language

All backend code must be written in Python. Do not introduce other backend languages.

## Features

- **Navigation:** Bottom navigation bar with large icons, optimized for thumb reach on mobile
- **Authentication:** Passwordless login via magic link (email weblink); in development the magic link is printed to the log instead of being emailed
- **Admin user:** Single admin user defined by email address in the `.env` file; has access to an additional Admin menu not visible to regular users
- **User invitations:** Admin invites users by email address via the Admin menu; only invited users can log in
- **Onboarding:** On first login, user sets their Name, Handicap, and Avatar
- **Profile:** Name, Handicap, and Avatar can be updated at any time via a Profile menu
- **Dashboard:** Landing page after login; shows the user's last played rounds/games with results and statistics derived from game data (e.g. scores, skins won, handicap trend, best/worst holes)
- **Game formats:** Architecture must support multiple formats. Only one format is implemented initially: Bingo Bango Bongo
- **Round length:** Players choose 9 or 18 holes when starting a game
- **Hole skipping:** Players can skip a hole; skipped holes are excluded from scoring
- **Score entry UI:** A swipe gesture toggles between the score entry view (current hole) and the score overview (all holes, running totals)

## Game Format: Bingo Bango Bongo

Three points are available per hole:
- **Bingo:** First player to get their ball on the green
- **Bango:** Player whose ball is closest to the pin once all balls are on the green; if multiple players are equidistant the point is split equally between them — Bango must support awarding fractional points to multiple players
- **Bongo:** First player to hole out

Players play in order of furthest from the hole (standard golf rules). Any number of players can participate. Points are tallied across all 18 holes; highest total wins.

## Design Principles

- Simple and clean — prefer straightforward solutions over clever ones
- No unnecessary functions, abstractions, or helpers
- Only build what is needed for the current feature; do not design for hypothetical future requirements

## Stack

- **Backend:** FastAPI (async, ASGI via Uvicorn)
- **Database:** SQLite
- **Frontend:** HTMX + Alpine.js + Jinja2 templates (no build step, no npm)
- **Real-time:** WebSocket for live score updates across players in the same group