Kosmo: Digitální Ekosystém Sofie

Tato dokumentace popisuje kompletní digitální strategii a softwarový stack pro ZŠ a MŠ Sofie.

Co je součástí ekosystému?

Aplikace Kosmo (Custom Vývoj):
- Portál pro rodiče (Feed, docházka, evidence, omluvenky).
- Interní nástroje pro učitele (PM Kanban, portfolio).
- AI asistentka Sofie (chat, email CC, hlas).
CRM (Twenty):
- Správa leadů a zájemců o školu.
Back Office (SaaS + Self-hosted):
- Ekonomika (Pohoda).
- Matrika (ŠkolaOnline).
- Knowledge Base (BookStack).
- Newsletter (Listmonk — Fáze 2+).

Aplikace Kosmo (Core)

Kosmo je srdcem ekosystému. Je to "lepidlo", které spojuje data a lidi. Cílem projektu je vytvořit moderní, bezpečnou a AI-powered aplikaci, která sjednotí komunikaci, evidenci a procesy v Montessori škole Sofie (MŠ + ZŠ).

Klíčové vlastnosti

Feed: Rodič otevře appku a vidí, co dítě dnes dělalo — fotky, aktivity, docházka. Jako Instagram školy.
Sofie: AI asistentka, která odbavuje dotazy rodičů 24/7 a eskaluje na učitele jen to důležité.
Evidence: Digitalizace prací žáka — fotka → AI štítek → v feedu rodiče.
Bezpečnost: Google Auth, Apple Auth, Magic Links, Safety Gate pro vyzvedávání.

Struktura dokumentace

Dokument	Obsah
Vize	Kontext školy, problémy, vize
Uživatelé	Role, user stories, onboarding
Požadavky	Funkční a nefunkční požadavky
Architektura	Tech stack, moduly, Feed
Datový model	Schema, ER diagramy
Sofie	AI persona, orchestrace, KB
Integrace	Storage, kanály, externí systémy
MVP	Scope a fázování
Deployment	Infrastruktura, prostředí, zálohy, CI/CD, denní workflow
Backlog	Fáze 2+ funkce, PM modul detail
Dev Log	Aktuální stav features, rozhodnutí

Rychlý start

Pro vývojáře: viz CLAUDE.md v rootu repa, nebo: 1. supabase start — lokální databáze 2. cd web && pnpm dev — Next.js na localhost:3000

Vize projektu Kosmo

O škole

Název: Základní škola a Mateřská škola Sofie, s.r.o.
Místo: Říčany u Prahy
Typ: Soukromá Montessori škola (ZŠ + MŠ)
Velikost: ~80 žáků ZŠ, ~22 zaměstnanců
Stupně: MŠ (předškolní) + ZŠ 1. stupeň + přechod na 2. stupeň (aktuálně po 7. ročník)
Ředitel: Patrik Matlák
Web: sofie.education
Motto: „V dítěti leží osud budoucnosti."

Montessori filosofie

„Pomoz mi, abych to dokázal sám." Děti se učí vlastním tempem, volí si aktivity, rozvíjejí samostatnost.
Věkově smíšené třídy — starší děti přirozeně pomáhají mladším.
Bez zvonění, bez známek — flexibilní rozvrh, slovní hodnocení zaměřené na pokrok dítěte.
Bez soutěžení — důraz na vnitřní motivaci.
Kosmická výchova — propojování předmětů do smysluplného celku.
Připravené prostředí — třída navržena pro samostatnou práci s materiály.

Bilingvální výuka (CLIL)

Angličtina je integrovaná do běžné výuky (Content and Language Integrated Learning). Předměty v angličtině: tělesná výchova, matematika, kosmická výchova. Děti se učí angličtinu přirozeně, v kontextu reálných aktivit.

Struktura školy

Stupeň	Popis
MŠ	Předškolní vzdělávání, Montessori přístup. Systém Twigsee (mimo Kosmo).
ZŠ	1.–7. ročník, věkově smíšené třídy. Klíčové kompetence: k učení, řešení problémů, komunikativní, sociální, digitální.

Typické akce a zvyky

Výlety a exkurze navazující na probíraná témata
Projektové dny — děti volí témata, pracují napříč ročníky
Besídky a slavnosti, adaptační týden, kroužky
Škola v přírodě — vícedenní pobytové akce

Kontakty

Email školy: info@zs-sofie.cz
Ředitel: patrik.matlak@zs-sofie.cz
Doména: sofie.education (Cloudflare DNS)
Interní nástroje: wiki.sofie.education, ai.sofie.education

Problém k řešení

1. Komunikační propast

Rodiče se cítí v „vzduchoprázdnu". Nerozumí, co děti dělají — integrovaná výuka, žádné známky, děti „neví/neřeknou".

Řešení: Feed — rodič vidí fotky a aktivity dítěte v reálném čase. Před vyzvednutím už ví, na co se zeptat.

2. Přetížení školy

Komunikace je zmatená, na poslední chvíli. Učitelé jsou zavaleni administrativou, systémy spolu nemluví.

Řešení: Sofie (AI persona školy) odbaví rutinu — učitel se soustředí na učení.

3. Fragmentovaná data

Systém	Účel
ŠkolaOnline	Výkaznictví pro MŠMT
Pohoda	Účetnictví
strava.cz	Školní jídelna
Excel, Outlook, Word	Evidence žáků, komunikace

Vize: Feed + Sofie

Kosmo je „centrální mozek" školy. Dvě klíčové dimenze:

Feed — „Instagram pro školu". Personalizovaný proud fotek, aktivit a zpráv. Rodič vidí, co se děje, aniž by musel něco hledat.
Sofie — AI persona školy. Jeden vstupní bod pro všechny (chat, email, hlas). Zpracovává text, odpovídá z ověřené znalostní báze, sleduje úkoly, učí se.

AI First: Cíl je stát se „AI first" školou. Budoucí vize osobního AI průvodce (Sokratův průvodce) pro každého žáka.

Google Workspace

Aktuální stav

Dva uživatelé s admin právy: Tomáš (tomas@zs-sofie.cz) a ředitel Patrik (patrik.matlak@zs-sofie.cz)
Čeká se na schválení edukační licence Googlem (žádost podána koncem ledna 2026)

Skupiny

Skupina	Členové	Účel
`admin@zs-sofie.cz`	Tomáš, Patrik	Super admini, přístup ke GCP konzoli

Nástroje pro správu

GAM — hromadná správa Google Workspace přes CLI (nainstalován, čeká na autorizaci)
gcloud — CLI pro GCP (nainstalován)

Google Cloud Platform (GCP)

Přístup pouze pro admin@zs-sofie.cz (18+)
Projekt: sofie-education (ID: sofie-education, Number: 54897879776)
Region: europe-west1 (Belgie) — Tier 1, latence z Prahy ~20–25 ms, zóna europe-west1-b
Služby: Vertex AI / Gemini, Compute Engine (e2-small), Cloud Run, Workspace APIs

Všechny nové služby zakládejte v regionu europe-west1.

Migrace z Microsoft 365

Škola migruje z Microsoft 365 na Google (Gmail, Drive, Calendar).

Zdroj	Cíl	Strategie
OneDrive	Google Můj disk	Přímá migrace 1:1 per uživatel
SharePoint	Google Sdílené disky	Rozdělit do více disků s plošší strukturou
Hybridní provoz	Google Drive for Desktop	Virtuální disk, lokální Office + cloud editace

Domény

Existují zs-sofie.cz a ms-sofie.cz (někteří učitelé učí na obou stupních, některé rodiny mají děti v MŠ i ZŠ)
sofie.education — primární doména, DNS na Cloudflare
Interní nástroje na subdoménách, Kosmo na app.sofie.education

Komunikace školy

S rodiči: vřelé vykání — tónová varianta A „Soused, který má PhD"
Interně (mezi učiteli): tykání
Sofie: AI asistentka, tyká — je kolegyně, ne systém
Primární kanály: email, aplikace Kosmo

Sloučeno z CONTEXT.md a SCHOOL_PROFILE.md. Poslední aktualizace: březen 2026.

Uživatelé a Role

Tento dokument definuje role uživatelů, jejich potřeby a konkrétní požadavky (user stories) v rámci aplikace Kosmo.

Ředitel

"Chci mít přehled o škole, ne trávit den odpovídáním na emaily."

Potřeby: Přehled o chodu školy, efektivní administrativa, snadný přístup k datům pro rozhodování.

#	Požadavek	Popis	Status
D1	Dashboard školy	Kolik žáků dnes chybí, kolik ticketů čeká, kolik omluvenek přišlo — vše na jedné obrazovce.	MVP
D2	FAQ schvalování	Sofie předpřipraví odpověď, ředitel schválí → FAQ.	MVP
D3	Hromadné zprávy	"Oznámení pro všechny rodiče ZŠ" — přes Sofii s push notifikací.	MVP
D4	Přehled plateb	Kdo nezaplatil školné — přehled splatností, upomínky.	Fáze 2 (Pohoda)
D5	Statistiky AI	Kolik dotazů Sofie odbavila sama vs. eskalovala? Trend v čase.	K řešení
D6	Přehled učitelů	Kdo eviduje pravidelně? Kdo ne? (Podpora, ne "big brother".)	K řešení
D7	Inspekce-ready výstupy	ŠVP plnění, docházka, IVP — export pro Českou školní inspekci.	Fáze 2
D8	Spokojenost rodičů	Kvartální anketa + trend graf.	K řešení
D9	Schvalování consent	Hromadné souhlasy (výlet, fotky) — přehled kdo podepsal / kdo ne.	K řešení
D10	Plánování kapacit	Kolik žáků mám, kolik přihlášek? Pipeline z Twenty CRM.	Fáze 2

Učitelé (Průvodci)

"Chci učit, ne klikat v aplikaci."

Potřeby: - Snadná evidence prací a pokroků žáků (digitalizace). - Automatizovaná příprava metodických listů. - Jednoduchá komunikace s rodiči (generování zpráv o aktivitách a kompetencích). - Minimalizace administrativy ("Kliknout a hotovo").

#	Požadavek	Popis	Status
U1	Fotka → hotovo	Vyfotím práci → AI oštítkuje → publikuji. Max 3 kliknutí.	MVP
U2	Docházka jedním tapem	Ráno: seznam žáků, tapnu kdo chybí. Hotovo za 30 sekund.	MVP
U3	Přehled ticketů	Sofie mi přeposlala dotaz od rodiče — vidím ho, odpovím, zavřu.	MVP
U4	Plánování výuky	Co budu učit tento týden? Vazba na ŠVP/kompetence.	Fáze 2+
U5	Hromadné hodnocení	Slovní hodnocení pro celou třídu — AI navrhne draft z evidence, učitel upraví.	Fáze 2
U6	Offline fotky	Na výletě fotím bez signálu. Nahraje se později. (PWA Service Worker)	MVP
U7	Přehled třídy	Kdo dnes chybí, kdo má IVP, kdo odchází dříve — na jedné obrazovce.	K řešení
U8	Zpráva rodičům třídy	"Zítra potřebujeme gumáky" — hromadně, přes Sofii, s potvrzením přečtení.	K řešení
U9	Tablet mód	Učitel používá tablet ve třídě. UI musí být touch-friendly, velké tlačítka.	K řešení
U10	Služba žáků	Žák-služba fotí práce spolužáků. Učitel jen potvrdí.	MVP

Rodina (Zástupci dítěte)

"Chci vědět, co se děje ve škole, a nechci kvůli tomu nikomu volat."

Koncept: Rodič, prarodič, chůva. Může jich být libovolný počet.

Role Overlap: Rodič může být zároveň učitel nebo ředitel (aplikace zvládne více rolí u jednoho uživatele).

Přepínání rolí: Uživatel s více rolemi má v aplikaci možnost přepínat kontext (např. "Přepnout na: Rodič Aničky" ↔ "Přepnout na: Učitel"). Domovská obrazovka (Feed/Dashboard) a funkce se mění podle aktivní role.

Potřeby: - Pravidelné a srozumitelné informace o dětech. - Docházka a vyzvedávání: Nastavení časů odchodů, správa osob oprávněných vyzvedávat. - Omluvenky: Snadné omlouvání absence přímo v aplikaci. - Přístup k hodnocení a plánům.

#	Požadavek	Popis	Status
R1	Feed dítěte	Časová osa prací a fotek — to, co ukážu babičce. Scrollovací feed.	MVP
R2	Víc dětí najednou	Mám Aničku i Tomáše. Souhrn chci za obě děti, ne se přepínat.	MVP
R3	Kalendář akcí	Třídní schůzky, výlety, prázdniny — na jednom místě. Export do Google Calendar (`.ics`).	K řešení
R4	Přehled plateb	"Zaplatil jsem školné?" — rodič vidí stav ve feedu.	Fáze 2
R5	Profily učitelů	Fotka, jméno, co učí. Důležité pro nové rodiče a expaty.	K řešení
R6	Urgentní notifikace	Úraz/incident = HNED (push + možná SMS). Rozlišit urgentní vs. běžné.	MVP
R7	Co na zítra?	"Sofie, co má Anička zítra mít?" — AI z rozvrhu/plánu.	Nice-to-have
R8	Přehled absencí	"Letos chyběla 5 dní (3 omluvené)." — Graf, ne hledání v historii.	K řešení
R9	Přímá zpráva učiteli	Někdy nechci Sofii, chci napsat přímo třídní.	K řešení
R10	Consent management	"Souhlasíte s výletem?" — tlačítko místo papíru. S `audit_log`.	MVP
R11	Appka nesmí ztichnout	Pokud po týdnu nejsou fotky/souhrny, rodič ztratí důvěru → riziková mitigace.	K řešení

Administrativa (Kancelář)

"Chci, aby se věci dělaly samy, a ne abych je přepisovala z jednoho systému do druhého."

Potřeby: Automatizace rutinních úloh, správa žáků a zaměstnanců, integrace s externími systémy (ŠkolaOnline, Pohoda).

#	Požadavek	Popis	Status
A1	Správa profilů	Přidání rodiče, přiřazení k dítěti, ověření identity. Bulk import z CSV.	MVP
A2	Export do ŠkolaOnline	Omluvenky, docházka — aby se nemusely přepisovat.	MVP
A3	Knowledge Base správa	Nahrávání dokumentů na Google Drive do správné složky.	MVP
A4	Fakturace a platby	Generování faktur za školné → XML do Pohody. Přehled plateb, automatické upomínky.	Fáze 2
A5	Kontaktní údaje	Přehled všech rodičů s kontakty. Hromadný export.	K řešení
A6	Nástěnka kanceláře	Co dnes potřebuji udělat? Neschválené omluvenky, nepodepsané souhlasy.	K řešení
A7	Šablony dokumentů	Potvrzení o docházce, výpis z evidence — generované z dat v systému.	Fáze 2
A8	Správa školního roku	Nový rok = nové třídy, přeřazení žáků, archivace starého roku.	K řešení

Děti / Žáci (MŠ – 7. třída)

"Chci vidět svoje věci a nechci, aby to bylo nudné."

Role: - Běžný žák: Vidí své plány, nahrává práce (starší žáci), komunikuje s průvodcem. - Služba (Dítě): Digitalizuje práce celé třídy (focení, skenování) pro učitele.

Potřeby: - Extrémně jednoduché UI (zejména pro mladší děti). - Sokratův průvodce (Vize): AI společník, který pomáhá s učením, reaguje na fotky/zájmy i mimo školu. - Bezpečné prostředí (schválení rodiči).

