Skip to content
KingReaper6940Public

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

☀️ Helios.ai

Extreme Weather Early-Warning Dashboard — SDG 13.1

Helios is an AI-powered early-warning dashboard that helps operations and safety teams see which locations in a city or university campus are at risk from upcoming extreme weather (heat, storms, flooding) — and what actions they should take.

"Every minute of advance warning saves lives."

Helios Dashboard License SDG 13.1


🎯 What It Does

Helios provides a real-time operational view of weather threats across monitored locations:

  • 🗺️ Interactive Map — Stamen Terrain tiles with risk-colored markers, analysis area boundaries, and click-to-inspect popups
  • 🚨 Smart Alerts — Severity-ranked alert cards (High / Moderate / Low) that update based on time horizon and city
  • 🧠 AI-Powered Reasoning — Click any alert to see a detailed modal explaining why the AI flagged it, how the prediction was made, and what to do about it
  • 🔬 3-Model Consensus — Every prediction is cross-referenced by 3 independent AI models (Helios, NOAA HRRR, ECMWF-IFS) with confidence scores
  • 📎 Source Verification — Clickable links to NWS, NOAA, USGS, and academic sources so humans can cross-verify every prediction
  • ⏱️ Time Horizon Toggle — Switch between Today, Tomorrow, and 3-Day outlooks to see how risk evolves
  • 🏙️ Multi-City Support — Switch between State College, Pittsburgh, and Philadelphia — each with unique locations, alerts, and analysis boundaries

🖼️ Screenshots

Dashboard — Alert View

The main dashboard showing the terrain map with risk markers and active weather alerts in the sidebar.

Alert Detail Modal

Clicking an alert opens a smooth animated modal with full AI reasoning, model consensus, predicted outcomes, recommended actions, and verification sources.


🏗️ Tech Stack

Layer Technology
Structure HTML5 (semantic, single-page)
Styling Vanilla CSS (custom design system with CSS variables)
Logic Vanilla JavaScript (ES Modules)
Mapping Leaflet.js with Stadia Stamen Terrain tiles
Fonts Inter via Google Fonts
Build None — zero build step, just open index.html

🚀 Getting Started

Quick Start

# Clone the repo
git clone https://github.com/KingReaper6940/Helios.ai.git
cd Helios.ai

# Serve locally (any static server works)
npx -y serve .
# or
python -m http.server 8080

Then open http://localhost:8080 in your browser.

Requirements

  • A modern web browser (Chrome, Firefox, Safari, Edge)
  • A local HTTP server (ES Modules require serving over HTTP, not file://)

Environment Variables

Helios now expects the OpenRouter key to live on the server, not in browser code.

Create a local .env only for Vercel/local function runtime use:

cp .env.example .env

Required variables:

OPENROUTER_API_KEY=your_openrouter_key
OPENROUTER_MODEL=google/gemini-3-flash-preview

Do not commit .env. The repo ignores it by default.

Deploying on Vercel

This project is a static dashboard plus one Vercel Function at api/openrouter.mjs, which securely proxies Gemini/OpenRouter requests.

  1. Import the repo into Vercel.
  2. In Project Settings -> Environment Variables, add:
    • OPENROUTER_API_KEY
    • OPENROUTER_MODEL (optional, defaults to google/gemini-3-flash-preview)
  3. Redeploy the project.

If the dashboard still shows mock data after deploy:

  • open https://your-deployment.vercel.app/api/openrouter in the browser and confirm it responds with 405 Method not allowed
  • if it returns a missing env error, the env var is not set in Vercel
  • after adding or changing env vars, redeploy so the function picks them up

Local Testing With Vercel Functions

If you want the AI features locally, use Vercel's local runtime instead of a plain static server:

npx vercel dev

That serves both the static files and the /api/openrouter function together.


📁 Project Structure

Helios.ai/
├── index.html                 # Main SPA entry point
├── css/
│   └── styles.css             # Complete design system (1400+ lines)
├── js/
│   ├── app.js                 # Orchestration — wires all modules together
│   ├── data.js                # Mock data — 3 cities × 3 time horizons
│   ├── map.js                 # Leaflet map with markers & boundaries
│   ├── alerts.js              # Alert card rendering & interactions
│   ├── modal.js               # Alert detail modal with AI reasoning
│   ├── details.js             # Location detail sidebar panel
│   └── timeline.js            # Upcoming timeline component
├── assets/
│   └── logo.svg               # Helios sun logo
├── Future_Implementations.md  # Roadmap to production
└── README.md

🧪 Demo Features

This is a prototype with live weather data support and AI reasoning routed through a server-side proxy. Here's what works:

Feature Status
Light ops-dashboard theme ✅ Working
Interactive map with terrain tiles ✅ Working
City switching (3 cities) ✅ Working
Time horizon toggle (Today/Tomorrow/3-Day) ✅ Working
Alert cards with severity ranking ✅ Working
Alert detail modal with AI reasoning ✅ Working
3-model consensus display ✅ Working (mock)
Source verification links ✅ Working (real URLs)
Loading states & animations ✅ Working
Per-city analysis area boundaries ✅ Working
Real-time weather API integration ✅ Working
Gemini/OpenRouter server-side proxy ✅ Working
Mobile app with push notifications 🔜 Future

🌍 SDG 13.1 — Climate Action

Helios directly supports UN Sustainable Development Goal 13.1:

"Strengthen resilience and adaptive capacity to climate-related hazards and natural disasters in all countries."

By providing earlier, more actionable weather warnings to campus operations teams, Helios aims to:

  • Reduce response times from hours to minutes
  • Increase warning coverage across vulnerable populations
  • Improve decision quality with AI-powered reasoning and multi-model consensus
  • Build trust through transparent, source-verified predictions

🛣️ Roadmap

See Future_Implementations.md for the full production roadmap, including:

  • Multi-model AI prediction engine
  • Real-time sensor integration (IoT weather stations, USGS stream gauges)
  • Mobile app with location-aware push notifications
  • Backend infrastructure (FastAPI, PostgreSQL + PostGIS)
  • Campus pilot deployment plan

👥 Team

Built for hackathon demonstration purposes.


📄 License

This project is open source under the MIT License.

About

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages