PolyWeather/README.md

# PolyWeather Pro

Production weather-intelligence stack for temperature settlement markets.

Official dashboard: [polyweather-pro.vercel.app](https://polyweather-pro.vercel.app/)

## Product Screenshots

### Global Dashboard

![PolyWeather global dashboard](docs/images/demo_map.png)

### City Analysis (Ankara)

![PolyWeather Ankara analysis](docs/images/demo_ankara.png)

## What This Project Does

- Aggregates weather observations and forecasts for monitored cities.
- Blends multi-model forecasts with DEB (Dynamic Error Balancing).
- Computes settlement-oriented probability buckets (mu-centered distribution).
- Maps model view to Polymarket read-only market data for mispricing/risk scan.
- Delivers the same core logic to web dashboard and Telegram bot.

## Overview Diagram

```mermaid
flowchart TD
    A["PolyWeather Pro"]

    subgraph DL["Data Layer"]
        DL1["METAR (Aviation Weather / METAR)"]
        DL2["MGM (Turkey MGM)"]
        DL3["Station 17130 (Ankara Center 17130)"]
        DL4["Open-Meteo"]
        DL5["weather.gov (US cities)"]
        DL6["Polymarket (P0 Read-only)"]
    end

    subgraph AL["Analysis Layer"]
        AL1["DEB (Dynamic Error Balancing)"]
        AL2["Probability Engine (mu + buckets)"]
        AL3["Trend Engine"]
        AL4["Risk Profiles"]
        AL5["Mispricing Radar"]
    end

    subgraph DEL["Delivery Layer"]
        DEL1["FastAPI"]
        DEL2["Next.js Dashboard"]
        DEL3["Telegram Bot"]
        DEL4["Alert Push"]
    end

    subgraph OL["Ops Layer"]
        OL1["Docker Compose (VPS backend + bot)"]
        OL2["Vercel (frontend)"]
        OL3["Cache + force_refresh"]
        OL4["Speed Insights"]
    end

    A --> DL
    A --> AL
    A --> DEL
    A --> OL
```

## Architecture

```mermaid
graph TD
    User[Web / Telegram User] --> FE[Next.js Frontend on Vercel]
    User --> Bot[Telegram Bot on VPS]
    FE --> API[FastAPI Service]
    Bot --> API

    API --> WX[Weather Data Collector]
    WX --> METAR[METAR / Aviation Weather]
    WX --> MGM[MGM API / nearby stations]
    WX --> OM[Open-Meteo]
    WX --> NWS[weather.gov]

    API --> DEB[DEB + Trend + Probability Engines]
    API --> PM[Polymarket Read-only Layer]
    PM --> Gamma[Gamma API]
    PM --> CLOB[CLOB / py-clob-client]
```

## Current Source Policy

| Domain              | Source Policy                                        |
| :------------------ | :--------------------------------------------------- |
| Primary observation | Aviation Weather / METAR                             |
| Ankara enhancement  | MGM + nearby stations, lead station fixed to `17130` |
| Forecast baseline   | Open-Meteo                                           |
| US official context | weather.gov                                          |
| Market layer        | Polymarket P0 read-only discovery + quotes           |
| Removed source      | Meteoblue (fully removed from code and docs)         |

## Recent Changes (2026-03-11)

- Removed all Meteoblue API integration and references.
- Fixed market top-bucket rendering path by deduplicating repeated temperature buckets.
- Added frontend fallback guard when market top buckets collapse to low-quality duplicates.
- Fixed detail panel accessibility issue (`aria-hidden` focus conflict) using `inert` + active-element blur.
- Added Vercel Speed Insights integration in `frontend/app/layout.tsx`.

## Repositories and Runtime Paths

- Frontend: `frontend/` (Next.js App Router)
- Backend API: `web/app.py` and `src/`
- Telegram runtime: `bot_listener.py` + `src/analysis/*`
- Docs: `docs/`

## Quick Start

### Backend + Bot (VPS / Docker)

```bash
docker compose up -d --build
```

### Frontend (local)

```bash
cd frontend
npm install
npm run dev
```

### Frontend production build check

```bash
cd frontend
npm run build
```

## Command Surface (Telegram)

| Command        | Purpose                       |
| :------------- | :---------------------------- |
| `/city <name>` | City real-time analysis       |
| `/deb <name>`  | DEB historical reconciliation |
| `/top`         | User leaderboard              |
| `/help`        | Help and command usage        |

## Documentation Index

- Chinese API guide: `docs/API_ZH.md`
- Commercial roadmap: `docs/COMMERCIALIZATION.md`
- Tech debt (EN): `docs/TECH_DEBT.md`
- Tech debt (ZH): `docs/TECH_DEBT_ZH.md`
- Chinese overview: `README_ZH.md`

## Status

- Version: `v1.3`
- Last Updated: `2026-03-11`
- Runtime: Stable (web + bot + market read-only layer in production)