Architektura Aplikace Kosmo

Tento dokument popisuje navrhovaný technologický stack a high-level architekturu aplikace.

Technologický Stack: "Vibe Stack"

Zvolili jsme moderní, flexibilní stack zaměřený na rychlost vývoje, skvělé UX a snadnou škálovatelnost.

Frontend & Backend (Next.js)

Framework: Next.js 14+ (App Router)
- Důvod: Průmyslový standard, React server components, skvělý routing. Umožňuje psát backend (API routes) přímo v projektu.
Jazyk: TypeScript
- Důvod: Typová bezpečnost, autocomplete, prevence chyb.
UI/Styling: Tailwind CSS + Shadcn/ui + Framer Motion
- Důvod: Umožňuje vytvořit prémiový "Apple-like" design s animacemi.
PWA (Progressive Web App):
- Funkce: Možnost "Nainstalovat na plochu" na iOS/Android.
- Notifikace: Web Push API (přes Service Workers) pro nativní notifikace na mobilu i PC.
- Offline: Service Worker + IndexedDB queue pro práci bez signálu (fotky, docházka). Data se synchronizují při obnovení spojení.
i18n (Dvojjazyčnost): next-intl — CZ/EN od začátku (bilingvální třídy, expat rodiče).
Hosting: Vercel (optimální pro Next.js).
Package Manager: pnpm
- Důvod: Rychlost, efektivní správa disku, "industry standard" pro moderní web development.

Data & Auth (Supabase)

Databáze: PostgreSQL (Managed via Supabase)
- Region: EU Central (Frankfurt) — nutnost pro GDPR.
- Důvod: Relační data (žáci, třídy), ale s jednoduchým API. Podpora vektorového vyhledávání (pgvector) pro AI.
Auth: Supabase Auth (Bezpečné přihlašování bez hesel)
- Google OAuth:
  - Pro koho: Učitelé (školní účty), rodiče s Androidem / Google účtem.
  - Flow: Kliknu na "Přihlásit přes Google" → Vyberu účet → Jsem tam.
- Apple Sign In:
  - Pro koho: Rodiče s iPhonem (vyžadováno Apple pro App Store).
  - Flow: FaceID/TouchID → Jsem tam.
- Magic Link (Email):
  - Pro koho: Všichni ostatní (Seznam.cz, Centrum.cz).
  - Flow: Zadáte email → Přijde vám jednorázový odkaz → Kliknete → Jste tam.
  - Výhoda: Nikdo si nemusí pamatovat další heslo. Bezpečnější než "heslo123".
- Row Level Security (RLS): Zabezpečení dat přímo v DB (např. "Rodič vidí jen své dítě").
- Ověření Identity (Strategie):
  - BankID: Pro MVP zamítnuto (cena/složitost).
  - Trusted Device: Fyzické ověření rodiče ve škole (admin potvrdí is_identity_verified). Následná přihlášení (Google/Apple) jsou považována za důvěryhodná. Kritické akce vyžadují "re-confirmation" v UI.
Storage: Supabase Storage (primární)
- Supabase Storage: Hlavní úložiště pro všechny soubory — poznámky, media, přílohy. RLS z boxu, žádná extra infra. Škola ~80 žáků, ~10–20 GB/rok — Supabase Pro (100 GB) stačí na roky.
- GCP Cloud Storage: Odloženo. Původně plánováno jako primární (viz INTEGRATIONS.md), ale pro aktuální velikost školy nepřináší výhodu navíc. Případná migrace v budoucnu je straightforward.
Realtime: Supabase Realtime
- Důvod: Okamžité notifikace pro rodiče (chat, nové zprávy).

AI & LLM Orchestrace

Hlavní AI model: Gemini API (volané z Next.js přes Vercel AI SDK).
- Multimodalita: Gemini umí zpracovat Audio a Obrázky přímo.
- Voice Input: Rodič nahraje vzkaz → Gemini dostane audio blob → vrátí text a JSON akci ({ "action": "excuse_student", "date": "tomorrow" }).
LLM Orchestrace: n8n (self-hosted)
- Workflow engine pro AI agenty, zpracování emailů, cron joby.
- Nahrazuje jednoúčelové skripty a umožňuje vizuální správu workflow.
Specializované úlohy: Python Scripts / Microservice
- Pohoda: XML import/export (mServer).
- ŠkolaOnline: Jednosměrná synchronizace (Master data).
- Tooling: uv (rychlý Python package manager).
- Integrace: Může běžet jako Supabase Edge Function nebo samostatná služba.
Sofie (AI asistentka): Podrobnosti o AI komunikaci a konfiguraci viz SOFIE.md.

