iCANS — AI Dispatch

Design PRD  ·  v0.1

1. Overview

AI Dispatch is an intelligent routing engine embedded in the iCANS Dispatch board. It automatically sequences driver workloads, selects optimal dumpsites, accounts for real-world constraints including traffic, landfill wait times, weather, and road restrictions, and continuously adapts as conditions change throughout the day. Dispatchers retain full control — they can override, lock, or adjust any decision the AI makes.

This feature is delivered in three phases:

Phase	Name	Description
Crawl (v1)	Deterministic AI	Rule-based routing engine. Priority levels, time windows, driver schedules, truck constraints, landfill data, inventory availability, and next-day job consideration. Generates data for v2.
Walk (v2)	Learned Intelligence	Adds real-time landfill wait times (iCANS driver network), historical traffic, weather, road restriction data, trash photo AI analysis, revenue weighting, predictive customer demand, fuel pricing, company-specific AI training, and a feedback loop for continuous improvement.
Run (v3)	Predictive & Autonomous	Pre-day AI route planning with dispatcher approval workflow, ML feedback loop with accuracy dashboard, Next-Day Prep Mode, automated broker/reschedule suggestions, and revenue flagging for unprofitable jobs.

2. How Dispatch Works Today

This section provides context for developers who are new to iCANS. It describes the current dispatch workflow that AI Dispatch is built on top of.

The Dispatch board is accessible from the main navigation under Daily Operations → Dispatch. It has two tabs: Map and Inventory.

Dispatch Board Layout

• Left panel — Unassigned Tasks: tasks that have not yet been assigned to a driver. Includes a past-due tasks alert and an asset management alert.
• Center panel — Drivers: lists all active drivers for the selected day. Each driver card shows their task queue and completion count.
• Right area — Map: Google Maps view showing driver locations, task pins, and territory overlays. Tapping a task pin opens a task card with job details.

Key Concepts

• Tasks are the unit of work. Each task has a type: Drop Off, Pick Up, Swap, Dump & Return, or Relocate.
• Drivers are assigned to territories. Tasks within a territory are generally routed to that territory's driver.
• The date selector at the top of the board allows dispatchers to view Today or Tomorrow.
• A task can be manually dragged to a driver or reordered within a driver's queue.
• Drivers interact with their assigned tasks in the Driver App on their mobile device.

3. Problem Statement

Dispatchers today sequence routes manually — a time-intensive process that cannot account for real-time traffic, landfill wait times, driver availability, inventory constraints, and changing order volumes simultaneously. As a result:

• Routes are suboptimal: jobs are often sequenced by habit rather than efficiency.
• Landfill decisions are made by feel rather than data — dispatchers do not have visibility into current wait times, pricing by material type, or gate hours when deciding where to dump.
• Inventory constraints are reactive: a full dumpster is not flagged for dump prioritization until it creates a scheduling conflict.
• New orders disrupt the day: when a high-priority order comes in mid-morning, manually re-sequencing a driver's queue around it is disruptive and slow.
• End-of-shift overruns are discovered late: dispatchers have no advance warning when a driver's workload exceeds available shift hours.

4. Goals

• Maximize the number of completed jobs per driver shift while honoring customer priority levels and time windows.
• Automate landfill selection based on wait times, accepted materials, pricing model (tonnage vs. yardage), and distance — not dispatcher intuition.
• Surface end-of-shift overrun risk early and give dispatchers actionable options before it becomes a problem.
• Keep dispatchers in control: AI routing is automatic, but any decision can be overridden or locked.
• Build a dataset through v1 that enables the AI to learn and improve in v2 and v3.

5. Dispatch Modes

Dispatchers can choose between four operating modes from the Dispatch board. The selected mode applies globally for all drivers for the current day. The mode selector is displayed prominently at the top of the Dispatch board and persists per user session (not per company). Each mode label includes a tooltip explaining its behavior.

5.1 Priority Mode (Default)

Customer priority levels and requested time windows are the primary routing criteria. Cost efficiency is applied as a secondary sort after all priority and time window conflicts are resolved.

Decision logic order:

1. Honor all ASAP tasks first.
2. Within the same priority tier, sequence by requested time window.
3. When two jobs have the same priority and overlapping or absent time windows, select the most cost-effective sequence.
4. Apply cost-efficient routing to all remaining lower-priority jobs after higher tiers are locked in.

Tooltip copy: "Prioritizes customer priority levels and time windows first. Routes are optimized for cost after all priority requirements are met."

5.2 Efficiency Mode

