# Project Kempe - Fantasy Hockey Backend

A CLEAN architecture backend application for managing and analyzing Yahoo Fantasy Hockey teams using NHL live data.

## Architecture

This application follows CLEAN architecture principles with clear separation of concerns:

```
src/
├── domain/              # Enterprise business rules
│   ├── entities/        # Core business entities
│   └── repositories/    # Repository interfaces (ports)
├── application/         # Application business rules
│   ├── use_cases/       # Use case implementations
│   └── dto/             # Data Transfer Objects
├── infrastructure/      # Frameworks and drivers
│   ├── adapters/        # External service adapters
│   │   ├── nhl/         # NHL API implementation
│   │   └── yahoo_fantasy/ # Yahoo Fantasy API implementation
│   ├── database/        # Database models and repositories
│   └── config/          # Configuration management
└── presentation/        # Interface adapters
    └── api/             # FastAPI routes and controllers
```

## Key Design Principles

- **Dependency Inversion**: Core business logic depends on abstractions, not implementations
- **Separation of Concerns**: Each layer has a single, well-defined responsibility
- **Testability**: Business logic can be tested without external dependencies
- **Swappable Adapters**: Data sources (NHL API, Yahoo Fantasy API) can be replaced without changing business logic

## Technology Stack

- **Framework**: FastAPI
- **Database**: PostgreSQL
- **Language**: Python 3.11+
- **Data Sources**:
  - NHL Unofficial API (via nhl-api-py)
  - Yahoo Fantasy Sports API (via yfpy)

## Setup

### Prerequisites
- Python 3.11 or higher
- PostgreSQL 14 or higher
- Yahoo Developer Account (for Fantasy API access)

### Installation

1. Clone the repository:
```bash
cd /Users/michaelsimard/dev/services/project-kempe-backend
```

2. Create and activate a virtual environment:
```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install dependencies:
```bash
pip install -r requirements.txt
```

4. Configure environment variables:
```bash
cp .env.example .env
# Edit .env with your actual credentials
```

5. Set up the database:
```bash
# Create PostgreSQL database
createdb fantasy_hockey

# Run migrations (once implemented)
alembic upgrade head
```

### Running the Application

Development server:
```bash
uvicorn src.presentation.api.main:app --reload --host 0.0.0.0 --port 8000
```

The API will be available at:
- Base URL: http://localhost:8000
- Interactive docs: http://localhost:8000/docs
- Alternative docs: http://localhost:8000/redoc

## Development

### Running Tests
```bash
pytest tests/ -v
pytest tests/ --cov=src --cov-report=html
```

### Code Quality
```bash
# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/
```

### Project Structure
See [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architecture documentation.

## API Documentation

Once running, visit http://localhost:8000/docs for interactive API documentation.