F FleetPilot

Developer documentation

Build, run, and extend FleetPilot.

FleetPilot combines a visual dispatch workspace with a TypeScript optimization engine. Run the complete product locally or in a container, integrate through the REST API, or use the solver package directly from Node.js.

Open consoleLocal SQLiteWebSocket progressISC licensed

01 / Get started

Start the complete product locally

Clone the source, install the workspace dependencies, and launch the custom development server. The first run opens a short terminal setup for the port, solver limits, and local data directory.

git clone https://github.com/sachncs/fleetpilot.git
cd fleetpilot
npm ci
npm run dev:frontend

# Open http://localhost:3000
No login required.

The browser console opens directly. API keys are only for external clients calling protected REST endpoints.

What the first run creates

  • data/fleetpilot.json — local server and solver settings.
  • data/fleetpilot.db — SQLite registry, scenarios, jobs, solutions, and audit history.
  • A default API key printed once in the terminal for external integrations.

02 / Docker

Run the production container

The image includes the web console, APIs, background solver worker, MapLibre assets, and native SQLite runtime. Persist /app/data outside the container.

docker build -t fleetpilot .

docker run --rm \
  --name fleetpilot \
  -p 3000:3000 \
  -v fleetpilot-data:/app/data \
  fleetpilot

# Open http://localhost:3000

For repository development, docker compose up --build mounts the local ./data directory for persistence.

03 / Product workflow

From registry to dispatch

  1. 1
    Register resources

    Add dispatch depots and active vehicles with capacity, region, cost, and emissions data.

  2. 2
    Add demand

    Create or import delivery stops with quantity, service time, priority, time window, and coordinates.

  3. 3
    Create a plan

    Select orders, a depot, and available vehicles. FleetPilot snapshots them into an immutable optimization scenario.

  4. 4
    Optimize and review

    Choose a search preset, follow live progress, inspect route geometry and KPIs, then replay the route.

  5. 5
    Export

    Download GeoJSON, KML, or CSV for downstream GIS, navigation, and spreadsheet workflows.

04 / Architecture

One product, clear runtime boundaries

01Next.js console

Product UI, REST routes, and server-rendered product surfaces.

02SQLite registry

Fleet, orders, scenarios, jobs, solutions, keys, and audit events.

03Solver worker

Runs ALNS and BRKGA outside the request path with cancellation support.

04Progress stream

WebSocket events plus persisted job-state recovery for fast completions.

The core solver is independently packaged as fleetpilot. The product server converts registry data into the solver problem schema, queues work, persists results, and exposes those results to review and export surfaces.

05 / Configuration

Runtime configuration

VariablePurposeContainer default
PORTHTTP and WebSocket port3000
DATABASE_URLSQLite database URLfile:/app/data/fleetpilot.db
FLEETPILOT_DATA_DIRConfig and persistent data directory/app/data
MAX_CONCURRENT_SOLVESConcurrent background solve limitSaved config
FLEETPILOT_WORKER_PATHBundled worker entrypoint override/app/worker.mjs

Solver time and generation limits are created by the first-run setup and stored in fleetpilot.json. The console reads those limits before submitting work.

06 / REST API

Integrate external systems

External requests use a bearer API key. The product console uses its local public-console marker; integrations should create and retain a dedicated key from Settings.

curl http://localhost:3000/api/system \
  -H "Authorization: Bearer $FLEETPILOT_API_KEY"
GET /api/depotsList dispatch locations
GET /api/fleetList vehicles and availability
GET /api/ordersRead delivery demand
POST /api/scenarios/from-registryCreate an optimization scenario
POST /api/jobsQueue a solver run
GET /api/jobs/:idRead persisted job status
GET /api/solutions/:idRead an optimized plan
GET /api/solutions/:id/exportExport geojson, kml, or csv

07 / Development

Contribute with confidence

# Full solver and package verification
npm run verify

# Web console checks
npm run lint -w @fleetpilot/web
npm run typecheck -w @fleetpilot/web
npm run build -w @fleetpilot/web

# Production image smoke test
npm run docker:smoke

The repository uses TypeScript, Rollup, Mocha, c8 coverage gates, ESLint, Prettier, Next.js, and a multi-stage Docker build. Keep changes focused and preserve deterministic seeds in solver tests.

08 / Production

Production checklist

  • Persist and back up /app/data.
  • Terminate TLS at the platform or reverse proxy and preserve WebSocket upgrades.
  • Keep the product behind the network boundary appropriate for your fleet data.
  • Create separate API keys for each external integration and rotate them independently.
  • Set solver concurrency and time limits for the available CPU and memory.
  • Monitor container health, disk growth, failed jobs, and optimization duration.
  • Run the shipped CI verification and container smoke test before promotion.

Ready to build?

Start with a local route.

Return to quickstart ↑Browse the source ↗