The most cost-effective route is always selected. Priority levels are used only as a tiebreaker when two route options produce results within 10% of each other in total cost.

Decision logic order:

1. Calculate the lowest-cost valid route across all assigned jobs.
2. When two route sequences produce costs within 10% of each other, select the one that services the higher-priority customer first.
3. Time windows are respected as hard constraints (a job cannot be arrived at before its earliest window), but are not used as a sorting criterion.

Tooltip copy: "Builds the lowest-cost route regardless of customer priority levels. When costs are within 10% between two options, the higher-priority customer is served first."

5.3 Manual Mode

The AI makes no automatic routing decisions. Dispatchers build and sequence the route entirely by hand. The AI remains active in an advisory capacity only — it can surface warnings (e.g., anticipated shift overrun, landfill closed) but will not reroute, resequence, or push changes to drivers automatically.

Tooltip copy: "AI routing is off. Build routes manually. The AI will still surface warnings but will not change any assignments."

6. Routing Decision Variables

The following variables are inputs to the routing engine. Phase indicates when each variable is introduced.

Input Variable	Data Source	Phase	Role in Decision
Customer priority level	Task data (existing)	v1	Primary sort key in Priority Mode. Tiebreaker in Efficiency Mode.
Requested time window	Task data (existing)	v1	Hard constraint (cannot arrive before window opens). Sort key after priority in Priority Mode.
Driver schedule (start/end)	Driver profile	v1	All routing stays within shift window. Driver break stops clock.
Driver territory	Territory settings	v1	Default assignment scope. Proximity overrides territory when it produces a more efficient overall route.
Truck type & capacity	Vehicle profile (AI questionnaire)	v1	Determines which jobs a truck can service and how many pickups before a dump run is required.
Truck out-of-service status	Vehicle profile	v1	Blocked from any routing assignment.
Landfill hours of operation	Socialized Landfills registry	v1	Dump runs only scheduled within open hours.
Landfill accepted materials	Socialized Landfills registry	v1	Only landfills accepting the load's material type are considered.
Landfill pricing model	Socialized Landfills registry (company-private)	v1	Tonnage vs. yardage pricing informs cost estimate per dump run.
Landfill address / distance	Socialized Landfills registry	v1	Drive time and fuel cost estimate.
Inventory availability by size	iCANS inventory	v1	Determines dump priority for full dumpsters. Low/unavailable inventory elevates dump priority.
Next-day confirmed jobs	iCANS order data	v1	Informs Next-Day Prep Mode. Confirmed orders only.
Job revenue	Order data (existing)	v1	Secondary tiebreaker when cost and priority are equal. Higher-revenue job preferred.
Task in-progress status	Driver App status	v1	In-progress tasks are locked from rerouting.
User-locked tasks	Dispatcher override	v1	Locked tasks are excluded from AI rerouting.
Real-time landfill wait times	iCANS Driver App network	v2	Estimated wait time at each landfill based on active iCANS drivers on-site. Modeled similarly to Google traffic.
Historical landfill wait patterns	iCANS platform data	v2	Day-of-week and time-of-day wait time baselines per landfill.
Historical traffic patterns	Google Maps / routing API	v2	Drive time estimates incorporate time-of-day traffic patterns.
Real-time traffic events	Google Maps / routing API	v2	Road closures, accidents, and construction detected mid-day. Triggers reroute evaluation.
Road weight & height restrictions	Public road restriction dataset (DOT / OSM)	v2	Routes avoid roads the truck cannot legally or physically use.
Weather forecast	Public weather API	v2	Rain and severe weather factored into drive time estimates and job completion probability.
Local fuel prices	Public fuel price API	v2	Per-mile cost estimate used in route cost calculations.
Driver pay type	Driver profile (future field)	v2	Hourly drivers make landfill wait time more expensive than per-job drivers.
Trash photo material analysis	Driver App camera + AI vision model	v2	AI identifies material type and estimates weight from driver photo to select optimal landfill.
Customer historical demand patterns	iCANS order history	v2	Repeat customers with consistent pickup days inform demand density estimates. Used only as a tiebreaker.
Gate codes (historical)	iCANS order history / future Gate Code feature	v3	Known gate codes pre-populate driver instructions and inform job time estimates.
Company-specific AI training	Dispatcher feedback	v2	Custom rules per company (e.g., hazmat handling, driver certifications, preferred routes).

7. Full Dumpster Dump Prioritization

When a dumpster is marked as full in iCANS (via the existing "full" status flag), the AI evaluates whether a dump run needs to be scheduled and at what priority level.

Priority Assignment Logic

