# bhakiyakalimuthu/backrunner architecture

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

- Interactive diagram: https://gitdiagram.com/bhakiyakalimuthu/backrunner
- Repository: https://github.com/bhakiyakalimuthu/backrunner

## Overview

##### Main Components
- Command-Line Entry Point: Represent the executable starting point in the "cmd" directory (cmd/main.go). This is where the application is bootstrapped.
- Configuration Manager: Show the "config" package (config/config.go) that loads and manages environment variables and other configuration data.
- The main runner logic (runner/runner.go, runner/trade.go, runner/unitrade.go) handling the arbitrage and trade flows.
- Unit tests (runner/unitrade_test.go) indicate that this module’s functionality is core to the system.
- ABI and Smart Contract Interfaces: Include the various ABI packages within the "runner/abi" directory. They provide the interface definitions to the deployed smart contracts such as BackrunExecutor, IERC20, ISushiPair, IUniPool, and factory contracts for Uniswap and SushiSwap. Also, note that the "contracts" folder contains the compiled ABI and binary files, which are the artifacts deployed on-chain.
- External Blockchain Services: Represent external interactions such as:
- Ethereum (using the ETH_CLIENT_WSS_URL) as the primary network interface for scanning transactions.
- Flashbots Relay (using FLASHBOTS_RELAY_URL) for bundling and relaying transactions.
- Environment and Deployment Utilities: Indicate support for Docker (Dockerfile, make docker-image/docker-run) and Makefile scripts used for tasks such as testing, building, and linting.

##### Relationships and Interactions
- Usage of contract artifacts by showing how the contract binaries and ABIs in the "contracts" folder are referenced by the ABI packages in runner/abi.
- That the application is containerizable by adding a Docker container block that encapsulates the entire process (referencing Dockerfile and Makefile scripts).

##### Important Architectural Patterns and Technologies
- Modular Design: Distinct separation between configuration management, business logic (arbitrage/trading), and blockchain smart contract interactions.
- Decoupling: The project design allows easy addition of more trade types (as mentioned in the README), suggesting modular expansion in the future.
- Use of Environment-Driven Configuration: The .env file (as shown by .env.example) is central to switching between testing or production roles.
- Technology Stack: Mention Go (version 1.19), operating systems (Ubuntu/OSX), and the usage of Docker for deployment. Additionally, highlight integration with external blockchain services (Ethereum node and Flashbots).

##### Essentials
- Component is clearly labeled (e.g., “cmd (Main Entry Point)”, “Configuration Manager”, “Trading & Runner Logic”, “Smart Contract ABI Interfaces”).
- Blockchain integration components (e.g., ABI modules, smart contracts, external services) in another.
- Deployment and auxiliary utilities (Docker, Makefile) in a separate style.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Initialization Layer
    subgraph "Initialization Layer"
        EP["Entry Point (cmd/main.go)"]:::core
        CM["Configuration Manager (config/config.go)"]:::core
        EP -->|"initializes"| CM
        EC["Environment Config (.env.example)"]:::deployment
        EC -->|"loads"| CM
    end

    %% Trading & Runner Layer
    subgraph "Trading & Runner Layer"
        RL["Runner Logic (runner/runner.go)"]:::core
        TL["Trade Logic (runner/trade.go, runner/unitrade.go)"]:::core
        UT["Unit Testing (runner/unitrade_test.go)"]:::core
        CM --> RL
        CM --> TL
        CM --> UT
    end

    %% Blockchain Integration Layer
    subgraph "Blockchain Integration Layer"
        ABI["Smart Contract ABI Interfaces (runner/abi)"]:::blockchain
        CA["Contract Artifacts (contracts/build)"]:::blockchain
        ETH["ETH Client"]:::external
        FB["Flashbots Relay"]:::external
        %% Relationships
        RL -->|"invokes"| ABI
        TL -->|"triggers"| ETH
        TL -->|"triggers"| FB
        ABI -->|"references"| CA
    end

    %% Deployment & Environment Utilities
    subgraph "Deployment & Environment Utilities"
        DOCK["Docker (Dockerfile)"]:::deployment
        MF["Makefile (Makefile)"]:::deployment
    end

    %% Deployment integration
    DOCK ---|"containerizes"| EP
    MF ---|"builds"| EP

    %% Classes and Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px,color:#1B4F72;
    classDef blockchain fill:#F9E79F,stroke:#B7950B,stroke-width:2px,color:#B7950B;
    classDef external fill:#A9DFBF,stroke:#196F3D,stroke-width:2px,color:#196F3D;
    classDef deployment fill:#F5B7B1,stroke:#922B21,stroke-width:2px,color:#922B21;

    %% Click Events
    click EP "https://github.com/bhakiyakalimuthu/backrunner/blob/main/cmd/main.go"
    click CM "https://github.com/bhakiyakalimuthu/backrunner/blob/main/config/config.go"
    click RL "https://github.com/bhakiyakalimuthu/backrunner/blob/main/runner/runner.go"
    click TL "https://github.com/bhakiyakalimuthu/backrunner/blob/main/runner/trade.go"
    click UT "https://github.com/bhakiyakalimuthu/backrunner/blob/main/runner/unitrade_test.go"
    click ABI "https://github.com/bhakiyakalimuthu/backrunner/tree/main/runner/abi"
    click CA "https://github.com/bhakiyakalimuthu/backrunner/tree/main/contracts/build"
    click DOCK "https://github.com/bhakiyakalimuthu/backrunner/tree/main/Dockerfile"
    click MF "https://github.com/bhakiyakalimuthu/backrunner/tree/main/Makefile"
    click EC "https://github.com/bhakiyakalimuthu/backrunner/blob/main/.env.example"
```
