mitai-jinkendo/.claude/docs/functional/DATA_ARCHITECTURE.md

Fachliche Datenarchitektur – Mitai Jinkendo

Version: 2.0 Status: Living Document Letzte Aktualisierung: 29. März 2026

---

Überblick

Dieses Dokument beschreibt die fachliche Datenarchitektur von Mitai Jinkendo aus Domänen-Perspektive. Es zeigt:

• Welche Datenobjekte (Domänen-Entitäten) existieren
• Wie sie zusammenhängen (Beziehungen)
• Welche Daten gespeichert vs. berechnet werden
• Welche Anreicherungen stattfinden (z.B. Trainingsqualität, Recovery Score)
• Wie Daten fließen (Import → Speicherung → Anreicherung → Auswertung)

Technische Schema-Details: Siehe DATABASE.md in .claude/library/

Berechnungen & Chart-Schicht (Code): backend/data_layer/ · Leitfaden: ../technical/DATA_LAYER_EXTENSION_GUIDE.md

---

Domänen-Übersicht

┌─────────────────────────────────────────────────────────────────┐
│                    NUTZER & ZIELSETZUNG                          │
├─────────────────────────────────────────────────────────────────┤
│ Profil → Goal Mode (Strategic) → Ziele (Tactical)              │
│ Focus Areas (Dynamic) → Membership → Access Control            │
└─────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐      ┌──────────────┐
│   KÖRPER     │    │   TRAINING   │      │  LIFESTYLE   │
├──────────────┤    ├──────────────┤      ├──────────────┤
│ Gewicht      │    │ Aktivitäten  │      │ Schlaf       │
│ Umfänge      │    │ Trainingstyp │      │ Ernährung    │
│ Caliper      │    │ HF-Daten     │      │ Ruhetage     │
│ Vitalwerte   │    │ Fähigkeiten ⚡│      │ Vitalwerte   │
│ Progress-Foto│    │ Qualität ⚡  │      │ Custom Goals │
└──────────────┘    └──────────────┘      └──────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              ▼
                    ┌──────────────────┐
                    │   AUSWERTUNGEN   │
                    ├──────────────────┤
                    │ Charts (20+) ⚡  │
                    │ KI-Analysen      │
                    │ Korrelationen ⚡ │
                    │ Scores ⚡        │
                    └──────────────────┘

⚡ = Berechnete/angereicherte Daten

---

1. Nutzer & Zielsetzung

1.1 Profil

Fachliche Bedeutung: Zentrale Nutzer-Entität mit persönlichen Daten, Auth und Zielsetzung

Gespeicherte Daten:

• Stammdaten: Name, Geschlecht, Geburtsdatum, Größe
• Auth: E-Mail, Passwort (bcrypt), Role (user/admin)
• Membership: Tier (free/premium/...), Trial-Ende
• Goal Mode: Strategische Ausrichtung (weight_loss, strength, endurance, recomposition, health)
• Einstellungen: Avatar-Farbe, Foto-ID, KI-Features

Berechnete Werte:

• Alter (aus Geburtsdatum)
• BMI (aus aktuellem Gewicht + Größe)
• Trial-Status (Tage verbleibend)
• TDEE (geschätzt, Harris-Benedict oder Profil-basiert)

Beziehungen:

• 1:N → Alle Tracking-Objekte (Gewicht, Aktivitäten, etc.)
• 1:1 → Goal Mode (aktuell)
• 1:N → Ziele (konkret)
• 1:N → Focus Area Weights (Prioritäten)
• 1:N → Sessions, Access Grants, Feature Usage

Datenquellen:

• Manuelle Eingabe (Registrierung, Settings)
• System-generiert (Trial-Start, Tier-Zuweisung)

---

1.2 Goal Mode (Strategic Layer)

Fachliche Bedeutung: Strategische Ausrichtung die KI-Analysen und Score-Gewichtung steuert

Verfügbare Modi:

• Weight Loss: Gewichtsreduktion, Kaloriendefizit
• Strength: Kraftaufbau, Muskelwachstum
• Endurance: Ausdauer, kardiovaskuläre Fitness
• Recomposition: Simultaner Fettabbau + Muskelaufbau
• Health: Gesundheit, Vitalwerte-Optimierung

Auswirkungen:

• Bestimmt Score-Gewichtung in KI-Analysen
• Beeinflusst automatische Trainingsphasen-Erkennung
• Steuert Empfehlungs-Algorithmen

Beziehungen:

• N:1 → Profil (ein aktiver Mode pro Nutzer)
• Beeinflusst: Focus Areas, Ziel-Priorisierung, KI-Prompts

---

1.3 Ziele (Tactical Layer)

Fachliche Bedeutung: Konkrete, messbare Ziele mit Fortschritts-Tracking

Ziel-Typen:

• Body Composition: weight, body_fat, lean_mass
• Fitness: vo2max, strength (1RM), flexibility
• Health: blood_pressure, resting_heart_rate
• Custom: Beliebige nutzerdefinierte Ziele

Gespeicherte Daten:

