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