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:

cd /Users/michaelsimard/dev/services/project-kempe-backend

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Configure environment variables:

cp .env.example .env
# Edit .env with your actual credentials

5. Set up the database:

# Create PostgreSQL database
createdb fantasy_hockey

# Run migrations (once implemented)
alembic upgrade head

Running the Application

Development server:

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

pytest tests/ -v
pytest tests/ --cov=src --cov-report=html

Code Quality

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

Project Structure

See ARCHITECTURE.md for detailed architecture documentation.

API Documentation

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