• Ziel-Typ, Start-Wert, Start-Datum
• Ziel-Wert, Ziel-Datum (optional)
• Beschreibung, Primär/Sekundär-Flag
• Focus Area Contributions (M:N, gewichtet)

Berechnete Werte:

• Aktueller Wert: Automatisch aus Datenquellen (weight_log, vitals, etc.)
• Progress (%): (Aktuell - Start) / (Ziel - Start) × 100
• Linear Projection: Fortschritts-Hochrechnung auf Ziel-Datum
• Time-Based Tracking:
  • Expected Progress = (elapsed_days / total_days) × 100
  • Deviation = actual_progress - expected_progress
  • Status: "behind schedule", "on track", "ahead of schedule"

Beziehungen:

• N:1 → Profil
• N:M → Focus Areas (via goal_focus_contributions)
• 1:N → Custom Goal Entries (tägliche Werterfassung)

Datenquellen:

• Manuelle Definition (Goals Page)
• Auto-Population: Start-Wert/-Datum aus historischen Messungen
• Fortschritt: Automatisch aus body metrics, vitals, fitness tests

---

1.4 Focus Areas (Dynamic)

Fachliche Bedeutung: Flexibles System zur Priorisierung von Lebensbereichen

26 Basis-Bereiche in 7 Kategorien:

• Körperkomposition (5): Gewicht, Körperfett, Magermasse, Umfänge, Ästhetik
• Kraft (4): Maximalkraft, Kraftausdauer, funktionelle Kraft, Core-Stabilität
• Ausdauer (4): Kardio, muskuläre Ausdauer, VO2 Max, Erholungsfähigkeit
• Mobilität (2): Flexibilität, Beweglichkeit
• Gesundheit (5): Blutdruck, Ruhepuls, HRV, Schlafqualität, Vitalwerte
• Leistungsfähigkeit (3): Energie-Level, Belastbarkeit, Reaktionsvermögen
• Lifestyle (3): Ernährungsqualität, Konsistenz, Balance

Gespeicherte Daten:

• Definitions: Name, Beschreibung, Kategorie, Icon (admin-erweiterbar)
• User Weights: Prozentuale Gewichtung pro Nutzer (dynamisch, summiert zu 100%)
• Goal Contributions: M:N Verknüpfung mit Gewichtung (ein Ziel zahlt auf 1-n Areas ein)

Berechnete Werte:

• Progress per Focus Area: Gewichtete Summe aller zugeordneten Ziele
• Category Scores: Aggregierte Fortschritte pro Kategorie

Beziehungen:

• N:M → Ziele (via goal_focus_contributions)
• N:1 → User Weights (Profil-spezifisch)
• 1:N → Definitions (admin-verwaltet)

Datenquellen:

• Definitions: Admin-UI (erweiterbar)
• Weights: Goals Page Edit-Modus
• Contributions: Ziel-Formular (Multi-Select mit Gewichtung)

---

1.5 Training Phases

Fachliche Bedeutung: Automatisch erkannte oder manuell definierte Trainingszyklen

Phase-Typen:

• Calorie Deficit: Diät-Phase (Weight Loss)
• Calorie Surplus: Aufbau-Phase (Strength/Muscle)
• Deload: Regenerations-Woche
• Maintenance: Status-Quo-Erhaltung
• Periodization: Zyklische Periodisierung

Gespeicherte Daten:

• Typ, Start-/End-Datum, Status (suggested/accepted/active/completed)
• Confidence Score (bei KI-Erkennung)
• Beschreibung, Notizen

Status-Flow:

suggested → (User-Approval) → accepted → (Start-Datum erreicht) → active → (End-Datum) → completed

Beziehungen:

• N:1 → Profil
• Beeinflusst: KI-Analysen, Empfehlungen, Score-Berechnung

Datenquellen:

• Automatische Erkennung (KI-basiert, Phase 0b+)
• Manuelle Definition (Goals Page, geplant)

---

1.6 Fitness Tests

Fachliche Bedeutung: Standardisierte Tests zur objektiven Leistungserfassung

Test-Typen:

• Cardio: Cooper-Test (12 min Lauf), VO2 Max Test, Step Test
• Kraft: 1RM Squat, 1RM Bench Press, Pushups (max), Plank (Zeit)
• Flexibilität: Sit-and-Reach

Gespeicherte Daten:

• Test-Typ, Datum, Ergebnis (Zeit/Distanz/Gewicht/Wiederholungen)
• Normwert-Klassifizierung (sehr gut, gut, durchschnittlich, unterdurchschnittlich)

Berechnete Werte:

• VO2 Max (aus Cooper-Test)
• Relative Kraft (1RM / Körpergewicht)
• Vergleich zu Normwerten (alters-/geschlechtsspezifisch)

Beziehungen:

• N:1 → Profil
• Kann verknüpft werden mit: Zielen (vo2max, strength)

Datenquellen:

• Manuelle Eingabe (Fitness Tests Page, geplant)

---

2. Körper-Tracking

2.1 Gewicht

