**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` for handling multiple concurrent API calls and tasks.
-   **API Integration**:
    -   Extensive use of the **EVE Swagger Interface (ESI)** API for fetching in-game data, such as trade orders, solar system details, and player locations.
-   **Automation**: Automatically sets waypoints in the EVE Online client through API interactions.
-   **Streaming Data**: Implements `StreamingResponse` to deliver real-time updates to the frontend.

### **Frontend (React)**

-   **Framework**: React for building dynamic, responsive user interfaces.
-   **State Updates**: Use of both polling and server-side events to update state

### **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.
    -   Automatically sets waypoints in the EVE Online client, simplifying navigation for players.

2.  **Profit Optimization**
    -   Identifies arbitrage opportunities by analyzing buy/sell orders across regions.
    -   Uses efficient filtering algorithms to recommend profitable trades.

3.  **Real-Time API Integration**
    -   Fetches live trade orders, player locations, 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 the following constraints:

1.  **Ship & Financial Limits**
    -   **Cargo Capacity**: Hard limit of 600m³. Orders that don't fit are ignored.
    -   **Maximum Route Capital**: Caps the up-front item purchase cost at 100,000,000 ISK when compounding multiple items in a route.
    -   **Profit Threshold**: A single trade must yield a minimum gross profit of 100,000 ISK to be considered.

2.  **Time & Navigational Costs**
    -   **Ship Speed**: Calculations factor in `max_warp_speed = 8.22 AU/s` and `max_subwarp_speed = 216.5 m/s`.
    -   **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 time value of ~4,166 ISK per second (`15_000_000 / 3600`) to punish overly long routes.

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 a theoretical 60m ISK penalty + the 50m ship value + the cargo value.

4.  **Trade Execution & Filtering Strategy**
    -   **Market Tax**: Accounts for an 8% transaction tax on all trades automatically.
    -   **Arbitrage Capital Limits**: Rejects individual items exceeding 20,000,000 ISK up-front capital during initial data processing but allows up to 100,000,000 ISK when compounding multiple items continuously.
    -   **Same-Region Filtering**: Ensures that pickup and dropoff stations for a single item are within the same region.
    -   **Evaluation Limit**: Limits pathfinding to the top 20,000 trades to conserve CPU overhead.
    -   **Snipe Feature Execution**: Background polling monitors loop regions actively for single trades that boast >20,000,000 ISK 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
    ```