Last-Mile Emergency Dispatch

Last-Mile Emergency Dispatch

Project Overview

Last-Mile Emergency Dispatch is a real-time relief logistics command center and deterministic simulation system developed using FastAPI and Vanilla JavaScript. The system coordinates the delivery of perishable emergency supplies, including cooked meals, raw rations, and infant formula, from donors to relief shelters through a fleet of riders.

Its primary objective is to minimize food wastage, ensure timely delivery, and respond dynamically to operational disruptions such as traffic delays, shelter closures, unavailable resources, and unresponsive riders.

1. Key Features

1.1 Deterministic Simulation Engine The system uses a simulated clock called FakeClock to control time advancement step by step. It simulates rider movement, pickups, transportation, and deliveries across a two-dimensional coordinate grid. The rider speed is set to 0.4 km per minute.

1.2 Perishability and Deadline Enforcement The system validates food safety deadlines (safe_until) and shelter delivery deadlines (need_by). A five-minute safety buffer is included in delivery ETA calculations to ensure that deliveries remain within acceptable time limits.

1.3 Resource Compatibility The system checks whether a shelter has the resources required to receive a particular type of supply.

• Raw rations require both water and fuel.
• Infant formula requires water.
• Cooked meals can be delivered to any open shelter.

1.4 Dynamic Rerouting If a shelter closes, loses access to essential utilities, or has its outstanding requirement fulfilled or reduced, the system recalculates the delivery route for riders who are already travelling. This helps prevent failed deliveries and unnecessary food wastage.

1.5 Dynamic Pickup Leases The system assigns claim expiration times according to the distance between a rider and a donor. If a rider does not collect the supplies before the claim expires, the reservation is cancelled and the items are returned to the available donor inventory.

1.6 Rider Heartbeat and Freeze Detection The system monitors rider activity through periodic pings. If a rider remains inactive for ten minutes, they are marked as unresponsive. Claims that have not yet reached the pickup stage are automatically cancelled, while deliveries already in transit are flagged as being at risk.

1.7 Traffic Delay Management Riders can report traffic delays up to three times for each delivery. Each valid report extends the claim expiration time by five minutes, provided the revised estimated arrival time remains within the permitted safety limits.

1.8 Live Command Center Dashboard The frontend provides a responsive, dark-themed dashboard through index.html. It displays live simulation metrics, delivery progress bars, simulation controls, and an interactive event timeline.

2. Project Structure

The project is organized into the following files and directories:

• main.py: Contains the FastAPI application, REST API endpoints, and static file mounting.
• engine.py: Implements the core simulation logic, rider movement, dynamic rerouting, and operational actions.
• rules.py: Defines business rules, ETA and lease calculations, and resource compatibility validations.
• models.py: Defines data classes and enumerations for donors, batches, shelters, needs, riders, portions, and events.
• store.py: Maintains the in-memory state of the simulation.
• clock.py: Implements the deterministic FakeClock for controlling simulation time.
• geo.py: Handles two-dimensional Euclidean distance calculations and travel-time estimation.
• seed.py: Provides initial demonstration data for donors, shelters, batches, needs, and riders.
• static/index.html: Contains the interactive frontend dashboard.

3. Core Mechanics and Business Rules

3.1 Rider Speed The rider speed is defined by SPEED_KM_PER_MIN and is set to 0.4 km per minute, equivalent to 24 km/h.

3.2 Delivery Safety Buffer The BUFFER_MINUTES parameter adds five minutes to delivery ETA calculations to account for the required safety margin.

3.3 Pickup Lease Duration The LEASE_BUFFER_MINUTES parameter is calculated using the greater of ten minutes or the rider-to-donor travel time plus five minutes. The lease is capped at the latest safe pickup time.

3.4 Heartbeat Timeout A rider who does not move or send a ping for ten minutes is marked as UNRESPONSIVE.

3.5 Pickup and Arrival Radius A rider must be within 0.2 km of the target coordinates to satisfy the pickup or arrival proximity requirement.

3.6 Traffic Delay Limits

Each portion permits a maximum of three traffic-delay messages. Every accepted message extends claim_expires_at by five minutes.

