# 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
1. **Input**: CSV files from FanGraphs/Baseball Reference placed in `data-input/[Year] [Type] Cardset/`
2. **Processing**: Statistics are normalized using league averages and converted to D20-based game mechanics
3. **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
```bash
pytest                    # Run all tests
pytest tests/test_*.py    # Run specific test file
```

### Card Generation
```bash
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
```bash
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