#	Požadavek	Popis	Status
Z1	Moje portfolio	Všechny moje práce na jednom místě. Vidím svůj pokrok.	K řešení
Z2	Nahrávání prací	Starší žák si sám nahraje projekt (fotka, text).	MVP
Z3	Sokratův průvodce	AI kamarád — "Vyfotil jsem brouka" → AI navrhne projekt. (VIZE)	K řešení
Z4	Gamifikace?	Odznaky, streaky, úrovně? Kontroverzní v Montessori, ale motivační.	Otevřená otázka
Z5	Bezpečnost	Dítě nemůže chatovat s kýmkoliv. Vše moderováno. Rodič povoluje přístup.	K řešení
Z6	Jednoduchý login	Dítě nemá email. QR kód? PIN? Školní Google účet?	K řešení
Z7	Co mám dnes?	Rozvrh dne — co budu dělat, co potřebuji.	Nice-to-have
Z8	Zpětná vazba	Učitel napíše komentář k práci — žák ho vidí. Motivace.	K řešení

Onboarding rodičů

Flow

Přijetí dítěte — ředitel ručně založí profil rodiče, ověří totožnost (OP), zapíše email → is_identity_verified: true. Pro stávající rodiče: hromadný CSV import ze ŠkolaOnline.
První přihlášení — rodič obdrží email s pozvánkou, přihlásí se přes Google / Apple / Magic Link. Supabase Auth propojí auth.users s profiles přes email.
Guided Tour (Sofie) — po prvním přihlášení chat se Sofií: orientace v aplikaci, jak funguje Montessori, omluvenky, notifikace, jídelníček. Probíhá v jazyce rodiče (preferred_language).

Předpoklady

Každý rodič má smartphone + email.
Magic Link pokrývá rodiče bez Google/Apple účtu.
CRM pro zájemce (leads): Twenty.

Poznámka: Tento dokument je living document. Body se budou přesouvat do Požadavky a Datový Model jakmile budou schváleny pro konkrétní fázi.

Požadavky (REQUIREMENTS.md)

Tento dokument obsahuje funkční a nefunkční požadavky na aplikaci Kosmo.

[!IMPORTANT] MVP scope: Pouze ZŠ (1.-7. třída). MŠ bude řešena v pozdější fázi — jiný workflow, jiné kompetence, jiný denní souhrn.

Funkční požadavky

1. Komunikace s Rodiči (Sofie) — PRIORITA Č. 1

Cíl: "Odbavit" rodiče okamžitě (24/7), nezatěžovat učitele rutinou.
Detailní popis viz SOFIE.md.
Koncept:
- Rodič komunikuje s chatbotem "Sofie".
- Sofie má kontext: zná rozvrh, jídelníček, akce, manuály.
- Triage (Třídění):
  1. Okamžitá odpověď: "Co má mít na školu v přírodě?" → Sofie pošle seznam (RAG).
  2. Akce: "Omlouvám Aničku." → Sofie zapíše do DB a notifikuje učitele.
  3. Eskalace: "Máme problém..." → Sofie vytvoří Ticket a předá ho řediteli/učiteli.
- Hlasový vstup (Voice Mode):
  - Rodič může zprávu rovnou namluvit (na mobilu podrží tlačítko).
  - "Sofie, omluv Aničku na zítra, má kašel." → AI zpracuje audio přímo.
Funkce:
- Automatické pravidelné zprávy: Co se děti učily (generováno z Evidence, zobrazeno ve Feedu).
- Kalendář a Připomínky: Automatické notifikace.

2. Evidence a Hodnocení Žáků — PRIORITA Č. 2

Cíl: Digitalizace prací s minimálním úsilím.
Architektura úložiště: Viz Úložiště souborů v INTEGRATIONS.md.
Funkce:
- Role "Služba": Dítě nebo učitel rychle nafotí/naskenuje práce celé třídy.
- Individuální nahrávání: Žák (starší) si nahrává své projekty.
- API First: Evidence musí jít vytvořit strojově (např. AI agentem z emailu, z n8n).
  - Use Case: Učitel pošle fotku na evidence@sofie.education → AI vytvoří draft, oštítkuje a připraví ke schválení.
- Štítkování: Vazba na kompetence a předměty (ideálně automatizovaně pomocí AI).
- Dopad: Každá naevidovaná práce se automaticky objeví ve Feedu rodiče.

3. Integrace se ŠkolaOnline — PRIORITA Č. 3

Cíl: Odlehčení administrativy (jedna pravda o žácích).
Funkce:
- Synchronizace databází žáků a rodičů.
- Přenášení absencí/kompetencí (pokud relevantní).

4. Docházka a Vyzvedávání (AI Action)

Cíl: Bezpečnost dětí a přehled pro školu.
Funkce (Chat Interface):
- Vyzvedávání: "Dnes vyzvedne babička." → Sofie to založí a dá vědět učiteli.
- Bezpečnostní Pojistka (Safety Gate):
  - AI nikdy neprovede akci "tiše".
  - Vždy vrátí Potvrzovací kartu: "Chápu správně, že dnes (9.2.) vyzvedne Aničku paní Marie Nováková?"
  - Rodič musí kliknout na [Potvrzuji a přebírám odpovědnost].
  - Teprve poté se vytvoří záznam.
- Omluvenky: "Anička je nemocná." → Sofie se doptá na detaily (od-do) a vytvoří omluvenku.
- Validace: Učitel na tabletu vidí "Dnes: Babička Nováková (tel: 777...)" a jen potvrdí předání.
- Zjednodušení: Není třeba spravovat "seznam oprávněných osob" v DB rodičem složitě. Rodič to napíše do chatu, AI to vytáhne.
Družina (Odpolední provoz):
- Rodič ve feedu vidí: "Anička je v družině. Plánovaný odchod: 15:30."
- Vyzvedávání z družiny = stejný Safety Gate jako ze školy.
- Vychovatel/ka družiny zadává docházku a aktivity (jako učitel).
Kroužky:
- Rozvrh kroužků v kalendáři (úterý šachy 14:00-15:00).
- Přihlašování na kroužky (anketa / formulář).
- Notifikace při zrušení kroužku: "Kroužek šachů ZRUŠEN — nemoc lektora."
- Feed item: "Anička dnes na kroužku šachů."

5. Ankety a Sběr Dat (Interaktivní Chat)

Cíl: Rychlé rozhodování.
Funkce:
- Rychlé otázky: Sofie se v chatu zeptá: "Máte zájem o kroužek šachů?"
- Odpověď: Rodič klikne na vygenerovaná tlačítka (Ano / Ne / Více info).
- Výhoda: Vypadá to jako konverzace, ne jako "úřední deska".
- Dashboard: Ředitel vidí graf výsledků hned.

6. Sokratův Průvodce — Fáze 4+

Cíl: Osobní AI průvodce pro každého žáka.
Funkce:
- Pomoc s učením ve škole i doma.
- Reakce na fotky a zájmy žáka ("Vyfotil jsem brouka" → AI navrhne projekt).
- Bezpečné prostředí (moderováno, schváleno rodiči).

7. Podpora Rodičů — Fáze 4+

Cíl: Pomoci rodičům rozvíjet dítě doma v souladu se školou.
Funkce:
- Tipy na aktivity: "Ve škole probíráme zlomky, zkuste doma krájet pizzu."
- Knihovna materiálů: Odkazy na Montessori pomůcky/literaturu.

8. Export Dat (Excellence)

Cíl: Podpora administrativy a reportingu.
Funkce:
- Export do Excelu: Tlačítko "Stáhnout .xlsx" u všech tabulek (Seznam žáků, Docházka, Ankety).
- Export do Google Sheets: Tlačítko "Otevřít v Google Sheets" (vytvoří nový list na Drive).
- Export do PDF: Tlačítko "Stáhnout PDF" u všech tabulek (Seznam žáků, Docházka, Ankety).
- Export do CSV: Tlačítko "Stáhnout CSV" u všech tabulek (Seznam žáků, Docházka, Ankety). Pokud je relevantní, tak formát pro ŠkolaOnline.
- Struktura: Čitelná pro člověka i stroje (žádné sloučené buňky).

Nástroj: Listmonk (self-hosted newsletter).
Status: Odloženo na Fázi 2. MVP focus = Chat + Evidence + Docházka.

10. Generování Metodických Listů — Fáze 2

Pipeline: Sofie chat → n8n → Typst → PDF.
Viz BACKLOG.md.

11. Integrace

Viz dedikovaný dokument: Integrace (úložiště souborů, channel adapters, Pohoda, ŠkolaOnline, Google, Strava.cz, CLIL).

12. Notifikace a Upozornění

Cíl: Dostatečně informovat, ale neobtěžovat ("Signal, not Noise").
Kanály:
- Email: Pro kritické věci (Faktura, Reset hesla, Urgentní zpráva ředitele). Walled Garden policy — no-reply emaily, odpovědi směřují zpět do aplikace.
- Push Notifikace: Pro web/mobil (Nový příspěvek v evidenci, Zpráva v chatu).
Nastavení: Uživatel si může vybrat, co chce dostávat (např. vypnout upozornění na obědy).

13. Feed (Killer Feature)

Cíl: "Proč si nainstalujete appku? Protože pokaždé, když ji otevřete, víte, co se děje."
Dopad: Souhrn je pinnutá karta v Feedu — hlavní důvod otevřít appku.
Adaptivní souhrn ("Od poslední návštěvy"):
- Systém trackuje last_seen_at pro každého rodiče.
- Při otevření appky AI vygeneruje souhrn za období od poslední návštěvy:
  - < 4 hodiny: "Právě probíhá: Matematika — zlomky. Od rána: dorazila 8:05, 1 nová fotka."
  - 1 den: "Včera: 2 nové práce, oběd č. 2, odchod 15:30."
  - 1 týden: "Minulý týden: 5 prací, docházka 100 %, výlet na Šumavu (fotky)."
  - 3+ týdny: "Za 3 týdny: 12 prací, 3 omluvenky, docházka 92 %." → po týdnech → dnech → detail.
- Zero config — rodič nemusí nic nastavovat, vše automaticky.
Push re-engagement: Pokud se rodič nepřihlásí 3+ dny → "Anička měla zajímavý týden — mrkněte se!"
Přehled zítřka: Každý den od ~14:00 karta s rozvrhem, obědem, kroužky + zvýrazněné výjimky. Viz Feed v ARCHITECTURE.md.
Drill-down navigace (ve 2 osách):
- Časová: Souhrn → Týden → Den → Detail (granularita dle období).
- Tematická: Souhrn → Detail kategorie (Fotky / Evidence / Docházka / Komunikace).
Pro ředitele: "Dnes chyběli 3 žáci, Sofie odbavila 15 dotazů, 2 tickety čekají."
Generováno AI: Sofie automaticky sestaví z dat v DB (evidence, docházka, tickety).
Personalizovaný styl (nastavitelný rodičem):
- Příběh: "Anička dnes pracovala na projektu o vesmíru..." (narativní, emoční).
- Odrážky: "Matematika: zlomky. Čtení: 20 min. Oběd: č. 2. Odchod: 15:30." (strohé, faktické).
- AI si pamatuje preferenci a generuje souhrn v odpovídajícím tónu.

Nefunkční požadavky

UX/UI: Maximální jednoduchost ("Apple-like"). Učitel nesmí trávit čas klikáním.
AI: Využití Gemini API.
Dostupnost: Webová aplikace (responzivní pro mobily/tablety).
Bezpečnost: Ochrana osobních údajů dětí (GDPR). Data musí být uložena v EU (Supabase Frankfurt).
IVP: Individuální vzdělávací plány se ukládají jako work_item (source: 'ivp') + soubory v GCP Cloud Storage. Separátní tabulku řešit až bude jasný workflow.
Fallback (odpůrci appky): Rodič, který odmítá technologii → telefonát kanceláři, učitel zadá za rodiče. Kritické akce (omluvenky, vyzvedávání) musí jít přes appku — škola toto definuje jako minimum.

Měřitelné cíle (KPI)

Adopce

80 % rodičů s aktivním účtem do 1 měsíce od spuštění.
90 % omluvenek zadáno přes appku do 3 měsíců.

Efektivita AI

70 %+ dotazů odbaveno Sofií bez eskalace.
Snížení emailů řediteli o 50 % do 6 měsíců.

Spokojenost

Pravidelný sběr zpětné vazby od rodičů (kvartálně):
- "Co vás trápí? Co byste chtěli zlepšit? Jak hodnotíte? Co se vám líbí?"
- Realizováno přes ankety v appce (Sofie se zeptá).
Dashboard pro ředitele: Vyhodnocení spokojenosti v čase (trendy, grafy).

Architektura

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é

Datový Model (Supabase / PostgreSQL)

Tento dokument popisuje databázové schéma aplikace Kosmo. Primární design dokument — SQL komentáře jsou zapsané i přímo v migračních skriptech.

1. Uživatelé a Role

ER Diagram: Evidence žáků a uživatelů