Integrace & Nástroje

CRM: Twenty (self-hosted)
- Evidence leadů/zájemců a rodičů.
- Microsoft SSO + SMTP konfigurace.
Project Management: Kosmo PM (vlastní kanban)
- Interní řízení školy — projekty, úkoly, deadliny.
Newsletter: Listmonk (Fáze 2+)
- Self-hosted email marketing, GDPR compliance.
ŠkolaOnline/Bakaláři (případně).

Feed — Hlavní obrazovka rodiče

Výchozí landing page rodiče je chronologický feed (à la Instagram) o jeho dětech a školních událostech. Ředitel a učitel si ponechávají klasický dashboard.

Proč Feed?

Rodič → dítě: Při vyzvedávání se dívám do appky a vím, na co se zeptat. "Tak jaký byl ten projekt o vesmíru?" místo "Co jste dělali?" → "Nevím."
Rodič → učitel: Vidím, že učitel fotí práce, eviduje → cítím hodnotu školy → důvěra.
Učitel → rodič: Učitel ví, že rodič reaguje → motivace evidovat.
Engagement loop: Appka žije, rodič se vrací, data pro AI rostou.

Struktura feedu

┌─────────────────────────────────┐
│ Souhrn od poslední návštěvy       │
│ "Od včera: 2 nové fotky,         │
│  Přítomna, Oběd č. 2"            │
├─────────────────────────────────┤
│ Evidence (14:30)                  │
│ [Fotka práce]                     │
│ "Anička — Projekt vesmír"         │
│ Přírodověda · Týmová práce        │
├─────────────────────────────────┤
│ Zpráva školy (12:00)             │
│ "Zítra nezapomeňte gumáky!"      │
├─────────────────────────────────┤
│ Jídelníček (11:00)               │
│ "Oběd: Kuřecí řízek, bramborová  │
│  kaše, salát"                     │
├─────────────────────────────────┤
│ Docházka (8:05)                  │
│ "Anička dorazila v 8:05"         │
└─────────────────────────────────┘

         [Sofie]  ← FAB overlay

Typy feed items

Typ	Zdroj	Příklad
Adaptivní souhrn	AI (pinned)	Souhrn od poslední návštěvy (auto-granularita)
Přehled zítřka	AI (od 14:00)	"Zítra: Škola do 13:30, plavání, přineste gumáky!"
Evidence/fotka	Učitel / Služba	Fotka práce + AI štítek
Docházka	Systém	"Dorazila v 8:05"
Družina	Vychovatel/ka	"Anička je v družině. Odchod: 15:30."
Kroužek	Systém / Lektor	"Dnes: Šachy 14:00" / "ZRUŠENO"
Zpráva školy	Ředitel / Učitel	"Zítra výlet — gumáky!"
Jídelníček	strava.cz (cron)	"Oběd č. 1: Řízek"
Akce / kalendář	Kalendář	"Za 3 dny: Třídní schůzka"
Odpověď na dotaz	Sofie / Učitel	"Odpověď na váš dotaz"
Platba (Fáze 2)	Pohoda (sync)	"Školné únor: zaplaceno" / "Splatnost: 15.2."

Multi-child

Rodič s více dětmi vidí prolínající se feed s avatarem/tagem dítěte. Filtr: "Zobrazit jen Aničku" / "Zobrazit jen Tomáše" / "Vše".

Sofie Overlay (FAB)

Plovoucí tlačítko vpravo dole (Floating Action Button).
Klik → otevře chat panel (slide-up nebo sidebar).
Vždy dostupný z jakékoliv obrazovky.
Badge s počtem nepřečtených zpráv.

Přehled zítřka (Tomorrow Preview)

Každý den od cca 14:00 se ve feedu objeví karta s přehledem následujícího dne: - Běžné položky: Rozvrh, konec školy, oběd, plánovaný odchod, kroužky. - Zvýrazněné výjimky: Výlet, plavání, "přineste si...", škola v přírodě. - Akce potřeba: Nepodepsané souhlasy, nezaplacené platby, chybějící dokumenty. - Generuje AI z rozvrhu, kalendáře a školních dat. - Push notifikace: "Sofie: Zítra plavání — nezapomeňte plavky!"

Adaptivní souhrn ("Od poslední návštěvy")

