# Architecture Documentation

## CLEAN Architecture Overview

This application implements CLEAN architecture principles to ensure maintainability, testability, and flexibility.

## Layer Responsibilities

### 1. Domain Layer (`src/domain/`)
**Purpose**: Contains enterprise business rules and core entities.

- **Entities** (`entities/`): Core business objects that represent the problem domain
  - `Player`: NHL player information
  - `SkaterStats`, `GoalieStats`: Player statistics
  - `NHLTeam`: NHL team information
  - `FantasyTeam`: Yahoo Fantasy team data

- **Repository Interfaces** (`repositories/`): Abstract contracts for data access
  - `PlayerRepository`: Interface for player data operations
  - `TeamRepository`: Interface for team data operations
  - `FantasyRepository`: Interface for fantasy team operations

**Dependencies**: None. This layer is completely independent.

### 2. Application Layer (`src/application/`)
**Purpose**: Contains application-specific business rules.

- **Use Cases** (`use_cases/`): Application business logic
  - `GetPlayerStatsUseCase`: Example use case for retrieving player statistics
  - Future: `AnalyzeFantasyRosterUseCase`, `ComparePlayersUseCase`, etc.

- **DTOs** (`dto/`): Data transfer objects for cross-layer communication

**Dependencies**: Depends only on Domain layer abstractions.

### 3. Infrastructure Layer (`src/infrastructure/`)
**Purpose**: Contains implementations of external interfaces and frameworks.

- **Adapters** (`adapters/`): Implementations of repository interfaces
  - `nhl/NHLPlayerAdapter`: Implements PlayerRepository using nhl-api-py
  - `nhl/NHLTeamAdapter`: Implements TeamRepository using nhl-api-py
  - `yahoo_fantasy/YahooFantasyAdapter`: Implements FantasyRepository using yfpy

- **Database** (`database/`): Database models and ORM configurations
- **Config** (`config/`): Application configuration and settings

**Dependencies**: Implements Domain interfaces using external libraries.

### 4. Presentation Layer (`src/presentation/`)
**Purpose**: Contains API routes and controllers.

- **API Routes** (`api/routes/`): FastAPI endpoint definitions
- **Dependencies** (`api/dependencies.py`): Dependency injection configuration

**Dependencies**: Uses Application use cases and Infrastructure implementations.

## Dependency Flow

```
Presentation Layer
       ↓
Application Layer
       ↓
Domain Layer (Abstractions)
       ↑
Infrastructure Layer (Implementations)
```

**Key Principle**: Dependencies point inward. Outer layers depend on inner layers, never the reverse.

## Swapping Data Sources

To replace the NHL API with a different data source:

1. Create a new adapter implementing `PlayerRepository` or `TeamRepository`
2. Update the dependency injection in `src/presentation/api/dependencies.py`
3. **No changes required** to domain entities, use cases, or API routes

Example:

```python
# In dependencies.py
def get_player_repository() -> PlayerRepository:
    # Change this line to use a different implementation
    return AlternativePlayerAdapter()  # Instead of NHLPlayerAdapter()
```

## Testing Strategy

- **Unit Tests**: Test domain entities and use cases in isolation
- **Integration Tests**: Test adapters against real or mocked external APIs
- **API Tests**: Test FastAPI routes using TestClient

All business logic can be tested without external dependencies by using mock repository implementations.