# CLAUDE.md

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

## Project Overview

This is a lunar calendar converter (lunar-converter) that provides:
- Western (Gregorian) calendar ↔ Chinese lunar calendar conversion
- Historical era name conversions (Ming/Qing dynasties, Taiping Heavenly Kingdom, Japanese eras, Republic of China era)
- Age calculation (real age and East Asian nominal age)
- REST API for date conversion services

## Core Architecture

### Data Generation Pipeline

1. **`lunar_calendar.py`** - Astronomical calculation engine using Skyfield
   - Computes lunar calendar data from first principles using JPL ephemeris
   - Uses `de421.bsp` / `de422.bsp` / `de440s.bsp` ephemeris files (must exist in working directory)
   - Calculates new moons, solar terms (24 jieqi), and determines leap months
   - Generates ganzhi (sexagenary cycle) and zodiac animals
   - Output: yearly JSON files with complete lunar calendar mapping

2. **`generate_lunar_calendar_json.py`** - Batch generation script
   - Generates JSON files for multiple years in parallel using multiprocessing
   - Outputs to `lunar_json/{year}.json` directory
   - Usage: `python generate_lunar_calendar_json.py`

### Conversion Layer

3. **`converter.py`** - Primary conversion class using JSON data
   - `Converter.solar_to_lunar(date_str)` - Convert "YYYY-MM-DD" to lunar date info
   - `Converter.lunar_to_solar(year, month, day, leap=False)` - Reverse conversion
   - `Converter.get_leap_month(year)` - Return leap month number or None
   - Depends on `lunar_json/` directory containing pre-generated JSON files

### Historical Era Conversion

4. **`chrono_converter.py`** - Historical era name conversions
   - Converts Western dates to era names (Ming/Qing dynasties, Taiping, Minguo)
   - Contains era date ranges as class constants

5. **`converter_with_eras.py`** - Combined converter (CLI tool)
   - Merges lunar conversion with era name conversion
   - CLI usage: `python converter_with_eras.py solar2lunar YYYY-MM-DD`
   - CLI usage: `python converter_with_eras.py lunar2solar YYYY-MM-DD [--leap]`
   - CLI usage: `python converter_with_eras.py era YYYY-MM-DD`

### Applications

6. **`api.py`** - FastAPI REST API server
   - `GET /solar2lunar?date=YYYY-MM-DD` - Solar to lunar conversion
   - `GET /lunar2solar?date=YYYY-MM-DD` - Lunar to solar (handles leap months)
   - `GET /leap-info?year=YYYY` - Leap month info for a year
   - Runs on a dynamically-assigned free port

7. **`age_calculator.py`** - Age calculator using lunar calendar
   - Calculates "real age" (足歲) and "East Asian age" (虛歲)
   - Uses dependency injection pattern with `Converter`
   - Accurately handles leap month birthdays

## Common Commands

### Generate lunar calendar data (required before conversions work)
```bash
# Generate all years (1-2149, parallel processing)
python generate_lunar_calendar_json.py

# Generate single year
python lunar_calendar.py 2025
```

### Run conversions
```bash
# Solar to lunar
python -c "from converter import Converter; print(Converter().solar_to_lunar('2025-01-01'))"

# Lunar to solar
python -c "from converter import Converter; print(Converter().lunar_to_solar(2025, 1, 1))"

# Era conversion
python converter_with_eras.py era 1900-01-01
```

### Run API server
```bash
python api.py
```

### Run tests
```bash
pytest
```

## Important Notes

- **Ephemeris files**: The JPL ephemeris files (`de421.bsp`, `de422.bsp`, or `de440s.bsp`) are required for astronomical calculations. These must be present in the working directory. `lunar_calendar.py:92` selects which ephemeris to use.

- **Data dependency**: `converter.py` and dependent modules require pre-generated JSON files in `lunar_json/` directory. Generate these first using `generate_lunar_calendar_json.py` or `lunar_calendar.py`.

- **Calendar systems**: The code handles multiple calendar systems:
  - Gregorian (Western) calendar
  - Chinese lunar calendar (with leap months)
  - Historical era names (Chinese dynasties, Japanese eras)
  - Republic of China (Minguo) calendar

- **Timezone**: All calculations use UTC+8 (Taipei timezone) as defined in `LunarCalendar.TZ_OFFSET`.

- **Date ranges**:
  - Chinese eras defined in `converter_with_eras.py:15-31` (CHINESE_ERAS_SOLAR)
  - Japanese eras defined in `converter_with_eras.py:91-98` (JAPANESE_ERAS)
  - Taiping Heavenly Kingdom: 1851-02-01 to 1872-07-05