# wtr.

`wtr.` to mobilna PWA pogodowa dla Polski oparta o publiczne dane IMGW oraz jawnie oznaczoną prognozę modelową łączącą IMGW ALARO z Open-Meteo.

Aplikacja pokazuje bieżącą analizę IMGW Hybrid, pomiary synoptyczne, prognozę godzinową i 7-dniową, ostrzeżenia meteorologiczne i hydrologiczne, dane hydro oraz deterministyczne briefy pogodowe bez użycia zewnętrznego modelu AI.

## Najważniejsze funkcje

- Bieżące warunki z lokalnej analizy IMGW Hybrid, z opisanym fallbackiem do stacji synoptycznej.
- Prognoza modelowa 7 dni: IMGW ALARO dla dostępnych godzin oraz Open-Meteo jako uzupełnienie i fallback.
- Wyszukiwanie miejscowości w Polsce oraz opcjonalny wybór lokalizacji GPS.
- Ostrzeżenia IMGW z filtrowaniem meteo po powiecie TERYT, gdy lokalizacja go dostarcza.
- Powiadomienia Web Push o nowych ostrzeżeniach, porannym briefie dnia i wieczornym briefie na jutro.
- Widoki dashboardu, prognozy szczegółowej dnia, ostrzeżeń, hydro, stacji i ustawień.
- PWA z manifestem, własnym service workerem i podstawowym fallbackiem offline.
- Interfejs po polsku i angielsku.

## Stack

- Next.js App Router, React, TypeScript
- Tailwind CSS
- TanStack Query
- Zustand
- Framer Motion
- Recharts
- Lucide React
- `web-push`
- własny service worker i manifest PWA

## Szybki Start

Wymagany jest Node.js 20.9 lub nowszy.

```bash
npm install
npm run dev
```

Aplikacja będzie dostępna pod adresem `http://localhost:3000`.

## Konfiguracja

Do podstawowego uruchomienia aplikacji pogodowej nie są potrzebne klucze API. Publiczne dane IMGW, Open-Meteo i Nominatim są pobierane przez route handlery Next.js.

Powiadomienia Web Push wymagają zmiennych środowiskowych:

```bash
WEB_PUSH_VAPID_PUBLIC_KEY=
WEB_PUSH_VAPID_PRIVATE_KEY=
WEB_PUSH_VAPID_SUBJECT=mailto:admin@example.com
NOTIFICATIONS_CRON_SECRET=
WTR_APP_URL=http://127.0.0.1:3000
NOTIFICATIONS_WARNING_INTERVAL_MINUTES=5
NOTIFICATIONS_MORNING_BRIEF_TIME=07:00
NOTIFICATIONS_TOMORROW_BRIEF_TIME=18:00
```

Przykład znajduje się w [.env.example](.env.example).

## Komendy

| Komenda | Opis |
| --- | --- |
| `npm run dev` | Uruchamia serwer deweloperski Next.js. |
| `npm run lint` | Uruchamia ESLint. |
| `npm run typecheck` | Uruchamia `tsc --noEmit`. |
| `npm run build` | Buduje aplikację produkcyjnie i uruchamia kontrolę TypeScript wykonywaną przez Next.js. |
| `npm run start` | Uruchamia zbudowaną aplikację. |
| `npm run notifications:worker` | Uruchamia self-hostowany worker powiadomień. Wymaga działającej aplikacji Next.js. |

Repozytorium nie ma obecnie skryptu testów ani formattera.

## CI

Repozytorium używa Gitea Actions. Workflow znajduje się w [.gitea/workflows/ci.yml](.gitea/workflows/ci.yml) i uruchamia się przy pushu do `main` oraz przy pull requestach.

Pipeline działa na `ubuntu-latest`, instaluje zależności przez `npm ci`, a następnie uruchamia:

- `npm run lint`,
- `npm run typecheck`,
- `npm run build`.

Na instancji Gitea musi być włączony Actions runner kompatybilny z etykietą `ubuntu-latest`.

## Struktura Projektu

```text
app/          routing, layout, route handlery i strony
components/   komponenty widoków, UI, stanów, prognozy, hydro i ostrzeżeń
hooks/        hooki TanStack Query
lib/          fetchery, normalizacja danych, Web Push, i18n, store i helpery
types/        typy danych IMGW, prognozy, lokalizacji i powiadomień
public/       manifest, service worker i ikony PWA
scripts/      worker powiadomień dla self-hostingu
docs/         szczegółowa dokumentacja techniczna
```

## Dokumentacja

- [Architektura i przepływ danych](docs/architecture.md)
- [Wewnętrzne endpointy API](docs/api.md)
- [Źródła danych i cache](docs/data-sources.md)
- [Logika pogody i fallbacki](docs/weather-logic.md)
- [Powiadomienia Web Push](docs/notifications.md)
- [Wdrożenie i uruchamianie](docs/deployment.md)

## Status i Ograniczenia

- `lib/push-store.ts` przechowuje subskrypcje Web Push w pamięci procesu. Produkcyjne wdrożenie wymaga trwałego magazynu, np. bazy danych albo KV.
- Endpoint IMGW Hybrid używany przez dashboard pochodzi z publicznego frontendu `meteo.imgw.pl`, a nie ze stabilnie opisanej dokumentacji `danepubliczne.imgw.pl`.
- Publiczne API IMGW potrafi zwrócić `404` z komunikatem `No products were found` dla pustych list ostrzeżeń; aplikacja traktuje to jako brak ostrzeżeń.
- Prognoza jest prognozą modelową, nie pomiarem IMGW. Bieżące pomiary i prognozy są w UI rozdzielane.