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 (podobně jako uv v Pythonu), 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
  • Důvod: Ukládání fotek prací a dokumentů.
• Realtime: Supabase Realtime
  • Důvod: Okamžité notifikace pro rodiče (chat, nové zprávy).

AI & Python (Special Agents)

• Hlavní AI: 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" }).
• Specializované úlohy: Python Scripts / Microservice
  • Pohoda: XML import/export (mServer).
  • ŠkolaOnline: Jednosměrná synchronizace (Master data).
  • Důvod: Využití expertní znalosti uživatele v Pythonu a matematice pro složitější analýzy, generování metodik nebo Sokratova průvodce.
  • Tooling: uv
    • Důvod: Rychlý Python package manager, user choice.
  • Integrace: Může běžet jako Supabase Edge Function (Python support in beta) nebo samostatná služba na Modal/Railway.

Marketingový Stack (FÁZE 2)

• Blog: Next.js + MDX (odloženo — MVP řeší WordPress).
• Newsletter: HubSpot Marketing Hub (Free).
  • Důvod: Integrace s CRM (Leads), kvalitní editor, GDPR compliance.

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 externí nástroje (Make/n8n).
  • Přijímá data (např. parsovaný email), 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)

• WorkItems: Evidence prací žáků (úkoly, projekty, testy).
• 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 (AI Concierge)

• Sofie Bot: Hlavní rozhraní pro rodiče.
  • Funkce: RAG nad daty žáka (Evidence, Docházka) + Knowledge Base školy (ŠVP, Řády).
• Ticket System:
  • Pokud AI nevyřeší dotaz, vytvoří "Ticket".
  • Routing: AI rozhodne, komu ticket přidělit (Třídní učitel / Jídelna / Ředitel).
  • Safety Check: Citlivé akce (Vyzvedávání, Zdraví) vyžadují expliciní potvrzení uživatele (Confirmation UI). AI pouze předpřipraví data, člověk je schválí.
• Email Sender: Notifikace o vyřešení ticketu nebo nové zprávě ze školy.

8. integrations & Externí Nástroje

• CRM: HubSpot (Free):
  • Google Integrace: Gmail Extension (logování emailů), Google Calendar Sync (schůzky).
  • Evidence Leadů a Rodičů.
• Project Management: Asana (Free):
  • Google Integrace: "Turn emails into tasks" (Gmail Add-on), Google Drive attachments.
  • Interní řízení školy.
• ŠkolaOnline/Bakaláři (případně).

9. components/ai

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

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

Bezpečný proces nasazování změn.

1. Local (Vývoj)
   • Kde: localhost:3000
   • Data: Lokální Supabase (Docker)
   • Kdo: Vývojář
2. 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)
3. Production (Ostrý provoz)
   • Kde: app.sofie.education (Vercel Production)
   • Data: Supabase Production Project (ostrá data)
   • Kdo: Všichni uživatelé