WeatherFall

Main page
Admin console
Simulation running
Simulation ended
Architecture Diagram 1
Architecture Diagram 2
Architecture Diagram 3

Inspiration

When Hurricane Ian hit Florida in 2022, it wasn't the wind that killed people - it was the cascade. A substation floods, a hospital loses power, its backup generators run dry, and suddenly a facility that was never in the storm's path becomes a life-or-death emergency. We watched this pattern repeat across every major disaster: the real damage isn't the initial impact, it's the domino effect through interdependent infrastructure.

We asked ourselves: What if operators could see the cascade before it happens? What if an AI could reason about which facilities to save first, when to abandon a lost cause, and how to justify that decision ethically?

WeatherFall is our answer. It's a geospatial command center that simulates disaster cascades through Miami's critical infrastructure and uses a multi-agent AI system to make (and explain) triage decisions in real time.

What it does

WeatherFall is an interactive GIS-based simulation platform for critical infrastructure resilience. It combines:

🗺️ Live Geospatial Topology: An interactive Leaflet map of Miami's infrastructure grid (energy, water, health, transport, comms) with street-routed dependency edges.
🌪️ 13 Disaster Scenarios: From hurricanes and tsunamis to cyber-physical SCADA attacks and Carrington-class geomagnetic storms, each with 5 severity tiers (L1–L5) and custom magnitude overrides.
⚡ Discrete Event Simulation (DES): A priority-queue simulation that advances a global clock from event to event, modeling epicenter impacts, battery deadlines, and cascading failures with real physics.
🤖 Multi-Agent Crisis Committee: When a facility enters CRITICAL_BATTERY, four LLM-powered agents debate the recovery route in real time:
- Engineering_Agent optimizes for shortest street path and grid stability
- Social_Agent prioritizes Social Vulnerability Index (SVI) and population served
- Finance_Agent enforces strict knapsack budget and crew conservation
- Supervisor_Agent issues a binding verdict and dispatches the final recovery command
⏱️ Time-Aware Knapsack Optimization: The AI solves a constrained optimization problem: can a crew physically reach this node and finish repairs before its UPS battery dies? If not, it strategically abandons it to save resources for higher-impact nodes.
📊 Full Audit Trail: A live incident timeline, NetworkX topological integrity validator, and exportable PDF incident reports for post-disaster analysis.

How we built it

Backend:

FastAPI (async Python) as the API layer with JWT authentication and role-based access
PostgreSQL (Neon serverless) for persistent topology storage
Redis (Upstash) as the Celery broker and result backend
Celery for asynchronous simulation dispatch (with sync fallback for serverless deploys)
SQLAlchemy 2.0 with async ORM and connection pooling tuned for Neon's PgBouncer
NetworkX for topological integrity validation (cycle detection, lifeline orphan detection, capacity bottleneck analysis)
Groq API with openai/gpt-oss-20b for the multi-agent crisis committee deliberation
Overpass API proxy for live OpenStreetMap infrastructure imports

Frontend:

Vanilla JavaScript with Leaflet.js for the interactive GIS map
Custom SVG data-URI markers for sector-specific node badges
CSS-driven reactive "war room" volumetric lighting that shifts from cyan → amber → crimson based on cascade severity
Intro.js for the interactive onboarding tour
html2pdf.js for canvas-rendered PDF incident reports with vector topology snapshots

Infrastructure:

Docker + docker-compose for local and production orchestration
Traefik as reverse proxy with automatic Let's Encrypt SSL (production)
Render for API hosting, Neon for PostgreSQL, Upstash for Redis

Data Model:

Directed graph where nodes represent facilities (with sector, lat/lon, SVI score, population served) and edges represent physical street-routed dependencies with cost, crew requirements, and recovery time.

Challenges we ran into

Neon + asyncpg incompatibility. Neon's connection string includes sslmode=require, but asyncpg doesn't accept that parameter; it uses ssl instead. We had to write a URL parser that strips unsupported parameters and converts them to connect_args, plus add statement_cache_size=0 to work with Neon's PgBouncer pooler.
The "empty database" trap. Our app frontend served topology from a static file, but the admin console read from PostgreSQL. On first deploy, the admin console showed zero nodes because the database was genuinely empty, not because of a bug. Teaching ourselves to distinguish "connection failure" from "no data" from "auth failure" was a turning point in our debugging methodology.
Modeling realistic cascade physics. Getting battery deadlines, crew release timing, and downstream propagation right required careful design of the DES event queue. A node can't be "saved" if the crew physically can't arrive before its UPS dies. That constraint had to be enforced mathematically, not heuristically.
Making AI decisions auditable. It's easy to have an LLM say "save this node." It's hard to have it explain why, in terms a human operator would accept under pressure. We designed the multi-agent debate structure so every decision carries a traceable rationale.
Serverless constraints. Render's free tier doesn't support background workers, so we had to make Celery degrade gracefully to synchronous execution when running in constrained environments.

Accomplishments that we're proud of

A working multi-agent deliberation system where four LLM agents with genuinely different objectives (engineering, social equity, financial) debate and reach a binding verdict; not just generate text.
Ethical AI triage that explains itself. When the Social_Agent says "save this hospital because its SVI is 0.89 and it serves 45,000 residents," that reasoning is visible in the incident timeline and auditable in the PDF report.
A complete, deployable full-stack application running on free-tier infrastructure with zero cost: FastAPI + PostgreSQL + Redis + Celery + Leaflet, all orchestrated with Docker.
Topological integrity validation using NetworkX to detect circular deadlocks and lifeline orphans before simulation runs, with a failsafe that locks the Start Simulation button if the graph is broken.
A genuinely useful admin console with live OpenStreetMap search, one-click node import, auto-connect to nearest compatible facility, and interactive edge drawing.

What we learned

Distributed systems debugging is a skill. Learning to read a stack trace across SQLAlchemy → asyncpg → PostgreSQL → Neon's pooler taught us more about connection management than any tutorial could.
Async Python has sharp edges. The sync/async bridge in SQLAlchemy 2.0, greenlet-based concurrency, and driver-specific quirks (sslmode vs ssl, statement_cache_size) are all things you learn by breaking them.
LLM agents work best with constraints, not freedom. Giving each agent a specific role with specific priorities produced far better outputs than a single "solve this" prompt.
Ethics need to be encoded, not assumed. We didn't want the AI to just save the biggest node. We wanted it to weigh vulnerability, population, cost, and physical feasibility — and explain the tradeoff.
Free-tier infrastructure is real infrastructure. Render + Neon + Upstash gave us a production-grade stack with zero cost, once we understood their quirks.

What's next for WeatherFall

Multi-city expansion. The topology is currently Miami-specific, but the simulation engine is city-agnostic. Next: New York, Houston, San Juan, and any city with OpenStreetMap data.
Real-time IoT integration. Ingest live SCADA telemetry, smart meter data, and generator fuel levels to run simulations against actual grid state.
Reinforcement learning for triage policy. Replace the LLM debate with a trained RL policy that learns optimal triage from thousands of simulated cascades, then compare its decisions against the LLM committee's reasoning.
Mutual aid coordination. Model multi-jurisdictional resource sharing, so Broward County's crews can rescue Miami-Dade's grid and vice versa.
Public-facing resilience dashboards. Give residents visibility into their neighborhood's infrastructure vulnerability, because climate resilience shouldn't be a black box.
Offline-capable field mode. A PWA that field crews can use on tablets with no connectivity, syncing decisions when they reconnect.