# Architektura i Przepływ Danych

`wtr.` jest aplikacją Next.js App Router z komponentami React, cache'owaniem przez TanStack Query i stanem preferencji w Zustand.

## Struktura

```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/         dokumentacja techniczna
```

## Routing

Najważniejsze widoki:

- `/` - dashboard pogody, wyszukiwarka lokalizacji, hero, prognoza, briefy i ostrzeżenia regionalne,
- `/warnings` - pełny widok ostrzeżeń meteo i hydro,
- `/hydro` - stacje hydrologiczne,
- `/settings` - język, motyw, lokalizacja powiadomień i Web Push,
- `/station/[id]` - szczegóły stacji,
- `/offline` - fallback offline.

## Przepływ Danych

1. Komponenty UI wywołują hooki z `hooks/`.
2. Hooki używają TanStack Query i fetcherów z `lib/`.
3. Fetchery pobierają dane przez route handlery w `app/api/`.
4. Route handlery walidują parametry, odpytują zewnętrzne usługi, ustawiają cache i normalizują błędy.
5. Moduły w `lib/` normalizują odpowiedzi do typów z `types/`.
6. Komponenty prezentują loading, error, retry oraz empty states.

## Stan Aplikacji

Zustand w `lib/store.ts` przechowuje trwałe preferencje użytkownika w `localStorage`, m.in.:

- ulubione stacje,
- wybraną stację albo lokalizację,
- ustawienia powiadomień,
- tryb wyboru województwa dla alertów.

Język interfejsu jest przechowywany osobno w `localStorage` pod kluczem `wtr:language`.

## PWA i Offline

Manifest znajduje się w `public/manifest.json`, a service worker w `public/sw.js`.

Service worker:

- cache'uje powłokę aplikacji,
- obsługuje fallback `/offline` dla nawigacji,
- cache'uje wybrane odpowiedzi API: `/api/imgw/*`, `/api/imgw-current`, `/api/current-weather`, `/api/forecast`,
- obsługuje zdarzenia `push` i kliknięcia w powiadomienia.

Rejestracja service workera działa w buildzie produkcyjnym.

## i18n

Interfejs jest dostępny po polsku i angielsku. Teksty są w `lib/i18n.tsx`. Nazwy stacji i oryginalne treści IMGW nie są automatycznie tłumaczone.

## Zasady Integracji

- Dane zewnętrzne przechodzą przez route handlery Next.js.
- IMGW pozostaje źródłem bieżących pomiarów, hydro i ostrzeżeń dla Polski.
- Poza Polską Open-Meteo jest źródłem modelowych bieżących warunków i prognozy.
- Prognoza modelowa jest opisana oddzielnie i nie jest przedstawiana jako pomiar IMGW ani oficjalny alert.
- Braki danych są pokazywane jawnie, bez generowania fikcyjnych wartości.