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

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, widoczność sekcji aplikacji i dashboardu, lokalizacja powiadomień i Web Push,
/station/[id] - szczegóły stacji,
/offline - fallback offline.

Przepływ Danych

Komponenty UI wywołują hooki z hooks/.
Hooki używają TanStack Query i fetcherów z lib/.
Fetchery pobierają dane przez route handlery w app/api/.
Route handlery walidują parametry, odpytują zewnętrzne usługi, ustawiają cache i normalizują błędy.
Moduły w lib/ normalizują odpowiedzi do typów z types/.
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,
widoczność opcjonalnych sekcji dashboardu,
widoczność opcjonalnych sekcji aplikacji w nawigacji.

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 i zapisuje udane nawigacje do cache,
cache'uje statyczne assety Next.js, style, skrypty, fonty, obrazy, manifest i ikony,
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.

3.0 KiB Raw Permalink Blame History