Fachliche Bedeutung: Tägliche Gewichtsmessungen als Basis-Metrik

Gespeicherte Daten:

• Datum, Gewicht (kg), Quelle (manual/apple_health/withings)

Berechnete Werte:

• BMI: Gewicht / (Größe in m)²
• Trends: 7d/28d/90d Steigung (lineare Regression)
• Prognose: Extrapolation auf Ziel-Datum
• Ziel-Fortschritt: % zum Zielgewicht
• Gewichtsänderung: Δ 7d/28d/90d

Beziehungen:

• N:1 → Profil
• Korreliert mit: Ernährung (Energie-Bilanz), Aktivität, Schlaf
• Verknüpft mit: Ziel-Typ "weight"

Datenquellen:

• Manuelle Eingabe (Dashboard, Weight Page)
• CSV-Import (Apple Health, Withings)

---

2.2 Umfänge

Fachliche Bedeutung: 8 Körperumfangspunkte zur Tracking von Muskelaufbau/Fettabbau

Messpunkte:

• Brust (c_chest), Bauch (c_waist), Hüfte (c_hip)
• Oberschenkel links/rechts (c_thigh_l/r)
• Wade links/rechts (c_calf_l/r)
• Oberarm (c_arm)

Gespeicherte Daten:

• Datum, 8 Messpunkte (cm), Quelle (manual)

Berechnete Werte:

• Trends: 7d/28d/90d pro Messpunkt
• Delta: Veränderung zu letzter Messung, zu Ausgangswert
• Best-of-Each: Beste Messung pro Punkt mit Altersangabe

Beziehungen:

• N:1 → Profil
• Korreliert mit: Gewicht, Körperfett, Training (Hypertrophie)

Datenquellen:

• Manuelle Eingabe (Circumference Page)

---

2.3 Caliper (Hautfaltenmessung)

Fachliche Bedeutung: Körperfettanteil via Hautfaltenmessung

7 Messpunkte:

• Brust, Axilla, Trizeps, Subscapular, Abdominal, Suprailiac, Oberschenkel

Gespeicherte Daten:

• Datum, 7 Hautfalten (mm), Methode (3/4/7-Site Jackson-Pollock)

Berechnete Werte:

• Körperfettanteil (BF%): Alters-/geschlechtsspezifische Formeln
• Magermasse (LBM): Gewicht × (1 - BF%)
• Fettmasse (FM): Gewicht × BF%
• Trends: LBM/FM Änderungen über Zeit

Beziehungen:

• N:1 → Profil
• Erfordert: Aktuelles Gewicht
• Verknüpft mit: Ziel-Typ "body_fat", "lean_mass"

Datenquellen:

• Manuelle Eingabe (Caliper Page)

---

2.4 Vitalwerte

Fachliche Bedeutung: Gesundheits- und Erholungs-Indikatoren

2.4.1 Baseline Vitals (Morgenmessung)

Gespeicherte Daten:

• Datum (1x täglich, morgens)
• Ruhepuls (bpm), HRV (ms), VO2 Max (ml/kg/min)
• SpO2 (%), Atemfrequenz (bpm)

Berechnete Werte:

• Baselines: 7d/14d/30d Durchschnitte (RHR, HRV)
• Abweichungen: Aktuell vs. Baseline (%)
• Recovery Score: Basierend auf HRV/RHR/Schlaf
• Trends: 7d/28d Steigung

Beziehungen:

• N:1 → Profil
• Korreliert mit: Schlaf, Aktivität (Load), Ruhetage
• Verknüpft mit: Ziel-Typ "rhr", Recovery Score

Datenquellen:

• Manuelle Eingabe (Vitals Page - Baseline Tab)
• CSV-Import (Apple Health, Garmin)

2.4.2 Blutdruck (mehrfach täglich)

Gespeicherte Daten:

• Datum + Uhrzeit (mehrfach möglich)
• Systolisch (mmHg), Diastolisch (mmHg), Puls (bpm)
• Context-Tag (nüchtern, nach Essen, Training, Stress, Medikation, Ruhe, Krank, Sonstiges)
• Unregelmäßiger Herzschlag (Flag), AFib-Warnung (Flag)

Berechnete Werte:

• WHO/ISH Klassifizierung:
  • Optimal (<120/80)
  • Normal (120-129/80-84)
  • Hochnormal (130-139/85-89)
  • Hypertonie Grad 1-3 (≥140/90)
• Trends: 7d/14d/30d Durchschnitte (Systolisch, Diastolisch)

Beziehungen:

• N:1 → Profil
• Korreliert mit: Stress, Aktivität, Medikation, Schlaf
• Verknüpft mit: Ziel-Typ "blood_pressure"

Datenquellen:

• Manuelle Eingabe (Vitals Page - Blutdruck Tab)
• CSV-Import (Omron Deutsch, Apple Health)

---

2.5 Progress-Fotos

Fachliche Bedeutung: Visuelle Fortschritts-Dokumentation

Gespeicherte Daten:

• Datum, Pose (front/side/back), Dateiname
• Caption (optional)

