Skip to content
Developer documentation

RouteBase for Developers

How RouteBase understands deliveries, routes, drivers and time, with code you can read. For everyday use, see the user docs.

Overview

RouteBase is a web application for planning and running deliveries. The browser app talks to a managed backend over HTTPS. Everything a company owns lives inside its own workspace, and planning work like route optimization runs right in the browser, so planners get results straight away.

Stack

React 19 with TanStack Start (file-based routing, server functions), Tailwind CSS v4, Motion for animation and @dnd-kit for drag-and-drop. Maps use Google Maps JS, road geometry comes from OSRM and address lookup uses Google Places with OpenStreetMap Nominatim as a backup.

text
src/
  routes/            # one file per page (file-based routing)
    _authenticated/  # workspace pages: app.planner, app.deliveries, …
    workbase.tsx     # combined driver + client mobile app
    track.$token.tsx # public delivery tracking
  components/app/    # workspace UI (maps, planner timeline, dialogs)
  lib/               # optimize.ts, geo.ts, i18n.tsx, plans.ts, ops.ts

Data model

Every business record belongs to exactly one workspace (organization). The core entities and how they relate:

ts
type Organization = { id: string; name: string; depot_lat: number; depot_lng: number; plan: string };

type Vehicle  = { id: string; organization_id: string; name: string; plate: string; capacity_kg?: number };
type Driver   = { id: string; organization_id: string; name: string; vehicle_id?: string; color?: string };
type Customer = { id: string; organization_id: string; name: string; address: string; lat: number; lng: number };

type Delivery = {
  id: string; organization_id: string; customer_id?: string;
  address: string; lat: number; lng: number;
  date: string;              // YYYY-MM-DD, can be planned ahead
  boxes: number;             // drives handling time
  window_start?: string; window_end?: string;
  status: "pending" | "planned" | "in_progress" | "delivered" | "failed";
};

type Route     = { id: string; organization_id: string; driver_id: string; vehicle_id?: string; date: string; status: string };
type RouteStop = { id: string; route_id: string; delivery_id: string; sequence: number; eta?: string };

Delivery lifecycle

A delivery moves through a fixed set of states. The planner, WorkBase and live map all read the same state, so a change anywhere shows up everywhere.

text
pending ──optimize/assign──▶ planned ──driver starts trip──▶ in_progress
                                                          ├─▶ delivered  (proof of delivery)
                                                          └─▶ failed     (reason + optional note)

Route optimizer

Optimization runs in the browser in three passes: sweep clustering by angle from the depot, a nearest-neighbour order inside each cluster, then 2-opt to remove crossing lines. Locked routes are never changed.

ts
import { haversineKm } from "@/lib/geo";

// 2-opt: reverse a segment whenever it shortens the tour
function twoOpt(stops: LatLng[]) {
  let improved = true;
  while (improved) {
    improved = false;
    for (let i = 1; i < stops.length - 2; i++)
      for (let k = i + 1; k < stops.length - 1; k++) {
        const before = haversineKm(stops[i - 1], stops[i]) + haversineKm(stops[k], stops[k + 1]);
        const after  = haversineKm(stops[i - 1], stops[k]) + haversineKm(stops[i], stops[k + 1]);
        if (after < before) { stops.splice(i, k - i + 1, ...stops.slice(i, k + 1).reverse()); improved = true; }
      }
  }
  return stops;
}

ETAs & handling time

Arrival times combine road drive time (from OSRM, with a straight-line × 1.3 fallback), handling time per stop, breaks and the route start time. More boxes means more time at the door.

ts
const handlingMin = (boxes: number, perStop = 3, perBox = 0.5) => perStop + boxes * perBox;

let t = routeStart;
for (const [i, stop] of stops.entries()) {
  t += legMinutes[i];              // drive
  t  = applyBreaks(t, breaks);     // skip over planned breaks
  stop.eta = t;
  t += handlingMin(stop.boxes);    // unload
}

Geocoding & road geometry

Addresses are turned into coordinates once, when they are saved. Road-following lines come from OSRM and are cached in memory, keyed by the rounded list of waypoints.

ts
import { geocode, osrmRoute } from "@/lib/geo";

const pos = await geocode("Damrak 1, Amsterdam");   // { lat, lng } | null
const road = await osrmRoute([depot, pos!]);         // { line, km, min } | null

Server functions

App logic that needs the server is written as typed server functions. The browser calls them like normal async functions, and they check their input before running.

ts
import { createServerFn } from "@tanstack/react-start";
import { z } from "zod";

export const getDayStats = createServerFn({ method: "GET" })
  .inputValidator(z.object({ date: z.string() }))
  .handler(async ({ data }) => {
    // runs on the server, scoped to the signed-in user's workspace
    return { date: data.date, delivered: 0 };
  });

// in a component
const stats = await getDayStats({ data: { date: "2026-10-07" } });

WorkBase (driver & client app)

WorkBase is one mobile web app at /workbase that changes based on who signs in. Drivers see their trips, navigation and proof of delivery. Clients see live progress, order history and messages. Workspace admins create the logins.

Tracking links

Each delivery can have a public tracking page at /track/<token>. The token is random and can't be guessed. The page only shows that delivery's progress, and shows the van only after the driver presses Navigate to that address.

text
https://useroutebase.com/track/<delivery-token>

AI agents (MCP)

RouteBase has a read-only Model Context Protocol server, so AI assistants can answer questions about your fleet once a workspace member approves access. It can't write or change anything.

text
Endpoint:  https://useroutebase.com/mcp
Tools:     list_workspaces · list_deliveries(date) · list_routes(date) · list_fleet
Access:    OAuth sign-in + explicit approval per user

Translations

Every UI string goes through useT(), keyed by its English text. When a translation is missing, the English text is shown.

tsx
const t = useT();
<button>{t("Optimize routes")}</button>   // EN, NL, DE, FR, ES, TR

Plans & limits

Plan limits (monthly deliveries, vehicles, features) are defined in one catalogue and read by the pricing page, checkout and workspace gates, so they always stay in sync.

Building something?

Want to connect RouteBase to your own systems, or need write access, webhooks or an export? Email mha.business.contact@gmail.com and tell us what you're building.