# john-trager/uchicago-trading-competition architecture

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

- Interactive diagram: https://gitdiagram.com/john-trager/uchicago-trading-competition
- Repository: https://github.com/john-trager/uchicago-trading-competition

## Overview

##### Main Components
- Data Sources & Ingestion:
- Historical Market and Economic Data (CSV files spread across archive and utc_xchange directories).
- Investor forecasts and other supplemental data.
- Data Processing & Analysis:
- Jupyter Notebooks (e.g., *.ipynb inside archive for data analysis, graph plotting, etc.).
- Python analysis scripts and utilities (e.g., metrics.py, display_results.py, utils.py).
- Trading Strategy Modules:
- Case-specific algorithms (Case 1: market making and forecasting models, Case 2: option market making with risk hedging, Case 3: portfolio optimization via Black-Litterman and possibly reinforcement learning).
- Separate “bot” implementations (files such as case1_bot.py, case2_bot.py and various my_bot_v*.py scripts).
- Model Training & Simulation:
- RL agent and training scripts (rl_agent.py, rl_train.py, rl_sim.py).
- Backtesting and simulation modules (simulation.py, weights_history.csv, weights_genetic.csv).
- Communication/Protocol Layer:
- Proto definition modules (such as proto/utc_bot.proto and round_manager.py) that seem to facilitate integration with a trading simulation platform.
- Deployment/Execution Components:
- Executable versions for different platforms (e.g., xchange_win.exe, xchange_linux) in the utc_xchange_v2.0 directory which suggest a deployment aspect or interface layer.

##### Relationships and Interactions
- Data flows from various input CSV files into processing scripts and notebooks.
- Processed data is then fed into the model training or trading strategy modules.
- Trading algorithms (bots) use these models and simulation/trading logic to interact with a simulated (or competition-provided) trading environment.
- The protocol components (proto directory) serve as interfaces to ensure the bots and market simulations communicate correctly.
- There is an iterative loop where experimental results (simulated trades, model evaluation) can be reviewed within notebooks and scripts, and then refinements are made (potentially reflected in varied versions in the utc_xchange directories).

##### Architectural Patterns
- Modular Design: Even though the code appears “disorganized” as per the README, the separation into archives for each case and further refinements in versioned directories shows a modular approach to tackling different problems.
- Experimentation Environment: The combination of Jupyter Notebooks with script-based implementations indicates an experimental and data-driven development style.
- Separation of Concerns: There is a clear separation between data ingestion/analysis, strategy logic, simulation components, and interfaces to the trading platform.
- Versioning & Iterative Development: The existence of multiple utc_xchange versions underscores the iterative nature of refining trading strategies.

