# Architektura a flow

Aktualizováno: 2025-12-07

## Přehled
- Next.js 14 (App Router) + TypeScript.
- Datová vrstva: `lib/persistence` je jediný vstup do databáze (lokální Postgres přes `LOCAL_DATABASE_URL` nebo Supabase; dev fallback in-memory). Supabase je používán jen pro auth a synchronizaci.
- Synchronizace: `npm run sync:push` čte lokální DB (Pool) a upsertuje do Supabase pomocí service role.
- Pull sync: `npm run sync:pull` stáhne rooms/codes/room_messages ze Supabase (service role) a upsertne je do lokální DB – použij pro dorovnání nových zpráv z cloudu do lokální instance.
- Ad-hoc pull zpráv: při načtení zpráv (`getMessagesByRoom`) se při dostupné service role pokusíme stáhnout nové zprávy dané místnosti ze Supabase a upsertnout je do lokální DB, aby se příchozí cloudové zprávy propsaly i do lokálního úložiště.
- Offline klient: `lib/offlineStore` (IndexedDB) ukládá zprávy a pending frontu; `lib/messages` při výpadku sítě ukládá zprávy lokálně a po návratu online volá `/api/sync/push` k jejich uložení do persistence/Supabase.
- Session: anonymní session v HTTP-only cookie (`setAnonymousSession`); Supabase auth pro registrované uživatele.
- Logging: `lib/logger` zapisuje do lokální DB (`logs`), při nedostupnosti do Supabase service-role nebo konzole. Úroveň `LOG_LEVEL=all|light|mini|off`.
- Rate limiting: `lib/rateLimiter` (paměťový bucket) blokuje brute-force pro kódy/PIN (IP+device). Rozšiřitelné i na další endpoints.

## Datový model (shrnutí)
- Viz `docs/DATAMODEL.md` a SQL v `src/db/localSQLcreate.sql` / `src/db/supabaseSQLcreate.sql`.
- Tabulky: `users`, `rooms`, `codes`, `room_messages`, `logs`.

## Hlavní flow
### Zadání/ověření kódu
- `/api/codes/validate`: ověřuje kód (persistence), větví na setup/pin/room; rate-limit IP+device; ukládá/čte anonymní session hash; loguje `validate_*`.
- `/api/codes/setup`: pro nepoužitý kód vytvoří pár, místnost, označí used; ukládá PIN hash nebo session hash; loguje `setup`.
- `/api/codes/enter`: pro použitý kód zajistí linked code, případně založí room; označí used; loguje `enter`.
- `/api/codes/verify-pin`: ověří PIN, nastaví session, loguje `verify_pin_success`; rate-limit.
- `/api/users/transfer-code`: převede kód k přihlášenému uživateli, loguje `transfer_to_user`.

### Místnosti a chat
- `/api/rooms/[roomId]`: CRUD nad místností přes persistence (vč. vlastnictví přes kód.user_id); loguje get/update/delete.
- `/api/messages/[roomId]`: čte a ukládá zprávy přes persistence, aktualizuje `rooms.date_last_message`, loguje insert. Chat klient (`components/chat/ChatRoom`) používá tuto API a polling, bez přímého Supabase klienta.

### Kódy a páry
- `lib/codes.createCodePair` generuje dvojici a kontroluje unikátnost přes persistence (ne Supabase přímo).
- `persistence.getCodeWithLinked` vrací primární + spárovaný kód; `updateCodesRoomId` zapisuje room_id pro obě strany.

## Synchronizace a prostředí
- Lokální DB: `LOCAL_DATABASE_URL`; init `npm run db:local:init` (vytvoří i `logs`).
- Supabase: `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` (auth), `SUPABASE_SERVICE_ROLE_KEY` pro sync/log fallback.
- Sync: `src/lib/syncLocalToSupabase.ts` upsertuje rooms, codes, room_messages.
- Pull: `src/lib/syncSupabaseToLocal.ts` upsertuje rooms, codes, room_messages z cloudu do lokální DB; ad-hoc sync zpráv se volá z `getMessagesByRoom`.

## Logging a observabilita
- Úrovně: `all` (včetně UA+data), `light` (bez UA), `mini` (bez UA+data), `off`.
- Záznam: module, operation, data (JSON), error, ip, user_agent, lang, level.
- Tabulka `logs` v obou SQL skriptech; RLS v Supabase dovoluje pouze service role.

## Bezpečnost a limity
- Rate limiter pro kódy/PIN (3 pokusy/5 min/IP+device, 5min blok; po 3 blocích 24h). Doporučeno přidat i na login/register až budou implementované.
- Session hash: anonymní uživatelé dostávají dlouhou/krátkou expiraci dle PIN, uloženou v DB i cookie.

## Frontend
- App Router stránky v `src/app`; sdílené komponenty `src/components`.
- Chat běží přes API messages; UI layouty dle `doc/design` (viz `docs/GITHUB_INSTRUCTIONS.md`).