Implementacja — Przegląd

Wprowadzenie

Ta sekcja opisuje jak budujemy Lumos Islands — tech stack, architekturę, design systemy i kluczowe decyzje technologiczne.

Ekosystem Techniczny

┌─────────────────────────────────────────────────────────────────┐
│                      LUMOS ISLANDS v2                            │
└─────────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              │               │               │
    ┌─────────▼──────────┐   ┌▼────────────────────┐  ┌▼──────────────┐
    │    FLUTTER APP      │   │  MANAGER-CONTENT     │  │  IDEA (docs)  │
    │  (iOS + Android)    │   │  (Go — web + API)    │  │  VitePress    │
    │                     │   │                      │  │               │
    │  Dart/Flutter       │   │  Web UI:             │  │  Markdown     │
    │  Widgetbook         │   │   Alpine.js, HTMX    │  │  TypeScript   │
    │  Riverpod           │   │   TailwindCSS        │  │               │
    │  GoRouter           │   │                      │  │               │
    └─────────┬──────────┘   │  /app/* (Flutter)    │  └───────────────┘
              │               │  /api/* (manager)    │
              │  /app/*       │   Auth, Database     │
              └──────────────▶│                      │
                              └──────────────────────┘

Manager-content pełni podwójną rolę:

1. Web UI — panel dla rodzica/szkoły (SSR + HTMX + Alpine.js)
2. Endpointy /app/* — REST/JSON dla Flutter app
3. Endpointy /api/* — REST/JSON do integracji z managerem (jeśli potrzebne)

Aplikacje

Flutter App (app/)

Aplikacja mobilna dla rodzica i dziecka. Priorytet: iOS, z wsparciem Android.

Aspekt	Technologia
Framework	Flutter / Dart
Platformy	iOS (priorytet) + Android
State management	Riverpod
Routing	GoRouter
Design system	Komponentowy, z Widgetbook (storybook)
HTTP	Dio
Testy	Widget tests + integration tests

Szczegóły: Flutter App

Manager-Content (manager-content/)

Serwer Go z trzema interfejsami: web UI dla rodzica/szkoły, endpointy /app/* dla Flutter app i /api/* do ewentualnych integracji z managerem.

Aspekt	Technologia
Backend	Go (net/http, chi router)
Frontend (web UI)	Alpine.js + HTMX
Styling	TailwindCSS
Rendering	Server-side (SSR) + progressive enhancement
Templating	Go html/template
/app/*	Endpointy REST/JSON dla Flutter app
/api/*	Endpointy REST/JSON do integracji z managerem
Design system	Odseparowany, komponenty UI

Szczegóły: Manager-Content

Design Systemy

Obie aplikacje mają odseparowane design systemy z własnymi tokenami, komponentami i narzędziami do przeglądania.

Aplikacja	Narzędzie	Podejście
Flutter App	Widgetbook	Komponentowy storybook w Dart
Manager-Content	Dedykowana strona	Komponenty HTMX + TailwindCSS

Wspólne elementy: kolory brand, typografia, spacing, zasady projektowe.

Szczegóły: Design Systemy

Architektura Wysokopoziomowa

┌─────────────────┐         ┌──────────────────────────────┐
│   Flutter App   │         │       Manager-Content        │
│                 │         │       (Go server)            │
│  ┌───────────┐  │         │                              │
│  │ UI Layer  │  │         │  ┌─────────┐  ┌───────────┐ │
│  │ (Widgets) │  │         │  │ Web UI  │  │  REST API │ │
│  └─────┬─────┘  │         │  │ (HTMX)  │  │  (JSON)   │ │
│  ┌─────▼─────┐  │         │  └────┬────┘  └─────┬─────┘ │
│  │ State     │  │         │       │              │       │
│  │ (Riverpod)│  │         │  ┌────▼──────────────▼────┐  │
│  └─────┬─────┘  │         │  │      Handlers (chi)   │  │
│  ┌─────▼─────┐  │         │  └───────────┬───────────┘  │
│  │ Repository│  │ REST/   │  ┌───────────▼───────────┐  │
│  │ (Dio)     │──┼─JSON───▶│  │      Services        │  │
│  └───────────┘  │         │  └───────────┬───────────┘  │
└─────────────────┘         │  ┌───────────▼───────────┐  │
                            │  │      Database         │  │
                            │  └───────────────────────┘  │
                            └──────────────────────────────┘

Flutter app komunikuje się z manager-content przez endpointy /app/* (JSON). Endpointy /api/* są zarezerwowane do integracji z managerem. Web UI jest renderowane przez osobne handlery (HTML). Dzięki temu trzy interfejsy są wyraźnie rozróżnione.

Kluczowe Decyzje Technologiczne

Flutter zamiast React Native

• Wydajny rendering na iOS i Android z jednego codebase
• Lepsza kontrola nad UI (globus, animacje, mapy)
• Silny typing z Dart
• Widgetbook jako natywny storybook

Go zamiast Node.js dla manager-content

• Prostota i wydajność
• Szybki start serwera, niskie zużycie pamięci
• Server-side rendering bez ciężkiego frameworka JS
• Jeden binarka do deploymentu

HTMX + Alpine.js zamiast SPA

• Progressive enhancement — działa bez JS, wzbogacone z JS
• Mniejszy bundle, szybsze ładowanie
• Server-side logic w Go, minimalna logika na frontendzie
• Prostsze utrzymanie niż pełny SPA framework

Odseparowane design systemy

• Każda aplikacja ma swój kontekst (mobile vs web)
• Wspólne tokeny brand (kolory, typografia) utrzymywane centralnie
• Niezależny rozwój komponentów w każdej aplikacji

Nawigacja Sekcji

• Flutter App — architektura, ekrany, state management
• Manager-Content — Go web app, SSR, HTMX
• Design Systemy — tokeny, komponenty, storybooki
• Infrastruktura — Supabase, Docker, CI/CD, JWT, deployment
• API Endpointy — pełna dokumentacja REST API (/app/*, /api/*, web routes)
• Ekrany Flutter — szczegółowe opisy ekranów aplikacji mobilnej
• Ekrany Manager — Apple-style design, ekrany panelu webowego