Module: Hyperlocal Delivery (hyperlocal / —)

Status: 🟡 Partially implemented (delivery tasks flow on hardcoded fee constants; rider fleet empty; no admin pricing-override row configured) · Last validated: 2026-09-06 · Priority: P1

The last-mile rider layer that CommerceX/Food/etc. route local deliveries through. Validated against classs/HyperlocalModule.php + schema.

A. Purpose

Assign nearby riders to delivery tasks, price by distance, track. No commission model defined. Correction (2026-09-06): an earlier pass of this page framed the fee model as incomplete because "the pricing settings key is absent from config." The admin_global_settings row for that key (hyperlocal_delivery_pricing) is indeed absent (verified live, 2026-09-06), but computeDeliveryFee does not need it to function: deliveryPricingConfig() (:243) treats hardcoded class constants DELIVERY_BASE_FEE=40.0, DELIVERY_PER_KM=8.0, DELIVERY_MIN_FEE=40.0 (:20-22) as "the source of truth" (its own docblock, :238) and only optionally overrides them from that admin key at runtime. So the fee model is live and computing real fees today (₹40 base + ₹8/km, ₹40 floor) — what is actually missing is an admin UI/config row to change those numbers without a code deploy, not a working fee calculation.

B. Actors

Rider (partner); the module that created the task (commerce/food); admin.

E. Feature registry (prefix HYP-)

Correction (2026-09-06): an earlier pass of this page named delivery_orders as the delivery task table throughout HYP-003/HYP-006, the data model, and the state machine. grep across classs/HyperlocalModule.php for delivery_orders returns zero hits — the module CREATE TABLE IF NOT EXISTSs and reads/writes exclusively hyperlocal_tasks (:56 schema, :221 INSERT in createDeliveryTask, :452/:465/:479 in assignRider/related). delivery_orders is a real, populated table (61 rows) but it belongs to a different module's code path, not this one — do not cite it for Hyperlocal claims. Code wins; corrected below.

G. Data model (2026-09-06)

hyperlocal_riders 0 (no riders onboarded) · hyperlocal_tasks 1 (the real live delivery-task table — createDeliveryTask INSERTs here). delivery_orders (61 rows) exists in the schema but is never referenced by HyperlocalModule.php; it is out of this module's scope (likely owned by another delivery/courier code path not audited here) — see correction above.

H. Financial impact

Delivery fee computed by computeDeliveryFee (:289) off hardcoded constants (₹40 base + ₹8/km, ₹40 floor — see correction under Purpose) and added to the parent order; there is no hyperlocal commission. The fee model itself works; what's missing is (a) an admin-configurable override row and (b) any commission on the delivery fee.

K. State machine (hyperlocal_tasks.status, ENUM confirmed at :64)

pending → assigned → picked_up → delivered / cancelled. assignRider (:427) is the only observed pending → assigned transition in this file; no code path in HyperlocalModule.php was found that moves a task to picked_up/delivered (OTP columns otp_pickup/otp_drop exist on the table but no method here reads/verifies them) — Requires Verification: confirm whether those transitions live in a rider-facing app/API file outside this class before assuming they're missing.

L / M / N

Errors: HYP-E001 no rider found (hyperlocal_riders=0 → nothing to assign). Depends on the calling module (commerce/food routing), geo. Change-impact: it is the shared last-mile layer — onboarding riders + an admin pricing override activates configurable pricing for every module that creates delivery tasks (the fee itself already works via constants without either).