# jared-chan/f1ml architecture

> Architecture diagram of the GitHub repository jared-chan/f1ml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jared-chan/f1ml
- Repository: https://github.com/jared-chan/f1ml

## Overview

##### Main components
- Client (Web Browser)
- Frontend/UI layer (Streamlit app in app.py + SessionState helper)
- Controller/Router (app.py orchestrates user input → data → model → output)
- Data Ingestion & Cache layer
– Ergast Developer API (external HTTP service)
– Local JSON cache (db/cache/*.json)
- Static Data Storage
– CSV files (db/*.csv: circuits, constructors, drivers, races, status)
– Pre-computed NumPy arrays (db/races_npy/…)
- Model Management & Inference
– PyTorch model files (db/models/model_split*.pth)
– fs_manifest.csv (model metadata)
- Business Logic / Prediction Engine
– Data preprocessing
– Feature assembly
– Model inference
– Randomness injection
- Presentation layer
– Interactive graph components
– Slider control for lap selection
- Deployment Environment
– Heroku dyno (Procfile, .slugignore)
– Runtime dependencies (requirements.txt, setup.sh)
- Development Artifacts
– Jupyter notebooks (notebooks/*.ipynb)
– images/ (screenshots used on site)

##### Relationships and data flow
1. Browser → HTTP(S) → Heroku/Streamlit server
2. UI invokes controller (app.py)
3. Controller checks local JSON cache
– if miss → HTTP GET → Ergast API → store JSON in db/cache
– if hit → load JSON from db/cache
4. Controller loads static CSV & NumPy data as needed
5. Controller invokes Prediction Engine
– loads model(s) from db/models
– preprocesses features, applies randomness
– runs PyTorch inference
6. Prediction results → UI components (graphs, tables) → Browser
7. Optional: Data scientists use notebooks to retrain models or explore data

##### Architectural patterns
- MVC-style separation:
– View: Streamlit frontend
– Controller: app.py
– Model: ML models + data sources
- Cache-aside pattern for external API calls
- Modular layering (UI, Controller, Data, Model)

##### Technologies & frameworks
– Python 3.x
– Streamlit (web UI)
– SessionState.py (Streamlit state management)
– PyTorch (.pth files)
– NumPy (race datasets)
– CSV (static reference data)
– Ergast Developer API (REST service)
– Heroku deployment (Procfile, setup.sh)

##### Don’t overthink—capture every discrete piece
Break the system into all logical subsystems:
– UI widgets (slider, graphs)
– Session state manager
– API fetcher + cache
– Static data loader
– Model loader
– Inference pipeline
– Deployment/Docker/Heroku

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["Web Browser"]:::external
        StreamlitUI["Streamlit UI (app.py)"]:::ui
        SessionState["SessionState Helper"]:::ui
    end

    %% Controller Layer
    subgraph "Controller Layer"
        direction TB
        Controller["Controller/Router (app.py)"]:::controller
    end

    %% Data Ingestion & Cache
    subgraph "Data Ingestion & Cache Layer"
        direction TB
        CacheDir["Local JSON Cache (db/cache/*.json)"]:::datastore
        ErgastAPI["Ergast Developer API"]:::external
    end

    %% Static Data
    subgraph "Static Data Storage"
        direction TB
        CSVStore["CSV Reference Data"]:::datastore
        NPYStore["Pre-computed NumPy Arrays (db/races_npy/)"]:::datastore
    end

    %% Model Store
    subgraph "Model Management & Inference"
        direction TB
        ModelSplit["Models (db/models/model_split/*.pth + fs_manifest.csv)"]:::model
        ModelSplit47["Models (db/models/model_split_47/*.pth + fs_manifest.csv)"]:::model
    end

    %% Prediction Engine
    subgraph "Business Logic / Prediction Engine"
        direction TB
        Preprocessing["Data Preprocessing & Feature Assembly"]:::controller
        Inference["Model Inference & Randomness"]:::controller
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Graphs["Interactive Graphs & Slider"]:::ui
    end

    %% Deployment
    subgraph "Deployment Environment"
        direction TB
        Procfile["Procfile"]:::deployment
        Slugignore[".slugignore"]:::deployment
        Requirements["requirements.txt"]:::deployment
        Setup["setup.sh"]:::deployment
    end

    %% Development Artifacts
    subgraph "Development Artifacts"
        direction TB
        Notebooks["Jupyter Notebooks (notebooks/)"]:::dev
        Images["Site Images (images/)"]:::dev
        Docs["README.md & .gitignore"]:::dev
    end

    %% Connections
    Browser -->|"HTTP(S) Request"| StreamlitUI
    StreamlitUI -->|UI events| Controller
    Controller -->|"Check Cache"| CacheDir
    CacheDir --|miss: HTTP GET|--> ErgastAPI
    ErgastAPI -->|JSON Response| CacheDir
    Controller -->|Load CSV| CSVStore
    Controller -->|Load NumPy| NPYStore
    Controller -->|Invoke| Preprocessing
    Preprocessing -->|Features| Inference
    Inference -->|Load .pth| ModelSplit
    Inference -->|Load .pth| ModelSplit47
    Inference -->|Prediction Results| Streams["Results"]:::ui
    Streams --> Graphs
    Graphs --> Browser

    %% Click Events
    click StreamlitUI "https://github.com/jared-chan/f1ml/blob/master/app.py"
    click SessionState "https://github.com/jared-chan/f1ml/blob/master/SessionState.py"
    click Controller "https://github.com/jared-chan/f1ml/blob/master/app.py"
    click CacheDir "https://github.com/jared-chan/f1ml/tree/master/db/cache"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/circuits.csv"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/constructors.csv"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/drivers.csv"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/drivers_short.csv"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/races.csv"
    click CSVStore "https://github.com/jared-chan/f1ml/blob/master/db/status.csv"
    click NPYStore "https://github.com/jared-chan/f1ml/tree/master/db/races_npy"
    click ModelSplit "https://github.com/jared-chan/f1ml/blob/master/db/models/model_split/*.pth"
    click ModelSplit "https://github.com/jared-chan/f1ml/blob/master/db/models/model_split/fs_manifest.csv"
    click ModelSplit47 "https://github.com/jared-chan/f1ml/blob/master/db/models/model_split_47/*.pth"
    click ModelSplit47 "https://github.com/jared-chan/f1ml/blob/master/db/models/model_split_47/fs_manifest.csv"
    click Procfile "https://github.com/jared-chan/f1ml/tree/master/Procfile"
    click Slugignore "https://github.com/jared-chan/f1ml/blob/master/.slugignore"
    click Requirements "https://github.com/jared-chan/f1ml/blob/master/requirements.txt"
    click Setup "https://github.com/jared-chan/f1ml/blob/master/setup.sh"
    click Notebooks "https://github.com/jared-chan/f1ml/tree/master/notebooks"
    click Images "https://github.com/jared-chan/f1ml/tree/master/images"
    click Docs "https://github.com/jared-chan/f1ml/blob/master/README.md"
    click Docs "https://github.com/jared-chan/f1ml/blob/master/.gitignore"

    %% Styles
    classDef ui fill:#D0E6F8,stroke:#026AA7,color:#026AA7;
    classDef controller fill:#E2F0D9,stroke:#3C8031,color:#3C8031;
    classDef datastore fill:#FDE9D9,stroke:#D9730D,color:#D9730D;
    classDef external fill:#E9D5F8,stroke:#8044A8,color:#8044A8;
    classDef model fill:#E2F0D9,stroke:#3C8031,color:#3C8031;
    classDef deployment fill:#F0F0F0,stroke:#606060,color:#606060;
    classDef dev fill:#F5F5F5,stroke:#909090,color:#909090;
```
