sendewerk/docs/DECISIONS.md

Entscheidungen

Stand der Quellenprüfung: 21. Oktober 2026. Verwendet wurden offizielle Dokumentationen und die npm-Registry für konkrete Paket-Metadaten.

D-001: SvelteKit 3 und Node-Unterstützung

Die Anwendung verwendet SvelteKit 3, Svelte 5, TypeScript und Vite 8. Das Projekt wurde gemäß aktueller Empfehlung mit npx sv create angelegt. Die Kit-Konfiguration liegt bei SvelteKit 3 in vite.config.ts, nicht in einer svelte.config.js.

Die lokale Mindestversion ist Node 22.17. Das Cloudron-Image nutzt Node 24 LTS. Der vorhandene lokale Lauf wurde mit Node 22.23.1 geplant.

Quellen:

• https://svelte.dev/docs/kit/creating-a-project
• https://svelte.dev/docs/kit/migrating-to-sveltekit-3
• https://svelte.dev/docs/cli/sv-create
• npm-Metadaten für @sveltejs/kit 3.1.0 am 21.10.2026

D-002: Offizieller Node-Adapter

@sveltejs/adapter-node erzeugt den Produktionsserver in build/. Gebaut wird mit npm run build, gestartet mit node build. HOST und PORT konfigurieren den Server. Der Adapter behandelt SIGTERM/SIGINT und kontrolliertes Herunter- fahren; ein eigener Server ist für Etappe 1 nicht erforderlich.

Quelle: https://svelte.dev/docs/kit/adapter-node

D-003: SQLite mit better-sqlite3

better-sqlite3 13.x wird als gekapselter synchroner Treiber verwendet. Das Paket ist MIT-lizenziert und verlangt Node 22 oder neuer. Gegenüber node:sqlite wird damit in Etappe 1 keine API verwendet, die in der offiziellen Node-24-Dokumentation noch als Release Candidate gekennzeichnet ist. Die Datenbankgrenze bleibt in src/lib/server gekapselt.

Migrationen sind eigene nummerierte SQL-Dateien und laufen transaktional. WAL wird in Etappe 1 nicht aktiviert; für die kleine Redaktion ist das Rollback-Journal zunächst ausreichend und vereinfacht die frühe Betriebsprüfung.

Quellen:

• https://nodejs.org/docs/latest-v24.x/api/sqlite.html
• https://www.sqlite.org/lang_transaction.html
• npm-Metadaten für better-sqlite3 13.0.3 am 21.10.2026

D-004: Cloudron-Paket

Das Paket nutzt manifestVersion: 2, internen HTTP-Port 3000 und /healthz. localstorage.sqlite.paths nennt /app/data/sendewerk.sqlite, damit Cloudron eine konsistente Sicherung der aktiven SQLite-Datei erstellen kann. Das Startskript stellt Verzeichnisse und Besitzrechte her, migriert als Benutzer cloudron und ersetzt sich zuletzt per exec durch den Node-Prozess.

Das Image ist auf die am 21.10.2026 offiziell dokumentierte datierte Node-24- Basis samt Digest gepinnt. Außer /app/data, /run und /tmp wird das Laufzeitdateisystem als read-only behandelt.

Quellen:

• https://docs.cloudron.io/packaging/
• https://docs.cloudron.io/packaging/manifest/
• https://docs.cloudron.io/packaging/addons/#localstorage
• https://docs.cloudron.io/packaging/cheat-sheet/

D-005: Theme ohne serverseitiges Nutzerkonto

Etappe 1 speichert light, dark oder system in localStorage. Ein kurzes Inline-Skript in app.html setzt das resultierende Theme vor dem ersten Paint auf dem Wurzelelement. Dies vermeidet einen falschen Theme-Blitz und benötigt vor Etappe 2 weder Cookie noch Konto. Die Einstellung bleibt bei Neuladen im gleichen Browser erhalten.

D-006: Etappe-1-Vorschauen statt Attrappen

Vorschauseiten lesen echte persistente SQLite-Seed-Daten, bieten aber keine funktionslosen Speichern- oder Live-Schaltflächen. Ein sichtbarer Hinweis grenzt Gestaltungsvorschauen von den späteren Fachfunktionen ab. Damit wird keine noch nicht implementierte Funktion als fertig dargestellt.

D-007: Arbeitsansicht nach verfügbarem Platz

Die feste Desktop-Seitenleiste wird bis 52rem verwendet und dann vollständig durch mobile Kopf- und Fußnavigation ersetzt. Der Sendungsbau schaltet bereits bis 72rem von zwei Spalten auf eine bedienbare Pane-Umschaltung um. Dadurch bleibt die Desktopnavigation in schmalen Fenstern erhalten, ohne Fundus und Ablauf zusammenzudrücken.

Der Fundus erscheint auf dem Desktop als kompakte Liste und auf kleinen Bildschirmen als Kartenfolge. Vorschau- und Schreibschutzinformationen sind in einem nativen, tastaturbedienbaren details-Element gebündelt. Diese Darstellungsentscheidung ändert weder Datenmodell noch Funktionsumfang.

D-008: Widerrufbare Datenbanksitzungen und Argon2id

Sendewerk verwendet Datenbanksitzungen statt JWT. SvelteKit empfiehlt diesen Ansatz, wenn sofortiger Widerruf wichtiger als eine zusätzliche Datenbankabfrage ist. Ein zufälliges Sitzungstoken liegt nur als SHA-256-Hash in SQLite; der Browser erhält es als HttpOnly-, SameSite=Lax-Cookie. Nutzerstatus und Rolle werden bei jedem Request erneut verbunden. Lokal erlaubt eine explizite http:-Origin Cookies ohne Secure, bei https: wird Secure gesetzt.

Passwörter hasht @node-rs/argon2 2.2.2 mit Argon2id und den dokumentierten Paketparametern. Zufallstokens und SHA-256 stammen aus node:crypto; eigene Kryptoprimitive werden nicht implementiert.

Quellen:

• https://svelte.dev/docs/kit/auth
• https://svelte.dev/docs/kit/hooks
• https://github.com/napi-rs/node-rs/tree/main/packages/argon2

D-009: Form-Actions, geschlossenes Setup und Rollenprüfung

Alle Auth-Schreibvorgänge verwenden POST-Form-Actions beziehungsweise einen POST-Endpunkt. SvelteKits gleichursprüngliche Formularprüfung bleibt aktiv. Der Erstadmin erfordert ein mindestens 32 Zeichen langes Betreiber-Setup-Token und eine transaktional geprüfte leere Nutzertabelle. Danach bleibt /setup geschlossen. Barkeeper-Rechte werden in jeder Verwaltungsaktion erneut geprüft; UI-Sichtbarkeit ist keine Sicherheitsgrenze.

Quelle: https://svelte.dev/docs/kit/form-actions

D-010: Lokale Mail-Outbox als sichere Vorgabe

Der Mailmodus ist standardmäßig local und schreibt Einladungs-/Resetnachrichten in einen konfigurierten persistenten Pfad. Dadurch wird lokal keine echte Mail ungefragt versandt. Nur die explizite Auswahl smtp initialisiert Nodemailer; bei SMTP sind Host und Absender verpflichtend. Outbox-Dateien sind private Geheimnisträger und werden weder versioniert noch über eine Route ausgeliefert.

Nodemailer 10.1.7 unterstützt Node 20 oder neuer und ist MIT-0-lizenziert. Quelle: https://github.com/nodemailer/nodemailer