Berechnete Werte:

• Zeitlicher Vergleich (Side-by-Side View)

Beziehungen:

• N:1 → Profil
• Kann verknüpft werden mit: Gewicht, Umfängen (Kontext)

Datenquellen:

• Foto-Upload (Photos Page)

---

3. Training

3.1 Aktivitäten

Fachliche Bedeutung: Training-Sessions mit Typ, Dauer, Intensität

Gespeicherte Daten:

• Datum, Trainingstyp, Dauer (min), Distanz (km)
• Ø Herzfrequenz, Max Herzfrequenz
• Kalorien (geschätzt oder gemessen)
• Notizen, Quelle (manual/apple_health/garmin)

Berechnete Werte:

• Training Volume: Dauer × Intensität (aus HF-Zonen)
• Quality Session: Boolean (≥45min + HF in Zielzone)
• ACWR (Acute:Chronic Workload Ratio): 7d Load / 28d Load
• Monotony: Standardabweichung der Last (inversiert)
• Strain: Load × Monotony
• Ability Balance: Verteilung über 7 Fähigkeiten (Radar)

Beziehungen:

• N:1 → Profil
• N:1 → Trainingstyp (via activity_type_mappings)
• Korreliert mit: Vitalwerte (RHR, HRV), Schlaf, Ruhetage

Datenquellen:

• Manuelle Eingabe (Activity Page)
• CSV-Import (Apple Health Deutsch/English)
• Automatisches Mapping (lernendes System)

---

3.2 Trainingstypen

Fachliche Bedeutung: 29 kategorisierte Trainingstypen zur systematischen Erfassung

7 Kategorien:

• Kraft (5): Krafttraining, Bodyweight, Crossfit, Functional, Powerlifting
• Cardio (6): Laufen, Radfahren, Schwimmen, Rudern, HIIT, Wandern
• Kampfsport (6): Boxen, Kickboxen, MMA, Karate, Judo, Jiu-Jitsu
• Beweglichkeit (4): Yoga, Stretching, Mobility, Pilates
• Sport (4): Fußball, Basketball, Tennis, Bouldern
• Alltag (2): Gehen, Tanzen
• Geist (2): Meditation, Achtsamkeit

Gespeicherte Daten:

• Name, Kategorie, Farbe, Icon
• Fähigkeiten-Mapping (7 Dimensionen, JSONB)

7 Fähigkeiten-Dimensionen:

• Maximalkraft, Kraftausdauer, Cardio, Flexibilität, Koordination, Schnelligkeit, Mentale Stärke

Berechnete Werte:

• Ability Balance: Fähigkeiten-Verteilung über alle Trainings (28d)
• Volume by Ability: Trainingsvolumen pro Fähigkeit

Beziehungen:

• 1:N → Aktivitäten
• N:M → Activity Type Mappings (lernendes System)

Datenquellen:

• System-definiert (29 Basis-Typen)
• Admin-erweiterbar (Admin Panel)

---

3.3 Activity Type Mappings (Lernendes System)

Fachliche Bedeutung: Automatisches Mapping von Import-Daten zu Trainingstypen

Gespeicherte Daten:

• Import-Name (z.B. "Traditionelles Krafttraining", "Traditional Strength Training")
• Training Type ID, Sprache
• User-spezifisch (optional) oder global
• Confidence Score

Lern-Mechanismus:

• Bulk-Kategorisierung im Admin-Panel speichert Mappings
• Zukünftige Imports nutzen gelernte Mappings automatisch
• Coverage-Stats: % zugeordnet vs. unkategorisiert

Beziehungen:

• N:1 → Training Type
• N:1 → Profil (bei user-spezifischen Mappings)

Datenquellen:

• Bulk-Kategorisierung (Admin Panel)
• CSV-Import (lernt bei jeder Zuordnung)

---

4. Lifestyle

4.1 Ernährung

Fachliche Bedeutung: Tägliche Makronährstoff- und Kalorien-Erfassung

Gespeicherte Daten:

• Datum, Kalorien (kcal)
• Protein (g), Kohlenhydrate (g), Fett (g)
• Quelle (manual/myfitnesspal/yazio)

Berechnete Werte:

• Makro-Verteilung: Protein/Carbs/Fat in % (28d Durchschnitt)
• Protein-Adequacy: Ist vs. Soll (1.6-2.2 g/kg LBM)
• Energie-Bilanz: Intake - (TDEE + Training kcal)
• Konsistenz-Score: Standardabweichung (inversiert)
• Intake Volatility: Schwankungen über Zeit

Beziehungen:

• N:1 → Profil
• Korreliert mit: Gewicht (Energie-Bilanz), Training, Ziele

Datenquellen:

• Manuelle Eingabe (Nutrition Page)
• CSV-Import (MyFitnessPal, Yazio)

---

4.2 Schlaf

Fachliche Bedeutung: Nächtliche Schlaferfassung mit Phasen-Details

Gespeicherte Daten:

