# pi-prasaad-krishna/formulaone-replayer architecture

> Architecture diagram of the GitHub repository pi-prasaad-krishna/formulaone-replayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pi-prasaad-krishna/formulaone-replayer
- Repository: https://github.com/pi-prasaad-krishna/formulaone-replayer

## Overview

##### What this project is (type + purpose)
This is a **single-repo, local-first Python desktop “tool suite”** for **interactive Formula 1 race visualization and telemetry analytics**, powered by **FastF1**. It’s not a client/server system; the “system” is primarily:
- A **launcher/hub GUI** (`main.py`)
- Two **GUI applications**:
- **Race Replayer** (`race_replayer.py`) – high-FPS visualization (2D/3D, leaderboard, playback controls)
- **Analytics Dashboard** (`analytics_dashboard.py`) – multi-view charts and telemetry comparisons
- A **data/telemetry acquisition layer** (FastF1) with a **local cache** (`f1_cache` created at runtime)

##### File-tree driven structure (what to reflect
Top-level files imply a very straightforward module layout:

- `main.py`
Central “Hub” / entrypoint. Likely contains the primary GUI that routes to the two tools.
- `race_replayer.py`
Race playback UI + rendering pipeline (3D view, camera smoothing, interpolation, blitting optimizations, leaderboard UI).
- `analytics_dashboard.py`
Analytics UI + multiple plots/visualizations (telemetry, strategy, degradation, position charts, radar charts, track maps, etc.).
- `readme.md`
Describes runtime behavior (FastF1 cache creation, dependencies, user flows).

##### Primary runtime dependencies
- **FastF1**: provides race sessions + telemetry; downloads data and caches locally.
- **CustomTkinter**: desktop GUI framework (hub + both apps).
- **Matplotlib**: plotting/visualization (dashboard; possibly some in replayer).
- **Pandas / NumPy / SciPy**: data frames, numeric processing, interpolation/smoothing.

##### Behavior
- **First run downloads** telemetry and writes to local **`f1_cache/`**.
- Users select **Year/Circuit** and optionally drivers; apps then load sessions/telemetry and render views.

##### Level 1: System Context (C4-ish context)
Shows: User → Hub → (Race Replayer / Analytics Dashboard) → FastF1 → External F1 data source + Local cache.

Break each tool into subcomponents: UI, data loading, processing, rendering/plotting, cache access.

This project benefits from “splitting into as many components as possible” because performance/visualization features (blitting, interpolation, camera physics) are meaningful internal subsystems.

##### Relationships & interactions (the “data flow story” to encode)

**User Input → FastF1 Session Load → Cache Check/Download → DataFrames/Telemetry → Processing (NumPy/Pandas/SciPy) → Render (Matplotlib / custom renderer) → GUI**

- Replayer branch emphasizes **real-time playback loop** + **rendering optimizations**
- Dashboard branch emphasizes **multi-view plotting** + **comparisons**

Small tech badges/labels on components:
- UI: **CustomTkinter**
- Telemetry: **FastF1**
- Charts: **Matplotlib**
- Data: **Pandas, NumPy**
- Math/interpolation: **SciPy**
- Storage: **Local filesystem cache (`f1_cache/`)**

