> ## Documentation Index
> Fetch the complete documentation index at: https://tif1.tracinginsights.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> Internal architecture, module ownership, and data flow in tif1

tif1 is built with a modular architecture focused on performance, reliability, and maintainability. Each module has a clear responsibility and well-defined boundaries.

## System Overview

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
graph TB
    User[User Code] --> Session[Session API]
    Session --> Cache[Cache Layer]
    Cache --> |Hit| Memory[LRU Memory Cache]
    Cache --> |Miss| SQLite[SQLite Cache]
    SQLite --> |Miss| CDN[CDN Manager]
    CDN --> HTTP[HTTP/2 Session]
    HTTP --> JS[jsDelivr CDN]
    JS --> Data[JSON Data]
    Data --> Pipeline[I/O Pipeline]
    Pipeline --> DF[DataFrame]
    DF --> User
```

## Module Ownership

* `tif1.session`: canonical session entrypoint (`Session`, `get_session`).
* `tif1.models`: canonical dataframe-backed domain models (`Laps`, `Lap`, `Driver`, `Telemetry`).
* `tif1.io_pipeline`: payload normalization helpers used by session loading paths.
* `tif1.lap_ops`: lap-number/time coercion and lap-column helpers.
* `tif1.http_session`: sole owner of HTTP session lifecycle and connection metrics.
* `tif1.async_fetch`: async fetch orchestration and executor lifecycle.
* `tif1.cache`: SQLite + in-memory caching.
* `tif1.events`: event/session lookup via packaged JSON schedules.
* `tif1.schedule_schema`: schema validation for schedule assets.

## Data Flow

The data pipeline transforms raw JSON from the CDN into structured DataFrames:

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant User
    participant Session
    participant Cache
    participant CDN
    participant Pipeline

    User->>Session: get_session(2025, "Monaco", "Race")
    Session->>Cache: Check for cached data
    alt Cache Hit
        Cache-->>Session: Return cached DataFrame
    else Cache Miss
        Session->>CDN: Fetch JSON from jsdelivr
        CDN-->>Session: Return JSON payload
        Session->>Pipeline: Transform JSON
        Pipeline-->>Session: Return DataFrame
        Session->>Cache: Store in cache
    end
    Session-->>User: Return Session object
    User->>Session: Access .laps property
    Session-->>User: Return laps DataFrame
```

### Data transformation steps

1. **CDN Fetch**: Parallel HTTP/2 requests to jsdelivr CDN
2. **JSON Parse**: Fast parsing with orjson
3. **DataFrame Construction**: Column mapping and type conversion
4. **Enrichment**: Add weather data, calculate derived fields
5. **Caching**: Store in SQLite + memory LRU
6. **Return**: Pandas or Polars DataFrame

## Data Flow

1. `get_session(...)` resolves event/session aliases and creates a `Session`.
2. `Session` methods load JSON payloads via CDN manager + shared HTTP session.
3. `io_pipeline` helpers normalize payloads into lib dataframes.
4. `cache` stores/retrieves JSON payloads and telemetry batches.
5. `models` expose dataframe-centric APIs for lap/driver/telemetry access.

## Schedule System

* Static schedules are packaged as JSON files in `src/tif1/data/schedules/f1schedule/` (one file per year: `schedule_2018.json`, `schedule_2019.json`, etc.).
* `events.py` reads these assets through `importlib.resources` and converts them to the internal format.
* `schedule_schema.validate_schedule_payload` enforces structure and schema versioning.
* CDN fallback fetches missing years from jsdelivr (f1schedule repository).

## Design Rules

* No compatibility shims for unsupported FastF1 namespaces.
* Shared network session ownership stays in `http_session`.
* Performance benchmarks live under `tests/benchmarks` and are excluded from default pytest runs.