• Datum (Nacht vom X auf Y)
• Gesamtdauer (h), Qualität (1-10)
• Sleep Segments (JSONB): Start, Ende, Phase (deep/rem/light/awake)

Berechnete Werte:

• Schlaf-Statistiken:
  • Ø Dauer (7d/28d)
  • Ø Qualität (Deep + REM %, 7d)
  • Schlafschuld (kumulativ): Σ(7.5h - Ist-Dauer)
• Sleep Score: Basierend auf Dauer + Deep/REM %

Beziehungen:

• N:1 → Profil
• Korreliert mit: Vitalwerte (RHR, HRV), Aktivität (Load), Recovery Score

Datenquellen:

• Manuelle Eingabe (Sleep Page)
• CSV-Import (Apple Health Deutsch/English)

---

4.3 Ruhetage

Fachliche Bedeutung: Multi-dimensionale Regenerations-Tracking

3 Ruhe-Typen:

• Kraft-Ruhe: Keine Kraft-/Muskeltraining
• Cardio-Ruhe: Keine intensive Ausdauer-Einheiten
• Entspannung: Aktive Erholung (Mobility, Spazieren)

Gespeicherte Daten:

• Datum, Ruhe-Typ (kann mehrfach kombiniert werden)
• Notizen

Berechnete Werte:

• Rest Days Count: Anzahl pro Typ (28d)
• Recovery Ratio: Rest Days / Training Days
• Validierung: Warnung bei geplanter Aktivität trotz Ruhetag

Beziehungen:

• N:1 → Profil
• Kann kollidieren mit: Aktivitäten (Validierung)

Datenquellen:

• Manuelle Eingabe (Rest Days Page - Quick Mode/Custom)

---

4.4 Custom Goals (Eigene Ziele)

Fachliche Bedeutung: Tägliche Werterfassung für individuell definierte Ziele

Gespeicherte Daten:

• Datum, Goal ID, Wert (Zahl oder Text)
• Notizen

Berechnete Werte:

• Fortschritt: Automatisch aus Einträgen berechnet
• Konsistenz: % Tage mit Eintrag
• Verlauf: Letzte 5 Einträge

Beziehungen:

• N:1 → Goal (source_table = NULL, custom goal)
• N:1 → Profil

Datenquellen:

• Manuelle Eingabe (Custom Goals Page - Capture Hub)

---

5. Auswertungen & KI

5.1 Charts & Visualisierungen

Fachliche Bedeutung: 20+ vorgefertigte Auswertungs-Charts

Chart-Kategorien:

Ernährung (E1-E5, 4 Charts)

• E1: Energiebilanz: Kalorien-Timeline vs. TDEE, Bilanz als Balken
• E2: Makro-Verteilung: Protein/Carbs/Fat (Pie Chart)
• E3: Protein-Adequacy: Protein vs. Ziel-Range (Timeline)
• E4: Ernährungs-Konsistenz: Konsistenz-Score (Bar)

Aktivität (A1-A8, 7 Charts)

• A1: Trainingsvolumen: Wöchentliches Volumen (Bar)
• A2: Trainingstyp-Verteilung: Typen (Pie)
• A3: Quality Sessions: Rate qualitativ hochwertiger Trainings (Bar)
• A4: Load Monitoring: Acute/Chronic Load + ACWR (Line)
• A5: Monotony & Strain: Monotonie + Strain (Bar)
• A6: Ability Balance: Fähigkeiten-Verteilung (Radar)
• A7: Volume by Ability: Volumen pro Fähigkeit (Bar)

Erholung (R1-R5, 5 Charts)

• R1: Recovery Score: Recovery-Timeline (Line)
• R2: HRV/RHR Baseline: HRV & RHR vs. Baseline (Multi-Line)
• R3: Schlaf Dauer + Qualität: Dauer + Deep/REM % (Multi-Line)
• R4: Schlafschuld: Kumulative Schuld (Line)
• R5: Vital Signs Matrix: Aktuelle Vitalwerte (Bar)

Korrelationen (C1-C4, 4 Charts)

• C1: Gewicht ↔ Energie: Scatter mit Lag-Korrelation
• C2: Magermasse ↔ Protein: Scatter mit Lag-Korrelation
• C3: Load ↔ Vitalwerte: Training Load vs. HRV/RHR (Scatter)
• C4: Recovery ↔ Performance: Top Treiber (Bar)

Berechnete Werte:

• Alle Chart-Daten kommen aus Data Layer (Single Source of Truth)
• Confidence Scores (Datenqualität)
• Metadata (Durchschnitte, Korrelationen, etc.)

Beziehungen:

• Konsumieren: Alle Tracking-Objekte
• Nutzen: Data Layer Funktionen (97 Funktionen in 6 Modulen)

Datenquellen:

• Chart Endpoints (20 neue APIs)
• Data Layer: body_metrics, nutrition_metrics, activity_metrics, recovery_metrics, scores, correlations

---

5.2 Data Layer (Phase 0c)

Fachliche Bedeutung: Zentrale Berechnungs-Schicht (Single Source of Truth)

6 Module, 97 Funktionen:

