Kajet - serwer

Chmura dla notatnika Kajet: konta, synchronizacja notatek z tabletem, udostępnianie linkiem, asystent AI i uruchamianie kodu w kontenerze. Napisane w Next.js 15 (App Router, React 19, TypeScript), z MySQL/MariaDB przez Prismę.

Aplikacja na Androida, która się z tym serwerem synchronizuje, leży w repo kajet_apk.

---

Co to robi

Konta i sesje. Rejestracja e-mailem z potwierdzeniem, logowanie hasłem albo przez Google (NextAuth v5 + adapter Prismy). Osobna ścieżka logowania dla urządzenia - tablet dostaje własny token, więc telefon nie wylogowuje tabletu.

Notatki w chmurze. Prawda o treści notatki to jeden dokument JSON - dokładnie ten sam, który leży w pliku content.json w katalogu notatki na tablecie. Baza trzyma ten dokument plus to, czego w nim nie ma: właściciela, zajęte miejsce i listę udostępnień. Dzięki temu synchronizacja jest porównaniem dwóch dokumentów, a nie tłumaczeniem modelu na model. W bazie dokument leży spakowany (brotli) i tyle też liczy się do limitu miejsca - gęsta notatka odręczna waży tak kilka razy mniej. Na zewnątrz nic się nie zmienia: każda wersja aplikacji i strona dostają zwykły JSON, a notatki zapisane wcześniej serwer pakuje sam w tle.

Rodzaje notatek. Tekstowa (Markdown z tabelami, obrazkami i skalowaniem szerokości), odręczna, mapa myśli, notatka z kodem, podgląd HTML. Każda ma edytor po stronie www, więc notatka zrobiona na tablecie jest edytowalna w przeglądarce i odwrotnie.

Udostępnianie. Link /n/<token> do notatki albo całego folderu (z podfolderami) - do podglądu albo do edycji, z załącznikami i opcjonalnym hasłem. Zwykły link otwiera się tylko na czas oglądania i nigdzie się nie zapisuje. Zaproszenie na adres e-mail trafia do biblioteki odbiorcy („Udostępnione mi" - na stronie i w aplikacji) dopiero wtedy, gdy osoba zalogowana tym adresem sama otworzy odnośnik; skaner linków w poczcie niczego nie przyjmie. Kto ma prawo edycji folderu, dodaje, zmienia i usuwa w nim notatki i podfoldery - wszystko należy do właściciela folderu, liczy się do jego miejsca, a usunięte trafia do jego kosza. Na Androidzie z zainstalowanym Kajetem odnośnik otwiera się od razu w aplikacji.

Edycja na żywo. Kilka osób (i urządzeń) w jednej notatce naraz - tekst, pismo odręczne i mapa myśli, na stronie i w aplikacji. Zmiany idą małymi deltami, a nie całym dokumentem; gdy notatki nikt inny nie ma otwartej, przez sieć nie idzie nic poza krótkim „ping" co 20 s. Zmiany zrobione bez sieci scalają się po powrocie z tym, co w tym czasie zrobili inni: tekst do poziomu słów (prawdziwy konflikt w tym samym miejscu zostawia obie wersje, jedna pod drugą), kreski zawsze się sumują, a przy tym samym węźle mapy wygrywa późniejsza zmiana.

KajetAI. Asystent oparty o Gemini (@google/genai), który edytuje notatkę narzędziami (a nie przez podmianę całego tekstu): zna markdown Kajetu, limity dzienne, zgodę użytkownika na przetwarzanie treści i historię swoich zmian, żeby dało się je cofnąć.

Uruchamianie kodu. Notatka z kodem może zostać wykonana w izolowanym kontenerze Dockera, z limitem czasu i liczby uruchomień na minutę. Domyślnie wyłączone (CODE_ENABLED=false).

Panel administratora. Konta i blokady, limity miejsca, wydania aplikacji na Androida (upload APK + notatki wydania), zgłoszenia awarii z tabletu, log akcji, limity KajetAI.

Dwujęzyczność. Cały interfejs idzie przez słownik (src/lib/i18n.ts) - polski i angielski, bez tekstów zaszytych w komponentach.

---

Stos

Warstwa	Technologia
Aplikacja	Next.js 15 (App Router), React 19, Server Actions
Język	TypeScript, walidacja wejścia przez Zod
Baza	MySQL / MariaDB + Prisma 6
Sesje	NextAuth v5 (credentials + Google)
AI	Google Gemini (@google/genai)
Poczta	Nodemailer (SMTP)
Testy	Vitest
Uruchamianie kodu	Docker (osobny obraz kajet-runner)

Układ katalogów

src/app/          strony i API (App Router)
  api/v1/         REST dla aplikacji na Androida: notatki, foldery, sync, konto, kod, awarie
  admin/          panel administratora
  api/v1/live/    edycja na żywo: strumień zmian (SSE) i wysyłanie delt
  api/v1/shared/  „udostępnione mi", otwieranie odnośników, praca w udostępnionym folderze
  n/[token]/      udostępniona notatka albo folder
  library/        biblioteka notatek zalogowanego użytkownika
src/components/   edytory (tekst, odręczne, mapa myśli, kod) i reszta UI
src/lib/          logika: auth, synchronizacja, limity, markdown, KajetAI, wydania APK
  live/           scalanie i delty (te same zasady co w aplikacji - wspólne przypadki
                  testowe w live-vectors.json), szyna zmian, dziennik LiveChange
prisma/           schemat bazy
scripts/          narzędzia serwisowe (migracje, wdrożenie, kontrola stanu, konta administratorów)
docker/           obraz do uruchamiania kodu + konfiguracja MySQL

Uruchomienie

cp .env.example .env     # uzupełnij bazę, AUTH_SECRET, SMTP
npm install
npm run db:push          # schemat do bazy
npm run dev              # http://localhost:9081

Przydatne skrypty:

npm test          # Vitest
npm run typecheck # tsc --noEmit
npm run build     # generuje klienta Prismy i buduje Next.js
npm run konta     # konta administratorów - patrz niżej (panel tego nie robi)
npm run sprawdz   # kontrola stanu działającego serwera

Wszystkie ustawienia są w .env - jego wzór z opisem każdej zmiennej leży w .env.example. Prawdziwy .env, katalog data/ z notatkami użytkowników i zrzuty bazy nigdy nie trafiają do repozytorium.

Wdrożenie edycji na żywo i odnośników do aplikacji

Baza. Po aktualizacji kodu raz, ręcznie, na serwerze:

npm run db:apply

Zmiana tylko dokłada: kolumny folderId, acceptedById i acceptedAt w Share (noteId może być teraz puste - udostępnienie folderu), version i clientId w LiveChange oraz indeksy. Nic nie jest kasowane.

This is the beginning of the README. Read the rest at the original. Read the full README ↗