# alextcn/dex-arbitrage architecture

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

- Interactive diagram: https://gitdiagram.com/alextcn/dex-arbitrage
- Repository: https://github.com/alextcn/dex-arbitrage

## Overview

- Bot Engine – This is the core part of the system with modules in the src directory (e.g., app.ts, dex.ts, trade.ts, pair.ts, token.ts, route.ts), which collectively implement the arbitrage logic.
- Smart Contracts – Found under the contracts and abi directories; these components include the deployed contracts and their corresponding ABIs. They are used for on-chain interactions.
- Utility and Helper Modules – In the src/utils folder (and parts of the scripts folder) that include functions for things like balance handling (bn.ts), dex utilities (dex.ts, uni.js), and general-purpose functions (utils.ts).
- Deployment and Scripting – The scripts directory contains various deployment and trading scripts (e.g., deploy.ts, trade.js, flashswap.js) used for deploying contracts and executing trades.
- Testing – The test folder indicates there are unit and integration tests (using both .js and .ts) to verify the arbitrage logic and flash loan mechanisms.
- Configuration – Components like hardhat.config.ts, config.json, and tsconfig.json specify the environment settings, network configurations, and TypeScript builds needed for blockchain connectivity and smart contract compilation.

##### External systems and interactions
- Ethereum Mainnet/Fork Node – As noted in the README’s instructions, the bot connects to a mainnet fork using Hardhat (forking from Alchemy via a provided API key). Represent this as an external blockchain network.
- DEX Platforms – Represent each supported DEX (Uniswap V2, Balancer V2, and planned Uniswap V3) as external services with which the bot interacts to monitor prices, fetch liquidity data, and execute trades.
- Environment Dependencies – Indicate configuration inputs (for example, via .env for API keys and private keys) which affect both contract deployment and transaction signing.

##### Relationships and data flows
- A flow from the deployment scripts to the Smart Contracts component, emphasizing contract deployment and subsequent interactions.
- Role of utility modules (in src/utils) as providing support functions leveraged by the trading and smart-contract interaction layers.

##### Architectural patterns and technologies
- Service Separation – Clearly demarcate application logic (in src) from deployment scripts (in scripts) and testing suites. This reflects a separation of concerns.
- Modular Structure – Note that the application is modular with each file (or closely related sets of files) handling specific aspects (e.g., routing, token management, DEX-specific calculations).
- Technology Stack – Optionally add notes on using TypeScript (due to the .ts files), JavaScript components (e.g., in the scripts and some utils files), and the Hardhat framework for deployment and testing.