body_metrics.py (20 Funktionen)

• Weight trends, goal projections
• Body composition: FM/LBM changes, recomposition quadrants
• Circumferences: Delta-Berechnungen, Fortschritts-Scores

nutrition_metrics.py (16 Funktionen)

• Energy balance, protein adequacy, macro consistency
• Intake volatility, nutrition scoring

activity_metrics.py (20 Funktionen)

• Training volume, quality sessions, load monitoring
• Monotony/Strain scores, ability balance

recovery_metrics.py (16 Funktionen)

• Sleep metrics, HRV/RHR baselines, recovery scoring

scores.py (14 Funktionen)

• Focus weights, goal progress, category scores

correlations.py (11 Funktionen)

• Lag correlations, plateau detection, top drivers

Architektur-Prinzip:

• Alle Berechnungen in Data Layer (keine Duplikation)
• Nutzbar für: Chart Endpoints + KI-Platzhalter
• Flexible Zeitfenster (7-365 Tage)
• Confidence System (Datenqualität-Prüfung)

Beziehungen:

• Konsumieren: Alle Tracking-Tabellen
• Genutzt von: Chart Endpoints, KI-Platzhalter, Frontend-Statistiken

---

5.3 KI-Analysen

Fachliche Bedeutung: Multi-Stage Pipeline-basierte KI-Auswertungen

Unified Prompt System:

• Basis-Prompts: Wiederverwendbare Templates (z.B. "Body Analysis")
• Pipeline-Prompts: Multi-Stage Workflows (z.B. "Complete Insight")
• Stages: Unbegrenzte Anzahl, parallele Ausführung möglich
• Platzhalter: 32+ dynamische Platzhalter ({{weight_current}}, {{goal_weight}}, etc.)

Gespeicherte Daten:

• Prompt-Typ (base/pipeline), Stages-Config (JSONB)
• Output-Format (text/json), Output-Schema (optional)
• AI-Response, Metadata (genutzte Platzhalter mit Werten)

Berechnete Werte:

• Stage-Outputs: JSON-Extraktion aus Basis-Prompts
• Cross-Stage References: {{stage_N_key}} Platzhalter
• Expert Mode: Vollständige Werte-Tabelle (nicht gekürzt)

Beziehungen:

• N:1 → Profil
• Nutzt: Data Layer, alle Tracking-Objekte
• Konsumiert: Platzhalter-Resolver (32 Funktionen)

Datenquellen:

• KI-Prompt-Editor (Admin Panel)
• Automatische Ausführung (Analysis Page)
• Test-Modus mit Debug-Info

---

5.4 Korrelationen & Scores

Fachliche Bedeutung: Automatische Muster-Erkennung und Fortschritts-Scores

Korrelations-Typen:

• Lag-Korrelationen: Energie-Bilanz → Gewichtsänderung (3d/7d/14d)
• Activity ↔ Recovery: Training Load → HRV/RHR
• Nutrition ↔ Body Composition: Protein → Magermasse
• Sleep ↔ Performance: Schlafqualität → Trainingsleistung

Score-Typen:

• Body Composition Score: Fortschritt zu Körper-Zielen
• Nutrition Score: Makro-Adherence + Konsistenz
• Activity Score: Volumen + Qualität + Balance
• Recovery Score: Schlaf + HRV/RHR + Rest Days
• Focus Area Scores: Gewichtete Ziel-Fortschritte

Berechnete Werte:

• Pearson Correlation: r-Wert + p-value
• Plateau Detection: Stagnation-Erkennung (21d ohne Fortschritt)
• Top Drivers: Rangliste der Einflussfaktoren
• Confidence Scores: Datenqualität (Anzahl Data Points)

Beziehungen:

• Konsumieren: Alle Tracking-Objekte
• Nutzen: Data Layer (correlations.py, scores.py)

Datenquellen:

• Automatische Berechnung (täglich/wöchentlich)
• Abrufbar via Chart Endpoints

---

6. Membership & Access Control

6.1 Membership Tiers

Fachliche Bedeutung: Stufen-basiertes Feature-Access-System

Tiers:

• Free: Basis-Features (Gewicht, Ernährung, 10 KI-Calls/Tag)
• Premium: Alle Features, unbegrenzte KI-Calls
• Trial: 14-Tage Premium-Test

Gespeicherte Daten:

• Tier, Trial-Start/-Ende
• Stripe Customer ID, Subscription ID (für spätere Payment-Integration)

Berechnete Werte:

• Trial-Status (aktiv/abgelaufen, Tage verbleibend)
• Feature-Zugriff (basierend auf Tier + Access Grants)

Beziehungen:

• 1:1 → Profil
• 1:N → Access Grants (individuelle Freischaltungen)
• Steuert: Feature Usage Tracking

---

6.2 Features & Limits

11 Feature-Kategorien:

• weight_entries, circumference_entries, caliper_entries
• activity_entries, nutrition_entries, photos
• ai_calls, ai_pipeline, data_export, data_import
• advanced_charts (geplant)

Tier Limits:

• Free: 1000 Einträge/Monat, 10 KI-Calls/Tag, 50 Fotos
• Premium: Unbegrenzt

Feature Usage Tracking:

• Tägliche/Monatliche Zähler pro Feature
• JSON-Logs (feature-usage.log)
• Reset: Täglich (ai_calls) oder monatlich (Einträge)

Beziehungen:

• N:1 → Profil
• Enforcement: HTTP 403 bei Limit-Überschreitung

---

6.3 Access Grants

Fachliche Bedeutung: Individuelle Feature-Freischaltungen (außerhalb des Tiers)

Gespeicherte Daten:

• Feature-Name, Granted-By (Admin-Profil)
• Grant-Date, Expiry-Date (optional)
• Grund/Notizen

Anwendungsfälle:

• Beta-Tester (früher Zugriff auf neue Features)
• Kompensation (nach Downtime)
• Partner/Freunde (kostenlose Premium-Features)

Beziehungen:

• N:1 → Profil
• Überschreibt: Tier-Limits für spezifisches Feature

---

7. Datenfluss & Anreicherung

┌────────────────────────────────────────────────────────────────┐
│                        DATENQUELLEN                             │
├────────────────────────────────────────────────────────────────┤
│ Manuelle Eingabe │ CSV-Import │ API-Sync (geplant)             │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                    SPEICHERUNG (PostgreSQL)                     │
├────────────────────────────────────────────────────────────────┤
│ Raw Data: weight_log, activity_log, nutrition_log, etc.       │
│ Source-Tracking: manual/import (Reimport-Schutz)              │
│ Profile-Isolation: profile_id auf allen Tabellen              │
└────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                  DATA LAYER (Berechnungen)                      │
├────────────────────────────────────────────────────────────────┤
│ 97 Funktionen in 6 Modulen:                                   │
│ • body_metrics: Trends, Projections, Body Composition         │
│ • nutrition_metrics: Energy Balance, Macro Consistency        │
│ • activity_metrics: Volume, Load, Quality, Abilities          │
│ • recovery_metrics: Sleep, HRV/RHR, Recovery Score            │
│ • scores: Focus Scores, Goal Progress, Category Scores        │
│ • correlations: Lag-Korrelationen, Plateau Detection          │
└────────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        ▼                     ▼                     ▼
┌──────────────┐    ┌──────────────┐      ┌──────────────┐
│   CHARTS     │    │  KI-ANALYSEN │      │  FRONTEND    │
├──────────────┤    ├──────────────┤      ├──────────────┤
│ 20 Endpoints │    │ 32 Platzh.   │      │ Statistiken  │
│ Chart.js     │    │ Multi-Stage  │      │ Dashboards   │
│ Format       │    │ Pipelines    │      │ Progress     │
└──────────────┘    └──────────────┘      └──────────────┘

---

8. Daten-Qualität & Confidence

Confidence Scoring

Fachliche Bedeutung: Automatische Bewertung der Datenqualität

Kriterien:

• Anzahl Datenpunkte: Mehr Daten = höhere Confidence
• Zeitspanne: Längere Historie = zuverlässigere Trends
• Konsistenz: Regelmäßige Erfassung (keine Lücken)
• Vollständigkeit: Alle relevanten Felder ausgefüllt

Confidence Levels:

0-29 Tage:    LOW (zu wenig Daten)
30-89 Tage:   MEDIUM (ausreichend)
90+ Tage:     HIGH (zuverlässig)

Anwendungen:

• Chart Metadata (Datenqualität anzeigen)
• KI-Analysen (Confidence-basierte Empfehlungen)
• Automatische Warnungen (bei zu wenig Daten)

Beziehungen:

• Berechnet von: Data Layer Funktionen
• Genutzt von: Chart Endpoints, KI-Platzhalter

---

9. Import & Export

9.1 CSV-Import

Unterstützte Formate:

• Gewicht: Apple Health (Deutsch/Englisch), Withings
• Ernährung: MyFitnessPal, Yazio
• Aktivität: Apple Health (Deutsch/Englisch)
• Schlaf: Apple Health (Deutsch/Englisch)
• Vitalwerte: Apple Health (Deutsch/Englisch), Omron (Deutsch)

Import-Logik:

• Duplikat-Erkennung: Nach (profile_id, date) oder (profile_id, date, start_time)
• Reimport-Schutz: Manuelle Einträge (source='manual') NIEMALS überschreiben
• Auto-Mapping: Activity Types via lernendes Mapping-System
• Error-Handling: Erste 10 Fehler im Frontend angezeigt

Beziehungen:

• Nutzt: activity_type_mappings (lernendes System)
• Speichert: source-Feld für Reimport-Tracking

---

9.2 Export

Formate:

• CSV: Pro Datentyp (weight.csv, activity.csv, etc.)
• JSON: Vollständiger Export (alle Daten, strukturiert)
• ZIP: Kombinierter Export (alle CSVs + JSON + Metadaten)

Umfang:

• Alle Tracking-Daten (Gewicht, Ernährung, Aktivität, Schlaf, Vitalwerte)
• Ziele, Focus Areas, Training Phases
• KI-Analysen (Insights)
• Membership-Daten (für Backup)

Beziehungen:

• Nutzt: Alle Tabellen (außer Auth-sensible Daten)
• Feature-Limit: 5 Exports/Monat (Free), unbegrenzt (Premium)

---

10. Fachliche Regeln & Constraints

10.1 Datenvalidierung

Gewicht:

• 30 kg ≤ Gewicht ≤ 300 kg
• Max 1 Eintrag pro Tag (Upsert bei Duplikat)

Körperfett:

• 3% ≤ BF% ≤ 60%
• Plausibilitäts-Check: LBM nicht höher als Gewicht

Vitalwerte:

• Ruhepuls: 30-200 bpm
• HRV: 10-300 ms
• Blutdruck: Systolisch 60-260 mmHg, Diastolisch 40-150 mmHg

Ernährung:

• Kalorien: 500-10000 kcal
• Protein/Carbs/Fat: 0-1000 g

Aktivität:

• Dauer: 1-1440 min (24h)
• Herzfrequenz: 40-220 bpm

---

10.2 Abhängigkeiten & Voraussetzungen

Caliper → Gewicht:

• Körperfettberechnung erfordert aktuelles Gewicht (±3 Tage)
• Wenn kein Gewicht: Warnung im Frontend

Ziele → Datenquellen:

• Ziel-Typ "weight" erfordert weight_log Einträge
• Ziel-Typ "vo2max" erfordert vitals_baseline Einträge
• Custom Goals: Keine Datenquelle (manuelle Erfassung)

KI-Analysen → Mindestdaten:

• Mindestens 7 Tage Daten für Trends
• Mindestens 30 Tage für Korrelationen
• Confidence-Warnung bei <30 Tagen

---

10.3 Zeitliche Constraints

Reimport-Schutz:

• Manuelle Einträge (source='manual') haben IMMER Vorrang
• Imports überschreiben nur source != 'manual'

Automatische Bereinigung:

• Sessions: Ablauf nach 7 Tagen (rolling refresh)
• Feature Usage: Reset täglich (KI) oder monatlich (Einträge)

Historische Daten:

• Keine Löschung (nur Soft-Delete geplant)
• Unbegrenzte Speicherung (außer bei GDPR-Request)

---

11. Erweiterbarkeit

Admin-erweiterbare Elemente

Training Types:

• Admin kann neue Typen hinzufügen (Name, Kategorie, Icon, Fähigkeiten)
• Automatisch verfügbar für alle Nutzer

Focus Areas:

• Admin kann neue Bereiche definieren (Name, Beschreibung, Kategorie)
• User können eigene Gewichtung setzen

KI-Prompts:

• Admin kann neue Prompts/Pipelines erstellen
• Unbegrenzte Stages möglich
• Basis-Prompts wiederverwendbar

Activity Mappings:

• System lernt automatisch bei Bulk-Kategorisierung
• Admin kann Mappings inline editieren

User-erweiterbare Elemente

Custom Goals:

• User kann beliebige Ziele definieren (Name, Typ, Einheit)
• Tägliche Werterfassung (Capture Page)

Focus Area Weights:

• User kann eigene Prioritäten setzen (Schieberegler)
• Dynamische Anpassung (jederzeit änderbar)

Training Phases:

• User kann manuelle Phasen definieren (geplant)
• Akzeptieren/Ablehnen von KI-Vorschlägen

---

Zusammenfassung: Daten-Architektur im Überblick

Datenobjekte (gespeichert):

• 1 Profil → N (Gewicht, Umfänge, Caliper, Vitalwerte, Fotos)
• 1 Profil → N (Aktivitäten, Ernährung, Schlaf, Ruhetage)
• 1 Profil → 1 Goal Mode → N Ziele → N Custom Goal Entries
• 1 Profil → N Focus Area Weights → N Goal Focus Contributions
• 1 Profil → N Training Phases, Fitness Tests, KI-Analysen

Berechnete Werte (Data Layer):

• 97 Funktionen in 6 Modulen
• Body, Nutrition, Activity, Recovery, Scores, Correlations
• Single Source of Truth für Charts + KI

Visualisierungen:

• 20+ Chart Endpoints (E1-E5, A1-A8, R1-R5, C1-C4)
• Chart.js Format, Confidence Scores, Metadata

KI-Integration:

• 32+ Platzhalter, Multi-Stage Pipelines, JSON-Output
• Expert Mode (vollständige Werte-Tabelle)

Access Control:

• Membership Tiers (Free, Premium, Trial)
• Feature Limits, Usage Tracking, Access Grants

Import/Export:

• CSV-Import (Apple Health, Garmin, Omron, etc.)
• Lernendes Mapping-System (Activity Types)
• CSV/JSON/ZIP Export

---

Stand: Phase 0c Complete (Multi-Layer Architecture) Nächste Phase: Phase 0d (Frontend Chart Integration) Version: v0.9h → v0.9i (geplant)