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:

python generate_report.py

Generate report with modern style:

python generate_report.py --style glassmorphism --output report.html
python generate_report.py --style brutalism --output report.html
python generate_report.py --style neumorphism --output report.html

Generate report with legacy Platinum template:

python generate_report.py --template templates/platinum.html --output report.html

All options:

python generate_report.py --db pga.db --output report.html --top 10 --background background.png --style glassmorphism

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/):

• modern.html: Unified template for modern styles (brutalism, glassmorphism, neumorphism)
• platinum.html: Legacy Mac OS 9 Platinum visual style (separate template due to unique structure)
• All templates use Chart.js doughnut charts and dynamic JavaScript filtering
• Placeholder tokens like __ALL_GAMES__, __BACKGROUND_IMAGE__ are replaced at generation time
• Modern templates support light/dark/auto theme toggle button

Style system (styles.py):

• CSS definitions for each modern style (brutalism, glassmorphism, neumorphism)
• Theme configurations (colors, fonts, chart options) injected via __THEME_CSS__
• Use --style argument to select a modern style instead of --template

Javascript (templates/script.js):

• A single common script is used for each modern style (brutalism, glassmorphism, neumorphism)
• Theme configurations (colors, fonts, chart options) injected via __THEME_CONFIG__
• Data inserted via __ALL_GAMES__ and __TOP_N__

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