# spidey13/stratsim architecture

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

- Interactive diagram: https://gitdiagram.com/spidey13/stratsim
- Repository: https://github.com/spidey13/stratsim

## Overview

##### Project Type and Purpose
- This is a full‐stack, multi‐agent simulation platform for F1 race strategy analysis.
- It integrates a data pipeline (ingest, process, validate historical race data), machine learning model training/serving, a orchestrator that runs the simulation loop via specialized agents, an interactive Streamlit web UI (and optional FastAPI endpoints), plus experiment tracking (MLflow) and containerized deployment (Docker).

##### Main Components
a. External Data Sources
- FastF1 API (historical race, telemetry, weather)
- OpenWeather API (optional live weather)
b. Data Pipeline Layer (src/data_pipeline)
- Collector (fastf1_collector, weather_collector)
- Processor / Preprocessor / Validator modules
- Data storage: raw cache, processed CSVs, validation reports
c. Model Training & Experiment Tracking
- Training scripts (notebooks & scripts/model_training)
- CatBoost / ML models stored under models/ and catboost_info/
- MLflow server (mlruns/ or via docker‐compose)
d. Core Simulation Orchestrator
- RaceSimulator (src/orchestrator/simulation_loop.py)
- Multi-agent subsystem (src/agents):
- BaseAgent, TireManagerAgent (and sub-agents), StrategyAgent,
LapTimeAgent, WeatherAgent, VehicleDynamicsAgent, GapEffectsAgent
e. API Layer (src/api/endpoints.py)
- Exposes simulation control or data retrieval (if deployed beyond Streamlit)
f. Web Interface (web/)
- Streamlit app (web/streamlit_app.py) – user configuration, live visualization
- Optional FastAPI app (web/app.py) for REST endpoints
g. Infrastructure & Deployment
- Dockerfile, docker-compose.yml (app, MLflow)
- .devcontainer for VSCode containerized dev
h. Configuration & Utilities
- src/config (settings, simulation_config)
- src/utils helpers, run_mlflow_ui

##### Relationships and Data Flow
- External Data → Data Pipeline Collector → Processor → Validated / Enhanced Data → Stored in data/processed.
- Processed Data → Model Training (scripts + notebooks) → Trained Models → models/
- Trained Models & Configs → Agents (loaded at runtime by orchestrator).
- Orchestrator (RaceSimulator) invokes each agent in sequence per lap, consuming model outputs and simulation state → Produces race history/results.
- Results → Web UI (Streamlit) via direct function calls or REST API.
- MLflow tracks training runs—accessible via separate UI container.
- Docker Compose wires together the Streamlit app container + MLflow server (and potentially a backend API).

