# ajslashtracey/hl_limit_chase_v2 architecture

> Architecture diagram of the GitHub repository ajslashtracey/hl_limit_chase_v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ajslashtracey/hl_limit_chase_v2
- Repository: https://github.com/ajslashtracey/hl_limit_chase_v2

## Overview

##### Project Type and Purpose
- This is a Python-based trading automation tool (a domain-specific “bot”) that implements a limit-order chasing strategy on the Hyperliquid exchange.
- It is neither a web app nor a microservices ecosystem but rather a standalone library/CLI utility with example scripts, designed to place, refresh, monitor, and abort limit orders via the Hyperliquid API.

##### File-Structure Analysis
- hl_limit_chase/
- limit_chase.py       – Core algorithm (business logic for placing and refreshing orders)
- executor.py          – Integration layer: wraps REST & WebSocket calls to Hyperliquid
- trade_logger.py      – Persistence: writes fills/logs to CSV or a database (via DATABASE_URL)
- examples/               – Entry-point scripts demonstrating usage (CLI style)
- scripts/                – Auxiliary tooling (diagnose_setup.py)
- data/                   – Sample/test output (CSV)
- requirements.txt        – Dependency manifest
- .env                    – Configuration (API keys, flags)

##### README Insights
- Workflow steps described under “How It Works” mirror the control flow inside LimitChaser.
- Highlights optional external services: database for logging, NTFY for notifications.
- Emphasizes real-time order-book monitoring via WebSocket and REST calls for order placement.

##### Main Components & Boundaries
a. Entry-Point Layer
- CLI script (examples/limit_chase_usage.py or scripts/diagnose_setup.py)
- Reads configuration from `.env`
b. Core Domain Layer
- LimitChaser (limit_chase.py): orchestration of order lifecycle (place, refresh, abort, poll)
c. Integration Layer
- HyperliquidExecutor (executor.py):
- REST client (order placement, cancellation)
- WebSocket client (order-book subscription, fill notifications)
- LiveExchangeClient (example import wrapper around executor and symbol selection)
d. Persistence & Logging
- trade_logger.py:
- CSV writer (`data/limit_chase_accuracy.csv`)
- Optional DB writer (via DATABASE_URL)
e. External Services
- Hyperliquid Exchange API (REST & WebSocket)
- Notification Service (NTFY)
- Optional database (PostgreSQL, SQLite, etc.)

##### Architectural Patterns & Principles
- Layered separation:
- Presentation/CLI → Domain → Integration → Persistence → External
- Single-Responsibility: executor only calls APIs; logger only persists; chaser only orchestrates logic
- Dependency Injection: scripts instantiate the pieces, passing executor/logger into LimitChaser
- Config-driven behavior via environment variables

##### Essential Elements
- Clear component names (e.g., LimitChaser, HyperliquidExecutor, TradeLogger)
- Config block (.env) and Example Scripts as entry points
- External services: Hyperliquid API and optional notification/database

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration"
        ENV[".env"]:::entry
        REQ["requirements.txt"]:::entry
    end

    subgraph "Entry-Point Layer"
        CLI1["examples/limit_chase_usage.py"]:::entry
        CLI2["examples/test_limit_chase.py"]:::entry
    end

    subgraph "Core Domain Layer"
        LC["LimitChaser"]:::core
    end

    subgraph "Integration Layer"
        HE["HyperliquidExecutor"]:::integration
    end

    subgraph "Persistence & Logging"
        TL["TradeLogger"]:::persistence
        CSV["data/limit_chase_accuracy.csv"]:::persistence
        DB["Database (Optional)"]:::external
    end

    subgraph "External Services"
        API["Hyperliquid API"]:::external
        NTFY["NTFY Notifications"]:::external
    end

    ENV --> CLI1
    ENV --> CLI2
    REQ --> CLI1
    REQ --> CLI2

    CLI1 -->|"Instantiate"| LC
    CLI2 -->|"Instantiate"| LC

    LC -->|"Place Order / Cancel Order"| HE
    HE -->|"REST/WS Calls"| API
    API -->|"Order-Book Data"| HE
    HE -->|"Market Data"| LC

    LC -->|"Log Fill Event"| TL
    TL -->|"Write CSV"| CSV
    TL -->|"Write DB"| DB
    TL -->|"Send Notification"| NTFY

    click LC "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/hl_limit_chase/limit_chase.py"
    click HE "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/hl_limit_chase/executor.py"
    click TL "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/hl_limit_chase/trade_logger.py"
    click CLI1 "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/examples/limit_chase_usage.py"
    click CLI2 "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/examples/test_limit_chase.py"
    click ENV "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/.env.example"
    click CSV "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/data/limit_chase_accuracy.csv"
    click REQ "https://github.com/ajslashtracey/hl_limit_chase_v2/blob/main/requirements.txt"

    classDef core fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef integration fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef persistence fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef entry fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef external fill:#dda0dd,stroke:#333,stroke-width:1px;
```
