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:

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:

git clone [Repository-URL]
cd slrpg_app

2. Abhängigkeiten installieren:

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):

API_URL=http://localhost:8090

4. Code-Generierung: Da das Projekt riverpod_generator, drift und freezed verwendet, müssen die Dateien generiert werden:

dart run build_runner build --delete-conflicting-outputs

5. App starten:

flutter run

7. Entwicklung

Testing

Das Projekt enthält Unit- und Widget-Tests (sofern implementiert). Ausführen der Tests:

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:

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.