documentation/ARCHITECTURE.md

# Architektur

Dieses Dokument beschreibt den aktiven Datenfluss, die Kernkomponenten und die
wichtigsten Design-Entscheidungen des Lotto-6aus49-Systems. Es wurde mit Hilfe
einer Code-Graph-Analyse (`graphify-out/`, siehe unten) erstellt und sollte bei
größeren strukturellen Änderungen aktualisiert werden.

## 1. Aktiver Datenfluss

```mermaid
flowchart LR
    subgraph Ingestion["1. Daten-Ingestion"]
        A[GitHub Lotto Archive] -->|LottoAPIUpdater| B[AlleLottozahlen.csv]
    end

    subgraph Training["2. Training"]
        B --> C[FeatureEngineer<br/>20 Features]
        C --> D[AIMLEngine<br/>RandomForest, 40 Zahlen]
        C --> E[DeepLearningEngine<br/>LSTM, PyTorch]
        D --> F[Hybrid Predictor<br/>RF 40% + LSTM 60%]
        E --> F
    end

    subgraph Generation["3. Tipp-Generierung"]
        F --> G[UltimateAIMLHybridGenerator]
        G --> H1[HYBRID-OPT]
        G --> H2[BALANCED-SPREAD]
        G --> H3[HIGH-EV]
        G --> H4[SOFT-CONTRARIAN]
        H1 & H2 & H3 & H4 --> I[Quality/Popularity Score]
        I --> J[10 Tipps als CSV]
    end

    subgraph Learning["4. Learning-Loop"]
        B -->|neue Ziehung| K[AutoUpdateAndLearn]
        K -->|evaluiert| J
        K -->|retrained| D
        K -->|retrained| E
        K --> L[learning_log.json /<br/>strategy_weights]
    end

    J --> M[LottoNotifier<br/>Telegram]
    K --> M

    L -.->|beeinflusst nächsten Lauf| G
```

**Zwei unabhängige Cron-Zyklen** (siehe Abschnitt 4):

| Schritt | Entrypoint | Ausführt |
| --- | --- | --- |
| Ingestion + Training + Learning | `run_update_and_learn.sh` → `scripts/automation/auto_update_and_learn.py` | Mi + Sa, 20:00 Uhr |
| Tipp-Generierung | `run_tip_generator.sh` → `scripts/automation/weekly_tip_generator.py` | Di + Fr, 21:00 Uhr |

Wichtig: Die Tipp-Generierung läuft **vor** dem nächsten Update-Lauf. Das
System hinkt daher strukturell immer bis zu einem Zyklus hinter neu
verfügbaren Ziehungen hinterher, falls die externe Datenquelle verspätet
aktualisiert (siehe Abschnitt 5).

## 2. Kernkomponenten (aktive Pipeline)

Alle Pfade relativ zum Projekt-Root.

| Komponente | Datei | Rolle |
| --- | --- | --- |
| `LottoAPIUpdater` | `scripts/utils/update_from_api.py` | Holt neue Ziehungen. Unterstützt 3 Quellen (Lottoland, GitHub-Archiv, lottoAPI) über `fetch_from_all_apis()`, **aber** `auto_update_and_learn.py` ruft aktuell fest `api_name='github'` auf — Lottoland/lottoAPI-Fallback ist im Code vorhanden, aber nicht verdrahtet (siehe Abschnitt 5). |
| `AutoUpdateAndLearn` | `scripts/automation/auto_update_and_learn.py` | Orchestriert den 4-Schritte-Workflow: Daten aktualisieren → neue Ziehung prüfen → letzte Tipps evaluieren → Learning-Update (Retraining). |
| `FeatureEngineer` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | Baut 20 Features (Frequenzen, Gaps, Momentum, Trends, Beziehungen, Zyklen) aus den Rohdaten. |
| `AIMLEngine` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | RandomForest-Modelle, ein Modell pro Zahl (1–49). Cached unter `data/ultimate_ml_models/`. |
| `DeepLearningEngine` | `scripts/utils/deep_learning_engine_pytorch.py` | LSTM (PyTorch) über Sequenzen der letzten 20 Ziehungen. Wird mit RF zu 40/60 kombiniert (`Hybrid Predictor`). |
| `UltimateAIMLHybridGenerator` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | **God Node der Pipeline** (35 Kanten im Code-Graph) — verbindet Training, die 4 Tipp-Strategien und den Quality/Popularity-Score. Zentraler Einstiegspunkt für `generate_ultimate_tips()`. |
| `PatternEngine` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | Historische Verteilungsmuster (N/M/H-Zonen etc.), fließt als `pattern_weight` in die Tipp-Bewertung ein. |
| `HybridOptimizer` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | Kandidaten-Generierung für die HYBRID-OPT-Strategie. |
| `RealTimeLearner` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | Persistiert Learning-State (`learning_state.json`), passt `strategy_weights` nach jedem Zyklus an (`_update_strategy_weights`). |
| `PerformanceTracker` | `scripts/generators/ultimate_ai_ml_hybrid_generator.py` | Loggt Trefferauswertungen nach `data/learning_log.json`. |
| `WeeklyTipGenerator` | `scripts/automation/weekly_tip_generator.py` | Ruft `generate_ultimate_tips()`, exportiert CSV nach `data/generated_tips/`, aktualisiert `generation_history.json`. |
| `LottoNotifier` | `scripts/utils/notifier.py` | Telegram-Benachrichtigungen für neue Tipps und Ziehungsergebnisse. |

