Top Down View of Demo
Side View of Demo

Inspiration

Every evening, a utility field supervisor has to decide where tomorrow's crews can safely go. Can a heavy truck reach a substation without sinking into wet ground? Is a thunderstorm or flood warning coming? Do we stage ground mats, or postpone? Right now, that means handling weather apps, soil maps, spreadsheets and texts from crews. Sperry's challenge asked us to turn that into one clear plan and to be honest about what's real data and what's an estimate. GroundWork tells utility crews where tomorrow’s trucks can safely go, and never lets a good score hide a storm warning.

What it does

GroundWork ranks 300 real power-substation sites across the US (60 in Florida) and gives each one two separate calls:

Weather safety for everyone: a transparent 0–10 hazard score from forecast rain, wind gusts and heat, with official National Weather Service warnings (thunderstorm, tornado, hurricane, tropical storm, flash flood, flood) forcing STOP WORK no matter what. A warning can never be "averaged away" by good numbers.
Ground access per vehicle: recent rain, tomorrow's rain and USDA soil drainage decide GO, MATS or NO GO, separately for a pickup and a heavy truck. -**

On top of that:

Mat and cost planning: estimates how many ground mats a route needs and compares renting mats with postponing, showing every step of the math. Blank costs are flagged, never silently counted as $0.
Crew hazard reports: photo + text from a phone; supervisors confirm or reject them, and a reported lightning sighting triggers STOP WORK with a 30-minute all-clear rule.
Storm replay: replays Hurricane Milton (Oct 9, 2024) with the real archived NWS warnings, so judges can watch STOP WORK sweep across Florida while the rest of the country stays clear.
A physical site beacon: an Arduino Uno with a soil-moisture sensor beside a tray of dirt. Pour water and the site's access call changes on the dashboard and on the beacon's LCD. When a storm triggers STOP WORK, the beacon flashes red and buzzes until a crew member taps to acknowledge. The tap silences it but never clears STOP WORK.
The 6 PM briefing: a ranked plan for tomorrow, narrated in plain English by Gemini, with every number checked against our data.
An ML second opinion: a logistic-regression model trained on archived forecasts and real NWS warnings at all 300 sites, shown beside the rules but never making the safety call.

Missing or stale data always shows as UNKNOWN, never as safe.

How we built it

Backend: Python 3.12, FastAPI and Pydantic, 28 REST endpoints under /api/v1, layered into routers, services and repositories, with SQLite through SQLAlchemy. Strict request validation, one error format, JSON logs with request IDs, rate limiting, and a committed OpenAPI contract that the frontend generates its TypeScript types from.
Data: OpenStreetMap substations (Overpass API), Open-Meteo forecasts and archives, NWS alerts, USDA Soil Data Access, NIFC wildfire incidents, iNaturalist wildlife sightings, and the Iowa Environmental Mesonet NWS archive for historical warnings. Outside data is fetched by scripts into timestamped snapshot files, so the demo works offline and every number keeps its source and fetch time.
Decision engine: pure, unit-tested Python rules with labeled demo thresholds, published at /api/v1/policies.
ML: logistic regression (scikit-learn) trained on archived Open-Meteo forecasts labeled with real NWS warnings (Jul 2023–Jun 2025), tested on the next year it never saw (Jul 2025–Jun 2026): ROC AUC 0.85 vs 0.78 for our rule score. It runs in pure Python in the API.
Frontend: React 19, TypeScript, Vite, Tailwind, React Leaflet, TanStack Query and Recharts. Live and mock modes, a STOP WORK takeover screen, a Sensor Lab with a beacon replica, and a phone-friendly crew report flow. The site was also officially deployed on Render.
Hardware: Arduino Uno with Grove moisture, light, barometer, touch and button inputs, and an LCD, LEDs and buzzer, plus a Python serial bridge (pyserial + httpx) with a recorded-data fallback.
AI: Gemini writes the 6 PM briefing narrative from structured facts (every number is checked, with a template fallback). An n8n workflow emails the plan at 6 PM, and an MCP server lets Claude Desktop answer follow-up questions from the live API.
Auth: Auth0 token validation on the backend with crew and supervisor roles, a login button on the website, and MFA available via Auth0.
Testing: 207 backend tests, 40 hardware and deploy tests, and 206 frontend tests, including one file that maps each README acceptance item to the test that proves it.

Challenges we ran into

Four people, one codebase, 36 hours. We hit real merge conflicts, including conflict markers that got committed and briefly stopped the server. We learned to agree on a written API contract first, keep every change additive, and check for conflict markers before committing.
Keeping safety rules honest. It's tempting to average everything into one score. We deliberately kept alerts as overrides and weather separate from ground access, so good numbers can never hide a warning.
Historical data. The live NWS alerts API only shows active alerts, so replaying Hurricane Milton meant pulling real warnings from the Iowa Environmental Mesonet archive and matching them to each site.
Unreliable conditions. Venue Wi-Fi and hardware can fail mid-demo, so we built snapshots, recorded sensor replays and a one-click demo reset.
Windows vs. Mac. Line endings, npx, and Unix-only test modules all needed fixes or workarounds due to 3 Mac users and 1 Windows user working on this project.

Accomplishments that we're proud of

A physical demo where pouring water on dirt visibly changes a safety decision, end to end, within a few seconds.
STOP WORK that can't be argued away: not by a good score, a dry site, a beacon tap, or the AI.
Every number on screen is traceable to a source and a timestamp, and anything simulated is labeled.
An ML model evaluated properly (trained on past years, tested on a held-out year (Jul 2025–Jun 2026), compared against our own rules), and kept advisory because the rules did better on our Florida sites.
A strict, tested API contract that let four people build in parallel without breaking each other.

What we learned

Agreeing on the interface first is what makes parallel work possible.
In safety tools, "I don't know" must look different from "it's fine." That's why our website marks unkown values and does not automatically assign them a value of 0.
An honest, explainable rule often beats a black box, and an ML model is most useful as a second opinion you can measure.
Git workflow matters as much as code when a team moves fast.

What's next for Groundwork

Calibrate thresholds with real crews and safety officers, using records of stuck trucks and mat use.
A licensed lightning-strike feed instead of crew reports alone.
Satellite fire hotspots (NASA FIRMS) and smoke forecasts alongside NIFC incidents.
Hourly "safe work windows" instead of a single daily call.
PostgreSQL and scheduled data refreshes for a real fleet, plus the full Auth0 login flow in production.