System Overview
Module Ownership
The package issrc/tif1/. Every module below exists in that directory. The former io_pipeline.py and lap_ops.py modules were removed; their helpers are in core.py and core_utils/.
Session and models
tif1.core: ownsSessionandget_session, plus the lap, telemetry, weather, and race-control parsing. It re-exports the model family for backward compatibility (tif1.core.Lapsistif1.models.Laps).tif1.session: thin re-export ofSessionandget_sessionfromtif1.core.tif1.models: canonical dataframe-backed domain models (Laps,Lap,Telemetry,Driver,SessionResults,DriverResult,CircuitInfo,LazyTelemetryDict) and theTelemetryProviderprotocol that the models consume. It never importstif1.coreat runtime.tif1.core_utils: shared helpers used by the loading paths:constants(column names, rename maps),helpers(payload normalization, lap-number/time coercion, DataFrame construction),json_utils(orjson parsing),backend_conversion(pandas/polars), andresource_manager.tif1.types: TypedDicts (LapDataDict,TelemetryDataDict, …) and Literals (SessionType,BackendType,CompoundType).
Loading and transport
tif1.payload_loader: single payload-loading pipeline (memo → cache → CDN fetch → validate → write-back). The pipeline runs behind an injectableHttpTransportseam (NiquestsTransportin production,InMemoryTransportin tests).tif1.cdn:CDNManagerand the source chain (jsDelivr primary, Hugging Face buckets, StaticDelivr last), with the fallback loopstry_sources/try_sources_asyncshared by the sync and async paths.raw.githubusercontent.comis never a data source.tif1.http_session: owner of the shared niquests HTTP session, its lifecycle, and the connection metrics.tif1.async_fetch: async parallel fetching and executor lifecycle.tif1.retry: retry with exponential backoff and the circuit breaker.tif1.validation: pydantic payload models and thevalidate_*functions.tif1.exceptions: the exception hierarchy rooted atTIF1Error, plusEventNotFoundErrorand its subclassEventNotInSeasonError(bothValueErrorsubclasses).
Caching and configuration
tif1.cache: every cache tier:LRUCache, the SQLiteCache(payload, frame, and negative-verdict tables), the process-global backend lap caches, and the per-sessionSessionMemo.tif1.config: theConfigsingleton (defaults, environment variables,.tif1rc).
Schedules and lookup
tif1.events: event and session lookup from the packaged JSON schedules, plus the livef1schedulefetch for the current and future seasons.tif1.schedule_schema: schema validation for schedule assets.tif1.fuzzy: fuzzy event-name matching, the last step of event resolution.events.pyaccepts a fuzzy match only at a score of 70 or more and otherwise raisesEventNotFoundError.
User-facing layers
tif1.cli: thetif1command (typer + rich).tif1.jupyter: HTML cards forSession,Driver, andLap, and an HTML DataFrame summary.tif1.plottingandtif1.plotting_constants: FastF1-compatible plotting helpers, and the team, driver, and compound colors per season.tif1.charts: the nativeplot_*chart functions, re-exported at the top level oftif1.tif1.assets: packaged car images, tyre images, and fonts undersrc/tif1/assets/.tif1.fastf1_compat: the FastF1-compatibleCachefacade andset_log_level.tif1.utils: small FastF1-style helpers such asdelta_time.
Data Flow
The data pipeline transforms raw JSON from the CDN into structured DataFrames:Data transformation steps
- CDN Fetch: Parallel HTTP/2 requests to the CDN source chain (jsDelivr primary, Hugging Face and StaticDelivr fallbacks)
- JSON Parse: Fast parsing with orjson
- DataFrame Construction: Column mapping and type conversion
- Enrichment: Add the
DriverandTeamcolumns from the driver list and the derivedLapTimeSecondscolumn - Caching: Store in SQLite and the in-memory LRU tiers
- Return: Pandas or Polars DataFrame
Loading sequence
get_session(...)resolves event and session aliases and creates aSession. No session data is fetched yet.Sessionproperties and methods load JSON payloads throughpayload_loader(memo, SQLite cache, CDN fetch, validation).core_utilshelpers normalize payloads into pandas or polars dataframes.cachestores and retrieves JSON payloads, telemetry batches, and materialized frames.modelsexpose 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.pyreads these assets throughimportlib.resourcesand converts them to the internal format.schedule_schema.validate_schedule_payloadenforces structure and schema versioning.- The current and future seasons, and years without a packaged file, come from the
theOehrly/f1schedulerepository onraw.githubusercontent.com. This is the file FastF1 reads, with a 5-minute edge cache. - The raw file is cached in the SQLite
jsontier underf1schedule/schedule_{year}.jsonforschedule_ttl_hours(default 6,TIF1_SCHEDULE_TTL_HOURS). - When the fetch fails or
offline_modeis on, a stale cached row is served, then the packaged file. A past season with a packaged file never uses the network. - This is the one sanctioned
raw.githubusercontent.comURL: one small file per season, never the data repositories.
Design Rules
- FastF1 compatibility covers
fastf1_compat(theCachefacade,set_log_level), the model classes, theeventsschedule objects,plotting, andutils. There are no shims for other FastF1 namespaces. - Shared network session ownership stays in
http_session. The sync payload pipeline sends HTTP through the injectableHttpTransportseam ofpayload_loader. - Data payloads come from jsDelivr, Hugging Face buckets, or StaticDelivr only, never
raw.githubusercontent.com. - Performance benchmarks live under
tests/benchmarksand are excluded from default pytest runs.