# Paper Dynasty Backend

FastAPI-based real-time baseball game engine with WebSocket support.

## Quick Start

```bash
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Apply database migrations
uv run alembic upgrade head

# Run server
uv run python -m app.main
```

## Database Migrations

This project uses [Alembic](https://alembic.sqlalchemy.org/) for database schema migrations.

### Initial Setup (New Database)

```bash
# Apply all migrations to create schema
uv run alembic upgrade head
```

### Creating New Migrations

```bash
# Auto-generate from model changes
uv run alembic revision --autogenerate -m "Description of changes"

# IMPORTANT: Always review the generated migration before applying!
# Then apply:
uv run alembic upgrade head
```

### Viewing Migration Status

```bash
# Show migration history
uv run alembic history

# Show current revision
uv run alembic current
```

### Rolling Back

```bash
# Rollback one migration
uv run alembic downgrade -1

# Rollback to specific revision
uv run alembic downgrade 001

# Rollback all (dangerous!)
uv run alembic downgrade base
```

### Migration Best Practices

1. **Always review auto-generated migrations** before applying - autogenerate is helpful but not perfect
2. **Test migrations on dev/staging** before production
3. **Keep migrations small and focused** - easier to rollback
4. **Never edit migrations that have been applied** to shared databases
5. **Include both upgrade and downgrade** for reversibility

### Existing Migrations

| Revision | Description |
|----------|-------------|
| 001 | Initial schema (games, plays, lineups, rolls, etc.) |
| 004 | Materialized views for statistics |

## Documentation

See `CLAUDE.md` for full documentation.