# cryptocj520/bphltaoli architecture

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

- Interactive diagram: https://gitdiagram.com/cryptocj520/bphltaoli
- Repository: https://github.com/cryptocj520/bphltaoli

## Overview

##### Main Components
- Arbitrage Engine: Represented by the core/arbitrage_engine.py module, this is responsible for the main logic of calculating opportunities, executing trades, and managing open/close conditions.
- Exchange Interfaces: Modules under funding_arbitrage_bot/exchanges (e.g., backpack_api.py, hyperliquid_api.py) abstract the API interactions with the respective exchanges.
- Risk Management: Although the README mentions risk_manager.py (even if it isn’t explicitly in the file tree, its concepts are detailed in the documentation), include this as a critical component to manage position sizes, stop-loss, and other controls.
- Strategy Module: The strategies directory (e.g., funding_arbitrage.py) contains the specific arbitrage tactics and conditional logic.
- Utilities: The utils directory contains supporting functions (logging, diagnostics, helpers, SDK wrappers) that provide cross-cutting support for error logging, data formatting, etc.
- Configuration & Data Management: The config.yaml file centrally defines API keys, strategy parameters, and risk settings. Also, include the data folder (which stores funding_diff_signs.json and possibly other data feeds) and logs folder for recorded telemetry.

##### Relationships and Interactions
- The Main Program Entry (main.py, run.py, run_bot.py) initiates the system, loads configurations from config.yaml, and sets up the arbitrage engine.
- The Arbitrage Engine pulls real-time market data and funding rates via the Exchange Interfaces.
- The engine then utilizes strategy logic to evaluate the arbitrage opportunity, while consulting risk management controls (even if implicit in the engine or configured via external modules).
- Once an opportunity meets the required conditions (including direction consistency, slippage control, and risk limits), the engine triggers trade execution.
- Throughout the process, the utilities (logger, diagnostics, display, helpers) record events, process data, and output user information in real time.

##### Architectural Patterns
- Layered Architecture: Separation of concerns is evident, with distinct layers for core logic, external APIs, strategies, and supporting utilities.
- Modular Design: Each component (arbitrage engine, exchange modules, utilities) is developed as a standalone module, promoting reusability and easy maintenance.
- Configurable Strategy: The system uses YAML files to manage dynamic configurations which allow for enhancing or altering trading conditions without deep code changes.
- Real-time Feedback: Integrated logging and diagnostic systems provide detailed transaction and error reporting.

##### Relevant Technologies
- Python 3.8+ as the core programming language.
- Usage of YAML for configuration management.
- API integrations with external trade exchanges (Hyperliquid and Backpack).
- Logging frameworks for detailed event recording.
- (Implicitly) JSON processing for funding data management.

– Configuration Manager (config.yaml and data management)
– Arbitrage Engine (core functionality including arbitrage_engine.py)
– Exchange API Modules (Hyperliquid and Backpack APIs)
– Strategy and Risk Management (strategy logic, risk controls)
– Utility Services (logging, diagnostics, helpers)
– User Interface/Display (terminal outputs, logging dashboards)
– Data flows (e.g., configuration settings and market data feed into the engine)
– Execution paths (from arbitrage engine to exchange API modules for placing orders)
– Feedback loops (logs and diagnostics returning status updates to the user)

##### Final Detailed Outline
- “Exchange API: Hyperliquid” and “Exchange API: Backpack” on one side (illustrate two parallel external integrations).
- “Risk Management” module attached to the arbitrage engine, influencing its decision process.
- “Strategy Module” (or “Arbitrage Logic/Strategy”) that defines conditions (like open/close conditions, slippage control, and direction consistency).
- “Configuration Manager” (with config.yaml) connected as the input fed by external settings and parameters.
- An “Utility Module” block connected to all major components (for logging, diagnostics, and display management).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Bootstrap Layer
    subgraph "Bootstrap Layer"
        MP("Main Program Entry"):::bootstrap
    end

    %% Configuration & Data Layer
    subgraph "Configuration & Data Layer"
        CF("Config File"):::config
        FD("Funding Data"):::config
    end

    %% Core Engine Layer
    subgraph "Core Engine Layer"
        AE("Arbitrage Engine"):::backend
    end

    %% Exchange Layer
    subgraph "Exchange Layer"
        EH("Exchange API: Hyperliquid"):::external
        EB("Exchange API: Backpack"):::external
    end

    %% Strategy & Risk Layer
    subgraph "Strategy & Risk Layer"
        SM("Strategy Module"):::strategy
        RM("Risk Management"):::risk
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        UT("Utilities"):::utility
    end

    %% Data & Logs Layer
    subgraph "Data & Logs Layer"
        DL("Data Store & Logs"):::datastore
    end

    %% Connections
    MP --> CF
    MP --> FD
    MP --> AE
    CF --> AE
    FD --> AE
    AE --> EH
    AE --> EB
    AE --> SM
    AE --> RM
    UT --- AE
    UT --- EH
    UT --- EB
    UT --- SM
    UT --- RM
    AE --> DL
    UT --> DL

    %% Click Events
    click MP "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/main.py"
    click AE "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/core/arbitrage_engine.py"
    click EH "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/exchanges/hyperliquid_api.py"
    click EB "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/exchanges/backpack_api.py"
    click SM "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/strategies/funding_arbitrage.py"
    click CF "https://github.com/cryptocj520/bphltaoli/blob/main/funding_arbitrage_bot/config.yaml"
    click FD "https://github.com/cryptocj520/bphltaoli/blob/main/data/funding_diff_signs.json"
    click UT "https://github.com/cryptocj520/bphltaoli/tree/main/funding_arbitrage_bot/utils/"

    %% Styles
    classDef bootstrap fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef config fill:#FFFFE0,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef external fill:#F08080,stroke:#000,stroke-width:2px;
    classDef strategy fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef risk fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef utility fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef datastore fill:#FFFACD,stroke:#000,stroke-width:2px;
```
