# EVE Haul Agent Guide

## Start Here

- See [readme.md](readme.md) for product context and the Python/React split.
- Treat the Python backend as the active application backend. The React frontend is hardcoded to `http://localhost:8000`.

## 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`
- 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.

## Repo-Specific Conventions

- Preserve the current port split: frontend `:3000`, Python backend `:8000`.
- 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.
- Be cautious about local-only runtime dependencies: Python expects ESI auth/cache state plus CSV map data under `backend/data/`.