Architecture

​

System Overview

​

Module Ownership

• tif1.session: canonical session entrypoint (Session, get_session).
• tif1.models: canonical dataframe-backed domain models (Laps, Lap, Driver, Telemetry).
• tif1.core_utils: payload normalization, lap-number/time coercion, and DataFrame helpers used by session loading paths.
• tif1.http_session: sole owner of HTTP session lifecycle and connection metrics.
• tif1.payload_loader: single payload-loading pipeline (memo → cache → CDN fetch → validate → write-back). The pipeline runs behind an injectable HttpTransport seam (NiquestsTransport in production, InMemoryTransport in tests).
• tif1.async_fetch: async fetch orchestration and executor lifecycle; shares the CDN fallback loops owned by tif1.cdn with the sync pipeline.
• 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

​

Data transformation steps

1. CDN Fetch: Parallel HTTP/2 requests to the CDN source chain (jsDelivr primary, Hugging Face and StaticDelivr fallbacks)
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. core_utils 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.