Condition	Priority Assigned	Rationale
Full dumpster; inventory of that size is available	Low (default)	No blocking dependency today.
Full dumpster; inventory of that size is low or unavailable; a Drop Off or Swap for that size is confirmed today	High	Dump run must be completed before the same-day drop/swap can be fulfilled.
Full dumpster; inventory low/unavailable; Drop Off or Swap confirmed for next day with an early time window and the landfill opens the same time or later than the job	High (escalated today)	Example: Drop Off at 7am tomorrow, landfill opens at 7am. Dump must happen today to have the asset ready in time.
High volume of High priority jobs tomorrow; running low on available inventory of any size	Medium → High (AI-elevated)	AI proactively clears inventory today to get ahead of tomorrow's load. Used in Next-Day Prep Mode.

The AI checks both today's and tomorrow's confirmed job schedule when evaluating dump priority. Draft and brokered jobs are excluded.

8. Landfill Selection Logic

When a driver needs to dump, the AI evaluates all landfills marked as "Used" in the company's Socialized Landfills registry.

8.1 Hard Constraints (must be satisfied)

• Landfill is open at the time the driver is estimated to arrive.
• Landfill accepts the material type being hauled.
• The route to the landfill does not require roads that exceed the truck's weight or height limits.

8.2 Scoring Factors (v1)

• Drive time to landfill from current driver location.
• Estimated dump cost based on the landfill's pricing model (tonnage vs. yardage) and the load.
• Number of remaining jobs on the driver's queue — a longer queue increases the cost of a far landfill.

8.3 Additional Scoring Factors (v2)

• Real-time wait time at each landfill based on iCANS Driver App network data. Modeled by monitoring active iCANS driver movement at landfill locations — slow movement indicates a queue. Historical wait patterns by day and time are used as a baseline when real-time data is insufficient.
• Driver pay type: hourly drivers make landfill wait time directly expensive. A longer wait at a closer, cheaper landfill may cost more in driver time than driving to a faster, slightly more expensive one.
• Trash photo AI analysis: the driver photographs the load in the Driver App before departure. The AI identifies material type and estimates weight or volume to determine which landfill accepts the material and which pricing model produces the lower cost.

Landfill Selection Example

Driver has a 20YD dumpster half-full of shingles. AI identifies material as roofing shingles via photo analysis. Estimates ~5,000 lbs.

Landfill	Distance	Rate	Wait	Estimated Total
Landfill A	8 miles	$42/ton	~45 min (real-time)	$105 + ~$30 driver time → Selected
Landfill B	14 miles	$58/ton	No wait	$145 + $0 wait → more expensive overall
Landfill C (Concrete)	—	—	—	Does not accept shingles → Excluded

AI routes to Landfill A and notes reasoning in the AI Reasoning panel.

8.4 Material-Specific Routing

• Clean concrete → concrete recycler (if available and accepted).
• Yard waste → yard waste disposal site (if available and accepted).
• Mixed MSW → standard landfill.
• Materials not accepted at any available landfill → AI surfaces a warning to the dispatcher.

8.5 Photo Analysis Failure Handling

If the AI returns low confidence on the material type from the first photo:

1. Driver App prompts the driver to retake the photo.
2. If the second photo also returns low confidence, the Driver App presents two options: select a landfill manually from the company's available list, or flag the load for a later dump decision.

There is no default landfill fallback. The driver must make a selection or defer.

9. Dispatcher Controls

9.1 Manual Override

Dispatchers can manually drag and reorder tasks on the Dispatch board at any time. When a task is moved manually:

• The AI immediately re-optimizes all remaining unlocked tasks around the new position.
• The manually placed task is treated as a soft anchor — the AI may suggest moving it if a significant efficiency gain is detected, but will not move it automatically.

9.2 Task Locking

Dispatchers can lock any task on the board to prevent the AI from rerouting it. A locked task displays a lock icon.

• Locked tasks are excluded from AI rerouting regardless of new information.
• In-progress tasks (driver has started the job) are automatically locked by the system. The AI cannot reroute an in-progress task.
• "In progress" is defined as the driver having tapped the status update in the Driver App indicating they have begun the job. The specific trigger (status tap vs. GPS proximity) is an engineering decision.

When a High-Priority Job Is Blocked by a Lock: If a new high-priority job arrives and the optimal route would require moving a locked task, the AI does not move the locked task. Instead, it sends an urgent push notification to all users with Dispatch permission: "A new high-priority job has been added. Unlock [Task Name] to allow AI to find a more efficient route."

9.3 Mid-Day Rerouting