##### Details
- Different versioned implementations (utc_xchange_v1.2 versus utc_xchange_v2.0) as perhaps “evolutionary branches” or iterations in the system.
- Use of machine learning frameworks or any libraries (inferred from notebooks like those using Keras or torch files in the logs) if applicable.
- Where external documents, presentations, or references (e.g., the slide deck and blog strategy) support understanding of the system's rationale, even though they may not be part of code execution.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Sources & Ingestion
    subgraph "Data Sources & Ingestion"
        DS1["Historical CSV (Archive Case1)"]:::data
        DS2["Historical CSV (Archive Case3)"]:::data
        DS3["Historical CSV (utc_xchange_v1.2/data)"]:::data
        DS4["Historical CSV (utc_xchange_v2.0/data)"]:::data
    end

    %% Data Processing & Analysis
    subgraph "Data Processing & Analysis"
        DP1["Case3 Notebook: UTC Case 3"]:::processing
        DP2["Case1 Notebook: Data Analysis"]:::processing
        DP3["Utility: display_results.py"]:::processing
        DP4["Utility: metrics.py"]:::processing
        DP5["Utility: utils.py"]:::processing
        DP6["Case2 Notebook: Greeks Tutorial (v1.2)"]:::processing
        DP7["Case2 Notebook: Greeks Tutorial (v2.0)"]:::processing
    end

    %% Trading Strategy Modules
    subgraph "Trading Strategy Modules"
        TS1["Case1 Bot"]:::strategy
        TS2["Case2 Bot"]:::strategy
        TS3["Case3 Module"]:::strategy
        subgraph "utc_xchange_v1.2 Bots"
            TS4["my_bot_v1.py"]:::strategy
            TS5["my_bot_v2.py"]:::strategy
            TS6["my_bot_v3.py"]:::strategy
            TS7["my_bot_v4.py"]:::strategy
            TS8["my_bot_v5.py"]:::strategy
            TS9["my_bot_v6.py"]:::strategy
            TS10["market_making_bot.py"]:::strategy
        end
        subgraph "utc_xchange_v2.0 Bots"
            TS11["my_bot_v1.py"]:::strategy
            TS12["my_bot_v2.py"]:::strategy
            TS13["my_bot_v3.py"]:::strategy
            TS14["market_making_bot.py"]:::strategy
            TS15["case1_bot.py"]:::strategy
        end
    end

    %% Model Training & Simulation
    subgraph "Model Training & Simulation"
        MT1["RL Agent"]:::training
        MT2["RL Train"]:::training
        MT3["RL Simulation"]:::training
        MT4["Simulation"]:::training
        MT5["Weights History"]:::training
        MT6["Weights Genetic"]:::training
        MT7["Darts Logs"]:::training
    end

    %% Communication/Protocol
    subgraph "Communication/Protocol"
        CP1["UTC Bot Proto (v1.2)"]:::protocol
        CP2["Round Manager (v1.2)"]:::protocol
        CP3["UTC Bot (v1.2)"]:::protocol
        CP4["UTC Bot Proto (v2.0)"]:::protocol
        CP5["Round Manager (v2.0)"]:::protocol
        CP6["UTC Bot (v2.0)"]:::protocol
        CP7["Init Proto"]:::protocol
    end

    %% Deployment/Execution
    subgraph "Deployment/Execution"
        DE1["xchange_win.exe"]:::deployment
        DE2["xchange_linux"]:::deployment
        DE3["setup_xchange.py"]:::deployment
        DE4["Platform Reference (v1.2)"]:::deployment
        DE5["Platform Reference (v2.0)"]:::deployment
    end

    %% Data Flow Connections
    DS1 --> DP1
    DS2 --> DP1
    DS3 --> DP1
    DS4 --> DP1

    DP1 --> TS1
    DP2 --> TS2
    DP6 --> TS2
    DP7 --> TS2
    DP3 --> MT1
    DP4 --> MT1

    TS1 --> CP3
    TS11 --> CP6
    MT1 --> CP1

    CP3 --> DE1
    CP6 --> DE2

    %% Feedback Loop
    DE1 -- "feedback" --> DP1

    %% Additional Flows
    DP5 --> MT1

    %% Styles
    classDef data fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef processing fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef strategy fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef training fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef protocol fill:#e0ccff,stroke:#800080,stroke-width:2px;
    classDef deployment fill:#fff2cc,stroke:#999900,stroke-width:2px;

    %% Click Events
    click DS1 "https://github.com/john-trager/uchicago-trading-competition/tree/master/archive/Case1"
    click DS2 "https://github.com/john-trager/uchicago-trading-competition/tree/master/archive/Case3"
    click DS3 "https://github.com/john-trager/uchicago-trading-competition/tree/master/utc_xchange_v1.2/data"
    click DS4 "https://github.com/john-trager/uchicago-trading-competition/tree/master/utc_xchange_v2.0/data"
    
    click DP1 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/UTC Case 3.ipynb"
    click DP2 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case1/data_analysis.ipynb"
    click DP3 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case1/display_results.py"
    click DP4 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case1/metrics.py"
    click DP5 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case1/utils.py"
    click DP6 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/data/case2/case2_greeks_tutorial.ipynb"
    click DP7 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/data/case2/case2_greeks_tutorial.ipynb"
    
    click TS1 "https://github.com/john-trager/uchicago-trading-competition/blob/master/case1_bot.py"
    click TS2 "https://github.com/john-trager/uchicago-trading-competition/blob/master/case2_bot.py"
    click TS3 "https://github.com/john-trager/uchicago-trading-competition/blob/master/Case3.py"
    click TS4 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v1.py"
    click TS5 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v2.py"
    click TS6 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v3.py"
    click TS7 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v4.py"
    click TS8 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v5.py"
    click TS9 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/my_bot_v6.py"
    click TS10 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/market_making_bot.py"
    click TS11 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/my_bot_v1.py"
    click TS12 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/my_bot_v2.py"
    click TS13 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/my_bot_v3.py"
    click TS14 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/market_making_bot.py"
    click TS15 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/case1_bot.py"
    
    click MT1 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/rl_agent.py"
    click MT2 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/rl_train.py"
    click MT3 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/rl_sim.py"
    click MT4 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/simulation.py"
    click MT5 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/weights_history.csv"
    click MT6 "https://github.com/john-trager/uchicago-trading-competition/blob/master/archive/Case3/weights_genetic.csv"
    click MT7 "https://github.com/john-trager/uchicago-trading-competition/tree/master/archive/Case1/darts_logs"
    
    click CP1 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/proto/utc_bot.proto"
    click CP2 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/proto/round_manager.py"
    click CP3 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/proto/utc_bot.py"
    click CP4 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/proto/utc_bot.proto"
    click CP5 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/proto/round_manager.py"
    click CP6 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/proto/utc_bot.py"
    click CP7 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/proto/__init__.py"
    
    click DE1 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/xchange_win.exe"
    click DE2 "https://github.com/john-trager/uchicago-trading-competition/tree/master/utc_xchange_v2.0/xchange_linux"
    click DE3 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/setup_xchange.py"
    click DE4 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v1.2/platform-reference.md"
    click DE5 "https://github.com/john-trager/uchicago-trading-competition/blob/master/utc_xchange_v2.0/platform-reference.md"
```
