**HAUL**
========

*Hyperspace Asset Unloading and Loading*

**HAUL** is my old route planner and automation tool designed for EVE Online. It simplifies asset transportation by optimizing trade routes, automatically setting waypoints in-game, and identifying profitable trade opportunities through API integrations.

![screenshot](screenshot.png)

* * * * *

**Table of Contents**
---------------------

-   [Overview](#overview)
-   [Tech Stack](#tech-stack)
-   [Key Features](#key-features)
-   [Project Structure](#project-structure)

* * * * *

**Overview**
------------

HAUL is a full-stack application tailored for players of EVE Online, offering seamless route planning, waypoint automation, and trade optimization. It fetches live game data via the **EVE Swagger Interface (ESI)** API and utilizes modern web technologies to deliver a fast and interactive user experience.

The project comprises:

-   A **Python backend** that handles route calculations, API calls, and real-time updates.
-   A **React frontend** providing a clean and dynamic interface.
-   An **experimental Rust rewrite** of the backend focused on performance improvements.

* * * * *

**Tech Stack**
--------------

### **Backend (Python)**

-   **Framework**: FastAPI for high-performance API development.
-   **Asynchronous Processing**: `asyncio` and `aiohttp` for handling multiple concurrent API calls and non-blocking tasks.
-   **Database**: In-memory SQLite (`aiosqlite`) for high-performance market order processing and indexing.
-   **API Integration**:
    -   Extensive use of the **EVE Swagger Interface (ESI)** API for fetching in-game data, such as trade orders, solar system details, player locations, and wallet transactions.
-   **Automation**: Set waypoints in the EVE Online client through API interactions on command.
-   **Streaming Data**: Implements `StreamingResponse` to deliver real-time updates to the frontend.

### **Frontend (React)**

-   **Framework**: React for building dynamic, responsive user interfaces.
-   **State Updates**: Real-time state updates using server-sent events (SSE).

### **Experimental Rust Backend**
-   A rewrite of the Python backend focused on improving performance in API-intensive operations like route calculations

* * * * *

**Key Features**
----------------

1.  **Route Optimization**
    -   Calculates the shortest and safest routes between in-game locations based on:
        -   Travel time, warp speeds, and stargate connections.
        -   Risk factors, including security ratings of solar systems.
    -   Suggests optimized paths for asset transportation and trading.
    -   Allows pushing calculated routes as waypoints to the EVE Online client with a single click.

2.  **Profit Optimization**
    -   Identifies arbitrage opportunities by analyzing buy/sell orders across regions.
    -   Tracks confirmed trades automatically via wallet transaction history to remove filled orders locally.

3.  **Real-Time API Integration**
    -   Fetches live trade orders, player locations, recent wallet transactions, and solar system details using the EVE Swagger Interface (ESI) API.
    -   Continuously updates routes and trade data in real-time.
    -   Utilizes server-sent events to deliver live updates on trade opportunities, routes, and player location changes.

* * * * *

**Algorithm Criteria & Limits**
-------------------------------

The route planning and arbitrage algorithms evaluate the profitability and safety of moving items using configurable constraints:

1.  **Ship & Financial Limits**
    -   **Cargo Capacity**: Default limit of 4000m³ (configurable).
    -   **Maximum Route Capital**: Caps the up-front item purchase cost at 20,000,000 ISK initially (configurable).
    -   **Profit Threshold**: A single trade must yield a minimum gross profit (default 100,000 ISK, configurable).

2.  **Time & Navigational Costs**
    -   **Ship Speed**: Subject to specified `max_warp_speed` and `max_subwarp_speed` (configurable via UI).
    -   **Stargate Delay**: Each jump is assigned a fixed 9.0-second delay.
    -   **In-system Warp**: Calculates exact 3D geometry for acceleration and deceleration.
    -   **Player Time Cost**: The algorithm assigns a real-life configurable time value.

3.  **Risk & Safety Penalties**
    -   **Gank Zones**: Hardcoded danger zones (e.g., Ahbazon) multiply the risk penalty heavily.
    -   **Security Status**: High-sec space carries virtually no penalty, low-sec applies a 0.005 penalty, and null-sec adds a massive 0.5 risk penalty.
    -   **Value at Risk**: The calculated risk percentage is multiplied against the fixed risk penalty plus cargo values.

4.  **Trade Execution & Filtering Strategy**
    -   **Market Tax**: Accounts for a configurable transaction tax (default 8%).
    -   **Cross-Region Pairing**: Allows pickup and dropoff stations for a single item to be in different regions when both stations are present in the loaded market and navigation datasets.
    -   **Evaluation Limit**: Limits pathfinding to the top scoring trade triplets to conserve CPU overhead.
    -   **Snipe Feature Execution**: Background polling monitors loop regions actively for single trades that boast >20,000,000 ISK (configurable) gross profit. If triggered, it executes an automatic ESI API call to forcefully open your in-game client's market window to intercept the trade instantly.
    -   **ESI Error Limits**: Pauses backend routines entirely if the X-Esi-Error-Limit-Remain headers fall below 50.
    -   **The Final Metric**: The route chosen is the one that produces the highest `profit_rate` (which is `net_profit = total_profit - risk * capital` divided by `transport_time`).

* * * * *

**Project Structure**
---------------------

```
.
├── backend/             # Python backend
│   └── src/             # Core backend logic
├── frontend/            # React frontend
│   ├── src/             # React components
│   └── package.json     # Frontend dependencies
├── rust_backend/        # Experimental Rust rewrite
│   ├── src/             # Rust codebase
│   └── Cargo.toml       # Rust dependencies
├── scripts/             # Setup and run scripts
│   └── haul.sh          # Unified script for data/auth setup and app runtime
```

* * * * *

**Getting Started**
-------------------

HAUL uses a unified shell script to handle setup, data fetching, authorization, and running the application.

1.  **Check Environment**:
    Verify what prerequisites are missing by running:
    ```bash
    ./scripts/haul.sh check
    ```

2.  **Fetch Static Data**:
    HAUL requires EVE Online CSV dumps. Download and extract them automatically:
    ```bash
    ./scripts/haul.sh setup-data
    ```

3.  **Authenticate**:
    Set up your EVE SSO credentials and generate the auth cache:
    ```bash
    ./scripts/haul.sh setup-auth
    ```

4.  **Run the Application**:
    Start both the Python backend and React frontend concurrently:
    ```bash
    ./scripts/haul.sh up
    ```

    Alternatively, run them separately:
    ```bash
    ./scripts/haul.sh backend
    ./scripts/haul.sh frontend
    ```