As new jobs come in throughout the day, the AI re-evaluates all unlocked, not-in-progress tasks and updates routes automatically. Drivers receive updated route instructions in the Driver App immediately when a reroute occurs.

Driver Offline During Reroute: If a driver is offline when a reroute is generated, the reroute is queued with a timestamp. When the driver comes back online, the Driver App syncs and pushes the updated route with a notification. If the driver's location has advanced past the point where the reroute would have applied, the AI discards the stale reroute and recalculates from the driver's current position. The dispatcher receives a badge notification that the driver is offline with pending routing updates.

10. Shift Overrun Detection & Escalation

The AI continuously monitors each driver's estimated completion time against their scheduled shift end. When it detects that a driver is at risk of not finishing their assigned jobs:

Trigger	Action	Channel
First detection of projected overrun	Alert sent to all users with Dispatch permission. AI provides estimated jobs at risk and options: reassign to another driver, broker the job, contact customer to reschedule, or extend the driver's shift.	Push notification (mobile) + urgent issue notification (desktop). Email/SMS to dispatch-permission users (v1).
Every 60 minutes if issue unresolved	Reminder alert with updated job count at risk.	Same channels as initial alert.

If another driver in the same territory has capacity, the AI identifies which jobs can be reassigned and includes the suggestion in the alert. If no internal capacity is available, the AI flags the job as a potential candidate for brokering or customer reschedule.

11. Dispatch Board UI Changes

The following UI elements are added to the existing Dispatch board. The current layout (Unassigned Tasks panel / Drivers panel / Map) is preserved.

11.1 Mode Selector

A mode selector control is added to the top of the Dispatch board, near the existing date selector. It displays the currently active mode and allows the dispatcher to switch modes. Each mode option includes a tooltip icon that opens a plain-language explanation on hover/tap.

11.2 AI Reasoning Panel

Each task card on the Dispatch board includes a collapsible "AI Reasoning" section. This section is collapsed by default and contains one to two plain-English sentences explaining why the AI placed that task in its current position in the route.

Examples:

• "Scheduled before Job #402 because both are Medium priority and this address reduces total drive time by 12 minutes."
• "Assigned to Tyrone rather than Dani because this address falls within Tyrone's territory and Dani has two ASAP jobs queued."
• "Routed to Landfill B instead of Landfill A — current wait at Landfill A is estimated at 35 minutes based on active driver reports."

11.3 Lock Indicator

Locked tasks display a lock icon on their task card. The lock can be toggled by the dispatcher from the task card directly.

11.4 Urgent Issue Notifications

Urgent issue notifications appear as a banner at the top of the Dispatch board on desktop. On mobile, they are delivered as push notifications with a badge count on the Dispatch nav item. Notifications are dismissible but persist until the underlying issue is resolved.

11.5 Tomorrow View

The existing Tomorrow toggle on the Dispatch board shows tomorrow's confirmed jobs. In Next-Day Prep Mode, the AI surfaces recommended dump runs for today based on tomorrow's job requirements — these appear as AI-suggested tasks in the Unassigned Tasks panel with a "Prep for Tomorrow" label.

12. Vehicle Profile — AI Questionnaire

Rather than presenting dispatchers with a list of form fields to fill out for each vehicle, truck setup is completed through a short conversational AI questionnaire in the Admin App. The questionnaire is triggered when a new vehicle is added or when an existing vehicle profile is incomplete.

The questionnaire captures:

• Truck type (roll-off, hook lift, residential, other).
• Maximum load capacity (cubic yards and estimated weight limit).
• Vehicle height and gross vehicle weight — used for road restriction routing.
• Fuel type and estimated fuel efficiency (miles per gallon or per tank range).
• Any known limitations (e.g., cannot service locations with low clearance, not rated for hazmat).

The AI interprets natural language answers and maps them to structured fields. For example, a dispatcher who answers "it's a standard 20-yard roll-off" will have capacity, type, and dimensional estimates pre-filled based on known industry specifications, with a confirmation step before saving.

13. Driver App Changes

13.1 Route Updates

When the AI reroutes a driver's queue, the Driver App updates automatically. The driver receives a push notification: "Your route has been updated." The updated sequence is reflected immediately in the Driver App task list.

13.2 Trash Photo Capture

Before departure for a pick-up job, the Driver App prompts the driver to photograph the load. This is a required step in the pick-up flow (v2). The AI analyzes the photo and returns:

• Estimated material type (e.g., MSW, clean concrete, shingles, yard waste).
• Estimated weight or volume range.
• Recommended landfill based on material, pricing model, current wait time, and distance.