erDiagram
    classes ||--o{ students : "obsahuje"
    students ||--o{ student_guardians : "má zástupce"
    profiles ||--o{ student_guardians : "je zástupcem"

    profiles {
        uuid id PK "Odkazuje na Supabase Auth ID"
        text first_name
        text last_name
        text email
        text phone_number
        text avatar_url
        array roles "admin, teacher, parent, student"
        enum preferred_language "cs, en (default: cs)"
        enum summary_style "narrative, bullets"
        boolean is_identity_verified
        timestamp identity_verified_at
        uuid identity_verified_by FK
        timestamp created_at
    }

    students {
        uuid id PK
        text first_name
        text last_name
        date date_of_birth
        uuid class_id FK
        text health_notes "alergie, diety"
        text special_needs "podklady pro SVP"
        text variable_symbol "YYNNN — identifikátor pro platby"
        enum status "active, graduated, transferred..."
        date enrollment_date
        date end_date
        text notes "interní poznámky"
    }

    student_guardians {
        uuid id PK
        uuid student_id FK
        uuid guardian_id FK
        enum relationship "mother, father, grandparent, other"
        boolean is_primary_contact
        boolean can_pickup "oprávněn vyzvedávat"
        boolean is_legal_guardian "zákonný zástupce"
    }

    classes {
        uuid id PK
        text name "např. Hvězdáři"
        text grade_level "např. 1-3"
        uuid lead_teacher_id FK
    }

Popis entit

profiles: Rozšíření nativní Supabase auth.users tabulky. Profil uživatele v Kosmo aplikaci — jméno, e-mail, funkční kontakty, preference jazyka a AI souhrnu.
students: Informace o jednom konkrétním žákovi sdílené bez ohledu na zastupování (zdravotní kód, pojišťovna, RČ, zdravotní omezení, specifické vzdělávání atp.). Citlivá data — RLS: pouze Admin/Ředitel.
student_guardians: Vazební M:N tabulka. Jednomu guardian přiřadíme např. dvě děti. Udržujeme vztah (matka, otec, babička), oprávnění k vyzvedávání a kontaktní prioritu.
classes: Seznam tříd/triád. Žák do třídy nastoupí a posouvá se.

Školní roky

school_years
- id: UUID
- name: Text (např. "2025/2026")
- is_active: Boolean
students_classes (Vazba Žák ↔ Třída ↔ Školní rok)
- student_id: UUID (FK → profiles.id)
- class_id: UUID (FK → classes.id)
- school_year_id: UUID (FK → school_years.id)

2. Docházka a Omluvenky

attendance_records (Denní docházka)
- id: UUID
- student_id: UUID (FK)
- date: Date
- status: Enum ('present', 'absent', 'excused', 'late')
- arrival_time: Time
- departure_time: Time
- pickup_person_name: Text (kdo vyzvedl, pokud to nebyl defaultní rodič)
attendance_plans (Plán odchodů)
- id: UUID
- student_id: UUID (FK)
- day_of_week: Int (0-6)
- regular_departure_time: Time
- type: Enum ('regular', 'exception')
- valid_from: Date
- valid_to: Date
excuse_notes (Omluvenky)
- id: UUID
- student_id: UUID (FK)
- author_id: UUID (FK → rodič)
- content: Text
- from_date: Date
- to_date: Date
- reason: Text
- status: Enum ('pending', 'approved', 'rejected')

Poznámka: Tabulka pickup_persons byla odstraněna. V modelu Sofie Chat rodič sdělí vyzvedávající osobu v chatu, AI extrahuje údaje a uloží je do attendance_records.pickup_person_name. Historická data jsou dohledatelná z communication_threads.

Fáze 2: Tabulky activities (kroužky/akce), activity_enrollments (přihlášky na kroužky), consents (definice souhlasů) a student_consents (podpisy souhlasů) jsou odloženy do Fáze 2.

3. Evidence Práce

ER Diagram: Soubory a AI zpracování

erDiagram
    students ||--o{ student_files : "má soubory"
    students ||--o{ competency_records : "má záznamy kompetencí"
    students ||--o{ ai_processing_runs : "má AI zpracování"

    student_files {
        uuid id PK
        uuid student_id FK
        text file_name "čitelný název souboru"
        text storage_path "plná cesta v GCS"
        text folder "evidence | portfolio"
        text type "document | work | assessment"
        text document_type "smlouva, rodny_list... (jen pro evidence)"
        text subject "předmět (jen pro portfolio)"
        timestamptz uploaded_at
        timestamptz created_at
    }

    competency_records {
        uuid id PK
        uuid student_id FK
        text competency_code "RVP nebo vlastní kód školy"
        text competency_name "Sčítání zlomků"
        text subject_area "Matematika"
        text evidence_source "assessment | work | teacher_manual"
        text source_file "název souboru v bucketu"
        text level "zvládá samostatně | s podporou | rozvíjí se"
        date observed_at
        text school_year "2025/2026"
        boolean ai_generated
        boolean teacher_confirmed
        text processing_model "gemini-2.0-flash"
        timestamptz processing_date
        timestamptz created_at
    }

    ai_processing_runs {
        uuid id PK
        uuid student_id FK
        text run_type "single_file | full_portfolio"
        text model_used "gemini-2.0-flash"
        timestamptz started_at
        timestamptz completed_at
        int files_processed
        int records_generated
        text status "running | completed | failed"
        text error_message
    }

Popis entit — soubory a AI

student_files: Lightweight cache/index souborů uložených v GCP Cloud Storage. Slouží pro rychlý listing v UI bez nutnosti volat GCS API. Regenerovatelné z manifest.json v bucketu. Zdrojem pravdy je bucket (gs://sofie-media/), ne databáze.
competency_records: AI-extrahované záznamy kompetencí žáka. Plněné z Gemini Vision analýzy fotek prací a scanů, nebo ručně učitelem. Centrální tabulka pro budoucí AI metodické listy. Pole processing_model a processing_date umožňují tracking modelu pro případný re-processing.
ai_processing_runs: Audit log AI zpracování. Každý běh (upload jednoho souboru nebo re-processing celého portfolia) vytvoří záznam. Slouží pro debugging, monitoring nákladů a plánování re-processingu.

Předměty a kompetence

subjects (Předměty)
- id: UUID
- name: Text
- color: Text
competencies (Kompetence)
- id: UUID
- subject_id: UUID (FK → subjects.id)
- name: Text
- description: Text

Evidence prací (work_items)

work_items (Práce / důkazy)
- id: UUID
- student_id: UUID (FK)
- created_by: UUID (FK, nebo NULL pro AI agenta)
- title: Text
- description: Text (Markdown)
- content: JSONB (strukturovaný obsah: textové bloky, URL na fotky/soubory, audio poznámky)
- source: Enum ('upload', 'email', 'api_agent', 'manual')
- external_reference_id: Text (např. Message-ID emailu)
- status: Enum ('draft', 'pending_approval', 'published', 'archived')
- ai_metadata: JSONB (analýza od Gemini: navržené kompetence, sentiment, klíčová slova)
- teacher_feedback: Text
- created_at: Timestamp
- published_at: Timestamp
- visibility: Enum ('private', 'teacher', 'parent', 'public')
work_item_tags (Štítky na pracích — kompetence)
- work_item_id: UUID (FK)
- competence_id: UUID (FK)
- confidence_score: Float (0.0–1.0, pokud navrženo AI)
- is_approved: Boolean (potvrzeno učitelem)

4. Komunikace (Sofie Chat)

communication_threads (Konverzace / Tickety)
- id: UUID
- student_id: UUID (FK, nullable — obecné dotazy nemají žáka)
- category: Enum ('obecne', 'omluvenka', 'zdravi', 'vyuka', 'incident', 'survey')
- status: Enum ('open', 'ai_resolved', 'teacher_review', 'closed')
- assigned_to: UUID (FK, nullable — pokud řeší AI)
- created_at: Timestamp
- updated_at: Timestamp
messages (Zprávy ve vlákně)
- id: UUID
- thread_id: UUID (FK → communication_threads.id)
- sender_id: UUID (FK, nebo NULL pro AI bota)
- content: Text (Markdown)
- is_internal: Boolean (poznámky učitelů, rodič nevidí)
- ai_metadata: JSONB (analýza sentimentu, navržené odpovědi)
- created_at: Timestamp

5. Ankety a Sběr Dat

surveys (Ankety)
- id: UUID
- title: Text
- description: Text
- author_id: UUID (FK)
- is_active: Boolean
- deadline: Timestamp
- target_audience: Enum ('all_parents', 'class_group', 'specific_parents')
survey_questions (Otázky)
- id: UUID
- survey_id: UUID (FK)
- question_text: Text
- question_type: Enum ('yes_no', 'single_choice', 'multiple_choice', 'text')
- order: Int
survey_options (Možnosti odpovědí)
- id: UUID
- question_id: UUID (FK)
- option_text: Text
- order: Int
survey_responses (Odpovědi rodičů)
- id: UUID
- survey_id: UUID (FK)
- question_id: UUID (FK)
- option_id: UUID (FK, nullable)
- respondent_id: UUID (FK)
- text_answer: Text (nullable)
- created_at: Timestamp

6. Knowledge Base & FAQ

knowledge_documents (Indexované dokumenty z Google Drive)
- id: UUID
- drive_file_id: Text (Google Drive File ID)
- title: Text
- trust_level: Enum ('verified', 'current', 'draft')
- content_hash: Text (detekce změn při syncu)
- last_synced_at: Timestamp
- created_at: Timestamp
faq_entries (Ověřené FAQ — samoučící se z dotazů rodičů)
- id: UUID
- question: Text
- answer: Text
- source_thread_id: UUID (FK → communication_threads.id)
- approved_by: UUID (FK — ředitel/zástupce)
- approved_at: Timestamp
- is_published: Boolean
- category: Text (např. 'stravování', 'výlety', 'pravidla')
- usage_count: Integer (kolikrát Sofie tuto FAQ citovala)
- created_at: Timestamp

7. Projekty a Úkoly (Kosmo PM)

Jednoduchý interní PM modul — vlastní kanban. Učitelé potřebují projekt s popisem, odkazy na zdroje a seznam úkolů s deadlinem a zodpovědnou osobou.

projects (Projekty / akce)
- id: UUID
- name: Text (např. "Rekonstrukce šatny", "Zahradní slavnost 2026")
- description: Text (Markdown)
- status: Enum ('active', 'completed', 'archived')
- calendar_url: Text (odkaz na Google Calendar událost, volitelné)
- drive_url: Text (odkaz na Google Drive složku, volitelné)
- created_by: UUID (FK)
- created_at: Timestamp
- updated_at: Timestamp
project_tasks (Úkoly v projektu)
- id: UUID
- project_id: UUID (FK → projects.id)
- title: Text
- note: Text (volitelná poznámka)
- assignee_id: UUID (FK — zodpovědná osoba)
- due_date: Date (deadline)
- is_completed: Boolean (default: false)
- completed_at: Timestamp
- order: Integer (pořadí zobrazení)
- created_at: Timestamp

8. Pipeline zápisů / CRM (Leads)

Modul pro sledování zápisového procesu. Zájemce → kontaktován → prohlídka → přihláška → zapsán. Klíčová výhoda: přechod lead → student jedním kliknutím.

leads (Zájemci o zápis)
- id: UUID
- family_name: Text
- contact_email: Text
- contact_phone: Text
- stage: Enum ('new', 'contacted', 'tour_scheduled', 'tour_done', 'application', 'enrolled', 'rejected', 'withdrawn')
- source: Enum ('website', 'referral', 'open_day', 'social_media', 'other')
- source_detail: Text
- created_by: UUID (FK)
- created_at: Timestamp
- updated_at: Timestamp
lead_children (Děti zájemce)
- id: UUID
- lead_id: UUID (FK)
- first_name: Text
- age: Integer
- target_grade: Text
- notes: Text
lead_notes (Historie komunikace)
- id: UUID
- lead_id: UUID (FK)
- type: Enum ('email', 'phone', 'in_person', 'tour', 'note')
- content: Text
- author_id: UUID (FK)
- created_at: Timestamp

Přechod lead → student

Když lead dosáhne fáze enrolled: 1. Z lead_children se vytvoří záznamy v students 2. Z kontaktních údajů leadu se vytvoří profiles (rodiče) 3. Vytvoří se vazby ve student_guardians 4. Lead se označí jako enrolled a archivuje

9. Generování dokumentů (šablony)

document_templates (Šablony dokumentů)
- id: UUID
- name: Text (např. "Smlouva o vzdělávání")
- category: Enum ('contract', 'consent', 'confirmation', 'notice')
- content: Text (Markdown šablona s {{proměnnými}})
- version: Integer (default: 1)
- is_active: Boolean
- created_by: UUID (FK)
- created_at: Timestamp
- updated_at: Timestamp
generated_documents (Vygenerované dokumenty — archiv)
- id: UUID
- template_id: UUID (FK)
- template_version: Integer
- student_id: UUID (FK)
- pdf_url: Text
- generated_by: UUID (FK)
- generated_at: Timestamp

10. Audit Log

audit_logs (Auditní stopa — právní pojistka)
- id: UUID
- user_id: UUID (FK)
- action: Text (např. 'pickup_confirmed', 'excuse_created', 'consent_granted')
- entity_type: Text (např. 'attendance_records', 'excuse_notes')
- entity_id: UUID
- details: JSONB (snapshot dat v okamžiku akce)
- ip_address: Text
- user_agent: Text
- created_at: Timestamp

11. Nastavení Notifikací

notification_preferences (Preference uživatele)
- id: UUID
- user_id: UUID (FK)
- channel: Enum ('push', 'email')
- category: Text (např. 'attendance', 'evidence', 'surveys', 'daily_digest')
- enabled: Boolean (default: true)
- summary_frequency: Enum ('daily', 'weekly', 'monthly')

12. Bezpečnost (RLS Policies)

Row Level Security (RLS) policies zajistí, že data vidí jen oprávnění uživatelé.

Tabulka	Pravidlo
`profiles`	Každý čte své (nebo veřejné profily učitelů). Admin může vše.
`students`	Pouze admin/ředitel (citlivá data).
`work_items`	Učitel vidí svou třídu, rodič vidí své dítě.
`communication_threads`	Rodič vidí jen své konverzace. Učitel vidí přiřazené tickety.
`attendance_records`	Rodič vidí své dítě. Učitel vidí svou třídu.
`faq_entries`	Publikované (`is_published: true`) vidí všichni.

Poznámka: Detailní RLS policies budou implementovány v migraci 0000_init_schema.sql.

Odloženo do Fáze 2

Následující entity jsou navrženy, ale budou implementovány až ve Fáze 2:

activities — Kroužky a akce (šachy, keramika, plavání...)
activity_enrollments — Přihlášky na kroužky
consents — Definice souhlasů (GDPR, výlety, fotky)
student_consents — Podpisy souhlasů s audit logem
Služba (role dítěte) — Žák-služba digitalizuje práce třídy

Sofie — AI persona školy

TL;DR

Sofie je AI persona školy — jedna „kolegyně", se kterou všichni komunikují (chatem, emailem, hlasem). Uživatel řekne pár hesel, Sofie zpracuje, navrhne, nechá schválit — hotovo.

Co Sofie dělá:

Přepisuje texty učitelů do tónu školy a kontroluje kompletnost
Buduje znalostní bázi organicky z každé interakce (wiki roste sama)
Odpovídá rodičům z ověřených informací; co neví, zeptá se a naučí se
Zpracovává omluvenky, docházku, obědy — jednou větou od rodiče
Plánuje akce konverzačně (výlet = 5 minut chatu místo 3 formulářů)
Sleduje úkoly a deadliny z konverzací (nahrazuje Kosmo PM)
Pamatuje si historii s každou rodinou (nahrazuje Twenty CRM)
Analyzuje fotky žákovských prací → buduje portfolio → generuje IVP
Automaticky překládá mezi češtinou a angličtinou (pro zahraniční učitele)

Nasazení: Postupně. Začne se CC v emailu (nikdo nemusí nic měnit), pokračuje appkou pro pár aktivních lidí, zbytek se přidává organicky.

Náklady: ~500 Kč/měsíc (MVP) → ~800 Kč/měsíc (plný provoz). Levnější než samotný Kosmo PM + Twenty + newsletter software.

Persona Sofie

Identita

Sofie není „systém" ani „chatbot" — je to kolegyně, která ví všechno a nikdy nespí.

Má vlastní email: sofie@sofie.education
Vždy tyká (interně učitelům) — je to její identita
Texty pro rodiče píše v tónu školy (vyká)
Přátelská, přesná, nikdy nespekuluje
Pokud neví, řekne to a zeptá se správné osoby

Dva tóny

Kontext	Oslovení	Příklad
Interně (učitelům, kolegům)	Tykání	„Petro, ještě nemám záznam za dnešek. Co jste dělali?"
Rodičům	Vykání (varianta A)	„Posíláme vám info k výletu."

Tónový manuál — komunikace s rodiči

Škola komunikuje s rodiči vřele, ale kompetentně. Jako soused, kterému na dítěti záleží a zároveň ví, co dělá. Vykání, ale bez formální strnulosti.

Pravidla

Pravidlo	Příklad	Anti-příklad
Vykáme, ale srdečně.	„Posíláme vám info k výletu."	„Vážení rodiče, dovolujeme si Vás informovat…"
Píšeme jako lidi. Krátké věty, běžná slova.	„Děti budou potřebovat gumáky."	„Je nezbytné zajistit nepromokavou obuv."
Pojmenováváme emoce.	„Moc nás potěšilo, kolik vás přišlo."	„Účast na akci byla vysoká."
Konkrétní, ne obecné. Čísla, data, jména.	„Ve čtvrtek 15. 5. v 8:30"	„V nejbližších dnech"
Aktivní slovesa. Kdo dělá co.	„Přihlaste děti do pátku."	„Přihlášky je třeba zaslat do pátku."
Montessori přirozeně. Filozofii jen tam, kde pomáhá pochopit „proč".	„Děti si samy vybraly téma projektu."	„V souladu s principy kosmické výchovy dle Dr. Montessori…"

Tón v číslech

Max délka zprávy: 150 slov (ideálně do 100)
Max bodů v seznamu: 5
Emoji: střídmě (max 2–3 na zprávu, funkční)

Vzorová komunikace

Výlet na farmu — čtvrtek 15. 5.

Posíláme vám info k čtvrtečnímu výletu na farmu do Kunratic.

Co budou děti potřebovat: - Svačinu + pití (oběd na farmě zajištěn) - Gumáky nebo pevné boty - Pláštěnku pro jistotu

Odjezd v 8:30 od školy, návrat kolem 15:00.

Pokud vaše dítě nejede, dejte nám prosím vědět do středy.

Architektura

Stack

n8n (orchestrátor, workflow automation)
  ├─→ Vertex AI Gemini (LLM — Flash + Pro, EU region)
  ├─→ BookStack API (znalostní báze, obsah)
  ├─→ Supabase pgvector (RAG embeddingy)
  ├─→ Gmail API (CC email trigger)
  ├─→ Listmonk API (newsletter, fáze 2+)
  └─→ Supabase (aplikační data Kosmo)

Proč n8n (ne Dify)

Jádro projektu je CC email → extrakce → znalostní báze → routing — to je workflow problém, ne chatbot problém.

Kritérium	n8n	~~Dify~~ (zamítnuto)
RAM	~256 MB (1 kontejner)	~4 GB (7 kontejnerů)
Email integrace	Nativní Gmail trigger	Vyžaduje custom glue code
Integrace	400+ nodes	~20 tools
Google Workspace	Nativní nodes	Omezená
Flexibilita	Workflow automation	Chatbot builder

Úspora RAM umožnila zmenšit VM z e2-standard-4 ($60/měs) na e2-small ($15/měs).

RAG pipeline

BookStack (obsah) → n8n sync → Gemini embedding → Supabase pgvector
Dotaz → Gemini embedding → pgvector similarity → kontext → Gemini Pro → odpověď

Žádný separátní vector DB. Pgvector je extension v PostgreSQL, Supabase ho má out of the box.

Strategie výběru modelu

n8n umožňuje per-workflow routing — nemusíme používat jeden model na vše:

Úloha	Model	Proč
Routing, klasifikace	Gemini Flash	Rychlé, levné, stačí
Reformulace textu	Gemini Pro	Kvalita výstupu důležitá
RAG odpovědi	Gemini Pro	Přesnost + citace
Portfolio analýza	Gemini Vision	Multimodální
IVP generování	Claude Sonnet / Opus	Nejkomplexnější úloha

Jeden vzorec pro vše

Každá interakce sleduje stejný vzorec:

Vstup (chat / email / CC / voice / upload)
    ↓
Sofie porozumí záměru
    ↓
Odhadne kompetentní osobu
    ↓
Připraví návrh (odpověď / draft / akce)
    ↓
Osloví osobu: [Schválit] [Upravit] [Přehodit na...]
    ↓
Sofie přeformuluje, uloží, publikuje, odpoví

n8n workflow schopnosti

Schopnost	Co dělá	Příklad
Reformulace	Přepíše text do tónu školy	Učitel napíše hesla → formátovaná zpráva
Zápis do KB	Extrahuje fakta, draft stránky v BookStack	„Od pondělka družina do 16:30" → draft změny
Plánování	Konverzačně založí akci, vygeneruje úkoly	„Chci naplánovat výlet" → event + zpráva
RAG lookup	Odpovídá z BookStack KB, cituje zdroj	„Kdy jedou třeťáci na výlet?"
Routing	Odhadne správnou osobu pro eskalaci	„jídlo" → kuchařka, „výlet 3B" → třídní 3B
Extrakce	Z emailu/voice vytěží strukturovaná data	Hlasový debrief → denní záznam

Znalostní báze (BookStack)

Veřejná vs. interní

BookStack tagy řídí viditelnost:

Tag	Viditelnost	Příklad obsahu
`visibility:public`	Veřejný chat, web	FAQ, pravidla školy, ŠVP
`visibility:internal`	Interní agenti	Metodiky, procesy, kontakty
`visibility:vedeni`	Pouze vedení	Finance, GDPR, smlouvy

n8n RAG pipeline má dvě sady embeddingů v Supabase pgvector: veřejná (sync jen visibility:public) a interní (sync vše). Veřejný chat nikdy nevidí interní data.

Trasovatelnost

Každá informace nese metadata o původu:

Tag: autor:petra.novakova
Tag: schvalil:patrik.matlak
Tag: zodpovida:jana.kralova
Tag: stav:ke-schvaleni|schvaleno|hotovo
Tag: deadline:2026-03-20
Tag: typ:akce|faq|pravidlo|ukol|sablona
Tag: visibility:public|internal|vedeni

Self-learning FAQ loop

Rodič se ptá → Sofie hledá v KB (visibility:public) → nenašla
    ↓
„Nemám ověřenou odpověď. Zeptám se."
    ↓
Odhadne kompetentní osobu → osloví s návrhem odpovědi
    ↓
Osoba schválí (klik / email reply / auto-publish)
    ↓
Draft publikován → n8n → pgvector sync → příště Sofie odpoví sama

Čím víc se rodiče ptají, tím je Sofie chytřejší — a nikdo nemusel FAQ psát ručně.

Struktura roste organicky

Nenavrhujeme strukturu BookStack předem. Prvních pár stránek vznikne z reálných interakcí, Sofie navrhuje kam zařadit, ředitel schválí. Struktura emerguje z potřeb.

Komunikační kanály

Sofie přijímá vstup z libovolného kanálu — vše volá stejné n8n workflow.

Email — progresivní integrace

Fáze	Sofie dělá	Učitel dělá	Technicky
E1 (CC)	Pozoruje, extrahuje, navrhuje drafty	Komunikuje normálně, přidá CC	Parsování CC emailů
E2 (asistent)	Navrhuje odpovědi na dotazy rodičů	Klikne Schválit/Upravit	+ přístup k mailboxu
E3 (persona)	Komunikuje sama, eskaluje když neví	Píše Sofii jako kolegyni	Plný email účet + n8n

E1 příklad (CC pattern):

Učitelka pošle email rodičům → CC sofie@sofie.education
Sofie pozoruje: extrahuje fakta, připraví draft do wiki,
sleduje odpovědi rodičů. Nic neposílá bez pokynu.

@sofie v emailových vláknech: Učitelé si mohou psát emaily a kdykoliv vyzvat Sofii zmínkou @sofie nebo přidáním do CC. Sofie odpovídá jen když je oslovena — reply-all, takže všichni vidí informaci.

Voice — hlas jako vstup

Varianta STT	Kvalita CZ	Cena
Browser Web Speech API	Dobrá	Zdarma
Whisper API (OpenAI)	Nejlepší	$0.006/min
Gemini multimodal	Výborná	Součást Gemini API

Klíčový use case — hlasový denní debrief:

Učitel nasadí sluchátka cestou z práce a 2 minuty přirozeně mluví. Z toho vznikne: - Denní záznam (náhrada třídnice) - Aktualizace portfolia - Detekce vzorců chování (vyrušování, nepřipravenost) - Podklady pro budoucí IVP

Sofie automaticky překládá — zahraniční učitel mluví anglicky, Sofie zapíše česky. Každý komunikuje ve svém jazyce.

Chat

Chat v aplikaci Kosmo (Next.js frontend) — primární rozhraní. Sofie navrhuje klikací akce:

Sofie: „Jak tě mám upozorňovat na důležité věci?"
       [Push]  [Email]  [Jen v appce]

Notifikace

Kanál	Kdy
In-app karta	Vše — základní notifikace
Web Push (PWA)	Urgentní: schválení, deadline, eskalace
Email	Denní digest, nebo urgentní pokud nereaguje
WhatsApp (budoucnost)	Rodiče, kteří nechtějí appku

Schvalovací workflow

Schvalovací politika dle rizika

Typ obsahu	Viditelnost	Kdo schvaluje	Auto-publish?
Public FAQ	Veřejnost	Vždy ředitel	Ne
Komunikace rodičům	Rodiče	Vždy ředitel	Ne
Personální / GDPR	Vedení	Vždy ředitel	Ne
IVP / portfolio	Učitel + rodič	Třídní učitel	Ne
Interní FAQ	Zaměstnanci	Oslovená osoba	Ano (opt-out 2–3 dny)
Zápis z porady	Zaměstnanci	Oslovená osoba	Ano (opt-out 2 dny)
Provozní info	Zaměstnanci	Oslovená osoba	Ano (opt-out 1 den)

Opt-out = pokud osoba nereaguje do timeoutu, obsah se publikuje. Může kdykoliv zablokovat.

Tři úrovně autorizace

Úroveň	Jak vzniká	Příklad
Autorizováno	Klik v appce nebo magic link	Ředitel schválil FAQ
Neautorizováno	Email odpověď zpracovaná AI	Učitel odpověděl emailem
Draft	AI vygenerovala bez lidského vstupu	Sofie navrhla odpověď z kontextu

U neautorizovaných odpovědí je vždy uvedeno: „Na základě odpovědi [jméno] (email, bez autorizace v appce)".

Smart routing

Fáze	Routing	Příklad
v1	Klíčová slova → osoba	„jídlo" → kuchařka, default → ředitel
v2	Tabulka `escalation_log` — kdo na co odpovídal	Kuchařka přehazuje „platby" na ředitele → naučeno
v3	Agent zná role, třídy, rozvrh	Dotaz o 3B → třídní 3B

Fallback: pokud routing selže → vše jde na ředitele.

Organická náhrada PM a CRM

Kosmo PM (úkoly z konverzací)

Úkoly vznikají z konverzací, ne ze separátního PM softwaru:

Učitel: „Sofie, je potřeba objednat autobus na výlet"
Sofie:  Vytvoří úkol (zodpovida + deadline + vazba na akci)
        „Kdo má objednat autobus?"
        [Já]  [Kancelář]  [Ředitel]

Ředitel vidí kartu „3 úkoly s blížícím se deadline". Implementováno přes BookStack tagy zodpovida + deadline, zobrazeno v dashboardu.

Twenty CRM (historie interakcí)

Sofie loguje každou interakci s rodinami. Kontakty se budují organicky z CC emailů:

1. Učitelka pošle email → CC sofie@ → Sofie propíše kontakt rodiče
2. Po měsíci: „Mám kontakty na rodiče u 28 z 31 dětí."

Nikdo nezadával kontakty ručně. Stačilo pár CC emailů.

Co tím odpadá

Původně plánovaný nástroj	Jak to řeší Sofie
PM software	Úkoly z konverzací, tagy v BookStack, karta v dashboardu
CRM software	Historie interakcí v Supabase, shrnutí per-rodina
Newsletter (Listmonk, fáze 2+)	Sofie vygeneruje obsah, ředitel schválí

Cenový odhad

Infrastruktura

Položka	Měsíčně	Poznámka
GCP VM (n8n + BookStack)	~375 Kč	`e2-small`, `europe-west1`
Supabase	0–600 Kč	Free tier stačí pro MVP
Vercel (Next.js)	0 Kč	Free tier
GCP Storage	~50 Kč	~$0.02/GB
Doména + DNS	~60 Kč	Cloudflare
Subtotal	~500–1 100 Kč

LLM API (~80 žáků, ~22 zaměstnanců, ~150 rodin)

Aktivita	Gemini Flash	Gemini Pro
Hlasové debriefy (10 učitelů × 2 min)	~70 Kč/měs	~70 Kč/měs
Reformulace + routing (~30 interakcí)	~5 Kč/měs	~80 Kč/měs
FAQ / RAG dotazy (~20 dotazů)	~3 Kč/měs	~50 Kč/měs
Email zpracování (~15 emailů)	~2 Kč/měs	~40 Kč/měs
Portfolio analýza (~5 fotek)	~8 Kč/měs	~8 Kč/měs
Proaktivní akce	~2 Kč/měs	~30 Kč/měs
Subtotal	~90 Kč/měs	~280 Kč/měs

Celkem

Scénář	Celkem
MVP (text, pár uživatelů)	~500 Kč/měs
Plný provoz (voice, portfolio, proaktivita)	~800 Kč/měs
Maximum (premium modely, vysoký traffic)	~1 300 Kč/měs

Fázování

Fáze	Období	Co se nasadí	Kanály
1	Týden 1–3	Reformulátor (n8n workflow)	n8n chat
2	Týden 4–5	Zapisovač do wiki, BookStack tagy	Beze změny
3	Týden 6–8	Plánovač akcí, klikací karty	+ CC email (E1)
4	Týden 9–12	Sofie email persona, @sofie v CC	+ Sofie email (E3)
5	Měsíc 4+	RAG Chat, Magic Links, SSO	+ voice (STT), push
6	Měsíc 6+	Feed, Twenty CRM / Kosmo PM organicky	+ WhatsApp, TTS
7	Měsíc 9+	Portfolio žáka (Gemini Vision)	Beze změny
8	Rok 2+	Sokratův průvodce, IVP	+ žákovský přístup

Onboarding — žádný big bang

Fáze 0: CC sofie@ v emailech → Sofie pozoruje, nikoho neoslovuje
Fáze 1: Aktivní uživatelé mají appku → Sofie posílá karty a návrhy
Fáze 2: Sofie potřebuje info → osloví emailem, zpracuje odpověď
Fáze 3: Neaktivní uživatel vidí, že to funguje → sám si otevře appku

Nulová bariéra. Nikdo není nucen. Přirozená adopce.

Trust gradient — stupně autonomie

Stupeň 0: Sofie jen pozoruje (CC pattern)
Stupeň 1: Sofie navrhuje, člověk schvaluje vše
Stupeň 2: Sofie schvaluje nízko-rizikové sama (auto-publish)
Stupeň 3: Sofie odpovídá rodičům z ověřené KB sama
Stupeň 4: Sofie zakládá akce z vlastní iniciativy
Stupeň 5: Sofie identifikuje mezery a navrhuje nové workflow

Klíčová rozhodnutí (přehled)

Oblast	Rozhodnutí	Zamítnuto
LLM orchestrátor	n8n + Vertex AI (Gemini)	Dify, Vertex AI Agent Builder
RAG	pgvector v Supabase	Weaviate
Znalostní báze	BookStack	Google Drive (jen pro dokumenty)
Email politika	Walled Garden (no-reply, rodič musí do appky)	—
CRM	Twenty	HubSpot
PM	Kosmo PM (vlastní kanban)	Asana, Plane
Newsletter	Listmonk (fáze 2+)	—

Sloučeno z DECISION_AI_COMMUNICATION.md, DECISION_KNOWLEDGE_BASE.md, DECISION_LLM_ORCHESTRATOR.md a TONE_MANUAL_DRAFTS.md. Poslední aktualizace: březen 2026.

Integrace (INTEGRATIONS.md)

Tento dokument popisuje strategii integrace s externími systémy a úložištěm souborů.

1. Úložiště souborů

Aktualizace (duben 2026): Primární storage přesunuto na Supabase Storage. Škola má ~80 žáků, odhadovaný objem ~10–20 GB/rok. Supabase Pro (100 GB) stačí na roky, RLS funguje z boxu bez extra infrastruktury. GCS plán níže zůstává jako reference pro budoucí migraci, pokud objem překročí kapacitu Supabase nebo bude potřeba přímá integrace s Vertex AI.

Původní plán: GCP Cloud Storage (odloženo)

Architektonický princip: File-first, Schema-light

GCP Bucket je source of truth. Supabase drží jen AI-derived data.

Škola potřebuje ukládat soubory ke každému žákovi:

Evidenční dokumenty — smlouvy, rodné listy, kartičky ZP, souhlasy GDPR. Málo souborů, vysoká citlivost, dlouhá retence.
Fotky prací žáků — sešity, projekty, výkresy. Fotky věcí (ne osob). Střední objem, AI zpracování.
Scany ověření — doklady o zvládnutí kompetencí. AI extrahuje strukturovaná data.
Právní dokumenty — vše jde do GCP Bucket (rozhodnuto).

Každý soubor má vedle sebe .meta.json s popisem. Supabase drží jen zpracované výstupy (competency_records), které lze kdykoliv přegenerovat z raw souborů. Toto umožňuje:

Periodické re-processing — až bude AI chytřejší, projdeš složku žáka znovu a vygeneruješ nové insights
Disposable schema — Supabase struktury je jednodušší zahodit a přepracovat, protože soubory + metadata v bucketu jsou nezávislé
Self-describing storage — i bez databáze lze procházet bucket a rozumět, co v něm je

Proč GCP Cloud Storage

Výhoda
Přímá integrace s Vertex AI / Gemini Vision (stejný projekt `sofie-education`, žádný data transfer)
Data v EU (`europe-west1`) — GDPR
Levné: Standard ~$0.02/GB/měsíc, Nearline pro archiv
Signed URLs pro bezpečné zobrazení v UI (time-limited)
Lifecycle rules (automatická archivace starších souborů)
Object Versioning (ochrana proti nechtěnému smazání + historie sidecar metadat)
Už máme GCP projekt, region, billing

Vyřazené alternativy

Alternativa	Proč ne
Google Shared Drive	Oddělení od Kosma — dvě místa. Žádná integrace s AI. Nemožnost kontrolovat kompletnost dokumentů v Kosmu.
Supabase Storage	Data v AWS. Gemini Vision v GCP. Cross-cloud transfer = latence + náklady.
Immich	Vyřazen z důvodu GDPR biometrie. Hardcodovaný Face Recognition u dětí = extrémní právní zátěž.

Bucket struktura

Dvě podsložky per žák: evidence/ (sekretářka, právní dokumenty) a portfolio/ (učitel, práce + ověření). Čitelné názvy souborů. Sidecar .meta.json vedle každého souboru.

gs://sofie-media/
└── {student_id}/
    ├── evidence/                                  # sekretářka spravuje
    │   ├── smlouva_2025.pdf
    │   ├── smlouva_2025.meta.json
    │   ├── rodny_list.pdf
    │   ├── rodny_list.meta.json
    │   ├── zp_karticka.jpg
    │   └── zp_karticka.meta.json
    ├── portfolio/                                 # učitel nahrává
    │   ├── 2026-03-15_projekt_vesmir.webp
    │   ├── 2026-03-15_projekt_vesmir.meta.json
    │   ├── 2026-03-20_overeni_zlomky.webp
    │   └── 2026-03-20_overeni_zlomky.meta.json
    └── manifest.json                              # auto-generovaný index přes obě složky

evidence/ = právní/administrativní dokumenty. Málo souborů, spravuje sekretářka, jiná oprávnění (admin only).
portfolio/ = vše co dokumentuje pokrok žáka (fotky prací + scany ověření). Spravuje učitel, AI zpracovává.
Manifest na root úrovni žáka — AI vidí oboje.

Pojmenování souborů

Čitelné názvy, ne UUID. Učitel/sekretářka zadá krátký popis při uploadu, systém vygeneruje filename:

Evidenční: {typ_dokumentu}_{rok}.{ext} → smlouva_2025.pdf, zp_karticka.jpg
Portfolio: {datum}_{popis}.{ext} → 2026-03-15_projekt_vesmir.webp, 2026-03-20_overeni_zlomky.webp

Duplicity

Soubor, který se týká více žáků (skupinový projekt), se nahraje duplicitně do složky každého žáka. Storage je levný ($0.02/GB/měsíc), konzistence a jednoduchost dotazování je cennější.

Sidecar `.meta.json`

Každý soubor má vedle sebe {filename}.meta.json se strukturovanými metadaty. Pole jsou volitelná dle type.

{
  "type": "work | document | assessment",
  "original_name": "IMG_4521.jpg",
  "uploaded_by": "ucitel@zs-sofie.cz",
  "uploaded_at": "2026-03-15T10:30:00Z",
  "school_year": "2025/2026",

  "teacher_note": "Projekt o vesmíru — korálkový materiál",
  "tags": ["projekt", "vesmír", "matematika"],
  "subject": "přírodověda",

  "document_type": "smlouva",
  "valid_until": "2027-06-30"
}

Pole dle typu

Pole	`document`	`work`	`assessment`
`type`	✅	✅	✅
`original_name`	✅	✅	✅
`uploaded_by`	✅	✅	✅
`uploaded_at`	✅	✅	✅
`school_year`	✅	✅	✅
`document_type`	✅	—	—
`valid_until`	✅ (volitelné)	—	—
`teacher_note`	—	✅	✅
`tags`	—	✅	✅
`subject`	—	✅	✅
`assessment_date`	—	—	✅

`manifest.json`

Auto-generovaný index všech souborů žáka. Regeneruje se po každém uploadu/smazání. Slouží jako rychlý vstup pro AI — místo listování bucketu AI dostane jeden JSON.

{
  "student_id": "uuid",
  "generated_at": "2026-03-24T12:00:00Z",
  "file_count": 8,
  "evidence": [
    {"name": "smlouva_2025.pdf", "document_type": "smlouva", "uploaded_at": "2026-03-15"},
    {"name": "rodny_list.pdf", "document_type": "rodny_list", "uploaded_at": "2026-03-15"},
    {"name": "zp_karticka.jpg", "document_type": "zp_karticka", "uploaded_at": "2026-03-15"}
  ],
  "portfolio": [
    {"name": "2026-03-15_projekt_vesmir.webp", "type": "work", "subject": "přírodověda", "uploaded_at": "2026-03-15"},
    {"name": "2026-03-20_overeni_zlomky.webp", "type": "assessment", "subject": "matematika", "uploaded_at": "2026-03-20"}
  ]
}

Supabase — minimální, disposable schema

Supabase drží jen to, co je AI-derived a slouží pro dotazování v UI. Vše je regenerovatelné z bucket souborů.

`student_files` — cache/index souborů

Lightweight cache pro UI listing bez GCS API volání. Regenerovatelné z manifest.json.

Sloupec	Typ	Popis
`id`	UUID PK
`student_id`	UUID FK → students
`file_name`	TEXT	Čitelný název souboru
`storage_path`	TEXT	Plná cesta v GCS
`folder`	TEXT	`evidence` nebo `portfolio`
`type`	TEXT	`document`, `work`, `assessment`
`document_type`	TEXT	Pro evidence: `smlouva`, `rodny_list`, `zp_karticka`, `souhlas_gdpr`...
`subject`	TEXT	Pro portfolio: předmět
`uploaded_at`	TIMESTAMPTZ
`created_at`	TIMESTAMPTZ

`competency_records` — AI-extrahované záznamy kompetencí

Centrální tabulka pro AI metodické listy. Plněna z AI zpracování fotek prací a scanů ověření.

Sloupec	Typ	Popis
`id`	UUID PK
`student_id`	UUID FK → students
`competency_code`	TEXT	Kód kompetence (RVP nebo vlastní školy)
`competency_name`	TEXT	Lidsky čitelný název: "Sčítání zlomků"
`subject_area`	TEXT	"Matematika", "Český jazyk"...
`evidence_source`	TEXT	`assessment`, `work`, `teacher_manual`
`source_file`	TEXT	Název souboru v bucketu (ne FK, jen reference)
`level`	TEXT	"zvládá samostatně", "zvládá s podporou", "rozvíjí se"
`observed_at`	DATE	Kdy kompetence pozorována
`school_year`	TEXT	"2025/2026"
`ai_generated`	BOOLEAN	Zda to generovala AI
`teacher_confirmed`	BOOLEAN	Zda učitel potvrdil
`processing_model`	TEXT	Jaký model generoval (pro re-processing)
`processing_date`	TIMESTAMPTZ	Kdy zpracováno
`created_at`	TIMESTAMPTZ

`ai_processing_runs` — log zpracování

Audit log pro tracking AI zpracování a re-processing.

Sloupec	Typ	Popis
`id`	UUID PK
`student_id`	UUID FK → students
`run_type`	TEXT	`single_file`, `full_portfolio`
`model_used`	TEXT	"gemini-2.0-flash", "gemini-2.5-pro"...
`started_at`	TIMESTAMPTZ
`completed_at`	TIMESTAMPTZ
`files_processed`	INTEGER
`records_generated`	INTEGER
`status`	TEXT	`running`, `completed`, `failed`
`error_message`	TEXT	Při selhání

Upload flow

sequenceDiagram
    participant U as Učitel/Sekretářka
    participant K as Kosmo (Next.js)
    participant B as GCP Bucket
    participant G as Gemini Vision
    participant DB as Supabase

    U->>K: Nahraje soubor + vyplní popis
    Note over K: Client-side resize fotek (2048px, WebP)
    K->>K: Vygeneruje čitelný filename + .meta.json
    K->>B: Upload soubor přes signed URL
    K->>B: Upload .meta.json přes signed URL
    K->>B: Regeneruje manifest.json
    K->>DB: Upsert student_files (cache)

    alt Portfolio soubor (work/assessment)
        K->>G: Analyze image
        G-->>K: Popis, předmět, štítky, kompetence
        K->>DB: Insert competency_records
        K->>DB: Insert ai_processing_runs
    end

    K->>U: Hotovo

Evidence upload (sekretářka)

Otevře kartu žáka → záložka "Soubory" → sekce "Evidence"
Vidí checklist povinných dokumentů (smlouva, GDPR souhlas, rodný list, ZP kartička)
Chybějící = červený badge, nahráno = zelený check
Klikne "Nahrát" u konkrétního typu → file picker (PDF/JPG/PNG)
Systém automaticky pojmenuje dle typu + roku
Upload do {student_id}/evidence/

Portfolio upload (učitel)

Otevře kartu žáka → záložka "Soubory" → sekce "Portfolio"
Klikne "Přidat" → vybere typ (fotka práce / scan ověření)
Na mobilu: camera capture, na desktopu: file picker
Vyplní krátký popis + předmět (volitelně)
Client-side resize na 2048px + WebP konverze
Upload do {student_id}/portfolio/
AI zpracování na pozadí (Gemini Vision → competency_records)

AI zpracování

Při uploadu (single file)

Typ souboru	AI vstup	AI výstup
Fotka práce (`work`)	Obrázek + teacher_note + subject	Popis scény, identifikované kompetence, štítky
Scan ověření (`assessment`)	Obrázek	Strukturovaná extrakce: úlohy, výsledky, kompetence, chyby
Evidenční dokument	—	Žádné AI zpracování (MVP)

Scan ověření — příklad AI extrakce

Vstup: Scan papírového ověření z matematiky. Gemini Vision výstup:

{
  "assessment_title": "Ověření — Zlomky",
  "tasks": [
    {"number": 1, "description": "Sečti zlomky", "result": "correct", "competency": "M-5-1-01"},
    {"number": 2, "description": "Odečti zlomky", "result": "partial", "competency": "M-5-1-02"},
    {"number": 3, "description": "Slovní úloha", "result": "correct", "competency": "M-5-1-03"}
  ],
  "teacher_comment": "Výborně, jen pozor na společný jmenovatel",
  "competencies_demonstrated": ["M-5-1-01", "M-5-1-03"],
  "confidence": 0.87
}

Učitel vidí extrakci v UI → potvrdí nebo upraví → teacher_confirmed = true.

Periodické re-processing (budoucí)

n8n workflow "Portfolio Re-processing": 1. Vezme manifest.json žáka 2. Pošle Gemini Pro s celým kontextem portfolia (všechny soubory za školní rok) 3. Přegeneruje competency_records s novým modelem 4. Zaloguje do ai_processing_runs

Spouštěno on-demand nebo měsíčně. Umožňuje využít nové AI modely s lepším porozuměním bez změny dat.

[!IMPORTANT] Žádné face recognition. Gemini Vision popisuje scénu a aktivitu, ne osoby. Přiřazení fotky ke konkrétnímu žákovi dělá učitel při uploadu. Biometrie dětí je zvláštní kategorie pod GDPR.

n8n workflows

Workflow	Trigger	Popis
Work/Assessment Processing	Webhook po uploadu	Gemini Vision analýza → upsert competency_records
Portfolio Re-processing	On-demand / měsíčně	Projde manifest.json → Gemini Pro s celým kontextem → přegeneruje competency_records
Methodology Sheet Generator	On-demand (budoucí)	Čte competency_records + manifest → Gemini Pro → Typst PDF

Document completeness

Jednoduché řešení bez cronu: UI na kartě žáka zobrazí checklist povinných typů dokumentů. Stav se derivuje z manifest.json / student_files cache.

Povinné typy (konfigurovatelné): - smlouva — Smlouva o vzdělávání - souhlas_gdpr — Souhlas se zpracováním osobních údajů - rodny_list — Rodný list (kopie) - zp_karticka — Kartička zdravotní pojišťovny

Chybí soubor s daným document_type? → červený badge. Sekretářka vidí stav přímo na kartě žáka.

Přístupová matice

Role	`evidence/`	`portfolio/`
Ředitel	✅ čtení + upload	✅ čtení + upload
Sekretářka	✅ čtení + upload	✅ čtení
Třídní učitel	❌ (výjimka: ZP kartička na výletě)	✅ všech žáků — čtení + upload
Rodič	❌	✅ svého dítěte — pouze čtení

Rozhodnuto: Učitel má read-only přístup k portfoliím všech žáků napříč třídami (nejen svých).

Implementováno přes Kosmo auth + signed URLs (server generuje URL jen pokud uživatel má oprávnění).

Fotky — rozhodnuté otázky

Retence fotek: 3 roky po odchodu žáka ze školy.
Souhlas: Obecný souhlas při zápisu (ne per-soubor).
Tagování fotek: Automaticky dle data, učitel potvrdí. Žádné biometrické rozpoznávání.

Lifecycle rules (GCS)

Prefix	Standard	Nearline (2 roky)	Coldline (5 let)	Archive
`*/evidence/`	✅	—	—	po 5 letech
`*/portfolio/`	✅	po 2 letech	po 5 letech	—

Object Versioning zapnutý — ochrana proti nechtěnému smazání + historie sidecar metadat při re-processingu.
Retence po odchodu žáka: 3 roky, poté smazání (v souladu s GDPR).

Optimalizace

Technika	Účel
Client-side resize (před uploadem)	Fotky max 2048px + WebP konverze → úspora storage i bandwidth
Thumbnaily	Generování náhledů (300px) při uploadu pro rychlé zobrazení v UI
Batch upload	Učitel nahraje 10 prací najednou → hromadný upload s AI taggingem na pozadí
manifest.json cache	student_files tabulka v Supabase = rychlý listing bez GCS API

Náklady

Položka	Odhad
Storage (~5 GB/rok)	~$0.10/měsíc
Gemini Vision (~500 fotek+scanů/rok)	~$1.25/rok
Speech-to-Text (budoucí, nahrávky)	~$20/rok
Signed URL generování	Zanedbatelné (API volání)
Celkem	< $5/rok

Implementační fáze

Fáze 1: GCS infrastruktura + evidenční dokumenty - GCP: vytvořit bucket sofie-media v europe-west1, CORS, Object Versioning - Next.js: API routes pro signed URL generování (upload + download) - Next.js: helper pro generování čitelných filenames + .meta.json - Next.js: helper pro regeneraci manifest.json po uploadu - Supabase migrace: student_files tabulka - UI: záložka "Soubory" na kartě žáka — evidence upload + completeness checklist

Fáze 2: Fotky prací žáků + AI tagging - UI: upload fotky práce (mobil: camera capture, desktop: file picker) - Client-side: resize na 2048px + WebP konverze (canvas API) - n8n: Work Processing workflow (Gemini Vision → popis, předmět, štítky) - Supabase migrace: competency_records + ai_processing_runs tabulky

Fáze 3: Scany ověření + strukturovaná AI extrakce - UI: upload scanu ověření + výběr předmětu/data - n8n: Assessment Processing workflow (Gemini Vision → strukturovaná extrakce úloh/výsledků) - UI: zobrazení AI extrakce + teacher verification - competency_records: plnění z assessment extrakcí

Budoucí fáze (mimo scope): - Audio/video nahrávky - Portfolio re-processing workflow - AI metodické listy (Gemini Pro → Typst PDF)

2. Channel Adapter Patterns

Referenční vzory pro napojování komunikačních kanálů Sofie přes n8n. Inspirováno architekturou OpenClaw.

`SofieMessage` — kanonické schéma zprávy

Všechny kanály normalizují příchozí zprávy do jednoho společného formátu:

{
  "senderId": "parent-uuid",
  "senderName": "Jana Nováková",
  "senderRole": "parent|teacher|admin",
  "channel": "email|webchat|whatsapp",
  "body": "text zprávy",
  "media": [{ "path": "...", "type": "image/jpeg" }],
  "childId": "student-uuid",
  "threadId": "conversation-uuid",
  "timestamp": "ISO 8601"
}

Inbound flow (příchozí zpráva)

Kanál (webhook/polling)
  → Normalizace do SofieMessage
  → Security check (allowlist / ověření rodiče)
  → Route resolution (který n8n sub-workflow)
  → Dispatch do AI agenta (Vertex AI)
  → Agent generuje odpověď

Outbound flow (odchozí zpráva)

Odpověď z agenta
  → Text chunking (respektuje limity kanálu)
  → Payload normalizace
  → Target resolution (kam poslat)
  → Delivery přes channel adapter (email / webhook / messaging API)

n8n workflow vzor

[Trigger node]  →  [Normalize node]  →  [Route node]  →  [AI node]  →  [Format node]  →  [Send node]
   (webhook,         (→ SofieMessage)    (→ správný       (Vertex AI)    (chunking,        (email,
    email,                                 sub-workflow)                   limity kanálu)     webhook)
    schedule)

Každý kanál = vlastní Trigger + Send node, ale prostřední logika je sdílená.

Klíčové vzory

Vzor	Aplikace v Sofii
Faceted adapters	Checklist pro nový kanál: min. trigger + normalize + send
Kanonická zpráva	`SofieMessage` JSON schema pro n8n
Early normalize, late deliver	Média normalizovat při příjmu, formátovat při odesílání
DM pairing	Ověřovací flow pro nové rodiče na messaging kanálech
Tiered routing	Switch node v n8n s prioritním matchingem

3. CRM & PM

CRM: Twenty (napojení plánováno).
PM: Vlastní Kanban modul v Kosmu.

4. Pohoda (Ekonomický systém)

Škola používá systém Pohoda pro účetnictví a fakturaci. Cíl: Automatizace fakturace školného/stravného a přenos plateb.

Technické možnosti

Dle příručky Ekonomický systém POHODA (2024), kapitola 16 (Datová komunikace):

XML Import/Export (Kapitola 16/6, str. 498)
- Pohoda podporuje nativní XML formát pro výměnu dat.
- Režim: Dávkový (soubor se nahraje do složky, Pohoda ho zpracuje).
- Využití: Generování faktur za školné (Kosmo → XML → Pohoda).
POHODA mServer (Kapitola 16/10, str. 511)
- HTTP server běžící nad Pohodou.
- Umožňuje zasílat XML požadavky přes API (např. dotaz na stav úhrady faktury).
- Výhoda: Online komunikace (není třeba ručně přenášet soubory).
- Nevýhoda: Vyžaduje veřejnou IP nebo VPN do školy (běží lokálně).

Doporučená strategie (Fáze 2/3)

MVP: Generování XML souborů (Faktury) v aplikaci Kosmo, které účetní ručně nahraje do Pohody.
Cílový stav: Využití mServeru pro automatické párování plateb (rodič vidí v aplikaci "Zaplaceno").
Dopad na uživatele:
- Rodič: Vidí ve Feedu stav platby ("Školné únor: zaplaceno" / "Splatnost: 15.2.").
- Ředitel: Dashboard s přehledem nezaplacených ("3 rodiče po splatnosti, celkem 25 500 Kč.").
- Administrativa: Přehled faktur, automatické upomínky, export pro účetní.

5. ŠkolaOnline (Školní Matrika)

ŠkolaOnline je hlavní evidenční systém (matrika). Cíl: Synchronizace žáků a rodičů (Single Source of Truth), přenos známek/omluvenek.

Analýza dokumentace

Dokumentace naznačuje velmi komplexní datový model (tisíce polí pro MŠMT výkaznictví). - Struktura: Hierarchická (Kraje → Školy → Žáci → Vzdělávací plány). - Data: Obsahuje citlivé údaje (RČ, zdravotní znevýhodnění, IVP).

Doporučená strategie

Jednosměrná synchronizace (ŠkolaOnline → Kosmo):
- ŠkolaOnline je "master" pro seznam žáků.
- Kosmo si stahuje data (ideálně přes API nebo noční CSV export).
Omluvenky:
- Rodič zadá v Kosmo → Kosmo pošle email učiteli / pokusí se zapsat do ŠOL (pokud API dovolí).

6. Google Workspace (Identita & Dokumenty)

Cíl: Single Sign-On (SSO) a úložiště. - Auth: OAuth 2.0 (přihlašování školním Google účtem). - Drive: Ukládání studentských prací (Evidence). Každý žák/třída může mít Shared Drive. - Docs/Sheets: Export reportů (vysvědčení, hodnocení).

7. Strava.cz (Školní Jídelna)

Cíl: Zobrazení jídelníčku v aplikaci (a odpovědi přes AI: "Co je dnes k obědu?").

Technické možnosti

XML Feed (Oficiální): Strava.cz nabízí XML feed jídelníčku pro každou jídelnu.
- URL: https://www.strava.cz/strava/...?xml=true&cisloJidelny=XXXXX
- Stačí znát ID jídelny školy.
Neoficiální API: Existují komunitní projekty (OpenStravaCZ/StravaProtocol) s dokumentací protokolu.

Doporučená strategie

MVP: Denní cron stáhne XML feed → uloží do DB/Knowledge Base → Sofie odpovídá.
TODO: Zjistit ID jídelny školy Sofie a ověřit XML feed.
Budoucnost: Objednávání obědů přes appku (pokud API dovolí).

8. Sofie Specifika (z Sofie - popis.pdf)

Dokument popisuje vzdělávací model, který musí Kosmo podporovat: - Slovní hodnocení: Nutnost rich-text editorů, ne jen známky 1-5. - Kompetence: Vazba na RVP (Klíčové kompetence). Evidence musí umožnit tagování ("Komunikativní", "Sociální"). - IVP: Individuální plány pro žáky se znevýhodněním (pole v databázi pro přílohy/cíle pro AI analýzu). - CLIL / Bilingvální třídy: Škola má bilingvální třídy s rodilými mluvčími i rodiče-expaty. - UI: Čeština + Angličtina (i18n od začátku — next-intl). - AI odpovědi: Sofie odpovídá v jazyce rodiče (auto-detect nebo nastavení profilu). - Reporty: Dvojjazyčné výstupy (česky pro MŠMT, anglicky pro expaty).

Implementace

MVP — Scope a Fázování

Poslední aktualizace: 24. března 2026

Fáze 0: Sofie CC email (paralelně)

Běží paralelně s vývojem Fáze 1. Cíl: škola se zmapuje organicky.

n8n workflow + Vertex AI (Gemini Flash/Pro) — already running na ai.sofie.education
CC email trigger: Ředitel přidá sofie@sofie.education do CC → n8n extrahuje fakta, osoby, úkoly → BookStack draft
Chat trigger: Ředitel komunikuje se Sofií přes chat widget na ai.sofie.education
RAG: BookStack → pgvector (Supabase) → similarity search → odpovědi s kontextem
Internal testing: Ředitel používá denně, dává feedback, KB roste organicky

Stack

Komponenta	Technologie
Orchestrátor	n8n (GCP VM, `e2-small`)
LLM	Vertex AI Gemini 2.0 Flash/Pro (`europe-west3`)
Znalostní báze	BookStack (`wiki.sofie.education`)
RAG storage	Supabase pgvector (EU Frankfurt)
Email trigger	Gmail API (CC na `sofie@sofie.education`)

Fáze 1: Evidence žáka (MVP pro ředitele)

Cíl: Funkční prototyp na app.sofie.education Uživatel: Ředitel + kancelář (sekretářka)

Deployment

Služba	Technologie	Region
Databáze	Supabase (Frankfurt EU) — staging + prod	EU
Frontend	Vercel — Next.js app	Free tier (MVP)
Soubory	Supabase Storage (RLS z boxu, 100 GB na Pro)	EU Frankfurt

Backend (Supabase)

Tabulky: - profiles — uživatelé (učitelé, ředitel, rodiče) - students — evidence žáků (osobní údaje, třída, stav, zdravotní info) - classes — třídy - student_guardians — vazba žák ↔ zákonný zástupce - documents / student_files — právní dokumenty žáka (smlouvy, souhlasy, RL)

RLS (Row Level Security): - Ředitel/admin vidí vše - Učitel vidí žáky svých tříd - Rodič vidí jen své děti

Auth: - Google OAuth (školní @sofie.education účty) - Apple Sign In - Magic Link (pro rodiče bez Google účtu)

Frontend (Next.js)

App shell: - Auth (Supabase Auth + middleware) - Role-based routing (ředitel vs. učitel vs. rodič) - i18n CZ/EN (next-intl)

Stránky:

/students              → Seznam žáků s filtrem podle třídy
/students/[id]         → Karta žáka (osobní údaje, zákonní zástupci)
/students/[id]/documents → Upload a preview právních dokumentů

Seznam žáků (/students): - Tabulka: Jméno, Třída, Stav, Zdravotní kód - Filtr podle třídy, vyhledávání - Řazení podle příjmení

Karta žáka (/students/[id]): - Osobní údaje (datum narození, rodné číslo, pojišťovna, adresa, VS) - Zákonní zástupci (jméno, email, telefon, vztah, primární kontakt) - Propojení sourozence se stávajícím rodičem (podle emailu)

Dokumenty (/students/[id]/documents): - Upload právních dokumentů (smlouva, GDPR souhlas, RL, ZP kartička) - Preview PDF/obrázků - Storage: GCP Bucket ({student_id}/evidence/...)

CSV import: - Hromadný import žáků ze ŠkolaOnline (CSV) - Mapování sloupců, validace, preview před importem

Design

Funkční prototyp. Works > looks.

UI kit: Shadcn/ui (Tailwind CSS)
Žádný custom design systém pro MVP
Responsive (desktop-first, funguje na tabletu)

Fáze 2: Teacher Tools

PM Kanban (Todo/Doing/Done, zodpovědná osoba, deadline) — vlastní modul v Kosmu
Portfolio upload (foto práce žáka + popis) — základ pro rodičovský feed
Generování pracovních listů (Sofie chat → n8n → Gemini → Typst → PDF)
Generování dokumentů (WYSIWYG TipTap editor → šablony s proměnnými → Typst → PDF)
Hlasový debrief (přepis porady → extrakce úkolů → PM modul)

Detaily: BACKLOG.md

Fáze 3: Parent Feed + Communication

Feed (/feed) — timeline aktivit dítěte (fotky, projekty, slovní hodnocení)
Adaptivní summary — Gemini shrne co se změnilo od poslední návštěvy rodiče
Sofie chat pro rodiče — FAQ z KB, omluvenky, informace o vyzvedávání
Multi-child feed — rodič s více dětmi, filtr podle dítěte
Push notifikace (PWA)

Fáze 4+: Students

Přístup žáků — přihlášení školním Google účtem (@sofie.education)
Sokratův průvodce — Gemini AI tutor (sokratovská metoda, ne podávání odpovědí)
Gamifikace — osobní milníky, Montessori-kompatibilní (bez soutěžení, vnitřní motivace)
Learning profile — 360° profil učení z dat napříč platformami (IXL, Khan, Brilliant)

Deployment: Infrastruktura a prostředí

Poslední aktualizace: 24. března 2026

TL;DR

Tři prostředí, všechna v EU, žádná ztráta dat. Self-hosted služby na GCP VM (e2-small), aplikační data v Supabase (Frankfurt), frontend na Vercelu.

Prostředí	Supabase	n8n	BookStack	Frontend
Local	Supabase CLI (Docker)	Docker Compose	Nepotřeba	`pnpm dev`
Staging	`sofie-staging` (EU Frankfurt)	Sdílená VM, neaktivní workflow	Sdílená VM	Vercel preview
Produkce	`sofie-prod` (EU Frankfurt)	Aktivní workflow	Sdílená VM	Vercel prod

1. Prostředí: Local → Staging → Prod

Lokální vývoj

~/Dev/sofie-kosmo/
├── web/                → Next.js app (pnpm dev)
├── supabase/           → Supabase CLI (supabase start)
│   ├── migrations/     → SQL migrace (verzované v Gitu)
│   └── seed.sql        → Testovací data (fiktivní, bezpečná pro Git)
├── infra/              → Docker Compose (VM produkce)
└── n8n/                → Exportované workflow JSON

supabase start spustí celý Supabase stack lokálně v Dockeru: PostgreSQL 15 (s pgvector), Auth (GoTrue), Realtime, Storage, Studio dashboard. Migrace, RLS policies, triggers — vše se testuje lokálně.

Supabase — dva projekty

	`sofie-staging`	`sofie-prod`
Region	EU Frankfurt	EU Frankfurt
Kdo používá	Dev + ředitel (testování)	Škola (produkce)
Data	Kopie z produkce	Reálná (zálohovaná)
pgvector	Enabled	Enabled

Flow migrací

Lokální (supabase start)
  │ supabase db reset — testuj migraci
  ▼
Staging (sofie-staging)
  │ supabase db push --linked — aplikuj migraci
  │ Ředitel testuje
  ▼
Produkce (sofie-prod)
  │ supabase link --project-ref <prod-ref>
  │ supabase db push --linked
  ✅ Hotovo

Vercel — Next.js hosting

MVP: Vercel free tier. Frontend neobsahuje osobní data (ta jsou v Supabase v EU). Next.js renderuje UI, osobní data se tahají client-side ze Supabase EU endpointu. Akceptovatelné pro MVP.
Produkce: Zvážit Vercel Pro s EU regionem ($20/měs) nebo Cloud Run v EU.

Data strategie

Prostředí	Zdroj dat	V Gitu?	Reálná data?
Local	`supabase/seed.sql`	Ano	Fiktivní
Staging	Kopie z produkce	Ne	Ano
Produkce	Živá data	Ne	Ano

2. GCP VM — self-hosted služby

Parametry VM

Parametr	Hodnota
VM typ	`e2-small` (2 vCPU, 4 GB RAM)
Boot disk	30 GB SSD (OS + Docker)
Data disk	100 GB HDD, oddělený, mountnutý jako `/data`
Statická IP	Pevná veřejná adresa
Region	`europe-west1-b` (Belgie, GDPR)
Cena	~$25/měs (VM + disky + IP)

Oddělený datový disk přežije restart i smazání VM, lze zvětšit online, umožňuje samostatné zálohy.

Kontejnery (8)

Kontejner	Image	RAM limit	Účel
traefik	traefik:v3.3	128 MB	Reverse proxy
landing	nginx:alpine	64 MB	Rozcestník sofie.education
postgres	postgres:16-alpine	1 GB	Sdílená DB (n8n, listmonk)
redis	redis:7-alpine	256 MB	Cache
n8n	n8nio/n8n (custom build)	256 MB	Workflow orchestrátor (Sofie AI)
listmonk	listmonk/listmonk	256 MB	Newsletter
bookstack	linuxserver/bookstack	512 MB	Wiki / znalostní báze
bookstack-db	mariadb:11	512 MB	BookStack MySQL

Celkem RAM: ~3 GB (VM má 4 GB). Po migraci z Dify: 8 kontejnerů místo 16, 3 GB místo 11 GB.

Služby a URL

Služba	URL	Účel
n8n	ai.sofie.education	Workflow orchestrátor, Sofie AI chat
BookStack	wiki.sofie.education	Znalostní báze (veřejná + interní)
Listmonk	newsletter.sofie.education	Newsletter pro rodiče
Landing	sofie.education	Rozcestník
Docs	docs.sofie.education	Cloudflare Pages (MkDocs)

Reverse proxy: Traefik

Internet → Cloudflare (HTTPS, edge certifikát) → sofie-vm (port 80)
                                                     ↓ Traefik
    ai.sofie.education         → n8n (:5678)
    newsletter.sofie.education → Listmonk (:9000)
    wiki.sofie.education       → BookStack (:80)
    sofie.education            → Landing page (:80)

HTTPS zajišťuje Cloudflare (SSL mode: Flexible). Traefik routuje po HTTP.

Data volumes

/data/
├── postgres/       → PostgreSQL data (n8n, listmonk)
├── redis/          → Redis persistence
├── n8n/            → n8n workflow data, credentials
├── bookstack/      → BookStack config + uploads
├── bookstack-db/   → MariaDB data
├── landing/        → Landing page HTML
└── backups/        → Database dumps

DNS: Cloudflare

Doména: sofie.education (registrovaná u Wedosu, DNS na Cloudflare)
CDN cache, DDoS ochrana zdarma, rychlá propagace DNS změn (~30s)

3. n8n + Vertex AI

Proč n8n (ne Dify)

	Dify	n8n
RAM	~4 GB (7 kontejnerů)	~256 MB (1 kontejner)
Email trigger	Custom glue code	Nativní (IMAP, Gmail, webhook)
Integrace	~20 tools	400+ nodes
Google Workspace	Omezená	Gmail, Calendar, Drive, Sheets

CC email → extrakce → KB → routing = workflow problém, ne chatbot problém.

Proč Vertex AI (ne Gemini API Studio)

	Gemini API (AI Studio)	Vertex AI
EU data residency	Ne	Ano (`europe-west3` Frankfurt)
DPA	Consumer ToS	GCP Enterprise DPA
Autentizace	API klíč	GCP IAM / service account

Pro školu s GDPR → Vertex AI.

Modely

Gemini 2.0 Flash — hlavní model (klasifikace, extrakce, běžné odpovědi)
Gemini 2.0 Pro — komplexní úlohy (sumarizace, reformulace, plánování)
text-embedding-004 — embeddingy pro RAG (pgvector v Supabase)

n8n: staging vs produkce

Jedna instance n8n na VM. Rozlišení přes workflow management:

Dev vytvoří workflow v n8n UI
Workflow je NEAKTIVNÍ (= staging), tag staging
Test s testovacími daty
Ředitel otestuje
Aktivace workflow (= produkce), tag production

Separátní credentials pro staging vs prod Supabase.

CC mapování školy

Ředitel nemusí „plnit systém". Komunikuje jako normálně a přidá sofie@sofie.education do CC:

Fáze 0 (Den 1–14): Pasivní pozorování
  Email s CC → n8n → Gemini extrahuje fakta → BookStack draft → loguje

Fáze 1 (paralelně): Chat na ai.sofie.education
  Ředitel → chat trigger → Gemini → KB zápis/RAG odpověď

Fáze 2 (Týden 3–4): Aktivní CC email
  n8n reaguje na CC emaily → navrhuje odpovědi učitelům

Fáze 3 (Měsíc 2+): Škola se zmapovala
  Měsíční report: zmapovanost KB, kontakty, chybějící info

RAG: BookStack → pgvector (Supabase)

BookStack (lidsky čitelný obsah)
    ↓ n8n sync workflow (denně / on-change webhook)
    ├─ GET /api/pages → Markdown
    ├─ text-embedding-004 → vector
    └─ Supabase: INSERT INTO embeddings

Dotaz:
    ├─ Embedding dotazu
    ├─ pgvector similarity search
    ├─ Top 5 výsledků → kontext
    └─ Gemini Pro: odpověď s citacemi

Náklady

Položka	Měsíčně
VM `e2-small` + disky + IP	~$25
Vertex AI (Flash + Pro)	~$10–20
Supabase	$0 (free tier)
Celkem	~$35–45

$300 kreditů = ~8–12 měsíců provozu.

4. Zálohovací strategie

Co kde zálohovat

Data	Kde žijí	Záloha	Frekvence	Retence
App data (studenti, docházka)	Supabase prod	Supabase auto + pg_dump na VM	Denně	30 dní
Memories (pgvector)	Supabase prod	Součást pg_dump	Denně	30 dní
KB obsah	BookStack (MariaDB)	mysqldump na VM	Denně	30 dní
KB soubory	BookStack (/data/bookstack)	GCP disk snapshot	Denně	14 dní
n8n workflow	PostgreSQL (n8n DB)	pg_dump + Git export	Denně	Git = neomezeně
Newsletter	Listmonk (PostgreSQL)	pg_dump	Denně	30 dní
Konfigurace	Git repo	Git	Při změně	Neomezeně

GCP disk snapshot (automatický)

gcloud compute resource-policies create snapshot-schedule sofie-backup \
  --region=europe-west1 \
  --max-retention-days=14 \
  --daily-schedule \
  --start-time=02:00

gcloud compute disks add-resource-policies sofie-data-disk \
  --resource-policies=sofie-backup \
  --zone=europe-west1-b

Disaster recovery

Scénář	Postup	Downtime
Služba spadne	`docker compose restart`	~30s
VM nereaguje	`gcloud compute instances reset`	~2 min
Data poškozena	Nový disk ze snapshotu	~10 min
Supabase výpadek	Čekáme (SaaS), app degraduje gracefully	N/A
Celý rebuild	Snapshot → nová VM + Supabase restore	~1 hod

5. EU Data Residency

Služba	Region	GDPR
GCP VM	`europe-west1` (Belgie)	OK
Vertex AI	`europe-west3` (Frankfurt)	OK
Supabase	EU Frankfurt	OK
Cloudflare DNS	Edge (globální, ale data = jen DNS)	OK
Vercel	US (free tier)	Akceptovatelné pro MVP (frontend nemá PII)
Google Workspace	EU (pokud nastaveno)	OK

6. CI/CD — trunk-based development

Princip: KISS pro solo vývojáře

Žádná staging větev. Vercel automaticky generuje preview URL pro každý PR — to je staging.

feature branch → PR → Vercel preview (+ staging Supabase) → review → merge to main → prod deploy

Git branching

Větev	Deploy kam	Kdy
`main`	Production (`app.sofie.education`)	Merge PR → auto-deploy
`feature/*` / PR	Preview (unikátní URL per PR)	Push → Vercel auto-preview

Žádná staging větev — zbytečná merge complexity pro jednoho vývojáře.

Vercel konfigurace

Production Branch:  main
Preview Branches:   * (všechny ostatní)
Environment Variables:
  Production:  NEXT_PUBLIC_SUPABASE_URL = <prod>
  Preview:     NEXT_PUBLIC_SUPABASE_URL = <staging>

Backend staging

Služba	Staging	Produkce
Supabase	`sofie-staging` projekt	`sofie-prod` projekt
n8n	Workflow s tagem `staging` (neaktivní)	Workflow s tagem `production` (aktivní)
BookStack	Sdílená instance	Sdílená instance
GCP Bucket	`sofie-media-staging`	`sofie-media`

Flow

┌──────────────────────────────────────────────────┐
│                 DEV (lokální)                     │
│  Next.js (pnpm dev) ←→ Supabase CLI (Docker)    │
│  Migrace: supabase migration new → test → commit │
└──────────────────┬───────────────────────────────┘
                   │ git push (feature branch)
                   ▼
┌──────────────────────────────────────────────────┐
│              PREVIEW (per-PR)                     │
│  Vercel preview URL ←→ Supabase staging           │
│  supabase db push --linked (staging)              │
│  Ředitel testuje na preview URL                   │
└──────────────────┬───────────────────────────────┘
                   │ merge PR to main
                   ▼
┌──────────────────────────────────────────────────┐
│              PRODUCTION                           │
│  app.sofie.education ←→ Supabase prod             │
│  supabase db push --linked (prod)                 │
│  n8n workflow activate                            │
└──────────────────────────────────────────────────┘

Checklist pro deploy

Migrace otestovaná lokálně (supabase db reset)
PR vytvořen, Vercel preview funguje
Migrace pushnutá na staging Supabase
Ředitel otestoval na preview URL
PR merged → Vercel auto-deploy to prod
Migrace pushnutá na prod Supabase
n8n workflow aktivován (pokud změněn)
Smoke test (chat, CC email, KB lookup)

7. Denní development workflow

Lokální vývoj

supabase start                  # Lokální Supabase (Docker)
cd web && pnpm dev              # Next.js na localhost:3000

Supabase CLI spustí Postgres, Auth, Storage, Studio (localhost:54323).

Změna DB

supabase migration new popis → napiš SQL → supabase db reset (smaže + znovu aplikuje) → commitni s frontend kódem.

Vždy migrace PŘED frontendem — DB o krok napřed, frontend se adaptuje.

n8n workflow nasazení

Vytvoř/uprav workflow, tag staging, neaktivní
Otestuj s testovacími daty (credentials → sofie-staging)
Přetaguj na production, aktivuj (credentials → sofie-prod)
Exportuj JSON do n8n/, commitni

Monitoring (minimum)

Nástroj	Co sleduje	Cena
Uptime Robot	Dostupnost app/ai/wiki.sofie.education	Zdarma
Vercel Analytics	Frontend performance	Free tier
Supabase Dashboard	DB velikost, API, Auth logy	Součást plánu
GCP Monitoring	VM CPU/RAM/disk	Součást GCP
n8n Execution Log	Chyby ve workflow	Součást n8n

Feedback loop: učitelé → vývoj

Primární: Učitel → Sofie chat → Gemini structured output → GitHub Issue → dev notifikace.

Záloha: Google Form (kdo, typ, popis) → Google Sheets → volitelně n8n → GitHub Issue.

Metriky úspěchu (za 1 měsíc)

Metrika	Cíl	Jak měřit
Ředitel používá chat/CC	Denně	n8n execution log
KB má reálný obsah	> 30 stránek	BookStack API
CC emaily zpracované	> 50	n8n log
FAQ odpovědi z RAG	> 10 automatických	n8n log
Budget	< $40/měs	GCP billing
VM RAM utilization	< 80 %	GCP monitoring

Backlog — Fáze 2+

Poslední aktualizace: 2. dubna 2026

Tento dokument shrnuje plánované funkce a rozhodnutí pro fáze po MVP. Položky jsou seřazeny podle priority a fáze.

RFC: Universal Knowledge Graph

Univerzální knowledge graph jako základ pro celý systém — content-agnostic graf myšlenek/nodů s AI overlay, který dynamicky generuje kontext per role.

→ RFC-knowledge-graph.md

Fáze 2: Teacher Tools

PM Kanban (vlastní modul v Kosmu)

Jednoduchý interní PM přímo v Kosmu. Detailní specifikace viz Příloha: PM modul na konci dokumentu.

Rozhodnutí: Vlastní modul místo SaaS. Důvod: jedna appka, nativní Gemini integrace, přepis porady → úkoly automaticky. Fallback: Trello/Todoist.

Portfolio upload

Učitel nahrává fotky práce žáků + popis. Základ pro rodičovský feed (Fáze 3).

Upload přes Kosmo UI → GCS bucket
Gemini Vision auto-popis fotky
Vazba na žáka, třídu, datum

Generování dokumentů (WYSIWYG + Typst → PDF)

Škola dnes plní Word šablony ručně. Řešení: WYSIWYG editor (TipTap v2) v Kosmu, kde ředitel tvoří šablony s proměnnými a sekretářka jedním klikem generuje PDF.

Editor: TipTap v2 s custom variable chips (inline {{student.fullName}})
Pipeline: Markdown → resolve proměnných z DB → MD → Typst → PDF
Typst: Moderní alternativa LaTeXu, ~30 MB binary, kompilace <1s
Školní šablona: Záhlaví (logo + adresa), patička (IČO, kontakty), font Inter
Batch: Generování pro celou třídu/školu najednou (n8n loop)
AI asistence (Sofie): Draftování šablon, vylepšení textu, GDPR formulace
Tabulky: document_templates, document_template_versions, generated_documents

Otevřené otázky (dokumenty): - D1) Font: výchozí Typst, nebo bundlovat Inter? - D2) Logo školy — potřeba SVG/PNG pro záhlaví - D3) Role v profiles: sloupec role nebo separátní user_roles? - D4) Podpisové pole v PDF? - D5) Archivace: PDF permanentně do GCS, nebo generovat on-demand? - D6) Email: odeslat PDF rodičům přímo?

Generování pracovních listů (Sofie chat → Typst → PDF)

Učitel popíše požadavek v chatu → Sofie (Gemini Flash) vygeneruje Typst markup → typst compile → PDF ke stažení.

Workflow: Chat trigger (ai.sofie.education) → AI Chain → extract Typst → compile → PDF
Typst šablona (worksheet.typ): Helper funkce #exercise(), #fill-blank(), #choice(), #instructions()
Error handling: Při chybě kompilace → Gemini opraví (max 1 retry)
Iterace: Window Buffer Memory (10 zpráv) pro úpravy
Infra: Custom n8n Dockerfile s Typst binary, sdílené s dokumentovým systémem

Otevřené otázky (pracovní listy): - W1) Font: výchozí Typst, nebo bundlovat vlastní? - W2) Logo školy v hlavičce? - W3) Kam učitelé přistupují — stávající ai.sofie.education, nebo dedikovaný endpoint? - W4) Ukládat historii vygenerovaných listů?

