# 🌡️ PolyWeather Pro

> **Professional Weather Intelligence System** — Specialized in edge data collection, DEB smart blending, and real-time decision alerts.

---

## 💎 Project Vision

PolyWeather is a specialized intelligence system built for **Polymarket** high-stakes participants. We aggregate top-tier meteorological sources, apply proprietary **DEB (Dynamic Error Balancing)** logic, and surface **actionable shift signals** at critical decision windows.

---

## 🏗️ Production Architecture

This project uses a decoupled production setup for reliability and iteration speed:

- **Frontend**: A **Next.js** dashboard on **Vercel** with React component rendering.
- **Backend API**: A **FastAPI** service on VPS for low-latency weather aggregation and analysis.
- **Bot & Alert Heartbeat**: A **Telegram Bot** on VPS for minute-level scanning and push alerts.

🔗 **Official Visit**: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)

---

## 🖼️ Preview & Interaction

<p align="center">
  <img src="docs/images/demo_ankara.png" alt="PolyWeather Demo - Ankara Live Analysis" width="450">
  <br>
  <em>📊 <b>Deep Query View</b>: DEB blended forecast + settlement probability + AI analysis context</em>
</p>

<p align="center">
  <img src="./docs/images/demo_map.png" alt="PolyWeather Web Map" width="850">
  <br>
  <em>🗺️ <b>Omni-Dashboard</b>: global station markers + nearby station context + right-side city intelligence panel</em>
</p>

---

## 🚀 Core Features

- **📡 Full-Spectrum Collection**
  - **Major Models**: ECMWF, GFS, ICON, GEM, JMA, Open-Meteo, and city-level daily/hourly guidance.
  - **Observed Data**: Aviation Weather / METAR as the primary observation source, plus Turkish MGM coverage for Ankara.
  - **City Specialization**: `17130` (`Ankara (Bölge/Center)`) remains the Ankara lead station without replacing LTAC settlement observation.
- **⚖️ DEB Smart Blending**
  - Dynamic weighting based on city-level performance and current model spread.
- **🧩 React Dashboard Runtime**
  - Typed store + typed API client + Leaflet/Chart.js lifecycle wrappers.
  - City click workflow: map focus + right panel open + nearby stations render.
  - Today analysis workflow: open modal + freeze map motion.
- **🔔 Alert Engine**
  - **Momentum Spike**: Captures rapid short-window temperature slope changes.
  - **Forecast Breakthrough**: Fires when observations break model envelopes plus margin.
  - **Advection Monitoring**: Tracks warm/cold advection using lead-station behavior and wind direction.

---

## 🔐 Alert Logic Details

| Trigger Name     | Core Logic                                    | Trading Value                                 |
| :--------------- | :-------------------------------------------- | :-------------------------------------------- |
| **Center Hit**   | Detects DEB trigger only at Ankara HQ `17130` | **Highest priority signal**, the "truth"      |
| **Momentum**     | 30min temperature slope exceed threshold      | Captures sudden weather fronts                |
| **Breakthrough** | Pierces all model highs + margin              | Captures high-volatility outlier events       |
| **Advection**    | Lead station rise + Wind match                | Gain 20-40 minutes of lead time for execution |

---

## 🧭 Current Data Logic

- **Primary observation source**: Aviation Weather / METAR
- **Ankara enhancement**:
  - Settlement observation: `LTAC / Esenboğa`
  - Official lead station: `Ankara (Bölge/Center)` / `17130`
  - Nearby station layer: Turkish MGM network (Ankara-specific preferred station ordering)
- **Other cities nearby layer**:
  - Production currently uses Aviation Weather METAR clusters
  - U.S. cities may later receive Mesonet augmentation while METAR stays baseline
- **Frontend request optimization**:
  - Initial map temperatures preload via `/api/city/{name}/summary`
  - City detail cache TTL = 5 minutes, revision probe avoids unnecessary refetch
  - Map movements, panel toggles, and modal open/close do not trigger redundant requests
  - Manual refresh always bypasses cache (`force_refresh=true`)

---

## 🏗️ System Architecture

```mermaid
graph TD
    subgraph "Client / Terminals"
        Web[Next.js React Web App]
        TG[Telegram Client]
    end

    subgraph "Edge Deployment (Vercel)"
        Web --> |BFF Routes| Fast[FastAPI API]
    end

    subgraph "Core Hub (VPS)"
        Fast --- |Shared Logic| Worker[Alert Engine / Worker]
        Bot[Telegram Bot] --- |Shared Logic| Worker
    end

    subgraph "External Sources"
        Worker --> |Pull| MGM[MGM Weather]
        Worker --> |Pull| METAR[Airport METAR]
        Worker --> |Pull| OM[Open-Meteo]
        Worker --> |Pull| MM[Multi-Model Integration]
    end

    Worker --> |Push Alert| TG
    Bot --> |Query| Worker
```

---

## 🛠️ Deployment

### 1. Backend / Bot (VPS)

```bash
# Pull source
git pull

# Environment
# Edit .env with TELEGRAM_BOT_TOKEN and other keys

# Launch
docker-compose up -d --build
```

### 2. Frontend (Vercel)

Set `frontend` as the Vercel root directory for automatic CI/CD.

---

## 💬 Bot Commands

| Command   | Description                             | Example        |
| :-------- | :-------------------------------------- | :------------- |
| `/city`   | Query real-time analysis for a city     | `/city ankara` |
| `/deb`    | View historical accuracy of DEB model   | `/deb london`  |
| `/top`    | View activity leaderboard               | `/top`         |
| `/help`   | Get detailed instructions               | `/help`        |

---

> [!NOTE]
> **Commercialization**: Current plans keep **Web Dashboard ($5/mo)** and **Telegram Signal Channel ($1/mo)** as the core entry offers.
> User entitlement and payment automation are tracked in `docs/COMMERCIALIZATION.md`.

> [!NOTE]
> **Frontend Model**: Production rendering is now fully handled by React components under `frontend/components/dashboard` and hooks under `frontend/hooks`.
> Legacy static files are retained for reference, but no longer act as the main runtime path.

---

---

**📅 Last Updated**: 2026-03-09
**🚀 Status**: v1.1 Stable - React Dashboard Runtime in Production

> [!TIP]
> **Production Note**: The UI layout and visual contract remain unchanged while data flow, map lifecycle, and modal interaction are now managed by typed React modules.