Delivery, dispatch and drivers

The platform runs its own last-mile network. When a seller accepts an order group, a delivery task is created; the worker assigns it to an eligible driver and plans the driver's route; the driver collects, delivers with proof and, for cash orders, collects the cash that dispatch later reconciles.

From accepted order to delivery task

1. Task created. When a seller accepts an order group (order.confirmed), one delivery task is created for that group. Task types are pickup, drop-off and return pickup.
2. Automatic assignment. Every minute the worker takes unassigned tasks, oldest first, and runs the assignment engine. If no driver is eligible the task stays in the pool and is retried — eligibility rules are never relaxed. Dispatchers can also assign and unassign by hand.
3. Route planning. Every minute the worker sequences each driver's assigned and accepted stops (nearest-neighbour, each pickup before the drop it feeds). Stops already started keep their place. Dispatchers can rebuild a driver's route on demand.
4. Driver runs the route. The driver app's Shift tab lists stops in the planned order; the driver starts and completes the route. A route cannot be completed while stops are still open.
5. Delivery with proof. The driver marks picked up and in transit, triggers a delivery code sent by SMS to the recipient, enters it, records cash if the order is COD, then completes the task.

How the assignment engine chooses a driver

A driver must first pass every hard rule; any failure excludes them:

Eligible drivers are then scored, weighting proximity most (0.6), then current load (0.3), then zone priority (0.1).

Task lifecycle

Failure reason codes: customer unavailable, wrong address, customer refused, payment not ready, access denied, vehicle breakdown, weather, other.

Proof of delivery

• Delivery code (OTP) — used by the app today. A 6-digit code valid for 30 minutes, sent by SMS to the recipient, never shown to the driver. Five guesses per code and at most five codes per task; only a hash is stored.
• The server also accepts photo, signature and ID check proofs referencing an uploaded file, but the driver app does not capture them yet.
• Proof captured more than 0.5 km from the drop point is flagged for review, not refused.

Cash on delivery

• Each COD task records a cash collection. The driver's "cash on hand" is derived from those records.
• When a driver hands cash in, a dispatcher records the settlement with a reference; the ledger moves the amount out of cash in transit. A shortfall raises a cod.settlement_discrepancy alert to finance.
• An hourly job reconciles collections against the ledger per currency; dispatchers can run the same check from the Cash view.

Shifts, zones and vehicles

• Dispatchers roster shifts and see adherence (scheduled versus actual start and end). Drivers clock in and out from the app; dispatch can end a driver's shift.
• Delivery zones are managed by dispatchers and admins; each driver is linked to zones with a priority.
• Vehicle types: motorcycle, car, van, truck, bicycle.

Becoming a driver

1. The applicant applies from their account, creating a driver record pending approval.
2. The applicant adds a vehicle and a bank account (the IBAN is stored encrypted). Their open items are licence and vehicle.
3. The review desk assigns zones and a cash limit (which must be above zero), verifies the bank account and approves. Approval grants the driver role.

An applicant who signs in to the driver app before approval sees an onboarding screen listing their own tasks and the review desk's, with forms to add a vehicle and bank account.

Driver earnings

An earning is recorded when a delivery completes — a per-task amount plus a per-kilometre amount. Earning types include task, distance, incentive, tip and adjustment. Drivers see earnings, payouts and cash on hand in the app.

The dispatch console

Views: Dispatch (task board, task drawer, SLA board), Drivers (roster, rebuild route), Shifts (roster and adherence), Cash (COD reconciliation and settlement). A live fleet map is not built yet.

The driver app

Tabs: Tasks, Shift (with the planned route), Cash, Earnings, Account — in English and Arabic, with an offline queue that replays actions when connectivity returns. The pickup step is a button; barcode scanning is not implemented, and the app does not yet send live location.