# S.L.R.P.G. - Streetlifting Role Playing Game S.L.R.P.G. ist eine hybride Android-Anwendung, die professionelles Krafttraining (speziell Streetlifting und Powerlifting) mit Gamification-Elementen aus Rollenspielen (RPGs) verbindet. Das Ziel der Anwendung ist die Steigerung der Nutzer-Motivation durch extrinsische Anreize (Level-System, Items, Quests) bei gleichzeitiger präziser Steuerung der Trainingsbelastung durch etablierte Algorithmen. ## Inhaltsverzeichnis 1. Projektübersicht 2. Technologie-Stack 3. Architektur 4. Kernfunktionen 5. Projektstruktur 6. Installation und Einrichtung 7. Entwicklung ## 1. Projektübersicht Die App implementiert das **Wendler 5/3/1 Trainingssystem** und adaptiert es für Calisthenics- und Streetlifting-Übungen. Trainingsfortschritte ("Progressive Overload") werden direkt in Spielmechaniken übersetzt: * Wiederholungen verursachen "Schaden" an Gegnern. * Absolvierte Workouts gewähren Erfahrungspunkte (XP). * Steigerungen der Kraftwerte (1RM) schalten neue Spielinhalte frei. Das System folgt einem **Offline-First** Ansatz, um die Funktionalität auch in Umgebungen ohne Internetverbindung (z. B. Fitnessstudios im Keller) vollständig zu gewährleisten. ## 2. Technologie-Stack ### Frontend & Mobile Framework * **Sprache:** Dart * **Framework:** Flutter (Cross-Platform Development) * **State Management:** Riverpod (mit Code Generation & Hooks) * **Routing:** GoRouter ### Datenhaltung & Persistenz * **Lokale Datenbank:** Drift (SQLite Abstraktionsschicht für Dart) * **Backend Integration:** PocketBase (Go-basiertes Backend) * **Synchronisierung:** Eigene Implementierung einer bidirektionalen Synchronisierung (`SyncService`) ### Weitere Bibliotheken * **Freezed / JSON Serializable:** Für unveränderliche Datenmodelle und Serialisierung. * **Flutter Localizations:** Unterstützung für Internationalisierung (i18n), aktuell DE und EN. * **Charts:** Visualisierung von Trainingsfortschritten. ## 3. Architektur Das Projekt folgt einer **Feature-First Layered Architecture** in Kombination mit **Clean Architecture** Prinzipien. ### Schichtenmodell (Layers) * **Presentation Layer:** Beinhaltet Widgets, Screens und Controller (Riverpod Notifier). Dieser Layer ist rein für die Darstellung und Benutzerinteraktion zuständig. * **Domain Layer:** Beinhaltet die Geschäftslogik (z. B. `WendlerCalculator`, `XpCalculator`), Entitäten (`Exercise`, `WorkoutSet`) und Interface-Definitionen. Dieser Layer ist unabhängig von externen Frameworks. * **Data Layer:** Implementiert die Repositories, verwaltet die lokale Datenbank (`AppDatabase`) und die API-Kommunikation (`ApiClient`). ### Offline-First Strategie Die lokale Drift-Datenbank fungiert als **Single Source of Truth** für die UI. 1. Die App liest und schreibt primär in die lokale SQLite-Datenbank. 2. Ein Hintergrund-Service (`SyncService`) synchronisiert Änderungen asynchron mit dem PocketBase-Backend, sobald eine Netzwerkverbindung besteht. 3. Konfliktlösung und Queueing von Requests stellen die Datenkonsistenz sicher. ## 4. Kernfunktionen ### Trainings-Management * **Automatisierte Planung:** Berechnung von Trainingszyklen basierend auf dem 1RM (One Repetition Max) mittels Wendler 5/3/1 Logik. * **Battle Mode:** Interaktive Durchführung des Workouts. Sätze werden als "Kampfrunden" dargestellt. * **Timer-System:** Integrierte Satzpausen- und EMOM-Timer (Every Minute on the Minute). * **Plate Calculator:** Visualisierung der benötigten Hantelscheiben für das aktuelle Gewicht. ### Gamification (RPG-Elemente) * **Avatar-System:** Anpassbarer Charakter mit Ausrüstungsslots. * **Inventar:** Verwaltung von virtuellen Gegenständen, die durch Training freigeschaltet werden. * **Quests:** Tägliche und wöchentliche Aufgaben zur Förderung der Konsistenz. * **Codex:** Wissensdatenbank und Sammlung freigeschalteter Erfolge. ### Multiplayer & Social * **Party-System:** Bildung von Gruppen für gemeinsame "Raids" (Workouts). * **Leaderboards:** Ranglisten basierend auf XP und Kraftwerten. * **Lobby:** Echtzeit-Warteraum für Multiplayer-Sessions. ### Statistik & Analyse * Detaillierte Historie aller absolvierten Workouts. * Grafische Auswertung der Kraftentwicklung in den Grundübungen. ## 5. Projektstruktur Der Quellcode befindet sich im Verzeichnis `lib/` und ist wie folgt gegliedert: ```text lib/ ├── main.dart # Einstiegspunkt der App ├── l10n/ # Lokalisierungsdateien (ARB) └── src/ ├── app.dart # Root-Widget und globale Konfiguration ├── core/ # Kern-Komponenten (Routing, Theme, Konstanten, Utils) ├── features/ # Funktionalitäten (Feature-First Struktur) │ ├── authentication/ # Login, Register, Profil │ ├── backup/ # Datensicherung │ ├── dashboard/ # Hauptmenü (Hub) │ ├── gamification/ # Quests, Avatar, Codex │ ├── history/ # Trainingshistorie │ ├── inventory/ # Item-Verwaltung │ ├── multiplayer/ # Social Features │ ├── onboarding/ # Setup-Flow für neue Nutzer │ ├── settings/ # Einstellungen │ ├── stats/ # Diagramme und Auswertungen │ ├── wiki/ # Übungsanleitungen │ └── workout_runner/ # Die eigentliche Trainings-Logik (Battle Screen) └── shared/ # Geteilte Ressourcen ├── data/ # Repositories, lokale DB (Drift), API-Client ├── domain/ # Geteilte Logik (z.B. WendlerCalculator) └── presentation/ # Wiederverwendbare Widgets ``` ## 6. Installation und Einrichtung ### Voraussetzungen * Flutter SDK (neueste stabile Version empfohlen) * Dart SDK * Ein laufendes PocketBase Backend (siehe separate Backend-Dokumentation) ### Schritte 1. **Repository klonen:** ```bash git clone [Repository-URL] cd slrpg_app ``` 2. **Abhängigkeiten installieren:** ```bash flutter pub get ``` 3. **Umgebungsvariablen konfigurieren:** Erstellen Sie eine `.env` Datei im Root-Verzeichnis des Projekts und fügen Sie die notwendigen Konfigurationen hinzu (z. B. Backend-URL): ```env API_URL=http://localhost:8090 ``` 4. **Code-Generierung:** Da das Projekt `riverpod_generator`, `drift` und `freezed` verwendet, müssen die Dateien generiert werden: ```bash dart run build_runner build --delete-conflicting-outputs ``` 5. **App starten:** ```bash flutter run ``` ## 7. Entwicklung ### Testing Das Projekt enthält Unit- und Widget-Tests (sofern implementiert). Ausführen der Tests: ```bash flutter test ``` ### Lokalisierung Texte werden in `lib/src/l10n/app_de.arb` und `app_en.arb` gepflegt. Nach Änderungen muss der Generator ausgeführt werden: ```bash flutter gen-l10n ``` ### Datenbank-Migrationen Bei Änderungen am Datenbankschema in `app_database.dart` oder `tables.dart` muss die Schema-Version erhöht und eine Migration geschrieben werden. Drift kümmert sich um die Generierung des Boilerplate-Codes.