##### Architectural Patterns and Principles
- Layered Architecture:
- Ingestion/ETL (data_pipeline)
- Business Logic / Simulation (orchestrator + agents)
- Presentation / API (web/ + src/api)
- Modular, Plug-in Agents (Strategy, Tire, Weather, etc.) adhering to BaseAgent interface → supports extensibility.
- Separation of Concerns: Data, Models, Simulation, UI, Config isolated in dedicated directories.
- Containerized Deployment for consistency across environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources"
        direction TB
        FastF1["FastF1 API"]:::external
        OpenWeather["OpenWeather API"]:::external
    end

    %% Data Pipeline Layer
    subgraph "Data Pipeline (src/data_pipeline)" 
        direction TB
        F1Collector["fastf1_collector"]:::pipeline
        WeatherCollector["weather_collector"]:::pipeline
        Processor["data_processor"]:::pipeline
        Preprocessor["preprocessor"]:::pipeline
        Validator["validator"]:::pipeline
        RunPreprocessor["run_preprocessor"]:::pipeline
        RawStorage["Raw Data (categories/*.json)"]:::storage
        ProcessedStorage["Processed Data (seasons_2023_2024_data*.csv)"]:::storage
        ValidationReports["Validation Reports (validation_report.txt)"]:::storage
    end

    %% Model Training & Experiment Tracking
    subgraph "Model Training & MLflow"
        direction TB
        Notebooks["model_training.ipynb"]:::ml
        TrainLapTime["train_lap_time_model.py"]:::ml
        TrainTireWear["train_tire_wear_model.py"]:::ml
        AnalyzeFeatures["analyze_feature_importance.py"]:::ml
        MLflowUI["run_mlflow_ui"]:::ml
        ModelsDir["Saved Models (src/models)"]:::storage
        CatBoostInfo["catboost_info"]:::storage
    end

    %% Core Simulation Orchestrator
    subgraph "Simulation Orchestrator"
        direction TB
        RaceSim["simulation_loop.py"]:::orchestrator
        subgraph "Agents (src/agents)"
            direction TB
            BaseAgent["BaseAgent"]:::agent
            StrategyAgent["StrategyAgent"]:::agent
            TireManager["TireManagerAgent"]:::agent
            LapTimeAgent["LapTimeAgent"]:::agent
            WeatherAgent["WeatherAgent"]:::agent
            VehicleDyn["VehicleDynamicsAgent"]:::agent
            GapEffects["GapEffectsAgent"]:::agent
            GripModel["GripModelAgent"]:::agent
            TireWear["TireWearAgent"]:::agent
            TireTemp["TireTemperatureAgent"]:::agent
        end
    end

    %% API Layer
    subgraph "API Layer (src/api)"
        direction TB
        APIEndpoints["endpoints.py"]:::api
    end

    %% Web Interface
    subgraph "Web Interface (web)"
        direction TB
        StreamlitApp["streamlit_app.py"]:::ui
        FastAPIApp["app.py"]:::ui
    end

    %% Scripts
    Scripts["run_simulation.py"]:::utils

    %% Configuration & Utilities
    subgraph "Config & Utils (src)"
        direction TB
        Settings["settings.py"]:::config
        SimConfig["simulation_config.py"]:::config
        Helpers["helpers.py"]:::utils
        UtilsConfig["config.py"]:::utils
    end

    %% Infrastructure & Deployment
    subgraph "Infrastructure & Deployment"
        direction TB
        DevContainer[".devcontainer.json"]:::infra
        Dockerfile["Dockerfile"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        MLflowServer["MLflow Server"]:::infra
    end

    %% Connections
    FastF1 -->|JSON| F1Collector
    OpenWeather -->|JSON| WeatherCollector

    F1Collector --> Processor
    WeatherCollector --> Processor
    Processor --> Preprocessor
    Preprocessor --> Validator
    Validator --> RawStorage
    Validator --> ProcessedStorage
    Validator --> ValidationReports
    RunPreprocessor --> Preprocessor

    ProcessedStorage --> Notebooks
    ProcessedStorage --> TrainLapTime
    ProcessedStorage --> TrainTireWear
    ProcessedStorage --> AnalyzeFeatures

    TrainLapTime --> ModelsDir
    TrainTireWear --> ModelsDir
    ModelsDir --> RaceSim
    CatBoostInfo --> RaceSim

    MLflowUI --> MLflowServer

    RaceSim --> BaseAgent
    RaceSim --> StrategyAgent
    RaceSim --> TireManager
    RaceSim --> LapTimeAgent
    RaceSim --> WeatherAgent
    RaceSim --> VehicleDyn
    RaceSim --> GapEffects
    RaceSim --> GripModel
    RaceSim --> TireWear
    RaceSim --> TireTemp

    RaceSim --> Scripts
    Scripts --> APIEndpoints
    Scripts --> StreamlitApp

    APIEndpoints -->|REST| FastAPIApp
    RaceSim -->|function calls| StreamlitApp

    Settings --> RaceSim
    SimConfig --> RaceSim
    Helpers --> RaceSim
    UtilsConfig --> RaceSim
    Helpers --> RunPreprocessor

    StreamlitApp -->|runs in| Dockerfile
    FastAPIApp -->|runs in| Dockerfile
    MLflowServer -->|runs in| DockerCompose
    Dockerfile --> DockerCompose
    DevContainer --> Dockerfile

    %% Click events
    click F1Collector "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/fastf1_collector.py"
    click WeatherCollector "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/weather_collector.py"
    click Processor "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/data_processor.py"
    click Preprocessor "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/preprocessor.py"
    click Validator "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/validator.py"
    click RunPreprocessor "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/run_preprocessor.py"
    click RawStorage "https://github.com/spidey13/stratsim/blob/main/src/data_pipeline/data/categories/*.json"
    click ProcessedStorage "https://github.com/spidey13/stratsim/blob/main/data/processed/seasons_2023_2024_data*.csv"
    click ValidationReports "https://github.com/spidey13/stratsim/blob/main/data/validation/validation_report.txt"
    click Notebooks "https://github.com/spidey13/stratsim/blob/main/notebooks/model_training.ipynb"
    click TrainLapTime "https://github.com/spidey13/stratsim/blob/main/scripts/model_training/train_lap_time_model.py"
    click TrainTireWear "https://github.com/spidey13/stratsim/blob/main/scripts/model_training/train_tire_wear_model.py"
    click AnalyzeFeatures "https://github.com/spidey13/stratsim/blob/main/scripts/model_training/analyze_feature_importance.py"
    click CatBoostInfo "https://github.com/spidey13/stratsim/tree/main/catboost_info/"
    click ModelsDir "https://github.com/spidey13/stratsim/tree/main/src/models/"
    click MLflowUI "https://github.com/spidey13/stratsim/blob/main/scripts/utils/run_mlflow_ui.py"
    click RaceSim "https://github.com/spidey13/stratsim/blob/main/src/orchestrator/simulation_loop.py"
    click BaseAgent "https://github.com/spidey13/stratsim/blob/main/src/agents/base_agent.py"
    click StrategyAgent "https://github.com/spidey13/stratsim/blob/main/src/agents/strategy_agent.py"
    click TireManager "https://github.com/spidey13/stratsim/blob/main/src/agents/tire_manager_agent.py"
    click LapTimeAgent "https://github.com/spidey13/stratsim/blob/main/src/agents/lap_time_agent.py"
    click WeatherAgent "https://github.com/spidey13/stratsim/blob/main/src/agents/weather_agent.py"
    click VehicleDyn "https://github.com/spidey13/stratsim/blob/main/src/agents/vehicle_dynamics_agent.py"
    click GapEffects "https://github.com/spidey13/stratsim/blob/main/src/agents/gap_effects_agent.py"
    click GripModel "https://github.com/spidey13/stratsim/blob/main/src/agents/grip_model_agent.py"
    click TireWear "https://github.com/spidey13/stratsim/blob/main/src/agents/tire_wear_agent.py"
    click TireTemp "https://github.com/spidey13/stratsim/blob/main/src/agents/tire_temperature_agent.py"
    click APIEndpoints "https://github.com/spidey13/stratsim/blob/main/src/api/endpoints.py"
    click StreamlitApp "https://github.com/spidey13/stratsim/blob/main/web/streamlit_app.py"
    click FastAPIApp "https://github.com/spidey13/stratsim/blob/main/web/app.py"
    click Scripts "https://github.com/spidey13/stratsim/blob/main/scripts/run_simulation.py"
    click Settings "https://github.com/spidey13/stratsim/blob/main/src/config/settings.py"
    click SimConfig "https://github.com/spidey13/stratsim/blob/main/src/config/simulation_config.py"
    click Helpers "https://github.com/spidey13/stratsim/blob/main/src/utils/helpers.py"
    click UtilsConfig "https://github.com/spidey13/stratsim/blob/main/src/utils/config.py"
    click DevContainer "https://github.com/spidey13/stratsim/blob/main/.devcontainer/devcontainer.json"
    click Dockerfile "https://github.com/spidey13/stratsim/tree/main/Dockerfile"
    click DockerCompose "https://github.com/spidey13/stratsim/blob/main/docker-compose.yml"

    %% Styles
    classDef external fill:#A6E1FA,stroke:#31708E,color:#000
    classDef pipeline fill:#FFF2CC,stroke:#E6B800,color:#000
    classDef storage fill:#D9EAD3,stroke:#6AA84F,color:#000
    classDef ml fill:#F4CCCC,stroke:#CC0000,color:#000
    classDef orchestrator fill:#C9DAF8,stroke:#0B5394,color:#000
    classDef agent fill:#EAD1DC,stroke:#990033,color:#000
    classDef api fill:#D0E0E3,stroke:#135D6A,color:#000
    classDef ui fill:#F9CB9C,stroke:#B45F06,color:#000
    classDef infra fill:#D5A6BD,stroke:#741B47,color:#000
    classDef config fill:#CCE5FF,stroke:#144A86,color:#000
    classDef utils fill:#E6E6E6,stroke:#666666,color:#000
```
