README.md

metadata

title: RouteForge | Fleet Optimization Studio
emoji: 🚚
colorFrom: green
colorTo: blue
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Offline fleet routing and delivery optimization
tags:
  - operations-research
  - optimization
  - logistics
  - vehicle-routing
  - decision-support
  - simulation
  - javascript

RouteForge | Fleet Optimization Studio

A self-contained, interactive laboratory for exact capacitated vehicle routing, fleet planning, operational sensitivity analysis and auditable decision-making.

Project 46 · RouteForge v1.0 · Offline-ready Static Space · MIT license

What makes this a real application

• Exact optimizer: Held–Karp dynamic programming solves the shortest tour of each subset, followed by a second exact dynamic program that partitions stops into feasible vehicle routes. For the stated mathematical model and up to nine stops, the chosen solution globally minimizes the modeled dispatch + distance + driver-time cost.
• Real constraints: every service location must be visited exactly once; routes start and end at a depot; vehicle load, maximum route duration, and fleet size cannot be exceeded. If no complete solution exists, the app reports infeasibility rather than dropping deliveries.
• Transparent benchmark: compares its cost against a nearest-neighbor feasible-insertion heuristic on the same input.
• What-if analysis: recomputes the plan under four levels of traffic, exposing when added congestion makes a full-coverage solution impossible.
• Interactive route network: SVG nodes, route selection, route times, cargo loads, essential/standard location categories, and a constraint audit.
• Data import and exports: validates user-supplied CSV, rejects malformed inputs without overwriting current work, and downloads JSON, CSV and Markdown reports.
• Local by design: HTML, CSS and JavaScript run in the browser. There are no dependencies, APIs, trackers, build steps or server-side operations.

Getting started

Visit the App tab. Use Fleet optimizer to adjust available vehicles, capacity, maximum minutes, traffic and cost rates. All scenarios contain synthetic data. To use your own CSV, go to Data & methodology → Import delivery stops.

CSV format

id,name,x,y,demand,service,priority
X01,Example Clinic,30,20,7,15,Essential
X02,Regional Hub,60,70,9,12,Standard

Required fields in this order: id,name,x,y,demand,service,priority.

• Provide between 2 and 9 locations with unique non-empty IDs.
• x, y: illustrative coordinates in the 0–100 range, not latitude/longitude.
• demand: integer 1–40 cargo units; service: minutes 0–60.
• priority: Essential or Standard, used for coverage reporting, not for different service rights.
• The depot remains set by the currently selected scenario; imported stops use that depot.
• Files are limited to 2 MB and processed only in the browser. CSV quoting of commas and embedded newlines is supported.

Mathematical formulation

For each route (r), minimize:

[ C_r = C_{dispatch} + d_r,C_{km} + \frac{t_r}{60},C_{hour} ]

where (d_r) is total round-trip distance and (t_r) includes travel and service time. Travel time is computed as (d_r / v\times 60\times\text{traffic factor}). Travel distances are synthetic Euclidean distances scaled by a configurable kilometers-per-coordinate-unit factor. Every route must respect cargo capacity and maximum duration. The total number of routes cannot exceed the available fleet.

Solver: (1) Held–Karp identifies the shortest round trip for every nonempty subset of stops. (2) An exact subset partitioning algorithm chooses feasible tours with minimum total modeled cost and fleet use within the specified bound. Deterministic tie-breaking aids repeatability. This is a deliberately bounded exact solver for small research examples, not an industrial-scale solver.

Demo datasets

1. Field service visits (default): eight synthetic technician visits. Under the defaults, the exact optimizer costs approximately $502 versus $542 for the greedy comparison, or 7.4% lower modeled cost. Results will change if parameters change.
2. Metro distribution: compact synthetic last-mile network.
3. Highland supply routes: spatially dispersed synthetic distribution points.

These are illustrative, not operationally observed datasets or verified addresses.

Auditability and tests

The full development archive contains the analytics core, a self-contained HTML build, Node.js unit tests and Chromium browser tests, including five independent exhaustive enumerations on smaller networks. The publishable ZIP contains only README.md, index.html, and LICENSE.

To run locally, open index.html in a modern browser. Running entirely inside Hugging Face Static Spaces requires no Python, Docker, GPU or paid compute.

Important limitations

RouteForge is a research/teaching demonstration, not a navigation or dispatch system. It does not use real road distances, accurate terrain, traffic feeds, road closures, vehicle time windows, work breaks, delivery restrictions or jurisdiction-specific rules. No savings or operational outcome is guaranteed. The optimization is globally exact for its simplified mathematical formulation, not for real-world vehicle routing.

The Essential category is a descriptive auditing label, not a proof of equitable access. Uploaded information is not saved between page reloads: export your findings when finished. Public Spaces expose code and demo files to everyone: do not upload private datasets into the repository.

License

MIT. See LICENSE.