# nitzv/fast-f1 architecture

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

- Interactive diagram: https://gitdiagram.com/nitzv/fast-f1
- Repository: https://github.com/nitzv/fast-f1

## Overview

FastF1 is a Python package for retrieving and analyzing Formula 1 schedules, session results, timing and telemetry, plus current and historical Ergast-compatible data. The principal workflow is to select an event/session, load data through the session layer and its data providers, then analyze extended Pandas objects or visualize them. Separate branches cover live SignalR capture, authenticated timing access, and Ergast queries. The graph follows shown imports and calls; several subsystems are represented from documented capabilities and the file tree, so their internal links are omitted where excerpts do not establish them.

Main entry points: [`fastf1/core.py`](https://github.com/nitzv/fast-f1/blob/main/fastf1/core.py) (Session model), [`fastf1/ergast/interface.py`](https://github.com/nitzv/fast-f1/blob/main/fastf1/ergast/interface.py) (Historical API), [`fastf1/events.py`](https://github.com/nitzv/fast-f1/blob/main/fastf1/events.py) (Event lookup), [`fastf1/req.py`](https://github.com/nitzv/fast-f1/blob/main/fastf1/req.py) (HTTP and cache)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_event["Events and sessions"]
  node_event_api["Event lookup<br/>[events.py]"]
  node_session["Session model<br/>[core.py]"]
end

subgraph group_data["Data providers"]
  node_official["F1 timing API<br/>[_api.py]"]
  node_ergast["Historical API<br/>[interface.py]"]
  node_ergast_shapes["Ergast responses<br/>[structure.py]"]
  node_mvapi["MV API data<br/>[data.py]"]
end

subgraph group_live["Live timing"]
  node_liveclient["SignalR client<br/>[client.py]"]
  node_live_data["Live data parser<br/>[data.py]"]
  node_account["Account auth<br/>[__init__.py]"]
  node_tokens["Token manager<br/>[tokens.py]"]
end

subgraph group_analysis["Analysis and visualization"]
  node_pandas["Extended Pandas<br/>[pandas_base.py]"]
  node_extensions["Pandas helpers"]
  node_plotting["Plotting interface<br/>[_interface.py]"]
end

subgraph group_infra["Shared infrastructure"]
  node_requests["HTTP and cache<br/>[req.py]"]
  node_parsing["Parsing helpers<br/>[parsing_helpers.py]"]
  node_fuzzy["Fuzzy matching<br/>[fuzzy.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("Analyst"))
node_f1_service(("F1 services"))
node_ergast_service(("Jolpica API"))
node_pandas_result["Analysis data"]
node_chart["Visualization"]

node_user -->|"selects event"| node_event_api
node_event_api -->|"creates session"| node_session
node_event_api -->|"fetches schedule"| node_requests
node_event_api -->|"uses historical data"| node_ergast
node_event_api -->|"matches names"| node_fuzzy
node_session -->|"loads timing"| node_official
node_session -->|"loads results"| node_ergast
node_session -->|"reads live data"| node_live_data
node_session -->|"loads API data"| node_mvapi
node_official -->|"fetches pages"| node_requests
node_official -->|"uses parsers"| node_parsing
node_ergast -->|"sends queries"| node_requests
node_ergast -->|"builds responses"| node_ergast_shapes
node_ergast -->|"returns frames"| node_pandas_result
node_f1_service -->|"provides timing"| node_official
node_ergast_service -->|"provides race data"| node_ergast
node_user -->|"captures stream"| node_liveclient
node_liveclient -->|"gets token"| node_account
node_account -->|"manages tokens"| node_tokens
node_liveclient -->|"subscribes stream"| node_f1_service
node_live_data -->|"uses parsers"| node_parsing
node_session -->|"extends dataframes"| node_pandas
node_pandas -->|"provides analysis data"| node_pandas_result
node_user -->|"requests plots"| node_plotting
node_plotting -->|"plots session data"| node_session
node_plotting -->|"renders chart"| node_chart
node_requests -.->|"requests data"| node_f1_service
node_requests -.->|"requests data"| node_ergast_service

click node_event_api "https://github.com/nitzv/fast-f1/blob/main/fastf1/events.py"
click node_session "https://github.com/nitzv/fast-f1/blob/main/fastf1/core.py"
click node_official "https://github.com/nitzv/fast-f1/blob/main/fastf1/_api.py"
click node_ergast "https://github.com/nitzv/fast-f1/blob/main/fastf1/ergast/interface.py"
click node_ergast_shapes "https://github.com/nitzv/fast-f1/blob/main/fastf1/ergast/structure.py"
click node_mvapi "https://github.com/nitzv/fast-f1/blob/main/fastf1/mvapi/data.py"
click node_liveclient "https://github.com/nitzv/fast-f1/blob/main/fastf1/livetiming/client.py"
click node_live_data "https://github.com/nitzv/fast-f1/blob/main/fastf1/livetiming/data.py"
click node_account "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/f1account/__init__.py"
click node_tokens "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/f1account/tokens.py"
click node_pandas "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/pandas_base.py"
click node_extensions "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/pandas_extensions.py"
click node_plotting "https://github.com/nitzv/fast-f1/blob/main/fastf1/plotting/_interface.py"
click node_requests "https://github.com/nitzv/fast-f1/blob/main/fastf1/req.py"
click node_parsing "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/parsing_helpers.py"
click node_fuzzy "https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/fuzzy.py"
click node_logger "https://github.com/nitzv/fast-f1/blob/main/fastf1/logger.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_event_api,node_session toneBlue
class node_official,node_ergast,node_ergast_shapes,node_mvapi toneAmber
class node_liveclient,node_live_data,node_account,node_tokens,node_ergast_service toneMint
class node_pandas,node_extensions,node_plotting toneRose
class node_requests,node_parsing,node_fuzzy,node_logger,node_user,node_f1_service,node_pandas_result,node_chart toneIndigo
```

## Components

### Events and sessions

- [Event lookup](https://github.com/nitzv/fast-f1/blob/main/fastf1/events.py): `fastf1/events.py`
- [Session model](https://github.com/nitzv/fast-f1/blob/main/fastf1/core.py): `fastf1/core.py`

### Data providers

- [F1 timing API](https://github.com/nitzv/fast-f1/blob/main/fastf1/_api.py): `fastf1/_api.py`
- [Historical API](https://github.com/nitzv/fast-f1/blob/main/fastf1/ergast/interface.py): `fastf1/ergast/interface.py`
- [Ergast responses](https://github.com/nitzv/fast-f1/blob/main/fastf1/ergast/structure.py): `fastf1/ergast/structure.py`
- [MV API data](https://github.com/nitzv/fast-f1/blob/main/fastf1/mvapi/data.py): `fastf1/mvapi/data.py`

### Live timing

- [SignalR client](https://github.com/nitzv/fast-f1/blob/main/fastf1/livetiming/client.py): `fastf1/livetiming/client.py`
- [Live data parser](https://github.com/nitzv/fast-f1/blob/main/fastf1/livetiming/data.py): `fastf1/livetiming/data.py`
- [Account auth](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/f1account/__init__.py): `fastf1/internals/f1account/__init__.py`
- [Token manager](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/f1account/tokens.py): `fastf1/internals/f1account/tokens.py`

### Analysis and visualization

- [Extended Pandas](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/pandas_base.py): `fastf1/internals/pandas_base.py`
- [Pandas helpers](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/pandas_extensions.py): `fastf1/internals/pandas_extensions.py`
- [Plotting interface](https://github.com/nitzv/fast-f1/blob/main/fastf1/plotting/_interface.py): `fastf1/plotting/_interface.py`

### Shared infrastructure

- [HTTP and cache](https://github.com/nitzv/fast-f1/blob/main/fastf1/req.py): `fastf1/req.py`
- [Parsing helpers](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/parsing_helpers.py): `fastf1/internals/parsing_helpers.py`
- [Fuzzy matching](https://github.com/nitzv/fast-f1/blob/main/fastf1/internals/fuzzy.py): `fastf1/internals/fuzzy.py`
- [Logging](https://github.com/nitzv/fast-f1/blob/main/fastf1/logger.py): `fastf1/logger.py`

### Other components

- **Analyst**
- **F1 services**
- **Jolpica API**
- **Analysis data**
- **Visualization**

## Connections

- Analyst → Event lookup: selects event
- Event lookup → Session model: creates session (evidence: `fastf1/events.py`)
- Event lookup → HTTP and cache: fetches schedule (evidence: `fastf1/events.py`)
- Event lookup → Historical API: uses historical data (evidence: `fastf1/events.py`)
- Event lookup → Fuzzy matching: matches names (evidence: `fastf1/events.py`)
- Session model → F1 timing API: loads timing (evidence: `fastf1/core.py`)
- Session model → Historical API: loads results (evidence: `fastf1/core.py`)
- Session model → Live data parser: reads live data (evidence: `fastf1/core.py`)
- Session model → MV API data: loads API data (evidence: `fastf1/core.py`)
- F1 timing API → HTTP and cache: fetches pages (evidence: `fastf1/_api.py`)
- F1 timing API → Parsing helpers: uses parsers (evidence: `fastf1/_api.py`)
- Historical API → HTTP and cache: sends queries (evidence: `fastf1/ergast/interface.py`)
- Historical API → Ergast responses: builds responses (evidence: `fastf1/ergast/interface.py`)
- Historical API → Analysis data: returns frames (evidence: `fastf1/ergast/interface.py`)
- F1 services → F1 timing API: provides timing
- Jolpica API → Historical API: provides race data
- Analyst → SignalR client: captures stream (evidence: `fastf1/livetiming/client.py`)
- SignalR client → Account auth: gets token (evidence: `fastf1/livetiming/client.py`)
- Account auth → Token manager: manages tokens (evidence: `fastf1/internals/f1account/__init__.py`)
- SignalR client → F1 services: subscribes stream (evidence: `fastf1/livetiming/client.py`)
- Live data parser → Parsing helpers: uses parsers (evidence: `fastf1/livetiming/data.py`)
- Session model → Extended Pandas: extends dataframes (evidence: `fastf1/core.py`)
- Extended Pandas → Analysis data: provides analysis data
- Analyst → Plotting interface: requests plots
- Plotting interface → Session model: plots session data (evidence: `fastf1/plotting/_interface.py`)
- Plotting interface → Visualization: renders chart
- HTTP and cache → F1 services: requests data
- HTTP and cache → Jolpica API: requests data