Travelling Salesperson Playground

A minimal Flask + OR-Tools demo that lets students and researchers sketch a Travelling Salesperson Problem, solve it, and visualise the optimal tour.

A full log of the interaction that led to this code is included in HOWTO.md. This contains the original prompt, clarifying questions, and the iteration history.

Prerequisites

• Python 3.10+ (with pip)
• A modern browser (Chrome, Edge, Firefox, Safari)
• A code editor to review the code.

Install Codex CLI

Follow these steps to get the Codex CLI running locally:

https://developers.openai.com/codex/cli/

Please note that Codex CLI runs natively for macOS and Linux. For Windows, you need to use WSL (Windows Subsystem for Linux) - instructions are provided in the above page.

Project Setup

Clone or download the repository, then from the project root run:

pip install -r requirements.txt

Run the Demo

./run.sh

The script exports the right Flask environment variables and starts the dev server at http://127.0.0.1:5000. Leave the terminal open while you experiment.

Walkthrough

1. Add nodes – Single-click anywhere on the canvas to drop a node. Grid snapping keeps positions tidy while the toggle is enabled.
2. Tweak nodes – Drag to reposition, double-click to remove, or press Add Random Nodes for a sandbox scenario.
3. Solve the tour – Hit Solve Tour. The status flips to “Running…”, the solution timer counts up in real time, and the optimal tour is rendered with an animated truck.
4. Inspect results – Check the panel for status, total distance, solution time, and visit order.
5. Reset – Use Clear Nodes whenever you want to start fresh.

Architecture at a Glance

• app.py exposes the Flask application factory plus the /solve JSON endpoint.
• solver.py uses the OR-Tools routing solver to generate Euclidean tours, returning total distance and visit order.
• templates/index.html, static/js/app.js, and static/css/styles.css implement the single-page canvas editor and animation.
• run.sh is a convenience launcher that keeps the dev loop snappy.

Extend the Tutorial

• Persist scenarios to disk so teams can share netork instances.
• Import/export coordinates (CSV/JSON), or let users tweak the distance metric.
• Layer on richer constraints (time windows, depot selection, multiple vehicles).

Have fun experimenting!