docs(frontend): add detailed offline-first architecture and web setup documentation

Added documentation to outline the Offline-First strategy for the KMP frontend, emphasizing the use of SQLDelight with cross-platform storage. Also included guidance for setting up Web targets, covering OPFS integration and Web Worker usage. Updated ADRs with decisions for SQLDelight and Koin adoption.
2026-01-13 15:59:25 +01:00
parent 8362a8b11d
commit bf8facfa66
10 changed files with 359 additions and 62 deletions
@@ -0,0 +1,34 @@
+# Web-Setup (Webpack & Worker)
+
+Dieses Dokument beschreibt die spezifische Konfiguration für das Web-Target (JS/Wasm) des KMP-Frontends.
+
+## OPFS (Origin Private File System)
+
+Um eine performante und persistente Speicherung der SQLDelight-Datenbank im Browser zu ermöglichen, verwenden wir das **Origin Private File System (OPFS)**. Die Nutzung von OPFS erfordert, dass die Webseite in einem "cross-origin isolated"-Kontext läuft.
+
+### HTTP-Header
+
+Dazu müssen die folgenden HTTP-Header vom Webserver ausgeliefert werden:
+
+*   `Cross-Origin-Opener-Policy: same-origin`
+*   `Cross-Origin-Embedder-Policy: require-corp`
+
+### Webpack Dev Server
+
+Für die lokale Entwicklung wird der Webpack Dev Server verwendet. Um die erforderlichen Header zu setzen, wurde die `webpack.config.d/opfs-headers.js`-Datei erstellt, die die Header zur Konfiguration des Dev Servers hinzufügt.
+
+## Web Worker für SQLDelight
+
+Um die UI nicht zu blockieren, werden alle Datenbank-Operationen in einem separaten **Web Worker** ausgeführt.
+
+*   **`sqlite.worker.js`:** Ein benutzerdefinierter Worker, der die SQLDelight-Datenbank initialisiert und die Anfragen vom Haupt-Thread entgegennimmt.
+*   **`WebWorkerDriver`:** Der SQLDelight-Treiber, der die Kommunikation zwischen dem Haupt-Thread und dem Worker-Thread managed.
+
+## Build-Konfiguration
+
+*   **`build.gradle.kts`:** Im `build.gradle.kts` des `meldestelle-portal`-Moduls wird das `wasmJs` oder `js` Target entsprechend konfiguriert, um die Web-Anwendung zu bauen.
+*   **Webpack-Integration:** Die Gradle-Plugins für KMP/JS und Compose for Web kümmern sich um die Integration mit Webpack und die Erstellung des finalen JavaScript-Bundles.
+
+## Aktueller Blocker (Januar 2026)
+
+Derzeit ist der Build für das `wasmJs`-Target aufgrund von Compiler-Fehlern im Zusammenhang mit dem JS-Interop und fehlenden DOM-API-Referenzen blockiert. Die Behebung dieses Problems hat höchste Priorität.