A comprehensive Rust workspace for working with EVE Frontier static datasets, providing pathfinding and navigation tools for the game world.

This repository contains multiple crates organized as a Cargo workspace:

• evefrontier-lib — Reusable library providing:
  • Dataset downloading and caching
  • Starmap loading with schema detection
  • Graph construction for gate, spatial, and hybrid routing
  • Pathfinding algorithms (BFS, Dijkstra, A*)
  • KD-tree spatial indexing for efficient neighbor queries
  • Temperature-aware routing constraints

• evefrontier-cli — Command-line interface exposing:
  • download — Download and cache dataset releases
  • route — Compute routes between systems with advanced options
  • index-build — Precompute spatial index for faster queries
  • scout gates — List star systems connected via jump gates
  • scout range — Find nearby systems within spatial range

• Lambda function crates:
  • evefrontier-lambda-route — Route planning endpoint
  • evefrontier-lambda-scout-gates — Gate-connected neighbors query
  • evefrontier-lambda-scout-range — Systems within jump range query
• Shared/infrastructure crate:
  • evefrontier-lambda-shared — Common Lambda infrastructure (runtime, error handling, tracing)

• Service crates (Docker/Kubernetes deployment):
  • evefrontier-service-route — HTTP route planning service
  • evefrontier-service-scout-gates — HTTP gate neighbors service
  • evefrontier-service-scout-range — HTTP range query service
• Shared/infrastructure crate:
  • evefrontier-service-shared — Common HTTP infrastructure (axum handlers, health checks, request/response types)

• docs/ARCHITECTURE.md — System architecture diagrams and data flows
• docs/INITIAL_SETUP.md — Configuration and data path resolution
• docs/USAGE.md — Comprehensive usage examples
• docs/adrs/ — Architectural Decision Records

1. Ensure the Rust toolchain pinned in .rust-toolchain is installed:

rustup toolchain install $(cat .rust-toolchain)
rustup override set $(cat .rust-toolchain)

2. Build the workspace:

cargo build --workspace
# Or use Nx for orchestrated builds with caching:
pnpm nx run-many --target=build --all

3. Run tests:

cargo test --workspace
# Or with Nx task orchestration:
pnpm nx run-many --target=test --all

4. Run the CLI (it will download the dataset automatically on first use):

# Download the dataset
cargo run -p evefrontier-cli -- download

# Compute a route
cargo run -p evefrontier-cli -- route --from "ER1-MM7" --to "ENQ-PB6"

# Or install globally
cargo install --path crates/evefrontier-cli
evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6"

The CLI automatically downloads the latest dataset on first use. Use --data-dir to specify a custom location, or set EVEFRONTIER_DATA_DIR. See docs/INITIAL_SETUP.md for data path resolution details.

This project uses Nx for task orchestration with intelligent caching and dependency management.

Requires Node 24 (per .nvmrc) and pnpm 10+:

nvm use  # Switches to Node 24
npm i -g pnpm@10
pnpm install

Nx automatically runs builds before tests, caches task outputs, and runs tasks in the correct order:

# Run tests (automatically builds first)
pnpm nx run evefrontier-lib:test

# Run tests for all projects
pnpm nx run-many --target=test --all

# Run only affected projects' tests
pnpm nx affected --target=test

# Run clippy across all crates
pnpm nx run-many --target=clippy --all

Use package.json scripts for consistency:

pnpm run build    # Build all crates
pnpm run test     # Test all crates
pnpm run clippy   # Lint all crates
pnpm run lint:md  # Lint markdown files

If Nx daemon issues occur:

NX_DAEMON=false pnpm nx run-many --target=test --all
pnpm nx reset

See CONTRIBUTING.md for complete Nx documentation and task orchestration details.

The CLI supports multiple output formats for the route subcommand via the --format flag:

• JSON for machine-readable output and integrations:

evefrontier-cli --format json route --from "ER1-MM7" --to "ENQ-PB6"

• Basic for minimal path-only output with +/|/- prefixes:

evefrontier-cli --format basic route --from "ER1-MM7" --to "ENQ-PB6"

• Note for in-game EVE notes with clickable system links:

evefrontier-cli --format note route --from "ER1-MM7" --to "ENQ-PB6"

• Text (default) for human-readable output, or Rich for Markdown-style formatting

The route subcommand supports advanced pathfinding options:

• Algorithm selection (--algorithm <bfs|dijkstra|a-star>):

evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --algorithm dijkstra

• Maximum jump distance (--max-jump <LIGHT-YEARS>):

evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --max-jump 80.0

• System avoidance (--avoid <SYSTEM>, repeatable):

evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --avoid "IFM-228"

• Gate-free routing (--avoid-gates):

evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --avoid-gates

• Temperature limit for spatial jumps (--max-temp <KELVIN>):

evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --max-temp 5000.0

• Avoid critical engine heat (--avoid-critical-state):

# Avoid spatial hops that would instantly reach CRITICAL temperature; requires --ship
evefrontier-cli route --from "ER1-MM7" --to "ENQ-PB6" --avoid-critical-state --ship "Reflex"

This flag is conservative: it omits spatial jumps whose instantaneous temperature (ambient + hop temperature delta) would reach or exceed the canonical HEAT_CRITICAL threshold. It is enabled by default when a ship is available; use --no-avoid-critical-state to opt out. Explicitly passing --avoid-critical-state without --ship will result in an error.

See docs/USAGE.md for comprehensive documentation and additional examples.

Precompute a KD-tree spatial index for faster neighbor queries:

evefrontier-cli index-build
# Creates {database_path}.spatial.bin

The index enables efficient nearest-neighbor and radius queries with temperature filtering.

Discover systems near your location using the scout subcommands:

# List systems connected via jump gates
evefrontier-cli scout gates "Nod"

# Find nearby systems within spatial range
evefrontier-cli scout range "Nod" --limit 10

# Filter by radius and temperature
evefrontier-cli scout range "Nod" --radius 50.0 --max-temp 300

# JSON output for programmatic use
evefrontier-cli scout gates "Nod" --format json

• ensure_dataset — resolves the dataset path using CLI arguments, environment variables, or platform-specific defaults, downloads the requested dataset release (latest by default), and caches it under the OS cache directory. Returns both database and spatial index paths.
• load_starmap — loads systems and jumps from the SQLite database with basic schema detection.
• plan_route — converts system names into IDs, validates routing options, and plans a route using BFS, Dijkstra, or A* while applying distance, avoidance, gate, and temperature constraints. Lower-level helpers such as build_graph/find_route_bfs remain available when needed.
• build_spatial_index / load_spatial_index — create and load KD-tree spatial indexes for efficient neighbor queries with temperature awareness.

Example:

use evefrontier_lib::{ensure_dataset, load_starmap, plan_route, RouteRequest, RouteConstraints, RouteAlgorithm, DatasetRelease};
use rusqlite::Connection;

let paths = ensure_dataset(None, DatasetRelease::latest())?;
let conn = Connection::open(&paths.database)?;
let starmap = load_starmap(&conn)?;

let request = RouteRequest {
    start: "ER1-MM7".to_string(),
    goal: "ENQ-PB6".to_string(),
    algorithm: RouteAlgorithm::AStar,
    constraints: RouteConstraints {
        max_jump: Some(80.0),
        ..Default::default()
    },
};

let plan = plan_route(&starmap, &request)?;
println!("Route: {} jumps", plan.jumps.len());

See docs/TODO.md for the comprehensive backlog covering the downloader, advanced pathfinding options, deployment infrastructure, and additional tooling.

The workspace includes AWS Lambda functions for serverless deployment:

• Route planning (evefrontier-lambda-route) — POST endpoint accepting start/end systems
• Gate neighbors (evefrontier-lambda-scout-gates) — GET gate-connected systems
• Range neighbors (evefrontier-lambda-scout-range) — GET systems within jump range

All Lambda functions use the same evefrontier-lib core and include bundled datasets for fast cold starts.

See docs/DEPLOYMENT.md for Terraform deployment instructions.

The workspace also includes containerized microservices for Docker Compose and Kubernetes:

# Start all services with Traefik reverse proxy
docker compose up -d

# Test the services
curl http://localhost/api/v1/route -X POST \
  -H "Content-Type: application/json" \
  -d '{"origin": "Nod", "destination": "Brana"}'

# Install from local chart
helm install evefrontier ./charts/evefrontier

# With custom values
helm install evefrontier ./charts/evefrontier -f values.yaml

The microservices use:

• Base image: gcr.io/distroless/cc-debian12 (~20MB runtime)
• Security: Non-root user, read-only filesystem, dropped capabilities
• Ingress: Traefik IngressRoute with optional rate limiting and CORS

See docs/DEPLOYMENT.md for comprehensive Docker/Kubernetes documentation.

Please review CONTRIBUTING.md and the ADRs before submitting changes. All code changes must add an entry to CHANGELOG.md.