CLAUDE.md

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

Project Overview

This is a baseball card creation system for Paper Dynasty, a sports card simulation game. The system pulls real baseball statistics from FanGraphs and Baseball Reference, processes them through calculation algorithms, and generates statistical cards for players. All generated data is POSTed directly to the Paper Dynasty API, and cards are dynamically generated when accessed via card URLs (cached by nginx gateway).

Key Architecture Components

Core Modules

batters/: Batting card creation with rating calculations (calcs_batter.py) and card generation (creation.py)
pitchers/: Pitching card creation with ERA/WHIP calculations (calcs_pitcher.py) and card generation (creation.py)
defenders/: Defensive rating calculations and fielding card generation (calcs_defense.py, creation.py)
db_calls.py: Paper Dynasty API interface with authentication and CRUD operations
creation_helpers.py: Shared utilities including D20 probability tables, stat normalization, and data sanitization

Data Flow

Input: CSV files from FanGraphs/Baseball Reference placed in data-input/[Year] [Type] Cardset/
Processing: Statistics are normalized using league averages and converted to D20-based game mechanics
Output: Generated card data is POSTed directly to Paper Dynasty API; cards rendered on-demand when URLs accessed

Entry Points

live_series_update.py: Main script for live season card updates (in-season cards)
retrosheet_data.py: Main script for historical replay cardsets
refresh_cards.py: Updates existing player card images and metadata
check_cards.py: Validates card data and generates test outputs
scouting_batters.py / scouting_pitchers.py: Generate scouting reports and ratings comparisons

Common Commands

Testing

pytest                    # Run all tests
pytest tests/test_*.py    # Run specific test file

Card Generation

python live_series_update.py     # Generate live series cards
python retrosheet_data.py        # Generate historical replay cards
python refresh_cards.py          # Update existing card images
python check_cards.py            # Validate card data

Scouting Reports

python scouting_batters.py       # Generate batting scouting data
python scouting_pitchers.py      # Generate pitching scouting data

Data Input Requirements

FanGraphs Data (place in data-input/[YEAR] [TYPE] Cardset/)

vlhp-basic.csv / vlhp-rate.csv: vs Left-handed Pitching stats
vrhp-basic.csv / vrhp-rate.csv: vs Right-handed Pitching stats
vlhh-basic.csv / vlhh-rate.csv: vs Left-handed Hitting stats
vrhh-basic.csv / vrhh-rate.csv: vs Right-handed Hitting stats

Baseball Reference Data

running.csv: Baserunning statistics
pitching.csv: Standard pitching statistics

Minimum Playing Time Thresholds

Live Series: 20 PA vs L / 40 PA vs R (batters), 20 TBF vs L / 40 TBF vs R (pitchers)
Season Cards: 50 PA vs L / 75 PA vs R (batters), 50 TBF vs L / 75 TBF vs R (pitchers)

Configuration

Database Settings (db_calls.py)

Production: https://pd.manticorum.com/api
Development: https://pddev.manticorum.com/api
Change alt_database variable to switch environments

Live Series Settings (live_series_update.py)

SEASON: Current year for live updates
CARDSET_NAME: Target cardset (e.g., "2025 Live")
GAMES_PLAYED: Season progress for live series calculations
IGNORE_LIMITS: Override minimum playing time requirements

Important Notes

The system uses D20-based probability mechanics where statistics are converted to chances out of 20
Cards are generated with both basic stats and advanced metrics (OPS, WHIP, etc.)
Defensive ratings use zone-based fielding statistics from Baseball Reference
All player data flows through Paper Dynasty's API with bearer token authentication
Cards are dynamically rendered when accessed via URL, with nginx caching for performance

4.1 KiB Raw Blame History