🗺️ ClearHowGuide Route Algorithm Explorer

Interactive browser-based route-search visualizer for Breadth-First Search, Dijkstra, A* and bidirectional Dijkstra.

It uses synthetic road networks to make search behavior visible. It is an educational simulator and does not reproduce Google Maps' proprietary routing system.

🚀 Live tool

Official live version

https://clearhowguide.com/en/tools/route-algorithm-explorer/

Full guide

https://clearhowguide.com/en/science/how-google-maps-finds-fastest-route/

🧭 What it does

Use the same graph, start point, destination and edge costs, then compare how different algorithms search.

You can:

choose start and destination nodes;
switch between City Grid, Highway Network, River & Bridges and BFS Trap;
run Breadth-First Search, Dijkstra, A* or bidirectional search;
animate the search frontier;
pause, resume, step and reset;
inspect nodes explored, maximum frontier, path edges, path cost and coverage;
race all four algorithms on the same graph;
add traffic by changing edge weights;
block roads;
randomize and reset traffic;
inspect algorithm internals in Advanced mode;
share reproducible experiments through URL parameters;
generate embeddable experiments;
export results as SVG or PNG;
compare many routes with the Benchmark Lab.

✨ Educational presets

The BFS Trap — fewest edges does not necessarily mean lowest weighted cost.
Dijkstra's Expanding Wave — watch uninformed weighted search spread.
A Gets a Compass* — see how an admissible heuristic can focus the search.
Meet in the Middle — compare two weighted frontiers searching from both ends.
Traffic Changes the Winner — change edge costs and watch the preferred path move.

📊 Metrics

The explorer emphasizes search work, not device-dependent browser timing:

Nodes explored
Maximum frontier
Path edges
Path cost
Search coverage
Local computation time (diagnostic only)

Nodes explored means nodes removed from the frontier and expanded by the algorithm.

🧠 Algorithms

Breadth-First Search

Minimizes the number of edges. On weighted road networks this can differ from the minimum-cost path.

Dijkstra

Expands the unsettled node with the lowest accumulated non-negative path cost.

A*

Uses:

f(n) = g(n) + h(n)

The explorer uses an admissible straight-line lower-bound heuristic.

Bidirectional search

The interface calls this Bidirectional Search. Internally, weighted graphs use bidirectional Dijkstra.

See ALGORITHMS.md for methodology details.

🏁 Benchmark Lab

The standalone explorer can run reproducible route samples and compare Dijkstra, A* and bidirectional Dijkstra.

Results describe this synthetic network and this implementation. They are not universal performance benchmarks and are not Google Maps benchmarks.

See BENCHMARKING.md.

🔗 Reproducible sharing

Experiment state can be encoded in the URL, including:

map preset;
seed;
start;
destination;
algorithm;
UI mode;
traffic overrides;
blocked roads.

This makes a specific experiment shareable and reproducible.

🌐 Embed on your website

The official hosted embed is designed for articles, lessons, blogs and course material.

See EMBEDDING.md.

🔐 Privacy

The explorer runs route-search calculations locally in the browser.

The project does not require an account, database, Google Maps API, geocoding service or routing backend.

See PRIVACY.md.

♿ Accessibility

The UI is designed to avoid communicating state through color alone and supports reduced-motion preferences.

See ACCESSIBILITY.md.

🏗️ Architecture

algorithms/
    ↓
graph + priority queue + runner
    ↓
render / share / export / benchmark
    ↓
app.ts
    ↓
RouteAlgorithmExplorer.astro
    ↓
standalone / embed / ClearHowGuide article

🧪 Run locally

Requirements:

Node.js 22+
npm

Install:

npm install

Development:

npm run dev

Open:

http://localhost:4321/en/tools/route-algorithm-explorer/

✅ Run checks

Algorithm tests:

npm test

Expected result:

Route Explorer algorithm tests passed: 121 cases.

Production build:

npm run build

📁 Repository structure

route-algorithm-explorer/
├── .github/
├── examples/
├── scripts/
│   └── test-route-explorer.mjs
├── src/
│   ├── components/
│   │   └── RouteAlgorithmExplorer.astro
│   ├── lib/
│   │   └── route-explorer/
│   │       ├── algorithms/
│   │       ├── app.ts
│   │       ├── benchmark.ts
│   │       ├── export.ts
│   │       ├── graph.ts
│   │       ├── presets.ts
│   │       ├── priorityQueue.ts
│   │       ├── render.ts
│   │       ├── runner.ts
│   │       ├── share.ts
│   │       └── types.ts
│   └── pages/
├── ACCESSIBILITY.md
├── ALGORITHMS.md
├── BENCHMARKING.md
├── CHANGELOG.md
├── CITATION.cff
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── EMBEDDING.md
├── LICENSE
├── PRIVACY.md
├── SECURITY.md
├── SUPPORT.md
└── THIRD_PARTY_LICENSES.md

⚠️ Important limitations

Synthetic graphs are educational abstractions, not real road maps.
The tool does not reconstruct or claim to know Google Maps' proprietary routing implementation.
Browser timing varies by device, browser and current workload.
BFS minimizes edge count, not weighted travel cost.
Benchmark results are implementation- and graph-specific.
Traffic values are synthetic unless explicitly set by the user.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

🛡️ Security

Please report security issues responsibly. See SECURITY.md.

💬 Support

See SUPPORT.md.

📚 Citation

Citation metadata is available in CITATION.cff.

📄 License

ClearHowGuide Route Algorithm Explorer is released under the MIT License.

See LICENSE.

🔗 Used by

ClearHowGuide: