# wefanull/nfl-local architecture

> Architecture diagram of the GitHub repository wefanull/nfl-local, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wefanull/nfl-local
- Repository: https://github.com/wefanull/nfl-local

## Overview

NFL Local downloads nflverse data into DuckDB, then provides statistics through a local Ollama tool-calling chat and a web dashboard with game reports and charts. The optional terminal bet log separately records bets and computes results. The graph follows the documented workflows and sampled imports/calls; the frontend’s individual API requests and some tool internals were not sampled.

Main entry points: [`chat.py`](https://github.com/wefanull/nfl-local/blob/main/chat.py) (Tool-calling chat), [`api.py`](https://github.com/wefanull/nfl-local/blob/main/api.py) (Web API), [`bets.py`](https://github.com/wefanull/nfl-local/blob/main/bets.py) (Bet tracking), [`tools.py`](https://github.com/wefanull/nfl-local/blob/main/tools.py) (Read-only analysis tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data ingestion"]
  node_fetch["Data builder<br/>[fetch_data.py]"]
  node_statsdb[("Stats database<br/>[fetch_data.py]")]
end

subgraph group_analysis["Stats and reports"]
  node_tools["Read-only analysis tools<br/>[tools.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_chat["Tool-calling chat<br/>[chat.py]"]
  node_api["Web API<br/>[api.py]"]
  node_webui["Dashboard and charts<br/>[index.html]"]
end

subgraph group_betlog["Optional bet log"]
  node_bets["Bet tracking<br/>[bets.py]"]
  node_betsdb[("Bet database<br/>[bets.py]")]
end

node_nflverse(("nflverse"))
node_user(("User"))
node_ollama{{"Ollama model"}}

node_nflverse -->|"supplies data"| node_fetch
node_fetch -->|"builds tables"| node_statsdb
node_tools -->|"reads statistics"| node_statsdb
node_user -->|"asks questions"| node_chat
node_chat -->|"sends prompts"| node_ollama
node_ollama -->|"requests tools"| node_chat
node_chat -->|"dispatches calls"| node_tools
node_chat -.->|"dispatches optional tools"| node_bets
node_user -->|"uses dashboard"| node_webui
node_webui -->|"uses web API"| node_api
node_api -->|"queries reports"| node_tools
node_api -->|"delegates chat"| node_chat
node_api -.->|"serves model chat"| node_ollama
node_bets -->|"validates games"| node_statsdb
node_bets -->|"stores and summarizes"| node_betsdb

click node_fetch "https://github.com/wefanull/nfl-local/blob/main/fetch_data.py"
click node_statsdb "https://github.com/wefanull/nfl-local/blob/main/fetch_data.py"
click node_tools "https://github.com/wefanull/nfl-local/blob/main/tools.py"
click node_chat "https://github.com/wefanull/nfl-local/blob/main/chat.py"
click node_api "https://github.com/wefanull/nfl-local/blob/main/api.py"
click node_webui "https://github.com/wefanull/nfl-local/blob/main/static/index.html"
click node_bets "https://github.com/wefanull/nfl-local/blob/main/bets.py"
click node_betsdb "https://github.com/wefanull/nfl-local/blob/main/bets.py"

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_fetch,node_statsdb,node_user toneBlue
class node_tools toneAmber
class node_chat,node_api,node_webui toneMint
class node_bets,node_betsdb toneRose
class node_nflverse,node_ollama toneIndigo
```

## Components

### Data ingestion

- [Data builder](https://github.com/wefanull/nfl-local/blob/main/fetch_data.py): `fetch_data.py`
- [Stats database](https://github.com/wefanull/nfl-local/blob/main/fetch_data.py): `fetch_data.py`

### Stats and reports

- [Read-only analysis tools](https://github.com/wefanull/nfl-local/blob/main/tools.py): `tools.py`

### User interfaces

- [Tool-calling chat](https://github.com/wefanull/nfl-local/blob/main/chat.py): `chat.py`
- [Web API](https://github.com/wefanull/nfl-local/blob/main/api.py): `api.py`
- [Dashboard and charts](https://github.com/wefanull/nfl-local/blob/main/static/index.html): `static/index.html`

### Optional bet log

- [Bet tracking](https://github.com/wefanull/nfl-local/blob/main/bets.py): `bets.py`
- [Bet database](https://github.com/wefanull/nfl-local/blob/main/bets.py): `bets.py`

### Other components

- **nflverse**
- **User**
- **Ollama model**

## Connections

- nflverse → Data builder: supplies data (evidence: `README.md`)
- Data builder → Stats database: builds tables (evidence: `fetch_data.py`)
- Read-only analysis tools → Stats database: reads statistics (evidence: `tools.py`)
- User → Tool-calling chat: asks questions (evidence: `README.md`)
- Tool-calling chat → Ollama model: sends prompts (evidence: `chat.py`)
- Ollama model → Tool-calling chat: requests tools (evidence: `chat.py`)
- Tool-calling chat → Read-only analysis tools: dispatches calls (evidence: `chat.py`)
- Tool-calling chat → Bet tracking: dispatches optional tools (evidence: `chat.py`)
- User → Dashboard and charts: uses dashboard (evidence: `README.md`)
- Dashboard and charts → Web API: uses web API (evidence: `README.md`)
- Web API → Read-only analysis tools: queries reports (evidence: `api.py`)
- Web API → Tool-calling chat: delegates chat (evidence: `api.py`)
- Web API → Ollama model: serves model chat (evidence: `README.md`)
- Bet tracking → Stats database: validates games (evidence: `bets.py`)
- Bet tracking → Bet database: stores and summarizes (evidence: `bets.py`)