3.7 Cancellation Policy Cancellation is permitted only while a portion is in the CLAIMED state. Cancelled items are returned to the available pool. Direct cancellation is not permitted once the portion enters the IN_TRANSIT state.

4. Portion Lifecycle

Each delivery portion moves through a defined lifecycle represented by the PortionStatus enumeration.

4.1 CLAIMED The rider has reserved a portion of the available supplies and is travelling to the donor location for pickup.

4.2 IN_TRANSIT The rider has collected the supplies from the donor and is travelling towards the designated shelter.

4.3 DELIVERED The supplies have been successfully handed over to an open, compatible shelter within the required deadlines.

4.4 CANCELLED The delivery is cancelled before pickup. This may occur because of rider cancellation, lease expiration, rider unresponsiveness, or shelter closure when no suitable fallback is available. The supplies are returned to the donor pool.

4.5 EXPIRED / WASTED The supplies are no longer deliverable because their food safety window has expired or an in-transit delivery has failed without a reachable fallback shelter. The affected quantity is permanently deducted from the batch inventory.

5. Installation and Setup

5.1 Prerequisites Python 3.10 or later must be installed on the system. The following dependencies are required:

pip install fastapi uvicorn pydantic

5.2 Running the Server Run the following command from the parent directory of the application package:

uvicorn app.main:app --reload

If the files are located directly in the current working directory without a package wrapper, use:

uvicorn main:app --reload

In the latter case, local imports may need to be adjusted by removing leading dots. Alternatively, run the application as a module from its parent directory.

5.3 Accessing the Dashboard Once the server is running, open a browser and navigate to the following addresses:

• Command Center Dashboard: http://127.0.0.1:8000/static/index.html
• Interactive API Documentation (Swagger): http://127.0.0.1:8000/docs

6. API Endpoints

The application exposes REST API endpoints for simulation control, rider operations, delivery management, and dynamic updates to simulation entities.

6.1 State and Simulation Control

GET /state

Retrieves the complete simulation state, including the clock, donors, batches, shelters, needs, riders, portions, and events.

POST /seed

Resets the simulation to its initial demonstration data.

POST /sim/advance

Advances the simulation clock by a specified number of minutes using the minutes parameter. Movement and simulation events are processed in one-minute steps.

Example request:

{  "minutes": 5}

6.2 Rider and Delivery Operations

GET /riders/{rider_id}/cards

Retrieves all valid and deliverable combinations of shelter needs and supply batches for a specific rider.

POST /claim

Allows a rider to claim a delivery portion by specifying rider_id, need_id, and batch_id.

POST /portions/{portion_id}/cancel

Cancels a delivery portion while it remains in the CLAIMED state.

POST /portions/{portion_id}/message

Allows a rider to report a traffic delay and request a five-minute extension to the claim lease, subject to the system's safety rules.

POST /sim/freeze_rider

Freezes or unfreezes a rider using the rider_id and frozen parameters.

6.3 Dynamic Disruptions and Entity Management

PATCH /shelters/{shelter_id} or POST /sim/shelter_status

Updates a shelter's availability status, water supply, or fuel availability. Supported shelter statuses include OPEN and TEMPORARILY_UNAVAILABLE. Changes automatically trigger rerouting for affected deliveries.

PATCH /needs/{need_id} or POST /sim/update_need

Updates a shelter's required quantity or delivery deadline (need_by) during the simulation.

POST /donors, /batches, /shelters, /needs, and /riders

Creates new donors, supply batches, shelters, requirements, and riders dynamically while the simulation is running.

7. Conclusion

Last-Mile Emergency Dispatch provides a simulation-based approach to managing emergency food distribution. By combining deterministic time control, delivery deadline enforcement, resource compatibility checks, dynamic rerouting, pickup lease management, and rider monitoring, the system models several operational challenges involved in last-mile relief logistics.

Its modular backend architecture and interactive frontend make it possible to monitor delivery operations, simulate disruptions, and evaluate how the system responds to changing conditions. The overall objective is to improve delivery reliability, reduce avoidable food wastage, and support more effective coordination between donors, riders, and relief shelters.