# davidteather/imc-prosperity-2024 architecture

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

- Interactive diagram: https://gitdiagram.com/davidteather/imc-prosperity-2024
- Repository: https://github.com/davidteather/imc-prosperity-2024

## Overview

This project is a simulation tool for an algorithmic trading competition (IMC Prosperity 2024). Its primary purpose is to simulate trading rounds by ingesting historical market data (prices and trades) from CSV files and executing trades (either manual or algorithmic) using a simulator module. The repository contains data sets for multiple trading rounds (organized into “datasets” and “datasets_2023”), helper scripts for manual trade executions and optimization routines, and a simulator package that contains both core simulation logic (simulator.py) and tests (simulator_test.py).

##### Main Components
- Data Sources: Represented by the datasets directories (e.g., “datasets”, “datasets_2023”). These directories contain CSV files with historical prices and trade data for various trading rounds.
- Data Preprocessor: The “preprocess.py” script likely serves to clean, validate, or organize incoming CSV data.
- Core Simulator: The “simulator” package (especially simulator.py) that handles the main simulation logic. This module receives processed data and executes simulation runs.
- Trading Logic / Algorithms: The “helpers” directory contains scripts for manual trading functions and an “optimize.py” that likely assists in strategy optimization. Although the README mentions that they did not have enough time to complete every algorithm for all rounds, these components still represent the trade decision-making aspect.
- Main Application: “main.py” acts as an entry point and leverages the simulator module to run simulations by accepting command-line arguments for data files.
- Testing/Validation: Simulator tests (simulator_test.py) show that there’s a testing component ensuring that simulation logic works as expected.
- Configuration/Build: Files like “requirements.txt”, “Makefile”, and “.gitignore” indicate dependency management and build/setup instructions.

##### Relationships and Interactions
- Data flows from the Data Sources (CSV files) into the Data Preprocessor, which then feeds validated and possibly cleaned data into the Simulator.
- The Simulator communicates with trading algorithms (from the “helpers” scripts) to determine trade actions based on the processed data.
- The Main Application scripts use the Simulator to drive an end-to-end simulation run by passing file inputs.
- Testing components validate the simulator’s functioning in a controlled environment.

##### Architectural Patterns & Design Principles
- Modularization: The system splits functionality into distinct modules – data ingestion, preprocessing, simulation core, and trade logic helpers.
- Separation of Concerns: Different directories clearly encapsulate various concerns (data vs. simulation logic vs. helper methods), even though the project notes it’s “fairly disorganized”.
- Command-line Interface (CLI): The README describes CLI commands that drive simulation execution which points to a decoupled input/processing structure.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        DS1["datasets (CSV Files)"]:::datasource
        DS2["datasets_2023 (CSV Files)"]:::datasource
    end

    %% Data Preprocessing
    PRE["preprocess.py"]:::processor

    %% Core Simulator
    subgraph "Core Simulator"
        SIM["simulator.py"]:::simulator
        SIM_TEST["simulator_test.py"]:::simulator
    end

    %% Trading Logic / Algorithms
    HELP["helpers (Trading Logic/Algorithms)"]:::helper

    %% Main Application
    MA["main.py (Entry Point)"]:::mainapp

    %% Configuration / Build Files
    subgraph "Configuration/Build"
        CONF1["Makefile"]:::config
        CONF2["requirements.txt"]:::config
        CONF3[".gitignore"]:::config
    end

    %% Data Flow
    DS1 -->|"CSVData"| PRE
    DS2 -->|"CSVData"| PRE
    PRE -->|"ProcessedData"| SIM
    SIM -->|"Validation"| SIM_TEST
    SIM -->|"TradingDecisions"| HELP
    HELP -->|"AlgorithmFeedback"| SIM
    MA -->|"ExecutesRun"| SIM

    %% Click Events
    click DS1 "https://github.com/davidteather/imc-prosperity-2024/tree/main/datasets"
    click DS2 "https://github.com/davidteather/imc-prosperity-2024/tree/main/datasets_2023"
    click PRE "https://github.com/davidteather/imc-prosperity-2024/blob/main/preprocess.py"
    click SIM "https://github.com/davidteather/imc-prosperity-2024/blob/main/simulator/simulator.py"
    click SIM_TEST "https://github.com/davidteather/imc-prosperity-2024/blob/main/simulator/simulator_test.py"
    click HELP "https://github.com/davidteather/imc-prosperity-2024/tree/main/helpers"
    click MA "https://github.com/davidteather/imc-prosperity-2024/blob/main/main.py"
    click CONF1 "https://github.com/davidteather/imc-prosperity-2024/tree/main/Makefile"
    click CONF2 "https://github.com/davidteather/imc-prosperity-2024/blob/main/requirements.txt"
    click CONF3 "https://github.com/davidteather/imc-prosperity-2024/blob/main/.gitignore"

    %% Styles
    classDef datasource fill:#8ecae6,stroke:#023047,stroke-width:2px;
    classDef processor fill:#ffb703,stroke:#fb8500,stroke-width:2px;
    classDef simulator fill:#219ebc,stroke:#001219,stroke-width:2px;
    classDef helper fill:#ffadad,stroke:#e63946,stroke-width:2px;
    classDef mainapp fill:#caffbf,stroke:#4caf50,stroke-width:2px;
    classDef config fill:#d0f4de,stroke:#00b894,stroke-width:2px;
```
