How can a transportation management TMS system use Mapbox to implement AI route planning visualization: multi-plan comparison and drag adjustment

Introduction

In a TMS system, route planning is the most typical "AI is strong, but humans are stronger" scenario. The backend can compute a theoretically optimal solution based on the VRP (Vehicle Routing Problem) model, traffic data, and restricted-zone rules, but real-world transportation always has variables the algorithm cannot cover: last-minute reassignments, changes to customer time windows, and drivers' experience-based judgment of local road conditions.

So a good route planning visualization is not about throwing a blue line at the user to look at; it needs to achieve three things: multiple plans can be compared side by side, humans can modify them, and after modification the impact can be calculated immediately.

This article focuses on the visualization layer of AI route planning—from obtaining multiple plans via the Mapbox Directions API and rendering them with differentiation, to the complete closed loop of dragging waypoints to trigger local recalculation—and provides an implementation approach that can be directly put into practice.

A transportation route in a TMS must simultaneously weigh at least: shortest distance, least time, lowest tolls, whether to avoid restricted zones, and whether customer time windows are satisfied. AI models (such as optimization services based on OSRM/OR-Tools) often produce not one but multiple Pareto-optimal plans—some fastest, some most economical, some a compromise. The frontend's task is to translate this "multi-objective trade-off" into a visual expression that dispatchers can understand, compare clearly, and modify.

Figure 1: The route planning interaction loop. The core design is a reversible loop of "AI produces plans → humans make decisions → humans modify and then recalculate."

II. Multi-Plan Comparison: From API to Differentiated Rendering

alternatives=true is the key to enabling multi-plan comparison, and differentiated styling is the key to turning "plan differences" into "visual differences."

2.1 Obtaining Multiple Routes

Line-by-line analysis:

① Mapbox coordinates are fixed as longitude,latitude (consistent with GeoJSON), which is the opposite of the common mathematical convention of "latitude first"—a high-frequency pitfall.

② alternatives=true requires the API to return alternative plans that are "significantly different from the fastest route but close in time," with at most 2 alternatives.

③ The returned routes array is sorted in descending order of recommendation, with routes[0] being the overall optimum—this is the basis for ranking visualization.

2.2 Differentiated Rendering: Making Plan Differences Visible at a Glance

Line-by-line analysis:

④ Each plan has its own independent Source, so changing one plan does not affect the others—this is the prerequisite for local recalculation on drag.

⑥ fitBounds automatically frames the view, preventing the route from being drawn off-screen.

⑦ The cleanup function prevents layer name conflict errors when the component is mounted repeatedly.

2.3 Plan Cards: Turning Numbers into Decision Basis

The sidebar uses three columns of cards side by side; clicking one triggers setData to highlight the corresponding plan—the map and the panel are linked through the same routes array, which is the foundation of a smooth "comparison" experience.

III. Drag Adjustment: Making Manual Intervention Take Effect Immediately

The essence of dragging is "coordinates changed → local recalculation → incremental rendering," and the difficulty lies in debouncing and state consistency.

3.1 Draggable Waypoints

Line-by-line analysis:

① Listen to dragend rather than drag: during dragging, dozens of coordinate changes may occur per second, and real-time requests would blow through the API quota; recalculating only on release matches the semantics of "human decision-making."

② Pass the new coordinates back to the upper-level state via a callback, triggering fetchRoutePlans to run again and forming a closed loop.

③ When adding or removing waypoints, detach the old markers first to avoid leftover markers.

3.2 Debounced Recalculation: Avoiding Consecutive Requests

Analysis: ④⑤ are a typical "debounce" pattern. When the user drags multiple waypoints in succession, a request is sent only after the last release followed by a pause of more than 500ms, ensuring both timely response and avoiding invalid calls.

3.3 Key Code Flowchart

Figure 2: The key code flow for drag recalculation. State changes drive API recalculation after debouncing, and the results ultimately flow back to the map layer.

IV. Visual Expression of Post-Modification Impact

After modifying a route, what people most want to know is "what is the cost of this change?"

4.1 Incremental Metric Comparison

4.2 Conflict and Constraint Alerts

If, after AI recalculation, the new route triggers restricted zones, time window conflicts, or vehicle load constraints, the frontend should indicate this with a yellow warning bar + dashed circles on the map, rather than silently overwriting. The recommended approach is to include a warnings field in the returned routes object, and have the frontend render by type.

V. Summary of Visualization Auxiliary Diagrams

5.1 Visual Encoding Rules for Plan Comparison

Figure 3: Visual encoding rules. Recommendation level is dual-encoded with line width + color saturation to lower the reading barrier.

5.2 Component Structure and Data Flow

Figure 4: Component and state data flow. A single data source (waypoints/routes) drives bidirectional linkage between the map and the cards.

removeLayer/removeSource in the cleanup function

Limit to ≤12 waypoints; for larger volumes, use the Optimization API

The Mapbox Directions API supports at most 25 coordinate points per request; when using the driving-traffic profile, at most 3 waypoints; for larger scales, switch to the Mapbox Optimization API or a self-hosted OSRM service.

6.2 Optimization Strategies

Incremental rendering: update only the Source of the changed plan, rather than redrawing all layers in full.

Web Worker computation: if weight/cost calculations are done locally, put them in a Worker to avoid blocking the UI thread.

Cache hits: cache requests with the same coordinate string + time window locally (TTL 5 minutes) to handle repeated plan switching.

Conclusion

This article has built a complete TMS frontend interaction solution around AI route planning visualization from four dimensions: multi-plan comparison, differentiated rendering, drag adjustment, and incremental feedback. The core points can be summarized as:

The essence of dragging is a closed loop: coordinate change → debounce → recalculation → incremental rendering → feedback on impact, and every step is indispensable;

What you will gain from this article: you will master how to use Mapbox GL JS to turn algorithm output into interactive visual objects, understand the necessity of "debounced recalculation" in real-time map scenarios, and gain the ability to handle engineering boundaries such as layer conflicts, coordinate order, and API rate limiting.