# notlelouch/arbibot architecture

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

- Interactive diagram: https://gitdiagram.com/notlelouch/arbibot
- Repository: https://github.com/notlelouch/arbibot

## Overview

##### Project type and purpose
- This is a backend service written in Go that functions as a high-performance, cross-exchange arbitrage bot.
- It is a CLI/daemon application that connects via WebSocket and REST to cryptocurrency exchanges (Hyperliquid, KuCoin), processes real-time order book data, identifies price discrepancies, and triggers trades.

##### File structure
- Top level:
- cmd/arbibot/main.go – the entrypoint
- internal/ – application code (no public API)
- assets/ – static files (demo gif)
- internal/ modules:
- exchange/… – one sub-package per exchange: hyperliquid, kucoin. Each handles connection setup, authentication, subscription to market data, order execution.
- arbitrage/… – core logic for comparing prices across exchanges, calculating spreads, and deciding when to execute trades.
- types/… – shared domain types (order book entries, price ticks, arbitrage opportunities).
- ui/… – simple dashboard (likely console or HTTP) for displaying live arbitrage stats.

##### README for additional insights
- Emphasizes real-time WebSocket feeds, low latency, modular design, graceful shutdown.
- Supported exchanges listed, demonstrating easy extension by adding new exchange sub-packages.

a. Main components
- ArbiBot Entrypoint (cmd/arbibot)
- Exchange Connectors (Hyperliquid WS client, KuCoin WS/REST client)
- Arbitrage Engine (internal/arbitrage)
- Shared Types Library (internal/types)
- UI Dashboard (internal/ui)
- External Exchanges (Hyperliquid, KuCoin)

b. Relationships and interactions
1. EntryPoint initializes connectors and the arbitrage engine.
2. Exchange Connectors open WebSocket/REST streams to external exchanges.
3. Market data flows (order book updates) from connectors into the Arbitrage Engine.
4. Arbitrage Engine analyzes data, emits “Opportunity” events.
5. On decision, the engine invokes connectors’ trade methods.
6. UI Dashboard subscribes to engine events and renders real-time stats.
7. Graceful shutdown signal propagates to all components, closing connections.

c. Architectural patterns/design principles
- Layered modularity: separates concerns into connectors, core logic, types, and UI.
- Plugin-style connectors: each exchange implements a uniform interface.
- Event-driven flow: data updates trigger analysis and trade events.
- Dependency inversion: core engine depends on interfaces defined in types, concrete implementations reside in exchange sub-packages.

d. Key technologies/frameworks
- Go modules for dependency management
- Go’s concurrency primitives (goroutines, channels) for streaming data and event handling
- WebSocket libraries (built-in or third-party) for real-time feeds
- REST client for authenticated trading APIs
- Makefile for building and running

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ArbiBot Service"
        EP["Entrypoint\ncmd/arbibot/main.go"]:::entrypoint
        SD["Shutdown Handler"]:::entrypoint
        subgraph "Connectors"
            EXAB["Connector Abstraction\ninternal/exchange/exchange.go"]:::connector
            HL["Hyperliquid Connector\nhyperliquid.go"]:::connector
            HLTypes["Hyperliquid Types\ntypes.go"]:::connector
            KCAuth["KuCoin Auth/REST\nauth.go"]:::connector
            KC["KuCoin Connector\nkucoin.go"]:::connector
        end
        AE["Arbitrage Engine\narbitrage.go"]:::core
        ST["Shared Types\ntypes.go"]:::core
        UI["UI Dashboard\ndashboard.go"]:::ui
    end

    subgraph External
        ExtHL["Hyperliquid Exchange"]:::external
        ExtKC["KuCoin Exchange"]:::external
    end

    EP --> AE
    EP --> EXAB
    EXAB --> HL
    EXAB --> KC
    HL --> HLTypes
    KC --> KCAuth
    HL -->|"OrderBookUpdate"| AE
    KC -->|"OrderBookUpdate"| AE
    AE --> ST
    AE --> UI
    AE -->|"TradeOrder"| HL
    AE -->|"TradeOrder"| KC
    HL -->|"WS/REST"| ExtHL
    KCAuth -->|"REST"| ExtKC
    SD --> EP
    SD --> EXAB
    SD --> HL
    SD --> KC
    SD --> AE
    SD --> UI

    click EP "https://github.com/notlelouch/arbibot/blob/main/cmd/arbibot/main.go"
    click EXAB "https://github.com/notlelouch/arbibot/blob/main/internal/exchange/exchange.go"
    click HL "https://github.com/notlelouch/arbibot/blob/main/internal/exchange/hyperliquid/hyperliquid.go"
    click HLTypes "https://github.com/notlelouch/arbibot/blob/main/internal/exchange/hyperliquid/types.go"
    click KCAuth "https://github.com/notlelouch/arbibot/blob/main/internal/exchange/kucoin/auth.go"
    click KC "https://github.com/notlelouch/arbibot/blob/main/internal/exchange/kucoin/kucoin.go"
    click AE "https://github.com/notlelouch/arbibot/blob/main/internal/arbitrage/arbitrage.go"
    click ST "https://github.com/notlelouch/arbibot/blob/main/internal/types/types.go"
    click UI "https://github.com/notlelouch/arbibot/blob/main/internal/ui/dashboard.go"

    classDef core fill:#ADD8E6,color:#000;
    classDef connector fill:#90EE90,color:#000;
    classDef external fill:#FFA500,color:#000;
    classDef entrypoint fill:#D3D3D3,color:#000;
    classDef ui fill:#ADD8E6,color:#000;
```
