# ashwin-nat/pits-n-giggles architecture

> Architecture diagram of the GitHub repository ashwin-nat/pits-n-giggles, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashwin-nat/pits-n-giggles
- Repository: https://github.com/ashwin-nat/pits-n-giggles

## Overview

##### Project Type & Purpose
- This is a full-stack telemetry visualization tool that ingests live F1 race data (from UDP packets) and provides both in-app live updates and stream overlay capabilities.
- The README describes both a direct “executable” option and a start-from-source configuration. It also details advanced features like post race data autosaving, packet capture/replay, and a rich web UI for telemetry display.
- It is clearly designed to be extended—other applications can build on the telemetry manager module.

##### File Structure
- Top-Level Files and Directories:
- app.py is the main entry point.
- “lib” contains various modules for processing telemetry data like packet parsing, collision analysis, and data forwarding. It includes a dedicated f1_types subdirectory with modules for each F1 telemetry packet type.
- “src” holds configuration (src/config.py), several telemetry handlers, the web API, and UI-related resources (static CSS/JS, HTML templates).
- “tests” contains a comprehensive suite testing modules from telemetry packet parsing to data-related functionalities.
- “utils” provides additional utility scripts for logging, data replay, and viewing post-race telemetry.
- Configuration and build scripts (run.bat, run.sh) indicate cross-platform command-line launch support.
- The architecture appears to follow modular design principles where distinct concerns (data collection, processing, UI, and testing) are clearly separated.

##### Key Components
a. Data Capture & Ingestion:
- Telemetry Input Listener: A UDP packet receiver (see lib/socket_receiver.py) listens on the default port (20777) for F1 telemetry packets.
- Packet Capture Module (packet_cap.py) and Packet Forwarder (packet_forwarder.py) are responsible for handling raw data and optionally saving or forwarding it.
b. Data Processing:
- Telemetry Manager (located in src/telemetry_manager.py and the telemetry_manager module referenced in the README) orchestrates the registration of callbacks and processing of different packet types.
- Specialized analyzers (collisions_analyzer.py, overtake_analyzer.py, race_analyzer.py, fuel_rate_recommender.py, tyre_wear_extrapolator.py) process specific aspects of the telemetry.
- The “lib/f1_types” folder and corresponding tests in “tests/f1_types” encapsulate parsing logic for every kind of telemetry packet.
c. Data Distribution & API:
- Telemetry Web API (src/telemetry_web_api.py) and the HTTP server (default port 5000) serve processed data to the UI.
- An inter-thread communicator (lib/inter_thread_communicator.py) likely handles data flow between background processes and the UI thread.
d. User Interface (UI):
- The web UI is built using static HTML templates (src/templates) combined with CSS (src/static/css) and JavaScript (src/static/js) to update live data.
- There is support for rich UI overlays (for stream integration as well as detailed driver info) as evident from both the detailed README and the screenshots folder.
e. Additional Utilities:
- Utilities for post-race data (dummy_data.json, telemetry_post_race_data_viewer.py) and logs, as well as packet replay and recording functions (telemetry_recorder.py, telemetry_replayer.py).

##### Relationships & Interactions
- Data flows from the F1 telemetry source (UDP packets) into the Telemetry Input Listener.
- Input data is passed to the Telemetry Manager, which routes data to specialized analyzers and parsers in the lib modules.
- Processed telemetry data is then served to the front-end: the HTTP server (running in app.py and via src/telemetry_web_api.py) feeds the UI updates.
- Optional interactions include packet capture/replay (triggered by command line flags in app.py) and data forwarding.
- Interactions between the UI’s frontend assets (JavaScript/CSS) and the backend API that pushes live race updates.

