FeelAloud/docs/ARCHITECTURE.md

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