The Driver App
Reference for the driver PWA — per-stage home actions, instant push notifications, Google-Maps-style location search, and empty-leg distance tracking.
This reference explains the driver-app features as operations sees them: the home screen and its actions, push notifications, smart location fields, and empty-leg distance tracking.
Home screen and actions
The home screen shows the active trip (or move order / blind loading order) card with the button for the current stage. The standing rule: the button is always available at every stage — as soon as a stage update arrives, the next button appears without restarting the app.
- Refresh happens automatically when the driver returns to the app, and via the explicit «Refresh» button.
- While a GPS fix is in progress (up to 10 seconds) a spinner starts the moment the button is tapped.
- If the stage is waiting on operations (checklist approval, Bayan al-Naql attachment…), a clear «waiting for operations» card appears instead of an empty screen.
- In the trips tab, the active trip is highlighted with a ring and a «current trip» badge.
Cancelling a trip releases the vehicle
When a trip is cancelled at any stage (even after the weight station or «cleared to move»), the vehicle returns automatically to «ready for loading» and the driver to «equipped» — no manual status fix needed, and a new loading order can be issued for the truck right away.
Push notifications (Web Push)
Notifications reach the driver's phone screen without opening the app, with a deep link to the exact trip or loading order. How it works:
- Subscription: the driver enables notifications from the «Notifications» card on the profile page (per device).
- Source: every in-app notification addressed to the driver also fires a push with the same bilingual text (per the driver's preferred language).
- Preferences: the driver's general mobile-notification toggle controls the whole channel — default-on for anyone subscribed.
- Maintenance: dead subscriptions (app removed, browser expired) are pruned automatically on the first failed send, so nothing accumulates.
Tapping a notification opens the relevant screen directly (the trip, the loading order, or the home page), and repeat notifications for the same event replace each other instead of stacking.
Location search in forms
The area/location fields on the move order and blind loading order forms work like Google-Maps search:
- Type an area name and suggestions appear (geographically biased to Saudi Arabia).
- Pick a suggestion, or tap the 📍 icon to drop a pin manually.
- Selecting a location attaches its coordinates to the order automatically, which feeds the geofence-assisted arrival when the driver arrives.
- Editing the text after picking clears the coordinates (a ✓ badge shows only when valid coordinates exist).
Empty-leg kilometres (blind loading)
The distance a driver covers empty to reach the loading area is computed automatically from the vehicle's odometer on arrival, and appears in:
- The blind-loading orders list (a «distance km» column) — the move orders list likewise.
- The driver-stats report: blind-loading order count and their empty kilometres.
Unreliable readings (odometer going backwards, or an implausible delta over 2,000 km) are stored as empty rather than a wrong number.