##### What *not* to do
- Don’t omit caching; it’s a first-order architectural element for performance and user experience.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================
    %% Level 1: System Context
    %% =========================
    subgraph "Level 1 — System Context (Local Desktop App, no backend)"
        U["User (Analyst/Fan)"]:::user

        HUB["F1 Visualizer Hub (main.py)"]:::app
        ROUTER["Tool Router / Launcher (main.py)"]:::module

        RR["Race Replayer (race_replayer.py)"]:::app
        AD["Analytics Dashboard (analytics_dashboard.py)"]:::app

        FASTF1["FastF1 Library (Telemetry + Session API)"]:::dep
        EXT["External F1 Telemetry/Data Source\n(FastF1 upstream endpoint)"]:::external
        CACHE[("Local Disk Cache\nf1_cache/ (created at runtime)")]:::store

        NOTE_CTX["Note: FastF1 handles network + caching transparently.\nFirst run downloads & caches; subsequent runs read cache."]:::note
    end

    U -->|"launch/select"| HUB
    HUB -->|"UI_event"| ROUTER
    ROUTER -->|"open_tool"| RR
    ROUTER -->|"open_tool"| AD

    RR -->|"request_session/telemetry"| FASTF1
    AD -->|"request_session/telemetry"| FASTF1

    FASTF1 <-->|"download"| EXT
    FASTF1 <-->|"read/write_cache"| CACHE

    FASTF1 -->|"sessions/dataframes"| RR
    FASTF1 -->|"sessions/dataframes"| AD

    NOTE_CTX -.-> FASTF1
    NOTE_CTX -.-> CACHE
    NOTE_CTX -.-> EXT

    %% =========================
    %% Level 2: Internal Components
    %% =========================
    subgraph "Level 2 — Internal Components (Runtime Data/Control Flow)"
        direction TB

        subgraph "Shared Runtime Dependencies"
            direction TB
            CTK["CustomTkinter (GUI framework)"]:::dep
            MPL["Matplotlib (Plotting)"]:::dep
            PNS["Pandas / NumPy (DataFrames + Numeric)"]:::dep
            SCIPY["SciPy (Interpolation/Smoothing)"]:::dep
        end

        subgraph "Hub (main.py)"
            direction TB
            HUB_UI["Hub UI Layer\n(CustomTkinter)"]:::ui
            HUB_LAUNCH["Tool Router / Launcher"]:::module
            HUB_UI -->|"button_clicks"| HUB_LAUNCH
        end

        subgraph "Race Replayer (race_replayer.py)"
            direction TB
            RR_UI["Replayer UI Layer\n(CustomTkinter)\n(play/pause, speed, year/circuit, drivers)"]:::ui
            RR_CLOCK["Playback Clock / Frame Scheduler\n(FPS ticks, speed factor)"]:::module
            RR_LOAD["Session Loader / FastF1 Adapter"]:::module
            RR_PROC["Position & Telemetry Processing\n(interpolation, smoothing,\nsmart movement detection)"]:::module
            RR_REND["Render Engine\n(2D/3D renderer, camera physics,\nelevation visual, smart blitting)"]:::module
            RR_OVR["UI Overlays / Widgets\n(leaderboard state caching,\ntyres, status/weather)"]:::module
            RR_CANVAS["Display Canvas / Viewport\n(CustomTkinter widgets)"]:::ui

            RR_UI -->|"control_flow"| RR_CLOCK
            RR_UI -->|"load_selection"| RR_LOAD

            RR_CLOCK -->|"tick → advance_time_index"| RR_PROC
            RR_LOAD -->|"raw_session/telemetry"| RR_PROC

            RR_PROC -->|"interpolated_positions"| RR_REND
            RR_PROC -->|"derived_state"| RR_OVR

            RR_REND -->|"draw_frame"| RR_CANVAS
            RR_OVR -->|"overlay_draw"| RR_CANVAS

            RR_NOTE["Render loop: tick → compute positions → draw → overlay → blit"]:::note
            RR_NOTE -.-> RR_CLOCK
            RR_NOTE -.-> RR_REND
            RR_NOTE -.-> RR_OVR
        end

        subgraph "Analytics Dashboard (analytics_dashboard.py)"
            direction TB
            AD_UI["Dashboard UI Layer\n(CustomTkinter)\n(tabs: telemetry battle, strategy,\ndegradation, position chart, maps, etc.)"]:::ui
            AD_LOAD["Session/Telemetry Loader\n(FastF1 Adapter)"]:::module
            AD_PROC["Data Processing Layer\n(filter/align drivers, lap deltas,\nderivations)\n(Pandas/NumPy/SciPy)"]:::module
            AD_PLOT["Plotting / Visualization Layer\n(Matplotlib charts: lines, radar, maps)"]:::module
            AD_CANVAS["Plot Canvases / Panels\n(embedded in GUI)"]:::ui
            AD_INTERACT["Interactive Exploration\n(zoom/pan/hover as supported)"]:::module

            AD_UI -->|"selection_events"| AD_LOAD
            AD_LOAD -->|"telemetry/dataframes"| AD_PROC
            AD_PROC -->|"plot_ready_series"| AD_PLOT
            AD_PLOT -->|"render_figures"| AD_CANVAS
            AD_CANVAS -->|"user_interaction"| AD_INTERACT
        end

        %% Wiring to shared deps
        HUB_UI -.->|"uses"| CTK
        RR_UI -.->|"uses"| CTK
        RR_CANVAS -.->|"uses"| CTK
        AD_UI -.->|"uses"| CTK
        AD_CANVAS -.->|"uses"| CTK

        AD_PLOT -.->|"uses"| MPL
        AD_PROC -.->|"uses"| PNS
        AD_PROC -.->|"uses"| SCIPY

        RR_PROC -.->|"uses"| PNS
        RR_PROC -.->|"uses"| SCIPY
        RR_REND -.->|"optional_plots"| MPL
    end

    %% Connect Level 2 loaders to FastF1 + cache context
    RR_LOAD -->|"calls"| FASTF1
    AD_LOAD -->|"calls"| FASTF1

    %% Connect Hub launcher to tools (Level 2)
    HUB_LAUNCH -->|"spawn_window"| RR_UI
    HUB_LAUNCH -->|"spawn_window"| AD_UI

    %% =========================
    %% Click Events (from component mapping)
    %% =========================
    click HUB "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/main.py"
    click ROUTER "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/main.py"
    click HUB_UI "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/main.py"
    click HUB_LAUNCH "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/main.py"

    click RR "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"
    click RR_UI "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"
    click RR_LOAD "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"
    click RR_PROC "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"
    click RR_REND "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"
    click RR_CLOCK "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/race_replayer.py"

    click AD "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/analytics_dashboard.py"
    click AD_UI "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/analytics_dashboard.py"
    click AD_LOAD "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/analytics_dashboard.py"
    click AD_PROC "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/analytics_dashboard.py"
    click AD_PLOT "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/analytics_dashboard.py"

    click NOTE_CTX "https://github.com/pi-prasaad-krishna/formulaone-replayer/blob/main/readme.md"

    %% =========================
    %% Styles
    %% =========================
    classDef user fill:#E3F2FD,stroke:#1565C0,stroke-width:1.5px,color:#0D47A1
    classDef app fill:#E8F5E9,stroke:#2E7D32,stroke-width:1.5px,color:#1B5E20
    classDef ui fill:#FFF3E0,stroke:#EF6C00,stroke-width:1.5px,color:#E65100
    classDef module fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1.5px,color:#4A148C
    classDef dep fill:#FAFAFA,stroke:#616161,stroke-width:1.5px,color:#212121,stroke-dasharray: 5 4
    classDef store fill:#E0F7FA,stroke:#00838F,stroke-width:1.5px,color:#004D40
    classDef external fill:#FFEBEE,stroke:#C62828,stroke-width:1.5px,color:#B71C1C,stroke-dasharray: 6 4
    classDef note fill:#FFFDE7,stroke:#9E9D24,stroke-width:1.2px,color:#827717,stroke-dasharray: 3 3
```
