> For the complete documentation index, see [llms.txt](https://adatrack.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://adatrack.gitbook.io/docs/documentation/features/route-planning.md).

# Route Planning

Route Planning lets you define where a device *should* go — an ordered sequence of stops with optional time windows — and then tracks how closely a real device follows that plan in real time. It builds on [Travel Log](/docs/documentation/features/travel-log.md) and [Geofencing](/docs/documentation/features/geofencing.md): every route execution is linked to a Travel Log trip, and each stop is backed by a geofence for arrival/departure detection.

***

## Building a Route

Navigate to **Route Planning** in the sidebar to open the Route Manager, which lists your saved routes with Edit, Duplicate, Delete, Manage Devices, and Execute Now actions.

The **Route Builder** is a two-panel editor: a stop timeline on the left and a map on the right.

* **Add stops** by clicking the map, or by searching for an address (backed by the same geocoding service as Travel Log). Address search is unavailable on air-gapped self-hosted deployments with no Mapbox token configured — stops there are placed by map click or coordinate entry.
* **Import from Trip** seeds a new route's stops from a previously recorded Travel Log trip, using either its detected dwell points or a simplified version of its path — a fast way to turn "how the driver actually went last Tuesday" into a repeatable plan.
* The map **auto-fits** to your current stops whenever you add, remove, or reorder one, and a **Recenter** button re-triggers the fit at any time without fighting your manual pan/zoom.
* The **stop timeline** shows every stop as a compact card in sequence, connected by a rail. Each connector now shows the distance (and, in Road-Snapped mode, drive time) between consecutive stops, e.g. "2.4 km · 5 min".

### Path Mode

Each route has one of three path modes, selectable in the builder:

| Mode              | Behavior                                                                                                                                                                                |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Straight Line** | The default — a straight-line join between stops in order.                                                                                                                              |
| **Road-Snapped**  | Computes a road-following path via the Mapbox Directions API, with optional **avoid tolls / avoid highways / avoid ferries** and a **live traffic** toggle for traffic-aware ETAs.      |
| **Manual**        | Drag the path directly on the map to shape it — insert a bend without adding a full stop. Reordering stops afterward prompts you to keep your manual shape or reset to a straight line. |

### Optimize Route

Once you have 3 or more stops (up to a limit of 12), the **Optimize Route** button reorders them for a shorter or faster trip using the Mapbox Optimization API. "Lock first stop" and "Lock last stop" checkboxes (both on by default) keep your start/end point fixed — useful for depot-to-depot routes — while stops in between are freely reordered. If live traffic is enabled, optimization runs without it and shows a one-time notice, since the Optimization API doesn't support traffic-aware routing.

***

## Assigning Devices & Running Routes

A route can be run in two ways:

* **Manual execution:** Open the **Execution Wizard**, pick a device and a scheduled date/time, and click Start.
* **Device assignment (automatic):** From a route's **Manage Devices** panel, assign one or more devices ahead of time. Once armed, the platform automatically starts an execution the moment an assigned device is detected near the route's first stop — no manual scheduling required. After an auto-started execution finishes, the assignment re-arms itself (after a short cooldown) so the same device triggers it again next time — ideal for recurring routes like a daily delivery run or school bus route. Executions started this way show an "Auto-started" badge in the Route Progress Panel so dispatchers can tell them apart from manually started ones at a glance.

While an execution is active, the **Live Execution Tracker** shows the device's real-time position against the planned path, a live ETA to the next stop, and stop arrival/departure as they happen. If the device strays beyond the configured deviation threshold for two consecutive readings, a deviation alert fires; it clears automatically once the device returns to the path.

Every route execution is linked to its corresponding Travel Log trip, and a route's description automatically carries over to that trip (only if the trip doesn't already have one set, so a manual edit is never overwritten). You can filter the Travel Log trip list by planned route to see execution history at a glance.

***

## Alerts & Workflow Integration

Route events are available as **AdaTrack Flow** trigger nodes and dispatch through your existing alert channels, the same as Geofencing and Telemetry Alerts:

* `route.execution_started`
* `route.deviation_started` / `route.deviation_ended`
* `route.stop_arrived` / `route.stop_departed`
* `route.completed`

**Example:** Notify a dispatcher on Slack the moment a device goes off-route:

> `Route Deviation Started` → `Send Slack Message "{{device_name}} is off-route on {{route_name}}"`

Both the **AI Assistant** and **Chat Bot** plugins have read access to routes and executions, following the same pattern already used for Travel Log.

***

## Quotas & Tier Limits

| Limit                            | Community (self-hosted)  | Standard (self-hosted)   | Enterprise (self-hosted) | Free (SaaS)              | Pro (SaaS)               | Flexible (SaaS, PAYG)              |
| -------------------------------- | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ------------------------ | ---------------------------------- |
| Saved Routes                     | 5                        | 100                      | Unlimited                | 5                        | 100                      | 5 baseline, then overage billing   |
| Stops per route                  | 10                       | 200                      | Unlimited                | 10                       | 200                      | 10                                 |
| Simultaneous active executions   | 3                        | 50                       | Unlimited                | 3                        | 50                       | 3                                  |
| Address Lookups / month          | 1,000                    | 1,000                    | Unlimited                | 150                      | 3,000                    | 200 baseline, then metered overage |
| Route Navigation Lookups / month | 500                      | 500                      | Unlimited                | 100                      | 2,000                    | 100 baseline, then metered overage |
| Route Optimization requests      | tracked, not hard-capped | tracked, not hard-capped | tracked, not hard-capped | tracked, not hard-capped | tracked, not hard-capped | tracked, not hard-capped           |

Address search and route-preview lookups you trigger interactively are blocked once your monthly quota is exhausted. Background operations — saving a Road-Snapped route, Travel Log's address enrichment, and off-route reverse geocoding — are never blocked; they're tracked for billing but won't stop you from saving your work. Flexible-tier accounts can exceed their baseline allowance for Saved Routes, Address Lookups, and Route Navigation Lookups, billed automatically via metered Stripe usage. Current usage for all Route Planning quotas is visible on the **Billing** page.