Lutris-Playtime-Report-Generator/CLAUDE.md

# CLAUDE.md

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

## Project Overview

Lutris Year in Review is a Python script that generates a static HTML playtime report from a Lutris gaming platform SQLite database. The report displays game playtime statistics with interactive Chart.js visualizations.

## Commands

Generate report with defaults:
```bash
python generate_report.py
```

Generate report with custom options:
```bash
python generate_report.py --db pga.db --output report.html --top 10 --background background.png --template templates/platinum.html
```

## Architecture

**Report generator (`generate_report.py`):**
- Reads Lutris SQLite database (`pga.db`) containing games, categories, and playtime data
- Embeds all data (games JSON, background image as base64) directly into a self-contained HTML file
- Loads HTML template from `templates/` folder (default: `templates/platinum.html`)

**HTML templates (`templates/`):**
- **platinum.html**: Mac OS 9 Platinum visual style
- **brutalism.html**: Bold industrial brutalist design with hard shadows
- **glassmorphism.html**: Modern frosted glass effect
- **neumorphism.html**: Soft 3D neumorphic style
- All templates use Chart.js doughnut charts and dynamic JavaScript filtering
- Placeholder tokens like `__ALL_GAMES__`, `__BACKGROUND_IMAGE__` are replaced at generation time
- Support light/dark mode with theme toggle button

**Database schema (`schema.py`):**
- Reference file documenting Lutris database structure
- Key tables: `games` (with `playtime`, `service` fields), `categories`, `games_categories` (many-to-many join)

**Generated output (`report.html`):**
- Fully static, can be hosted on any web server
- Client-side filtering by service (Steam, GOG, itch.io, local)
- Expandable "Others" row in games table
- Light/dark/auto theme toggle button with persistent preference
- Responsive design for mobile and desktop

## Key Data Relationships

- Games have a `service` field (steam, gog, itchio, humblebundle, or NULL for local)
- Games link to categories via `games_categories` join table
- Categories like `.hidden` and `favorite` are filtered out in the report display
- `playtime` is cumulative hours (REAL), not per-session data