Systém trackuje last_seen_at timestamp pro každého rodiče.
Při otevření appky AI vygeneruje souhrn za období od last_seen_at:
- < 4 hodiny: Live stav
- 1 den: Včerejší souhrn (fotky, oběd, odchod)
- 1 týden: Týdenní souhrn → rozklikne po dnech
- 3+ týdny: Souhrn za delší období → po týdnech → dnech → detail
Zero config — rodič nemusí nastavovat frekvenci, vše automaticky.
Push re-engagement: Pokud se rodič nepřihlásí 3+ dny → push notifikace.

Skupinový chat / Komentáře — NE

Rozhodnutí: Ne. Reakce místo diskuze. Důvody: moderace, GDPR, scope creep, negativity bias. Pro volné diskuze mezi rodiči slouží WhatsApp komunity školy.

Funkce	Popis
Reakce	Rodič "lajkne" fotku práce dítěte. Učitel vidí počet reakcí → motivace.
Strukturované odpovědi	Škola: "Kdo jede na výlet?" → Tlačítka Ano/Ne.
Otázky → Sofie	Rodič má dotaz k oznámení? Zeptá se Sofie.
Privátní zpráva učiteli	Přes Sofii jako prostředníka nebo přímo učiteli.

Důsledky pro architekturu

work_items tabulka je primární zdroj dat pro feed items.
Nový koncept: feed_events view, který agreguje data z různých tabulek (evidence, docházka, družina, kroužky, zprávy) do jednoho chronologického streamu.

Messaging & Email: Walled Garden (no-reply)

Aplikace je jediný kanál pro komunikaci rodič ↔ škola. Emailové notifikace jsou "hluché" (noreply@) — nutí rodiče kliknout a odpovědět v aplikaci.

Rodič nepíše "paní učitelce", ale píše Sofii (AI Chatbot), která buď odpoví sama, nebo eskaluje.
Pokud někdo napíše email, učitel může odkázat na aplikaci.
Důsledek: Žádný "split-brain" (půlka v mailu, půlka v chatu). Pravda je v ticketu/konverzaci v aplikaci.

Hlavní Moduly (Aplikace)

1. `app/(platform)`

Hlavní aplikace pro přihlášené uživatele.
Rodič: Feed (scrollovací přehled dětí). Sofie chatbot jako FAB overlay.
Ředitel/Učitel: Dashboard s přehledy a akcemi.

2. `app/api`

Backend endpointy pro specifickou logiku, kterou nevyřeší přímé volání Supabase.
Evidence Ingestion (/api/evidence/ingest): Endpoint pro AI agenty a n8n workflow. Přijímá data, ukládá work_item jako Draft.

3. `structure` (Organizace školy)

Třídy (Triády), Ročníky, Uživatelé.
Správa rolí a vazeb (kdo koho učí, kdo je čí rodič).

4. `evidence` (Srdce systému)

Evidence prací žáků: Úkoly, projekty, testy, fotky.
Hodnocení: Známky, slovní hodnocení, kompetence.
AI Analýza: Automatické štítkování a návrhy hodnocení.

5. `attendance` (AI Action)

Docházka: Validace příchodů/odchodů.
Vyzvedávání: Chat-based správa ("Dnes vyzvedne babička").
Omluvenky: Konverzační zadávání omluvenek.

6. `surveys` (Interaktivní Chat)

Sběr Dat: "Chatové tlačítka" místo dlouhých formulářů.
Vyhodnocení: Real-time grafy pro vedení.

7. `communication` (Sofie Chat)

Sofie Bot: Hlavní rozhraní pro rodiče. RAG nad daty žáka + Knowledge Base školy.
Ticket System: AI routing, eskalace, safety check.
Podrobnosti viz SOFIE.md.

8. `components/ai`

UI komponenty pro interakci s AI (Chat, Generátor reportů).

9. `utils`

Excel Export: Knihovna xlsx nebo exceljs pro generování reportů.
Google Sheets Export: Využití googleapis pro vytváření tabulek přímo na Drive uživatele.
Date Formatting: date-fns pro práci s daty a časy.

Deployment & Workflow (CI/CD)

Doména: sofie.education

Local (Vývoj)
- Kde: localhost:3000
- Data: Lokální Supabase (Docker)
- Kdo: Vývojář
Staging (Testování)
- Kde: staging.sofie.education (Vercel Preview)
- Data: Supabase Staging Project (anonymizovaná data nebo testovací set)
- Kdo: Ředitel, vybraní učitelé (UAT testy)
Production (Ostrý provoz)
- Kde: app.sofie.education (Vercel Production)
- Data: Supabase Production Project (ostrá data)
- Kdo: Všichni uživatelé