Documentation

Storm Response Platform

The Storm Response Platform helps electrical storm teams track outages, separate real work into clear lists, dispatch technicians faster, and stay aligned during high-pressure operations. The design goal is simple: fast, reliable, low-friction use when crews are tired, mobile, and moving quickly.

Quickstart

To start using the platform during a storm event, office staff configure storm mode, field techs investigate dots, and dispatch uses the job queue for real work.

Office quickstart (5 steps)

• Log in with an office, admin, or owner account.
• Set Storm Phase (Phase 1, 2, or 3) and Temp-Out mode in Admin.
• Confirm data sources (Xcel / Connexus) are enabled.
• Monitor Job Queue and Opportunities as separate lists.
• Use Assign and Optimize Route when dispatching.

Field tech quickstart (4 steps)

• Log in as a field technician.
• Open Live Map and tap the nearest unvisited dot.
• Complete the investigation form (under 20 seconds when possible).
• If sold or actionable, the item moves to the correct downstream list automatically.

Roles & Access

Each role sees the parts of the system they need. Permissions are enforced on API routes and in the UI.

Core Workflow

The platform follows a simple operational loop designed for storm speed:

1. Outage dots load on the map from utility sources.
2. Techs investigate and tag each location.
3. Statuses update marker color, shape, and list placement.
4. Office dispatches confirmed jobs from the queue.
5. ETA and auto-arrival reduce manual status updates.

The Three Lists

Three separate lists prevent mixing hunting work with dispatch-ready jobs.

Outages

Raw map activity and unvisited storm dots. This is your hunting board during Phase 1.

Confirmed Opportunities

Damage confirmed and customer contact occurred, but the job is not sold yet. Used for follow-up and sales routing.

Job Queue

Dispatch-ready work only: call-ins, sold jobs, started jobs, temp power, grounding, and wants-to-proceed.

Field Investigation

The investigation form is optimized for speed on mobile devices. Techs pick one primary outcome first; additional fields appear only when needed.

Primary outcomes

• Utility Issue
• No Damage Found
• Opportunity Found

When Opportunity Found is selected

• Door Hanger Left (square marker on map)
• Job Sold (temp power submenu when applicable)
• Job Started (grounding submenu when applicable)
• Customer Thinking
• Customer Declined
• Verbal Price Quoted (stored for office follow-up)

Power status (opportunity flow)

• Has Power
• No Power — power on line drop
• No Power — no power on line drop
• Neighborhood Dead
• Honey Hole (multi-customer opportunity)

Map & Markers

Markers communicate status at a glance. Office users can hide completed or declined dots to reduce clutter.

• Color and shape indicate status (including square markers for door hangers).
• New utility dots can be highlighted when first seen.
• Stale dots can be faded for back-to-back storm visibility.
• Territory, priority, and exclusion zones can be drawn and applied.

Smart Queue Sort

The job queue supports multiple sort modes so dispatch can prioritize by score, distance, or customer value.

• Priority — highest operational score first.
• Distance — closest jobs first (when tech location is available).
• Value — higher customer impact first.
• Smart — balances score and travel distance.

Multi-Stop Routes

Multi-stop optimization builds an ordered route from the tech's current location and selected queue candidates.

In the Job Queue, click Optimize Route to generate a stop sequence with estimated miles and minutes. Use Go Next Stop to navigate to the first location in the plan.

POST /api/routing/multi-stop
Body: { origin: { lat, lng }, stops: [...], maxStops: 8 }

Cluster Routing

Cluster detection finds dense groups of nearby stops so teams can work one hotspot efficiently instead of driving between scattered dots.

Click Find Clusters in the Job Queue to see hotspot packs ranked by size and average priority, then navigate to the cluster center or top stop.

Auto-Dispatch Recommendations

When office clicks Assign on a queue item, the system recommends the best available technician before confirming dispatch.

The recommendation score considers:

• Distance to the job
• Territory fit (ZIP-based when configured)
• Current workload (open assigned jobs)
• Return-trip burden
• Overtime and load guardrails

The result banner shows score, shift hours, load, reasons, and backup alternatives.

POST /api/jobs/assign
Body: { jobId | outageId, targetLat, targetLng, confirm: false | true }

ETA & Auto-Arrival

While a tech is on shift, GPS heartbeats run every 30 seconds. The system calculates ETA for assigned jobs and can automatically mark arrival when the tech is within the threshold distance.

• Job status updates to in_progress on auto-arrival.
• A timestamped note is added to the job record.
• Linked outage status can update to job_started.

Storm Controls

Office and admin users control how the operation behaves during a storm.

Crew Guardrails

Dispatch guardrails are configurable in Admin under Dispatch Guardrails and used in assignment scoring.

Cleanup & Export

Between storms or during cleanup phases, office can reduce map clutter and export historical data.

Map cleanup actions

• Remove one marker from the active map.
• Sweep completed and declined statuses in bulk.
• Archive stale dots older than 48h or 72h.

Data storage & export

Primary storage is Supabase Postgres (outages, jobs, investigations, technicians, settings). CSV export is available for outages, jobs, and investigations via Admin or API.

Tech GPS Tracking

Technician locations refresh on a 30-second interval while the app is open. Map markers animate smoothly between positions so office can see near-live movement.

POST /api/techs        — update tech lat/lng (field heartbeat)
POST /api/jobs/eta     — ETA + auto-arrival check

SMS Notifications

Optional Twilio SMS alerts notify techs on dispatch assignment and notify office on auto-arrival.

API Endpoints

Key backend routes used by the platform. All authenticated routes require a Bearer token unless noted.

Platform Status

Current implementation status for storm season operations:

• Operational: streamlined investigation, three-list separation, map controls.
• Operational: routing v1, smart dispatch v2, GPS tracking, auto-arrival.
• Operational: storm phase, temp-out, guardrails, SMS hooks (when configured).
• Roadmap: deeper route optimization, expanded notifications, advanced scheduling.

Last updated: May 2026