# mkreiser/espn-fantasy-football-api architecture

> Architecture diagram of the GitHub repository mkreiser/espn-fantasy-football-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mkreiser/espn-fantasy-football-api
- Repository: https://github.com/mkreiser/espn-fantasy-football-api

## Overview

This is a JavaScript client for retrieving ESPN Fantasy Football v3 data and mapping responses into usable objects. The primary workflow is: a consumer calls the Client with league and season parameters; the Client requests ESPN data and returns domain models such as teams, matchups, draft picks, and free agents. Models parse nested player and statistics data, with shared base classes providing response mapping and caching. The README also documents private-league support, which is Node-only. Some client methods and model details were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`src/client/client.js`](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/client/client.js) (Client), [`src/player/player.js`](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player/player.js) (NFL Player), [`src/base-classes/base-object/base-object.js`](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/base-classes/base-object/base-object.js) (Response Mapper), [`src/player-stats/player-stats.js`](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player-stats/player-stats.js) (Player Statistics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client and API"]
  node_client["Client<br/>[client.js]"]
end

subgraph group_league["League Data"]
  node_league_model["League Settings<br/>[league.js]"]
  node_team["Fantasy Team<br/>[team.js]"]
  node_boxscore["Matchup Boxscore<br/>[boxscore.js]"]
  node_boxscore_player["Boxscore Player<br/>[boxscore-player.js]"]
  node_nfl_game["NFL Game<br/>[nfl-game.js]"]
end

subgraph group_players["Player Data"]
  node_draft_player["Draft Pick<br/>[draft-player.js]"]
  node_free_agent["Free Agent"]
  node_player["NFL Player<br/>[player.js]"]
  node_player_stats["Player Statistics<br/>[player-stats.js]"]
end

subgraph group_foundation["Mapping Foundation"]
  node_base_object["Response Mapper<br/>[base-object.js]"]
  node_cacheable["Cacheable Objects"]
  node_constants["API Mappings<br/>[constants.js]"]
  node_utils["Mapping Utility<br/>[utils.js]"]
end

node_consumer(("API Consumer"))
node_espn["ESPN API"]

node_consumer -->|"calls"| node_client
node_client -->|"requests data"| node_espn
node_client -->|"builds matchups"| node_boxscore
node_client -->|"builds league data"| node_league_model
node_client -->|"builds teams"| node_team
node_client -->|"builds draft picks"| node_draft_player
node_client -->|"builds free agents"| node_free_agent
node_client -->|"builds game data"| node_nfl_game
node_boxscore -->|"builds roster players"| node_boxscore_player
node_boxscore_player -->|"extends"| node_player
node_boxscore_player -->|"parses stats"| node_player_stats
node_team -->|"builds roster"| node_player
node_draft_player -->|"extends"| node_player
node_draft_player -->|"parses stats"| node_player_stats
node_free_agent -->|"uses player model"| node_player
node_free_agent -->|"uses stats parser"| node_player_stats
node_cacheable -->|"extends"| node_base_object
node_player -->|"extends"| node_cacheable
node_team -->|"extends"| node_cacheable
node_league_model -->|"extends"| node_base_object
node_boxscore -->|"extends"| node_base_object
node_nfl_game -->|"extends"| node_base_object
node_player_stats -->|"extends"| node_base_object
node_base_object -->|"flattens data"| node_utils
node_player -->|"maps identifiers"| node_constants
node_league_model -->|"maps settings"| node_constants
node_player_stats -->|"maps scoring"| node_constants

click node_client "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/client/client.js"
click node_league_model "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/league/league.js"
click node_team "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/team/team.js"
click node_boxscore "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/boxscore/boxscore.js"
click node_boxscore_player "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/boxscore-player/boxscore-player.js"
click node_draft_player "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/draft-player/draft-player.js"
click node_free_agent "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/free-agent-player/free-agent-player.js"
click node_player "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player/player.js"
click node_player_stats "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player-stats/player-stats.js"
click node_nfl_game "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/nfl-game/nfl-game.js"
click node_base_object "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/base-classes/base-object/base-object.js"
click node_cacheable "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/base-classes/base-cacheable-object/base-cacheable-object.js"
click node_constants "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/constants.js"
click node_utils "https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/utils.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_client toneBlue
class node_league_model,node_team,node_boxscore,node_boxscore_player,node_nfl_game toneAmber
class node_draft_player,node_free_agent,node_player,node_player_stats,node_consumer,node_espn toneMint
class node_base_object,node_cacheable,node_constants,node_utils toneRose
```

## Components

### Client and API

- [Client](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/client/client.js): `src/client/client.js`

### League Data

- [League Settings](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/league/league.js): `src/league/league.js`
- [Fantasy Team](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/team/team.js): `src/team/team.js`
- [Matchup Boxscore](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/boxscore/boxscore.js): `src/boxscore/boxscore.js`
- [Boxscore Player](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/boxscore-player/boxscore-player.js): `src/boxscore-player/boxscore-player.js`
- [NFL Game](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/nfl-game/nfl-game.js): `src/nfl-game/nfl-game.js`

### Player Data

- [Draft Pick](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/draft-player/draft-player.js): `src/draft-player/draft-player.js`
- [Free Agent](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/free-agent-player/free-agent-player.js): `src/free-agent-player/free-agent-player.js`
- [NFL Player](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player/player.js): `src/player/player.js`
- [Player Statistics](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/player-stats/player-stats.js): `src/player-stats/player-stats.js`

### Mapping Foundation

- [Response Mapper](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/base-classes/base-object/base-object.js): `src/base-classes/base-object/base-object.js`
- [Cacheable Objects](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/base-classes/base-cacheable-object/base-cacheable-object.js): `src/base-classes/base-cacheable-object/base-cacheable-object.js`
- [API Mappings](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/constants.js): `src/constants.js`
- [Mapping Utility](https://github.com/mkreiser/espn-fantasy-football-api/blob/main/src/utils.js): `src/utils.js`

### Other components

- **API Consumer**
- **ESPN API**

## Connections

- API Consumer → Client: calls (evidence: `README.md`)
- Client → ESPN API: requests data (evidence: `src/client/client.js`)
- Client → Matchup Boxscore: builds matchups (evidence: `src/client/client.js`)
- Client → League Settings: builds league data (evidence: `src/client/client.js`)
- Client → Fantasy Team: builds teams (evidence: `src/client/client.js`)
- Client → Draft Pick: builds draft picks (evidence: `src/client/client.js`)
- Client → Free Agent: builds free agents (evidence: `src/client/client.js`)
- Client → NFL Game: builds game data (evidence: `src/client/client.js`)
- Matchup Boxscore → Boxscore Player: builds roster players (evidence: `src/boxscore/boxscore.js`)
- Boxscore Player → NFL Player: extends (evidence: `src/boxscore-player/boxscore-player.js`)
- Boxscore Player → Player Statistics: parses stats (evidence: `src/boxscore-player/boxscore-player.js`)
- Fantasy Team → NFL Player: builds roster (evidence: `src/team/team.js`)
- Draft Pick → NFL Player: extends (evidence: `src/draft-player/draft-player.js`)
- Draft Pick → Player Statistics: parses stats (evidence: `src/draft-player/draft-player.js`)
- Free Agent → NFL Player: uses player model (evidence: `src/free-agent-player/free-agent-player.js`)
- Free Agent → Player Statistics: uses stats parser (evidence: `src/free-agent-player/free-agent-player.js`)
- Cacheable Objects → Response Mapper: extends (evidence: `src/base-classes/base-cacheable-object/base-cacheable-object.js`)
- NFL Player → Cacheable Objects: extends (evidence: `src/player/player.js`)
- Fantasy Team → Cacheable Objects: extends (evidence: `src/team/team.js`)
- League Settings → Response Mapper: extends (evidence: `src/league/league.js`)
- Matchup Boxscore → Response Mapper: extends (evidence: `src/boxscore/boxscore.js`)
- NFL Game → Response Mapper: extends (evidence: `src/nfl-game/nfl-game.js`)
- Player Statistics → Response Mapper: extends (evidence: `src/player-stats/player-stats.js`)
- Response Mapper → Mapping Utility: flattens data (evidence: `src/base-classes/base-object/base-object.js`)
- NFL Player → API Mappings: maps identifiers (evidence: `src/player/player.js`)
- League Settings → API Mappings: maps settings (evidence: `src/league/league.js`)
- Player Statistics → API Mappings: maps scoring (evidence: `src/player-stats/player-stats.js`)