### Die 4 Tipp-Strategien

Pro Lauf werden 10 Tipps über 4 Strategien verteilt (Gewichtung passt sich
über `RealTimeLearner` dynamisch an, Startwerte: HYBRID-OPT 40%,
BALANCED-SPREAD 30%, HIGH-EV 20%, SOFT-CONTRARIAN 10%):

- **HYBRID-OPT** — AI-Score + Pattern-Gewicht kombiniert (`HybridOptimizer`)
- **BALANCED-SPREAD** — erzwingt Verteilung über N/M/H-Zonen, Summenbereich 127–171
- **HIGH-EV** — 2–3 Zahlen >31, meidet empirisch belegte populäre Einzelzahlen (siehe Abschnitt 3)
- **SOFT-CONTRARIAN** — bevorzugt in den letzten 30 Ziehungen unterrepräsentierte Zahlen

## 3. Design-Entscheidung: Quality-Score = EV-Optimierung, nicht Trefferprognose

Lotto-6aus49-Ziehungen sind mechanisch geprüfte, unabhängige Zufallsereignisse
(i.i.d.). Kein Modell — auch kein LSTM — kann daraus einen Vorteil gegenüber
reinem Zufall bei der **Trefferwahrscheinlichkeit** ableiten. Das bestätigen
auch die eigenen `learning_log.json`-Daten: die durchschnittlichen
Haupttreffer schwanken um den Erwartungswert von Zufallstipps (~0.73 Treffer
pro 6er-Tipp), ohne erkennbaren Aufwärtstrend trotz kontinuierlichem Retraining.

Der `_calculate_quality_score()` in `ultimate_ai_ml_hybrid_generator.py`
optimiert deshalb bewusst nicht auf Trefferwahrscheinlichkeit, sondern auf
**Expected Value im Gewinnfall**: unpopuläre Zahlenkombinationen haben bei
einem Treffer weniger Mitgewinner und damit eine höhere Auszahlung.
`_calculate_popularity_score()` bewertet dafür (Gewicht 50% der Quality-Formel):

1. Geburtstags-Range (>31 bevorzugt)
2. Empirisch belegte populäre Einzelzahlen (`POPULAR_PLAYER_PICKS`)
3. Zahlenfolgen/arithmetische Muster (nicht nur direkte Nachbarn)
4. Odd/Even-Split-Extremität (Menschen bevorzugen "ausgeglichen aussehende" 3-3-Splits)

Die Superzahl-Auswahl (`_get_smart_superzahl`) folgt derselben Logik: eine
feste EV-Rangfolge unpopulärer Ziffern statt (bedeutungsloser) historischer
Ziehungshäufigkeit, da die Superzahl pro Ziehung unabhängig gleichverteilt ist.

AI-Score, Pattern-Gewicht und Recency fließen weiterhin mit reduziertem
Gewicht in die Quality-Formel ein — nicht weil sie die Trefferchance erhöhen,
sondern weil eine gewisse Portfolio-Diversität über die 10 Wochentipps
gewünscht ist.

## 4. Automatisierung

Die Automatisierung läuft über **launchd** (`~/Library/LaunchAgents/`), nicht
über `crontab` — die Kommentare in `crontab -l` sind veraltete Doku-Reste und
spiegeln nicht den tatsächlichen Zeitplan wider:

| launchd Job | Plist | Zeitplan (tatsächlich) |
| --- | --- | --- |
| `com.lotto.update` | `scripts/automation/com.lotto.update.plist` | Mi + Sa, 20:00 Uhr |
| `com.lotto.weekly` | `scripts/automation/com.lotto.weekly.plist` | Di + Fr, 21:00 Uhr |

Logs: `logs/update_stdout.log` (Update+Learning), `logs/stdout.log`
(Tipp-Generierung).

## 5. Bekannte Schwachstellen / offene Punkte

- **Ungenutzter Fallback:** `LottoAPIUpdater.fetch_from_all_apis()` unterstützt
  Lottoland → GitHub → lottoAPI als Fallback-Kette, aber
  `AutoUpdateAndLearn.update_data()` ruft fest `api_name='github'` auf. Bei
  Verzögerungen der GitHub-Quelle (schon mehrfach vorgekommen) hinkt die
  Pipeline entsprechend hinterher, obwohl Lottoland oft schneller aktuell ist.
- **`update_from_web.py`** (lotto.de-Scraper) ist als dritter Fallback
  implementiert, aber nirgends in der automatisierten Pipeline eingebunden.
- **Utility-Skripte** in `scripts/utils/` (`health_check.py`, `validate_csv.py`,
  `verify_draws.py`, `model_evaluator.py`) existieren, sind aber nicht in die
  Cron-Automatisierung eingebunden; manuelle Ausführung bei Bedarf.

## 6. Code-Graph

Eine navigierbare Graph-Ansicht aller Module, Klassen und ihrer Beziehungen
liegt unter `graphify-out/`:

- `graphify-out/graph.html` — interaktive Visualisierung (im Browser öffnen)
- `graphify-out/GRAPH_REPORT.md` — God Nodes, Communities, auffällige Verbindungen
- `graphify-out/graph.json` — Rohdaten (GraphRAG-fähig)

Bei größeren strukturellen Änderungen: `/graphify --update` zum
inkrementellen Neuaufbau.