Hlasový debrief

Přepis porady → extrakce úkolů → automatické vytvoření v PM modulu.

Nahrávka (telefon) → Gemini přepis → extrakce "kdo, co, do kdy" → úkoly v Kosmu

Pro MVP: manuálně přes Google AI Studio (zdarma, až 3h přepis)
Budoucí: Google Meet „Take notes for me" (vyžaduje Business Standard)

Listmonk již běží na VM (newsletter.sofie.education). Plán pro aktivní využití:

~150 rodin, měsíční newsletter
SMTP: Google Workspace (limit ~2 000/den) nebo Resend (3 000/měs zdarma)
Gemini workflow: Konec měsíce → Gemini projde fotky, projekty, poznámky → draft newsletteru → ředitel schválí → Listmonk odešle
Lead magnet: „5 Montessori aktivit — PDF zdarma" → email → Listmonk segment „zájemci" → nurturing → den otevřených dveří

Rozhodnutí: Listmonk zůstává (256 MB RAM, dělá jednu věc dobře). Mailchimp zamítnut (limit 500, branding v patičce).

Fáze 2: Montessori kurikulum (Transparent Classroom → Kosmo)

Transparent Classroom (TC) je nasazený, ale UX je zastaralé (design z 90. let). Jediná jeho hodnota je strukturované Montessori kurikulum. Cíl: vytáhnout kurikulum přes TC API, uložit lokálně do Kosma a použít jako kontext pro AI-driven tracking kompetencí.

Datový model — 3 nové tabulky

montessori_areas        — oblasti (Practical Life, Sensorial, Math, Language, Cultural)
  id, name, name_cs, tc_id, sort_order

montessori_lessons      — lekce a skupiny lekcí (flat s parent referencí)
  id, area_id FK, parent_id FK (nullable), tc_id,
  name, name_cs, level ('lesson_set'|'lesson'),
  age_range, description, sort_order

montessori_rvp_mapping  — mapování Montessori → RVP (many-to-many)
  id, lesson_id FK, rvp_code, rvp_name,
  confidence (0.0–1.0), is_verified BOOLEAN

Plus montessori_lesson_id UUID FK na existující competency_records.

Proč odděleně od RVP: Montessori kurikulum je pedagogická struktura, RVP je regulatorní. Many-to-many vztah — jedna lekce pokrývá víc RVP kódů a naopak.

Import kurikula (n8n workflow)

TC má REST API (/api/v1/) s token auth. Klíčové endpointy: - GET /lesson_sets.json — strom oblastí a skupin lekcí - GET /lessons.json — jednotlivé lekce

Workflow "TC Curriculum Import": 1. Manual Trigger (jednorázový, re-runnable) 2. HTTP Request → TC API s X-TransparentClassroomToken header 3. Code Node → transformace na Kosmo schéma, zachovat tc_id 4. Postgres Node → UPSERT do tabulek (on conflict tc_id = idempotentní) 5. Gemini Flash → vygenerovat české překlady name_cs (~$0.01)