##### Architectural Patterns & Design Principles
- Modular design: Each component (data capture, processing, presentation) is isolated in its own module or package.
- Callback registration and event-driven processing via the telemetry manager indicate a decoupled, extensible design.
- A clear separation between processing (lib, src) and presentation (static assets and templates under src/templates and src/static) following an MVC-like separation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Source
    Source["F1 Telemetry Source"]:::external

    %% Data Ingestion & Processing Subgraph
    subgraph "Data Ingestion & Processing"
        Listener["Telemetry Listener (UDP Packet Receiver)"]:::ingestion
        PacketCap["Packet Capture Module"]:::ingestion
        PacketForwarder["Packet Forwarder"]:::ingestion
        
        TelemManager["Telemetry Manager"]:::processing
        
        CollisionAnalyzer["Collisions Analyzer"]:::processing
        OvertakeAnalyzer["Overtake Analyzer"]:::processing
        RaceAnalysis["Race Analysis Analyzer"]:::processing
        FuelRecommender["Fuel Rate Recommender"]:::processing
        TyreExtrapolator["Tyre Wear Extrapolator"]:::processing
        
        PacketParsing["F1 Telemetry Packet Parsing"]:::processing
        InterThread["Inter-Thread Communication"]:::processing
    end

    %% Data Distribution / API Subgraph
    subgraph "Data Distribution (API)"
        WebAPI["Telemetry Web API / HTTP Server"]:::api
    end

    %% Web UI Subgraph
    subgraph "Web UI"
        UITemplates["Web UI Templates"]:::frontend
        UIStaticCSS["Web UI Static CSS"]:::frontend
        UIStaticJS["Web UI Static JS"]:::frontend
    end

    %% Post-Race Utilities Subgraph
    subgraph "Post-Race Utilities"
        PostRaceViewer["Telemetry Post-Race Viewer"]:::utility
        Recorder["Telemetry Recorder"]:::utility
        Replayer["Telemetry Replayer"]:::utility
        DummyData["Dummy Data"]:::utility
    end

    %% Connections
    Source -->|"sends UDP packets"| Listener
    Listener -->|"for data capture"| PacketCap
    PacketCap -->|"for forwarding"| PacketForwarder
    Listener -->|"delivers telemetry"| TelemManager

    TelemManager -->|"analyzes"| CollisionAnalyzer
    TelemManager -->|"analyzes"| OvertakeAnalyzer
    TelemManager -->|"analyzes"| RaceAnalysis
    TelemManager -->|"analyzes"| FuelRecommender
    TelemManager -->|"analyzes"| TyreExtrapolator
    TelemManager -->|"parses data"| PacketParsing
    TelemManager -->|"communicates via"| InterThread

    InterThread -->|"channels data to"| WebAPI
    WebAPI -->|"serves data to"| UITemplates
    WebAPI -->|"serves data to"| UIStaticCSS
    WebAPI -->|"serves data to"| UIStaticJS

    %% Optional Utilities for post-race and debugging
    TelemManager -->|"optional export"| PostRaceViewer
    TelemManager -->|"optional recording"| Recorder
    TelemManager -->|"optional replay"| Replayer

    %% Click Events
    click Listener "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/socket_receiver.py"
    click PacketCap "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/packet_cap.py"
    click PacketForwarder "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/packet_forwarder.py"
    click TelemManager "https://github.com/ashwin-nat/pits-n-giggles/blob/main/src/telemetry_manager.py"
    click CollisionAnalyzer "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/collisions_analyzer.py"
    click OvertakeAnalyzer "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/overtake_analyzer.py"
    click RaceAnalysis "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/race_analyzer.py"
    click FuelRecommender "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/fuel_rate_recommender.py"
    click TyreExtrapolator "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/tyre_wear_extrapolator.py"
    click PacketParsing "https://github.com/ashwin-nat/pits-n-giggles/tree/main/lib/f1_types/"
    click InterThread "https://github.com/ashwin-nat/pits-n-giggles/blob/main/lib/inter_thread_communicator.py"
    click WebAPI "https://github.com/ashwin-nat/pits-n-giggles/blob/main/src/telemetry_web_api.py"
    click UITemplates "https://github.com/ashwin-nat/pits-n-giggles/tree/main/src/templates"
    click UIStaticCSS "https://github.com/ashwin-nat/pits-n-giggles/tree/main/src/static/css"
    click UIStaticJS "https://github.com/ashwin-nat/pits-n-giggles/tree/main/src/static/js"
    click PostRaceViewer "https://github.com/ashwin-nat/pits-n-giggles/blob/main/utils/telemetry_post_race_data_viewer.py"
    click Recorder "https://github.com/ashwin-nat/pits-n-giggles/blob/main/utils/telemetry_recorder.py"
    click Replayer "https://github.com/ashwin-nat/pits-n-giggles/blob/main/utils/telemetry_replayer.py"
    click DummyData "https://github.com/ashwin-nat/pits-n-giggles/blob/main/dummy_data.json"

    %% Styles
    classDef external fill:#eeeeee,stroke:#333,stroke-width:2px;
    classDef ingestion fill:#a1c4fd,stroke:#333,stroke-width:2px;
    classDef processing fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef api fill:#ffcc80,stroke:#333,stroke-width:2px;
    classDef frontend fill:#fbd3e9,stroke:#333,stroke-width:2px;
    classDef utility fill:#d7ccc8,stroke:#333,stroke-width:2px;
```
