thats-me/documentation/architektur.md

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 (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 (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.).