From 78cb2dc211782b3812ffda91a667733b2edb834c Mon Sep 17 00:00:00 2001
From: Samuel Enocsson <samuel.enocsson@consid.se>
Date: Sat, 21 Feb 2026 15:57:48 +0100
Subject: [PATCH] chore: Add CLAUDE.md project documentation

---
 CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..661b817
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# PDGA Rating Tracker
+
+PDGA rating scraper and display app. Scrapes player ratings and course data from pdga.com, stores in SQLite, serves via Express with EJS templates and HTMX.
+
+## Tech Stack
+
+- **Runtime:** Node.js 18 (Alpine in Docker)
+- **Server:** Express with EJS templates
+- **Database:** SQLite3 (file: `ratings.db`, Docker: `/app/data/ratings.db`)
+- **Frontend:** HTMX + vanilla JS (in `public/js/`)
+- **Scraping:** Puppeteer (with stealth plugin) + direct HTTP
+- **Logging:** Pino (JSON in production, pino-pretty in dev)
+- **CI/CD:** Release Please + Docker build/push to GHCR
+
+## Project Structure
+
+```
+server.js              # Express app entrypoint
+src/
+  logger.js            # Pino logger instance
+  db.js                # SQLite init, migrations, seeding
+  models/              # Data access (player.js, course.js)
+  routes/              # Express routes (players, courses, pages)
+  scrapers/            # PDGA scrapers (HTTP + Puppeteer)
+  services/            # Business logic (player-service, rating-calculator)
+views/
+  pages/               # EJS page templates
+  partials/            # EJS partials (shared layout)
+public/
+  css/                 # Stylesheets
+  js/                  # Client-side JS (HTMX interactions)
+```
+
+## Commands
+
+- `npm start` — Start production server (port 3000)
+- `npm run dev` — Start with nodemon (auto-reload)
+- `LOG_LEVEL=debug npm start` — Enable debug logging
+- `docker compose up` — Run via Docker
+
+## Conventions
+
+- **Logging:** Use `require('./logger')` (or relative path). Never use `console.log/error` in backend code. Use appropriate Pino levels: `debug` for verbose/diagnostic data, `info` for operational status, `warn` for retries/degraded state, `error` for failures, `fatal` for startup crashes.
+- **Frontend JS:** `console.error` is fine in `public/js/` — runs in browser, no Pino.
+- **Commits:** Conventional commits (`feat:`, `fix:`, `refactor:`, `chore:`) — drives release-please.
+- **Scraping:** Two strategies per entity: direct HTTP (fast, preferred) with Puppeteer fallback (stealth plugin for anti-bot). Rate limiting must be respected.
+- **Database:** Migrations run automatically on startup in `db.js`. Schema changes go there.
+- **Templates:** EJS with shared layout in `views/partials/`. Pages use HTMX for dynamic content loading.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOG_LEVEL` | `info` | Pino log level |
+| `NODE_ENV` | — | Set to `production` for JSON logs |
+| `DB_PATH` | `./ratings.db` | SQLite database path |
+| `PUPPETEER_EXECUTABLE_PATH` | — | Chromium path (set in Docker) |