docs/ARCHITECTURE.md

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).