# EVE Haul Agent Guide

## Start Here

- See [readme.md](readme.md) for product context and the Python/React/Rust split.
- Treat the Python backend as the active application backend. The React frontend is hardcoded to `http://localhost:8000`.
- Treat `rust_backend/` as an experimental rewrite. It runs separately on `127.0.0.1:8080` and is not a drop-in replacement for the Python backend.

## Run and Validate

- Frontend: `cd frontend && npm install && npm start`
- Frontend tests: `cd frontend && npm test -- --watchAll=false`
- Frontend build: `cd frontend && npm run build`
- Python backend: `cd backend/src && python -m uvicorn main:app --reload --port 8000`
- Rust backend: `cd rust_backend && cargo run`
- Rust tests: `cd rust_backend && cargo test`
- The Python backend has no checked-in dependency manifest. Before running it, confirm the local environment already has the required packages plus the EVE auth/cache files and CSV map data under `backend/data/`.

## Architecture

- `backend/src/main.py` is a thin FastAPI shell. `backend/src/manager.py` owns mutable state, polling, and route generation.
- `backend/src/esi/` owns ESI auth, character location, waypoint updates, and other live API side effects.
- `backend/src/graph.py`, `loader.py`, `market.py`, `arbitrage.py`, `pathfinder.py`, and `route.py` form the route-planning and market-analysis pipeline.
- `frontend/src/` uses small function components. `usePolling.js` and `useSSE.js` own long-lived network subscriptions; display components render the returned payloads.
- `rust_backend/src/main.rs` is a thin Actix entrypoint. `manager.rs` owns shared state and polling, `eve_service.rs` wraps `eve_api.rs`, and `pathfinding/` plus `market/` stay modular.

## Repo-Specific Conventions

- Preserve the current port split unless the task is explicitly a migration: frontend `:3000`, Python backend `:8000`, Rust backend `:8080`.
- Keep external API calls and UI side effects out of the route-planning and market-analysis modules.
- Prefer typed models, named thresholds/constants, and small transformations over ad hoc inline logic in backend algorithms.
- When changing the Rust backend, do not assume Python endpoint parity. Add routes, SSE or polling support, and CORS explicitly before wiring the frontend to it.
- Be cautious about local-only runtime dependencies: Python expects ESI auth/cache state plus CSV map data under `backend/data/`; Rust expects OAuth env vars and `token.json`.