##### Final recommendations for the principal software engineer
- That every module or component has a clear label.
- Out the interactions not only within the code base (e.g., function calls among files in the src directory) but also the integration points with external systems like the Ethereum node and DEX APIs.
- The design should capture the complexity of the arbitrage logic, the smart contract deployment & interaction flow, as well as how configuration (like API keys and network settings) ties into the overall architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    EN["Ethereum Mainnet/Fork Node"]:::external
    subgraph "DEX Platforms"
        UniswapV2["Uniswap V2"]:::external
        BalancerV2["Balancer V2"]:::external
        UniswapV3["Uniswap V3 (Planned)"]:::external
    end

    %% Configuration Cluster
    subgraph "Configuration Files"
        Hardhat["Hardhat.config.ts"]:::config
        ConfigFile["config.json"]:::config
        TSConfig["tsconfig.json"]:::config
    end

    %% Bot Engine (src) Cluster
    subgraph "Bot Engine (src)"
        App["app.ts"]:::botengine
        Dex["dex.ts"]:::botengine
        Trade["trade.ts"]:::botengine
        Pair["pair.ts"]:::botengine
        Token["token.ts"]:::botengine
        Route["route.ts"]:::botengine
    end

    %% Utility and Helper Modules (src/utils)
    subgraph "Utility Modules (src/utils)"
        BN["bn.ts"]:::util
        DexUtil["dex.ts"]:::util
        UniUtil["uni.js"]:::util
        UtilsUtil["utils.ts"]:::util
        Xapp["xapp.js"]:::util
    end

    %% Smart Contracts Cluster
    subgraph "Smart Contracts"
        Contracts["Contracts (contracts/)"]:::smart
        ABIs["ABIs (abi/balancer.ts)"]:::smart
    end

    %% Deployment and Scripting Cluster
    subgraph "Deployment Scripts (scripts)"
        Deploy["deploy.ts"]:::script
        TradeScript["trade.js"]:::script
        Flashswap["flashswap.js"]:::script
    end

    %% Testing Suite Cluster
    subgraph "Testing Suite (test)"
        FlashLoanTest["FlashLoanSwap.test.js"]:::test
        FlashswapTest["Flashswap.test.ts"]:::test
        TradeTest["Trade.test.ts"]:::test
    end

    %% Relationships and Data Flows
    %% Configuration influences Bot Engine and Deployment Scripts
    Hardhat --> App
    ConfigFile --> Deploy
    TSConfig --> App

    %% Bot Engine calls on-chain data and DEX market feeds
    App -->|"onchain_call"| EN
    App -->|"fetch_prices"| UniswapV2
    App -->|"fetch_prices"| BalancerV2
    App -->|"fetch_prices"| UniswapV3

    %% Internal Module Interactions within Bot Engine
    App -->|"calls"| Trade
    Trade -->|"uses"| Dex
    Trade -->|"uses"| Pair
    Trade -->|"uses"| Token
    Trade -->|"uses"| Route

    %% Bot Engine leverages Utility Modules
    Trade -->|"utilizes"| UtilsUtil

    %% Bot Engine interacts with Smart Contracts for on-chain transactions
    Trade -->|"contract_call"| Contracts

    %% Deployment Scripts deploy contracts
    Deploy -->|"deploys"| Contracts

    %% Testing Suite validates Bot Engine and Deployment Scripts interactions
    FlashLoanTest -->|"tests"| Trade
    FlashswapTest -->|"tests"| Flashswap
    TradeTest -->|"tests"| Trade

    %% Styling Connections from Configuration to Deployment Scripts
    Hardhat --- Deploy

    %% Styling: External dependencies from Configuration to Utility Modules can be assumed
    ConfigFile --- BN

    %% Class Declarations
    classDef botengine fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef smart fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef util fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef script fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef test fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#F39C12,stroke-width:2px;

    %% Click Events for Bot Engine Files
    click App "https://github.com/alextcn/dex-arbitrage/blob/main/src/app.ts"
    click Dex "https://github.com/alextcn/dex-arbitrage/blob/main/src/dex.ts"
    click Trade "https://github.com/alextcn/dex-arbitrage/blob/main/src/trade.ts"
    click Pair "https://github.com/alextcn/dex-arbitrage/blob/main/src/pair.ts"
    click Token "https://github.com/alextcn/dex-arbitrage/blob/main/src/token.ts"
    click Route "https://github.com/alextcn/dex-arbitrage/blob/main/src/route.ts"

    %% Click Events for Smart Contracts
    click Contracts "https://github.com/alextcn/dex-arbitrage/tree/main/contracts/"
    click ABIs "https://github.com/alextcn/dex-arbitrage/blob/main/abi/balancer.ts"

    %% Click Events for Utility Modules
    click BN "https://github.com/alextcn/dex-arbitrage/blob/main/src/utils/bn.ts"
    click DexUtil "https://github.com/alextcn/dex-arbitrage/blob/main/src/utils/dex.ts"
    click UniUtil "https://github.com/alextcn/dex-arbitrage/blob/main/src/utils/uni.js"
    click UtilsUtil "https://github.com/alextcn/dex-arbitrage/blob/main/src/utils/utils.ts"
    click Xapp "https://github.com/alextcn/dex-arbitrage/blob/main/src/utils/xapp.js"

    %% Click Events for Deployment Scripts
    click Deploy "https://github.com/alextcn/dex-arbitrage/blob/main/scripts/deploy.ts"
    click TradeScript "https://github.com/alextcn/dex-arbitrage/blob/main/scripts/trade.js"
    click Flashswap "https://github.com/alextcn/dex-arbitrage/blob/main/scripts/flashswap.js"

    %% Click Events for Testing Suite
    click FlashLoanTest "https://github.com/alextcn/dex-arbitrage/blob/main/test/FlashLoanSwap.test.js"
    click FlashswapTest "https://github.com/alextcn/dex-arbitrage/blob/main/test/Flashswap.test.ts"
    click TradeTest "https://github.com/alextcn/dex-arbitrage/blob/main/test/Trade.test.ts"

    %% Click Events for Configuration Files
    click Hardhat "https://github.com/alextcn/dex-arbitrage/blob/main/hardhat.config.ts"
    click ConfigFile "https://github.com/alextcn/dex-arbitrage/blob/main/config.json"
    click TSConfig "https://github.com/alextcn/dex-arbitrage/blob/main/tsconfig.json"
```