The driver sees the recommended landfill and can accept it or choose a different one from the company's available list. The AI recommendation is advisory — the driver always has final selection.

13.3 Break Handling

Drivers can tap a "Take Break" button in the Driver App to pause their shift clock. While on break, the AI pauses routing calculations for that driver and does not generate reroute decisions based on their location. When the driver resumes, the AI recalculates from their current position.

14. AI Feedback & Improvement

14.1 Feedback Loop (v2)

The AI logs every routing decision alongside key parameters: estimated drive time, estimated landfill wait, estimated cost, priority levels, and mode. After each job is completed, the system captures actual outcomes: actual drive time, actual landfill wait, actual completion time. This dataset is used to identify systematic estimation errors and improve routing model accuracy over time.

14.2 Dispatcher Feedback

Dispatchers can submit feedback on any AI decision directly from the AI Reasoning panel. A thumbs-up / thumbs-down control is visible on each expanded reasoning panel. Thumbs-down opens a short feedback form.

The feedback form includes:

• A reason selector (e.g., wrong landfill, wrong priority, traffic estimate was off, job took longer than expected).
• A free-text notes field for additional context.
• A toggle: "Report to iCANS" vs. "Company note only."

Feedback Routing Rules:

• Company note only: feedback is stored privately on the company account. Informs company-specific model adjustments only.
• Report to iCANS: feedback is shared with the platform. Informs platform-wide model improvements (e.g., landfill wait time estimation, traffic patterns, material weight estimates).

14.3 Company-Specific AI Training (v2)

Companies can define custom routing rules through a training interface in the Admin App. Training rules are stored per company and take precedence over platform-level model outputs where they conflict.

14.4 AI Accuracy Dashboard (v3)

A read-only dashboard accessible to Admin users shows AI decision accuracy over time: estimated vs. actual drive times, estimated vs. actual landfill wait times, on-time job completion rate, and jobs completed per shift trend.

15. Customer Demand Prediction

The AI analyzes order history to identify customers with consistent pickup patterns (e.g., a customer who calls for a pickup every Thursday). This data is used at a low weight in routing decisions — it is only applied when two route options produce similar results across higher-priority variables.

Predicted pickups do not appear as tasks on the dispatch board and are never surfaced to the driver. They influence only the AI's positioning decisions when all other factors are equal.

Customer demand predictions are only factored into routing when the AI is resolving a near-tie between two route options. They are never the primary driver of a routing decision.

16. Gate Code Handling

Gate codes are a future parallel-track feature. When available, historically captured gate codes will pre-populate driver instructions and will be used by the AI to factor in access delay time for jobs at gated locations. This feature is out of scope for v1 and v2 and is documented here as a future dependency.

17. Out of Scope — This Phase

• Pre-day AI route plan with dispatcher approval workflow (v3).
• ML feedback loop accuracy dashboard (v3).
• Gate code socialization and auto-population (parallel track, future dependency).
• Brokering workflow — AI flags jobs as broker candidates but the brokering flow itself is a separate feature.
• Customer-facing notifications related to AI-driven reschedules.
• Driver App map/navigation UI redesign — route updates push to existing Driver App task list only.
• Tentative (draft) and brokered jobs are not considered in any AI routing calculations in any phase.

18. Dependencies

• Socialized Landfills — must be live before AI Dispatch ships.
• Driver App status updates — in-progress detection relies on drivers actively tapping status updates.
• Vehicle profiles — AI routing accuracy depends on truck type, capacity, and dimensional data being populated before dispatch begins.
• Google Maps / routing API — required for drive time estimation, real-time traffic (v2), and road restriction routing (v2).
• Public road restriction dataset (DOT / OpenStreetMap) — required for weight and height routing (v2).
• Public weather API — required for weather-adjusted routing (v2).
• Public fuel price API — required for per-mile cost estimation (v2).

19. Next Steps

• Share with Daria for wireframe exploration of Dispatch board UI changes (Section 11).
• Confirm in-progress task lock trigger (status tap vs. GPS proximity) with engineering.
• Confirm road restriction dataset source (DOT vs. OpenStreetMap) with engineering for v2 planning.
• Confirm AI vision model selection for trash photo analysis (v2) with engineering.
• Dev PRD to follow once wireframes are approved. Dev PRD will include routing algorithm spec, data schema, API contracts, and logging requirements for the v2 feedback loop.

---

Overall Rating *

Please select a rating.

What do you like most about this feature? *

This field is required.

What concerns you or needs more thought? *

This field is required.

Any additional comments? (optional)

Submit Feedback