# michael-harris-dr/fantasy_hockey architecture

> Architecture diagram of the GitHub repository michael-harris-dr/fantasy_hockey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/michael-harris-dr/fantasy_hockey
- Repository: https://github.com/michael-harris-dr/fantasy_hockey

## Overview

This is a browser-based fantasy hockey player lookup and projection app backed by a FastAPI service. A user searches by surname; the browser requests player data, computes remaining-season projections from player stats and team games played, and displays current and projected stats. The backend validates API keys, resolves names against local NHL roster snapshots, enriches matches with NHL season statistics, and also serves team games played. Source also supports refreshing roster snapshots. The tree and sampled source show no persistent database beyond JSON files; frontend projection and rendering share index.js.

Main entry points: [`backend/fan.py`](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/fan.py) (Hockey operations), [`index.js`](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js) (Search interface), [`backend/endpoints.py`](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/endpoints.py) (FastAPI routes), [`backend/helpy.py`](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/helpy.py) (Player data helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser app"]
  node_browser["Search interface<br/>[index.js]"]
  node_projection["Stat projections<br/>[index.js]"]
  node_results["Stats table<br/>[index.js]"]
end

subgraph group_service["API service"]
  node_api["FastAPI routes<br/>[endpoints.py]"]
  node_security["API key check<br/>[security.py]"]
  node_fan["Hockey operations<br/>[fan.py]"]
  node_helpers["Player data helpers<br/>[helpy.py]"]
end

subgraph group_data["Roster data"]
  node_teamlist["Team catalog<br/>[NHL_TEAMS.json]"]
  node_rosters[("Roster snapshots")]
end

subgraph group_integrations["NHL integration"]
  node_nhl["NHL API"]
end

node_user(("Fantasy user"))

node_user -->|"searches"| node_browser
node_browser -->|"requests players"| node_api
node_browser -->|"requests teams"| node_api
node_api -->|"checks key"| node_security
node_api -->|"dispatches lookup"| node_fan
node_api -->|"dispatches teams"| node_fan
node_fan -->|"resolves players"| node_helpers
node_helpers -->|"reads teams"| node_teamlist
node_helpers -->|"reads rosters"| node_rosters
node_helpers -->|"fetches player stats"| node_nhl
node_fan -->|"fetches standings"| node_nhl
node_fan -->|"reads teams"| node_teamlist
node_fan -.->|"fetches rosters"| node_nhl
node_fan -.->|"writes snapshots"| node_rosters
node_api -->|"returns JSON"| node_browser
node_browser -->|"projects stats"| node_projection
node_projection -->|"renders stats"| node_results
node_browser -->|"renders current stats"| node_results

click node_browser "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js"
click node_projection "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js"
click node_results "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js"
click node_api "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/endpoints.py"
click node_security "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/security.py"
click node_fan "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/fan.py"
click node_helpers "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/helpy.py"
click node_teamlist "https://github.com/michael-harris-dr/fantasy_hockey/blob/main/db/NHL_TEAMS.json"
click node_rosters "https://github.com/michael-harris-dr/fantasy_hockey/tree/main/db/team_rosters"

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_browser,node_projection,node_results,node_user toneBlue
class node_api,node_security,node_fan,node_helpers toneAmber
class node_teamlist,node_rosters toneMint
class node_nhl toneRose
```

## Components

### Browser app

- [Search interface](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js): `index.js`
- [Stat projections](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js): `index.js`
- [Stats table](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/index.js): `index.js`

### API service

- [FastAPI routes](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/endpoints.py): `backend/endpoints.py`
- [API key check](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/security.py): `backend/security.py`
- [Hockey operations](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/fan.py): `backend/fan.py`
- [Player data helpers](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/backend/helpy.py): `backend/helpy.py`

### Roster data

- [Team catalog](https://github.com/michael-harris-dr/fantasy_hockey/blob/main/db/NHL_TEAMS.json): `db/NHL_TEAMS.json`
- [Roster snapshots](https://github.com/michael-harris-dr/fantasy_hockey/tree/main/db/team_rosters): `db/team_rosters`

### NHL integration

- **NHL API**

### Other components

- **Fantasy user**

## Connections

- Fantasy user → Search interface: searches
- Search interface → FastAPI routes: requests players
- Search interface → FastAPI routes: requests teams
- FastAPI routes → API key check: checks key
- FastAPI routes → Hockey operations: dispatches lookup
- FastAPI routes → Hockey operations: dispatches teams
- Hockey operations → Player data helpers: resolves players
- Player data helpers → Team catalog: reads teams
- Player data helpers → Roster snapshots: reads rosters
- Player data helpers → NHL API: fetches player stats
- Hockey operations → NHL API: fetches standings
- Hockey operations → Team catalog: reads teams
- Hockey operations → NHL API: fetches rosters
- Hockey operations → Roster snapshots: writes snapshots
- FastAPI routes → Search interface: returns JSON
- Search interface → Stat projections: projects stats
- Stat projections → Stats table: renders stats
- Search interface → Stats table: renders current stats