Initial FeelAloud project

docs/ARCHITECTURE.md

@@ -0,0 +1,152 @@
+# Architektur
+
+## Überblick
+
+FeelAloud ist eine einzelne native iOS-App ohne Backend und ohne externe
+Paketabhängigkeiten. Alle Produktdaten werden mit Apple-Frameworks auf dem
+Gerät verarbeitet. Das Xcode-Projekt enthält derzeit ein App-Target.
+
+## Komponenten
+
+| Datei | Verantwortung |
+| --- | --- |
+| `FeelAloudApp.swift` | App-Einstieg, SwiftData-Container und globaler Router |
+| `RootView.swift` | Tabs, Sheets, App-Intent-Ausführung und Follow-up-Auswahl |
+| `HomeView.swift` | Startseite, Schnellaktionen und 7-Tage-Zusammenfassung |
+| `EntryFlowView.swift` | Aufnahme-, Analyse-, Prüf- und Speicherablauf |
+| `SpeechRecognizer.swift` | Mikrofon, lokale deutsche Spracherkennung und Transkript |
+| `MoodAnalysisService.swift` | Typisierte Extraktion über Foundation Models |
+| `MoodEntry.swift` | Datenmodell eines ausführlichen Tagebucheintrags |
+| `MoodSnapshot.swift` | Datenmodell und Regeln eines kurzen Check-ins |
+| `SnapshotView.swift` | Fünf-Stufen-Auswahl und spätere Kontextfrage |
+| `SnapshotNotificationScheduler.swift` | Lokale Erinnerungen und Notification-Routing |
+| `HistoryView.swift` | Zeitraumfilter, Diagramm, Detailansichten und Exportstart |
+| `SettingsView.swift` | Erinnerungszeiten, KI-Status, CSV-Export und Hinweise |
+| `XLSXExporter.swift` | OOXML-Arbeitsmappe und minimaler ZIP-Writer |
+| `CSVExporter.swift` | Semikolon-CSV mit UTF-8-BOM für Numbers/Excel |
+| `StartDiaryEntryIntent.swift` | Kurzbefehl und Action-Button-Integration |
+| `ShareSheet.swift` | Übergang zum systemweiten iOS-Share-Sheet |
+
+## Datenfluss: ausführlicher Eintrag
+
+1. `EntryFlowView` startet `SpeechRecognizer`.
+2. `SpeechRecognizer` fordert Mikrofon- und Speech-Berechtigung an und setzt
+   `requiresOnDeviceRecognition = true`.
+3. Nach dem Stoppen erhält `MoodAnalysisService` ausschließlich das erkannte
+   Transkript.
+4. `LanguageModelSession` erzeugt eine typisierte `GeneratedDiaryEntry`-Antwort.
+5. Die Person prüft und korrigiert alle Werte im Formular.
+6. Erst die bestätigten Werte werden als `MoodEntry` in SwiftData gespeichert.
+
+Ist Sprache oder Foundation Models nicht verfügbar, kann die Person zur
+manuellen Eingabe wechseln. Die App fällt nicht auf einen eigenen Cloud-Dienst
+zurück.
+
+## Datenfluss: Momentaufnahme
+
+1. Ein Check-in wird manuell oder über eine lokale Mitteilung geöffnet.
+2. Ein Tipp erzeugt einen `MoodSnapshot` mit Wert 1 bis 5 und Quelle.
+3. Bei **Sehr gut**, **Schlecht** oder **Sehr schlecht** bleibt
+   `awaitsFollowUp` aktiv.
+4. Beim nächsten normalen Aktivieren der App am selben Kalendertag sucht
+   `RootView` den jüngsten offenen Snapshot.
+5. Eine Antwort setzt `followUpNote`; **Heute nicht mehr fragen** setzt
+   `followUpDismissed`.
+
+Das direkte Öffnen aus einer Mitteilung unterdrückt genau eine sofortige
+Follow-up-Prüfung, damit zuerst die gewünschte Fünf-Stufen-Auswahl erscheint.
+
+## Persistenz
+
+Der `ModelContainer` verwaltet zwei SwiftData-Modelle:
+
+### MoodEntry
+
+| Feld | Zweck |
+| --- | --- |
+| `id`, `createdAt` | Eindeutigkeit und Zeitpunkt |
+| `moodRaw` | Dreistufige Bewertung des ausführlichen Eintrags |
+| `musicInHead`, `songName`, `earwormStrengthRaw` | Musik-/Ohrwurmangaben |
+| `socialContact` | Sozialkontakt vorhanden |
+| `distressRaw` | Leidensdruck durch Musik im Kopf |
+| `countermeasures`, `countermeasureActivity` | Gegenmaßnahmen |
+| `stress` | Stress, wenn keine Musik im Kopf vorhanden ist |
+| `transcript` | Bestätigter gesprochener Text |
+
+### MoodSnapshot
+
+| Feld | Zweck |
+| --- | --- |
+| `id`, `createdAt` | Eindeutigkeit und Zeitpunkt |
+| `ratingRaw` | Fünfstufige Bewertung |
+| `followUpNote` | Später ergänzter Kontext |
+| `followUpDismissed` | Kontextfrage für diesen Snapshot verworfen |
+| `sourceRaw` | `manual` oder `notification` |
+
+Für zukünftige Schemaänderungen muss vor Veröffentlichung einer inkompatiblen
+Version ein `VersionedSchema` mit `SchemaMigrationPlan` eingeführt werden.
+
+## Routing und Lebenszyklus
+
+`AppRouter` ist ein `@MainActor`-gebundener, beobachtbarer Singleton. Er hält
+nur flüchtigen UI-Zustand. `RootView` reagiert auf:
+
+- manuelle Aktionen der Oberfläche;
+- `StartDiaryEntryIntent`;
+- Antworten auf lokale Mitteilungen;
+- Wechsel der `scenePhase` zurück zu `.active`.
+
+Persistente Produktdaten liegen nicht im Router, sondern ausschließlich in
+SwiftData beziehungsweise `@AppStorage` für Erinnerungseinstellungen.
+
+## Erinnerungen
+
+`SnapshotNotificationScheduler` verwendet drei stabile Request-IDs. Beim
+Ändern der Konfiguration werden bestehende Requests entfernt und neu geplant.
+Die Trigger enthalten nur Stunde und Minute und wiederholen sich täglich.
+
+Es handelt sich um lokale Notifications. APNs, Push-Zertifikate und ein Server
+sind nicht erforderlich.
+
+## Export
+
+Der XLSX-Exporter erstellt drei Arbeitsblätter:
+
+1. **Übersicht** – Zeitraum, Anzahl, Durchschnitt und Verteilung;
+2. **Momentaufnahmen** – Zeitpunkt, Bewertung, Kontext und Quelle;
+3. **Tagebuch** – strukturierte Felder und Transkript.
+
+Die Arbeitsmappe besteht aus OOXML-Dateien in einem unkomprimierten ZIP-Archiv.
+Text wird XML-escaped; ZIP-Einträge erhalten CRC32-Prüfsummen. Der CSV-Export
+bleibt als kompatibler Alt-Export für ausführliche Einträge erhalten.
+
+Temporäre Exportdateien werden im temporären App-Verzeichnis erzeugt und erst
+nach einer ausdrücklichen Aktion an das Share-Sheet übergeben.
+
+## Fehler- und Verfügbarkeitsmodell
+
+- Fehlende Berechtigungen werden als verständliche, lokale Fehlermeldung
+  angezeigt.
+- Fehlende lokale Spracherkennung verhindert eine versehentliche Cloud-
+  Transkription.
+- Vor jeder KI-Nutzung wird `SystemLanguageModel.default.availability` geprüft.
+- Fehler beim Speichern werden aktuell nicht sichtbar eskaliert (`try?`). Vor
+  einem öffentlichen Release sollte dafür ein zentraler Fehlerpfad ergänzt
+  werden.
+- FeelAloud erteilt keine medizinischen Ratschläge und gibt dem Modell
+  ausdrücklich nur eine Extraktionsaufgabe.
+
+## Abhängigkeiten
+
+Es gibt keine Drittanbieterpakete. Verwendete Frameworks:
+
+- AppIntents
+- AVFoundation
+- Charts
+- Foundation / FoundationModels
+- Observation
+- Speech
+- SwiftData
+- SwiftUI
+- UIKit
+- UserNotifications