docs: reorganize project documentation

docs/architecture.md

@@ -0,0 +1,71 @@
+# 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/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ń.
+- Prognoza modelowa jest opisana oddzielnie i nie jest przedstawiana jako pomiar IMGW.
+- Braki danych są pokazywane jawnie, bez generowania fikcyjnych wartości.