update readme

documentation/readme.adoc

@@ -39,8 +39,80 @@ Die HTWKalender-PWA bietet folgende Features:
 * fix shadow in ical viewer
 * screenshots with "form_factor" set to "wide" pwa installation
 
+
 * share api for room occupation/calendar
 * app version in settings and update notification
+* more options in room finder
+* offline room finder
+* downloadable ical/csv file for room occupation
+
+
+== Projektstruktur
+
+Für den HTWKalender gibts es als Serverseitige Anwendungen zwei Services die Daten bereitstellen und verarbeiten.
+Dabei handelt es sich um einen Datenservice für die Raumbelegung und Veranstaltungen der HTWK Leipzig und einen Service nur
+für die Generierung und Bereitstellung von der iCal-Feeds. Im Rahmen des PWA Projekts steht aber das Frontend im Vordergrund, welches die Daten dieser Services verarbeitet und anzeigt.
+Dabei wurden bestehende Komponenten aus dem HTWKalender Projekt übernommen und um PWA spezifische Features erweitert. Einen genauen Überblick über die Projektstruktur und die Änderungen sind über den link:https://gitlab.dit.htwk-leipzig.de/htwk-software/htwkalender-pwa.[HTWKalender-PWA Fork] im DIT-Gitlab einsehbar.
 
 
 
+== Locale Entwicklung
+
+Für die lokale Entwicklung der HTWKalender-PWA nutzen wir den Vite-Server. Dieser kann mit dem Befehl `npm run dev` gestartet werden.
+Aber um Service Worker und PWA Features zu testen, muss die App über HTTPS aufgerufen werden. Zudem werden Daten aus den anderen Services benötigt die auch gestartet werden müssen.
+Um diese Anforderungen zu erfüllen, haben wir ein Docker-Compose File erstellt, welches die benötigten Services startet und die HTWKalender-PWA über HTTPS bereitstellt.
+Dazu muss das Docker-Compose File mit dem Befehl `docker-compose up` gestartet werden.
+
+== Service Worker
+
+Der Service Worker ist ein zentrales Element einer PWA. Er ermöglicht es, die Anwendung offline verfügbar. Der Service Worker wird beim Start der Anwendung installiert und aktiviert. Er lädt die benötigten Dateien in den Cache und stellt sie offline zur Verfügung. Der Service Worker wird im `public/sw.js` definiert.
+
+[source, javascript]
+----
+import { precacheAndRoute, cleanupOutdatedCaches } from 'workbox-precaching';
+import { clientsClaim } from 'workbox-core';
+
+self.skipWaiting();
+clientsClaim();
+
+cleanupOutdatedCaches();
+
+// Precache the files from the manifest
+precacheAndRoute(self.__WB_MANIFEST);
+
+// Custom precaching logic for the /api/modules endpoint
+self.addEventListener('install', (event) => {
+  event.waitUntil(
+    caches.open('api-modules-cache').then((cache) => {
+      return fetch('/api/modules')
+        .then((response) => {
+          if (response.ok) {
+            return cache.put('/api/modules', response);
+          }
+          throw new Error('Failed to fetch /api/modules');
+        })
+        .catch((error) => {
+          console.error('Precaching /api/modules failed:', error);
+        });
+    })
+  );
+});
+----
+
+
+== Deployment
+
+Für das Deployment der HTWKalender-PWA haben wir uns für die Nutzung von Gitlab CI/CD entschieden. Dabei wird bei jedem Push in das Gitlab-Repository ein Build- und Deploy-Job ausgeführt. Der Build-Job erstellt ein Docker-Image, welches die HTWKalender-PWA enthält. Der Deploy-Job startet dann ein Docker-Container mit dem erstellten Image. Der Container wird auf einem Server gehostet, der über eine Subdomain erreichbar ist. Die Subdomain wird über einen Reverse-Proxy auf den Docker-Container weitergeleitet.
+Eine Laufende Instanz der HTWKalender-PWA ist unter link: https://pwa.htwkalender.de[pwa.htwkalender.de] erreichbar.
+Die Konfiguration für das Deployment ist im Gitlab-Repository unter
+link:https://gitlab.dit.htwk-leipzig.de/htwk-software/htwkalender-pwa/-/blob/main/.gitlab-ci.yml[.gitlab-ci.yml] zu finden.
+
+
+
+== Zukünfitige Features
+
+Folgende Features wurden in der aktuellen Version noch nicht umgesetzt, könnten aber in zukünftigen Versionen hinzugefügt werden:
+
+* push notifications for upcoming events (through firebase/cloud messaging)
+
+