diff options
| -rw-r--r-- | .github/instructions/frontend.instructions.md | 14 | ||||
| -rw-r--r-- | .github/instructions/python-backend.instructions.md | 13 | ||||
| -rw-r--r-- | .github/instructions/rust-backend.instructions.md | 12 | ||||
| -rw-r--r-- | AGENTS.md | 33 |
4 files changed, 72 insertions, 0 deletions
diff --git a/.github/instructions/frontend.instructions.md b/.github/instructions/frontend.instructions.md new file mode 100644 index 0000000..7ce27c0 --- /dev/null +++ b/.github/instructions/frontend.instructions.md @@ -0,0 +1,14 @@ +--- +description: "Use when editing the React frontend, polling hooks, SSE hooks, or display components under frontend/src. Covers data flow, backend assumptions, and styling boundaries." +name: "Frontend Data Flow" +applyTo: + - "frontend/src/**/*.js" + - "frontend/src/**/*.css" +--- +# Frontend Data Flow + +- Keep data fetching in hooks or small container components. `Path.js`, `Info.js`, `Log.js`, and `Options.js` wire backend data into display components; `usePolling.js` and `useSSE.js` own subscription cleanup. +- Preserve the current backend contract unless the task explicitly coordinates with backend changes. The frontend is hardcoded to `http://localhost:8000`, not the Rust backend on `:8080`. +- Keep display components render-focused. Formatting, icons, animation, and simple click handlers belong near `DataDisplay.js`, `InfoDisplay.js`, and `LogComponent.js`; reusable network behavior belongs in hooks. +- Stick to the current stack: React function components, Tailwind utility classes, and local CSS files. Do not introduce a new state library, routing layer, or styling system unless asked. +- If you add polling or SSE behavior, always include cleanup and keep the return shape simple for the consuming component.
\ No newline at end of file diff --git a/.github/instructions/python-backend.instructions.md b/.github/instructions/python-backend.instructions.md new file mode 100644 index 0000000..6bb9158 --- /dev/null +++ b/.github/instructions/python-backend.instructions.md @@ -0,0 +1,13 @@ +--- +description: "Use when editing the Python backend, FastAPI endpoints, ESI integration, or route-planning modules under backend/src. Covers service boundaries, side effects, and runtime assumptions." +name: "Python Backend Boundaries" +applyTo: "backend/src/**/*.py" +--- +# Python Backend Boundaries + +- Keep `backend/src/main.py` thin. Add request/response wiring there, but keep orchestration in `backend/src/manager.py`. +- Keep live ESI calls, token refresh, waypoint updates, and market-window side effects inside `backend/src/esi/`. Do not introduce direct ESI `requests` calls in `graph.py`, `market.py`, `arbitrage.py`, `pathfinder.py`, or `route.py`. +- Treat `Manager` as the mutable state boundary. If you add background work, keep thread and polling ownership explicit instead of spreading shared state across modules. +- Preserve the current data-oriented style in the route-planning pipeline: dataclasses, module-level constants, and functions that transform orders, trades, and graph data. +- The active frontend depends on `/route`, `/route_info`, `/create_route`, `/data_stream`, and `/open_market_window/{type_id}` on `http://localhost:8000`. Keep those contracts stable unless the task includes coordinated frontend changes. +- ESI-backed code needs local auth and data files that are not checked in. Avoid assuming clean-room execution unless the task is specifically about environment setup.
\ No newline at end of file diff --git a/.github/instructions/rust-backend.instructions.md b/.github/instructions/rust-backend.instructions.md new file mode 100644 index 0000000..719544a --- /dev/null +++ b/.github/instructions/rust-backend.instructions.md @@ -0,0 +1,12 @@ +--- +description: "Use when editing the Rust backend, Actix handlers, EVE service client, or pathfinding and market modules under rust_backend/src. Covers experimental status, service boundaries, and integration gaps." +name: "Rust Backend Boundaries" +applyTo: "rust_backend/src/**/*.rs" +--- +# Rust Backend Boundaries + +- Treat `rust_backend/` as an experimental rewrite, not a drop-in replacement for the Python backend. The current frontend does not target it. +- Keep `main.rs` as a thin Actix entrypoint. Shared state and polling belong in `manager.rs`; ESI and OAuth transport belongs in `eve_service.rs` and `eve_api.rs`. +- Keep `pathfinding/` and `market/` self-contained. Avoid pulling HTTP concerns, UI assumptions, or Actix types into those modules. +- Do not assume feature parity with the Python backend. If a task requires frontend integration, add the missing routes, payload shapes, and CORS deliberately rather than silently reusing Python assumptions. +- Rust runtime work depends on local OAuth env vars (`CLIENT_ID`, `CLIENT_SECRET`, `CHARACTER_ID`, `REDIRECT_URL`) and `token.json`. Preserve that flow unless the task is specifically about changing auth setup.
\ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e01bd4e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,33 @@ +# 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`.
\ No newline at end of file |