Kurikulum se mění max 1×/rok. Celkem ~200–500 položek.

AI mapování na RVP (n8n workflow)

Workflow "Generate RVP Mappings": 1. Načíst všechny montessori_lessons 2. Gemini Flash — batch prompt (po 20–30 lekcích): „Pro každou lekci identifikuj RVP ZV kódy, vrať JSON" 3. INSERT do montessori_rvp_mapping s is_verified = false 4. Učitelé postupně ověřují přes UI

Cena: ~$0.05 za celý mapping.

Rozšíření AI pipeline (Gemini Vision)

Aktuální plán: Fotka → Gemini Vision → competency_records

Rozšířený pipeline: Fotka → načti Montessori lekce pro oblast → Gemini Vision → competency_records (s montessori_lesson_id + RVP kódem)

Gemini Vision prompt dostane kurikulum jako kontext:

Analyzuj fotku studentské práce.
Dostupné Montessori lekce pro tuto oblast:
- Golden Bead Addition (Sčítání se zlatým materiálem) → RVP M-3-1-01
- Stamp Game Subtraction (Odčítání s kolkovou hrou) → RVP M-3-1-02
...
Identifikuj: kterou lekci práce demonstruje, úroveň zvládnutí, RVP kódy.

Jedna oblast = 30–80 lekcí → bez problémů se vejde do kontextového okna.

