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)