first commit

documentation/architektur.md

@@ -0,0 +1,88 @@
+# Architekturübersicht
+
+Dieses Dokument beschreibt die grundlegende Architektur der "That's Me"-Anwendung, die als Offline-First-Anwendung mit einem Quasar-Frontend und einem Laravel-Backend konzipiert ist.
+
+## Hauptkomponenten
+
+1.  **Frontend (Quasar SPA):** Eine Single-Page Application (SPA) und Progressive Web App (PWA), entwickelt mit dem [Quasar Framework](https://quasar.dev/) (Vue.js 3). Verantwortlich für die Benutzeroberfläche, die "LifeWave"-Visualisierung (via Anime.js), die Offline-Datenspeicherung und die Synchronisation mit dem Backend. Kann auch als native mobile App via Capacitor bereitgestellt werden.
+2.  **Backend (Laravel):** Eine Webanwendung und API, entwickelt mit dem [Laravel Framework](https://laravel.com/) (v12). Dient als zentrale Datenverwaltung, API-Provider, Authentifizierungsinstanz und (optional) als WebSocket-Server-Schnittstelle. Beinhaltet ein Admin-Panel (erstellt mit Livewire/Volt und gestylt mit Tailwind/Flux UI).
+
+## Technologie-Stack im Detail
+
+- **Frontend:**
+  - Framework: Quasar (Vue.js 3)
+  - Build-Tool: Vite (via Quasar CLI)
+  - Styling: Quasar UI-Komponenten (primär), Tailwind CSS (optional, für spezifische Anpassungen wie LifeWave)
+  - Animation: Anime.js (für die SVG-basierte "LifeWave"-Darstellung)
+  - State Management: Pinia (Verwaltung des Anwendungszustands, insbesondere Offline-Daten und Sync-Status)
+  - Offline-Speicher:
+    - IndexedDB (via Dexie.js Wrapper): Für strukturierte Daten (Metadaten, Texte, kleine Vorschaubilder).
+    - Capacitor Filesystem (bei nativer App): Für große Multimedia-Dateien (Bilder, Videos).
+  - Offline-Fähigkeit: Service Worker (via Quasar PWA-Modus) für Caching von App-Shell und statischen Assets.
+- **Backend:**
+  - Framework: Laravel 12 (PHP)
+  - Admin-Panel UI: Livewire & Volt (für interaktive Komponenten)
+  - Admin-Panel Styling: Tailwind CSS + Flux UI (Komponentenbibliothek)
+  - Datenbank: MySQL (Nutzerdaten, Metadaten, Sync-Logs)
+  - Objektspeicher: Synology C2 Object Storage (S3-kompatibel, für Multimedia-Dateien via Laravel Flysystem)
+  - Authentifizierung: Laravel Passport (OAuth2 für API-/WebSocket-Zugriff)
+  - API/Web-Server: PHP-FPM (+ Nginx/Apache für Produktion)
+  - Asset Bundling: Vite
+  - _(Skalierungsoption: Node.js/Express.js mit TypeScript für dedizierten WebSocket-Server)_
+
+## Interaktion und Datenfluss (Offline-First)
+
+Die Anwendung folgt einem Offline-First-Ansatz. Die Kommunikation variiert je nach Verbindungsstatus und gewählter Synchronisationsstrategie (Polling oder WebSockets).
+
+1.  **Lokale Aktionen (Offline/Online):**
+
+    - Benutzer interagiert im Quasar-Frontend (z.B. fügt ein Ereignis hinzu).
+    - Änderungen werden _sofort_ im lokalen State (Pinia) reflektiert und persistent in IndexedDB (via Dexie.js) gespeichert. Große Dateien werden ggf. im Capacitor Filesystem abgelegt.
+    - Die "LifeWave"-Visualisierung (Anime.js) wird basierend auf den lokalen Daten aktualisiert.
+    - Die Änderung wird als "zu synchronisieren" markiert (z.B. "dirty" flag in Pinia/IndexedDB).
+
+2.  **Synchronisation (wenn online):**
+
+    - **Basis (Polling):**
+      - Das Frontend prüft periodisch (intelligentes Polling) die Verbindung und ob zu synchronisierende Daten vorhanden sind.
+      - Bei Bedarf wird eine Anfrage an die REST-API des Laravel-Backends gesendet (z.B. `/api/sync`), authentifiziert via Laravel Passport Token.
+      - Die Anfrage enthält die lokalen Änderungen (ggf. als Delta/Diff).
+      - Das Laravel-Backend verarbeitet die Änderungen:
+        - Validiert die Daten.
+        - Löst Konflikte (anhand von Timestamps/Versionen, ggf. `sync_logs` Tabelle).
+        - Aktualisiert die MySQL-Datenbank.
+        - Lädt ggf. Multimedia-Dateien zu Synology C2 hoch.
+        - Sendet eine Bestätigung und ggf. serverseitige Änderungen (Delta-Updates) zurück an das Frontend.
+      - Das Frontend verarbeitet die Antwort, aktualisiert IndexedDB/Pinia und entfernt die "zu synchronisieren"-Markierung.
+    - **Skalierung (WebSockets):**
+      - Bei bestehender Online-Verbindung wird eine WebSocket-Verbindung zum (Node.js oder via Pusher angebundenen Laravel Echo) Server aufgebaut, authentifiziert via Passport Token.
+      - Lokale Änderungen werden _sofort_ über WebSockets gesendet.
+      - Das Backend verarbeitet die Änderungen (ähnlich wie bei Polling) und sendet Bestätigungen/Updates in Echtzeit über WebSockets zurück.
+      - Das Frontend empfängt Echtzeit-Updates von anderen Clients/Geräten über WebSockets und aktualisiert den lokalen Speicher und die UI.
+
+3.  **Authentifizierung:**
+
+    - Der Login erfolgt über das Laravel-Backend.
+    - Laravel Passport stellt OAuth2-Tokens aus, die im Frontend sicher gespeichert und für alle API- und WebSocket-Anfragen verwendet werden. Tokens haben eine längere Gültigkeit, um Offline-Szenarien zu unterstützen.
+
+4.  **Admin-Panel:**
+    - Das Backend stellt ein separates Admin-Panel bereit, das direkt über Laravel geroutet wird.
+    - Die UI wird serverseitig mit Blade, Livewire und Volt gerendert.
+    - Styling erfolgt durch Tailwind CSS und Flux UI Komponenten.
+
+## Verzeichnisstruktur (Übersicht)
+
+- `frontend/`: Enthält den gesamten Quasar-Frontend-Code.
+  - `src/`: Haupt-Quellcode (Pages, Layouts, Components, Stores (Pinia), Boot-Files, etc.).
+  - `src-pwa/`: PWA-spezifische Konfiguration (Service Worker, Manifest).
+  - `src-capacitor/`: Capacitor-spezifische Konfiguration (falls native App).
+  - `quasar.config.js`: Quasar-Konfigurationsdatei.
+- `backend/`: Enthält den gesamten Laravel-Backend-Code.
+  - `app/`: Kernanwendungscode (Models, Controller, Livewire/Volt-Komponenten, Jobs, etc.).
+  - `config/`: Konfigurationsdateien (inkl. `filesystems.php` für Synology C2).
+  - `database/`: Migrationen, Seeds, Factories.
+  - `resources/`: Views (Blade, Volt für Admin), Sprachdateien, Frontend-Assets (CSS, JS für Backend/Admin vor Kompilierung).
+  - `routes/`: Routendefinitionen (`web.php` für Web/Admin, `api.php` für REST-API).
+  - `public/`: Öffentlicher Einstiegspunkt, kompilierte Assets.
+  - `vite.config.js`: Vite-Konfiguration für das Backend-Asset-Building.
+  - `.env`: Umgebungsspezifische Konfiguration (DB, Passport Keys, C2 Credentials, APP_URL etc.).