Prerekvizity

TC API token — školní admin: TC Settings → API → vygenerovat token
Zmigrovaná competency_records tabulka (zatím jen v docs, ne v migrations)

Otevřené otázky (TC)

TC1) Má škola přístup k TC API? (ověřit s adminem)
TC2) Které Montessori programy jsou v TC aktivní? (AMI Primary? Elementary?)
TC3) Chceme jednorázově importovat i pokrok dětí z TC? (nízká priorita)
TC4) Kdo bude ověřovat RVP mapping? (ředitel? učitelé?)

Fáze 3+: Learning Tools

Adaptivní vzdělávací platformy pro žáky (4.–7. třída, bilingvální Montessori). Cíl: 360° profil učení každého žáka v Kosmu.

Doporučené platformy

Tier	Platforma	Cena	Integrace do Kosma
1	Khan Academy	Zdarma	Přes Google Classroom
1	Brilliant.org	Zdarma (Educators program)	Přes Google Classroom
1	IXL	~$10/žák/měs	Přímá (LTI v1.3 + API)
2	Eduten	~$15–36/žák/rok	Bez API
2	Matika.in	Zdarma (Hejný)	Bez API

Plán integrace

Ihned: Doporučit Khan + Brilliant + Matika.in (zdarma, 0 effort)
Fáze 2: Sekce „Rozšiřující práce" v Kosmu — kurátorované odkazy (~4–8h dev)
Fáze 3: Google Classroom jako hub (~16h dev)
Fáze 4: IXL přímá LTI v1.3 integrace (~16–24h dev)
Fáze 5: Sokratův průvodce — Gemini agreguje data a navrhuje learning path

Otevřené otázky (learning tools): - L1) Investovat do IXL licence? - L2) Vyzkoušet Eduten trial? - L3) Google Classroom jako prostředník? - L4) Od jaké třídy samostatná práce? - L5) Matika česky nebo anglicky? - L6) Které platformy povinné pro sledování žáka? - L7) Ručně doplňovat data z platforem bez API?

Fáze 3+: Marketing a komunikace

Filozofie: žádné reklamy, žádné slogany. Pouze hodnotný obsah — autentický příběh, zprostředkování emoce.

Vrstvy obsahu

Vrstva hodnoty — SEO články 2x/měs („Jak vypadá den čtvrťáka u nás vs. na běžné ZŠ")
Vrstva emoce — Instagram Reels, fotopříběhy 3–4x/týden
Vrstva expertízy — thought leadership 1x/měs (LinkedIn, blog)
Vrstva komunity — doporučení, veřejné akce, rodičovská komunita
Montessori zdroje — tipy, aktivity, materiály k tisku (lead magnety)

Gemini jako content engine

Z jednoho vstupu (poznámka učitele + 5 fotek) → obsah pro 3 kanály za 5 minut:

Učitel nafotí/napíše poznámku → Gemini vygeneruje IG caption + blogpost + newsletter snippet
→ Ředitel schválí → Kosmo publikuje přes API (IG Graph, FB Pages, Listmonk)

Priorita kanálů

Google Business (zdarma, lokální SEO)
Instagram (emoční obsah, Reels)
Blog na webu (SEO, „Montessori škola Říčany")
Newsletter (nurturing zájemců)
Facebook (lokální komunita)

Předpoklady k ověření s ředitelem

Logo ve vysoké kvalitě (SVG/PNG)
GDPR souhlasy na fotky dětí pro veřejné kanály
Google Business profil — existuje? aktuální?
Instagram/Facebook účet — kdo spravuje?
Branding: tón komunikace, hodnoty, příběh zakladatele

Fáze 3+: Web (sofie.education)

Škola má dva WordPress weby (ms-sofie.cz, zs-sofie.cz). Cíl: sjednotit pod sofie.education.

Fáze	Stav
Teď	WordPress zůstává, Kosmo na `app.sofie.education`
Léto 2026	Migrace statického webu do Next.js, jedna doména `sofie.education`

Cílový stav: Web + blog + aplikace na jednom Next.js stacku. Obsah přes MDX nebo headless CMS (Sanity/Strapi).

Fáze 3+: Gamifikace

Odznaky, streaky, osobní milníky — motivace žáků. Ale Montessori filozofie odmítá soutěžení a vnější motivaci.

Otevřená otázka: Gamifikace ano / ne / „jemná" verze (bez soutěžení, jen osobní milníky)?

Starší žáci potřebují přístup ke svému portfoliu, nahrávání projektů, Sokratův průvodce.

Varianta	Popis
Školní Google účet	Po migraci na Google Workspace
QR kód / PIN	Fyzická karta
Rodičovský účet	Sdílený přístup

Otevřené otázky: - 7a) Jak se přihlásí žák? - 7b) Od jaké třídy vlastní přístup?

Fáze 4+: Sokratův průvodce

Gemini AI jako personalizovaný tutor pro žáky. Sokratovská metoda — neptá se „jaká je odpověď?" ale „jak jsi na to přišel?".

Agreguje data ze všech vzdělávacích platforem + interní evidenci
Navrhuje žákovi personalizovaný learning path
Inspirace: Khan Academy Khanmigo

Fáze 4+: Podpora rodičů

Feed (/feed) — timeline aktivit dítěte (fotky, projekty, hodnocení)
Adaptivní summary — Gemini shrne co se změnilo od poslední návštěvy
Sofie chat pro rodiče — FAQ, omluvenky, vyzvedávání
Multi-child feed s filtrem (rodič s více dětmi)
Push notifikace (PWA)

Otevřená rozhodnutí (nerozřešená)

Následující rozhodnutí z DECISIONS_OPEN.md zatím nemají finální odpověď:

#	Téma	Urgence	Poznámka
7	Login dětí	Fáze 3+	Školní Google účet / QR / PIN?
8	Gamifikace	Fáze 3+	Montessori vs. motivace
L1–L7	Learning Tools	Fáze 3+	IXL licence, GC integrace, jazyk matiky
D1–D6	Generování dokumentů	Fáze 2	Font, logo, role, archivace
W1–W5	Pracovní listy	Fáze 2	Font, logo, archiv PDF

Příloha: PM modul (detail)

TL;DR

Rekurzivní hierarchie projektů (projekt → podprojekty → …), membership-based viditelnost, AI-generované summary. 3 tabulky, 4 enumy.

Datový model

CREATE TYPE public.project_status AS ENUM ('draft', 'active', 'done', 'cancelled');
CREATE TYPE public.subproject_priority AS ENUM ('required', 'nice_to_have');
CREATE TYPE public.project_member_role AS ENUM ('leader', 'collaborator');
CREATE TYPE public.resource_kind AS ENUM ('file', 'link', 'note');

projects — rekurzivní hierarchie (parent_id → self). Top-level = parent_id NULL. Sloupce: id, parent_id, title, description, leader_id, status, priority, due_date, ai_summary, timestamps. ON DELETE CASCADE na parent_id.

project_members — M:N vazba profilů na projekty. UNIQUE(project_id, profile_id). Role: leader (vše) / collaborator (editace, zdroje).

project_resources — přílohy s diskriminátorem kind (file/link/note). Sloupce: title, url, body, storage_path, ai_summary, uploaded_by.

Viditelnost (RLS)

Viditelnost se dědí dolů, ne nahoru. Member parent projektu vidí všechny podprojekty (rekurzivní CTE). SELECT/INSERT/UPDATE/DELETE pravidla dle role.

Progress tracking

get_project_progress(p_id) — rekurzivní CTE počítá done/total podprojektů → progress bar v UI.

Soubory

GCS bucket projects/{project_id}/{timestamp}_{filename} + sidecar .meta.json. V1 jen linky + poznámky, file upload ve v2.

AI summary

n8n webhook po vytvoření/úpravě projektu → Gemini → souhrn stavu (2–3 věty česky).

UI

/projects              → seznam mých top-level projektů
/projects/new          → nový projekt
/projects/[id]         → detail (podprojekty, progress, tým, zdroje, AI summary)
/projects/[id]/edit    → editace

Implementační kroky

SQL migrace (enumy, tabulky, indexy, RLS, RPC)
Server Actions + Zod validace
UI stránky
Navigace — "Projekty" do layoutu
n8n AI summary workflow
File upload (závisí na GCS signed URL infra)

Plány

Návody

Twenty CRM + Microsoft 365 — návod pro schůzku (2026-03-20)

Cíl: Napojit Twenty CRM (crm.sofie.education) na Microsoft 365 — SSO přihlášení, synchronizace emailů/kalendáře a servisní emaily (reset hesla, pozvánky).

Potřebujeme: Přístup admina do Azure portálu (Entra ID) + Exchange Admin Center pro doménu školy.

Krok 1 — Nová App Registration

Otevřít https://entra.microsoft.com
Identity → Applications → App registrations → + New registration
Vyplnit:
Name: Twenty CRM
Supported account types: Accounts in this organizational directory only (Single tenant)

Redirect URI (Web):

https://crm.sofie.education/auth/microsoft/redirect

Kliknout Register

Krok 2 — Druhý Redirect URI

V nově vytvořené aplikaci → Authentication

+ Add URI a přidat:

https://crm.sofie.education/auth/microsoft-apis/get-access-token

Save

Krok 3 — Client Secret

Certificates & secrets → + New client secret
Description: twenty-crm
Expires: 24 months
Add → ihned zkopírovat Value (zobrazí se jen jednou!)

Zapsat si: - Client ID (ze stránky Overview → Application (client) ID) - Client Secret (právě vytvořený)

Krok 4 — API Permissions

API permissions → + Add a permission → Microsoft Graph → Delegated permissions
Zaškrtnout:
openid
email
profile
offline_access
User.Read
Mail.ReadWrite
Mail.Send
Calendars.Read
Add permissions
Kliknout Grant admin consent for [organizace] → potvrdit Yes

Krok 5 — Ověření

Zkontrolovat, že u všech permissions svítí zelená fajfka "Granted for [organizace]".

SMTP — servisní emaily (reset hesla, pozvánky, notifikace)

Twenty aktuálně nemá nastavený SMTP — nemůže posílat žádné servisní emaily. Použijeme SMTP relay přes M365.

Krok 6 — Povolit SMTP AUTH v Exchange Admin

Otevřít https://admin.exchange.microsoft.com
Recipients → Mailboxes → vybrat účet crm@zs-sofie.cz
V novějším Exchange Admin Center přepínač SMTP AUTH chybí v UI — je nutné použít PowerShell:

# Na Windows otevřít PowerShell, na macOS: brew install powershell && pwsh
Install-Module ExchangeOnlineManagement
Connect-ExchangeOnline
Set-CASMailbox -Identity "crm@zs-sofie.cz" -SmtpClientAuthenticationDisabled $false

Po schůzce (technická část — Docek)

✅ Hotovo — konfigurace je v infra/docker-compose.yml, credentials v infra/.env (proměnné AUTH_MICROSOFT_CLIENT_ID, AUTH_MICROSOFT_CLIENT_SECRET, SMTP_PASS).

Na VM stačí:

cd /data && docker compose up -d twenty twenty-worker

Pak restartovat:

cd /data && docker compose up -d twenty twenty-worker

Známé problémy

Refresh token bug (#18550): Na self-hosted Twenty může po ~1h přestat fungovat sync. Řešení: upgrade Twenty na nejnovější verzi.
First consent race condition (#18405): Při prvním přihlášení může Azure hodit chybu — stačí to zkusit znovu.

Kosmo: Digitální Ekosystém Sofie

Co je součástí ekosystému?

Aplikace Kosmo (Core)

Klíčové vlastnosti

Struktura dokumentace

Rychlý start

Vize projektu Kosmo

O škole

Montessori filosofie

Bilingvální výuka (CLIL)

Struktura školy

Typické akce a zvyky

Kontakty

Problém k řešení

1. Komunikační propast

2. Přetížení školy

3. Fragmentovaná data

Vize: Feed + Sofie

Google Workspace

Aktuální stav

Skupiny

Nástroje pro správu

Google Cloud Platform (GCP)

Migrace z Microsoft 365

Domény

Komunikace školy

Uživatelé a Role

Ředitel

Učitelé (Průvodci)

Rodina (Zástupci dítěte)

Administrativa (Kancelář)

Děti / Žáci (MŠ – 7. třída)

Onboarding rodičů

Flow

Předpoklady

Požadavky (REQUIREMENTS.md)

Funkční požadavky

1. Komunikace s Rodiči (Sofie) — PRIORITA Č. 1

2. Evidence a Hodnocení Žáků — PRIORITA Č. 2

3. Integrace se ŠkolaOnline — PRIORITA Č. 3

4. Docházka a Vyzvedávání (AI Action)

5. Ankety a Sběr Dat (Interaktivní Chat)

6. Sokratův Průvodce — Fáze 4+

7. Podpora Rodičů — Fáze 4+

8. Export Dat (Excellence)

9. Marketing a Komunikace (Newsletter) — Listmonk (Fáze 2+)

10. Generování Metodických Listů — Fáze 2

11. Integrace

12. Notifikace a Upozornění

13. Feed (Killer Feature)

Nefunkční požadavky

Měřitelné cíle (KPI)

Adopce

Efektivita AI

Spokojenost

Architektura

Architektura Aplikace Kosmo

Technologický Stack: "Vibe Stack"

Frontend & Backend (Next.js)

Data & Auth (Supabase)

AI & LLM Orchestrace

Integrace & Nástroje

Feed — Hlavní obrazovka rodiče

Proč Feed?

Struktura feedu

Typy feed items

Multi-child

Sofie Overlay (FAB)

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

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

Skupinový chat / Komentáře — NE

Důsledky pro architekturu

Messaging & Email: Walled Garden (no-reply)

Hlavní Moduly (Aplikace)

1. app/(platform)

2. app/api

3. structure (Organizace školy)

4. evidence (Srdce systému)

5. attendance (AI Action)

6. surveys (Interaktivní Chat)

1. `app/(platform)`

2. `app/api`

3. `structure` (Organizace školy)

4. `evidence` (Srdce systému)

5. `attendance` (AI Action)

6. `surveys` (Interaktivní Chat)

7. `communication` (Sofie Chat)

8. `components/ai`

9. `utils`