mood-tracking/AGENTS.md

AGENTS.md

Projektueberblick

Mood ist ein dateibasierter Stimmungstracker fuer klassische PHP/LAMP-Deployments ohne Datenbank. Die App rendert serverseitig PHP-Templates und speichert Nutzer-, Einstellungs- und Trackingdaten unter storage/.

Einstiegspunkte

• index.php: Front-Controller, bootet die App.
• src/bootstrap.php: laedt Dateien, initialisiert Session und stellt storage/ sicher.
• src/App.php: zentrales Routing und Grossteil der Anwendungslogik.

Wichtige Struktur

• src/Domain/: dateibasierte Repositories und Fachlogik.
• src/Support/: Auth, View, Verschluesselung, OpenAI, Web Push.
• templates/layout.php: globales Layout.
• templates/pages/: serverseitige Seiten.
• assets/css/app.css: gesamtes Styling.
• assets/js/app.js: Frontend-Logik fuer Charts, Formulare, Archiv, Push und PWA.
• storage/system/: globale Systemdaten wie Nutzer, Throttle, Notifications, Key-Dateien.
• storage/users/<user>/: Nutzerdaten, Einstellungen, Tage, Zusammenfassungen und Push-Status.

Routing

Die App nutzt keinen Router von aussen. Routen werden direkt in App::run() per switch ($path) behandelt.

Wichtige Routen:

• /setup
• /login
• /logout
• /
• /track
• /archive
• /options
• /push/subscribe
• /push/unsubscribe
• /push/test
• /reminders/run

Datenmodell

• Nutzer stehen in storage/system/users.json.
• Einstellungen pro Nutzer in storage/users/<user>/settings.json.
• Tagesdaten in storage/users/<user>/days/YYYY-MM-DD.txt.
• Wochen- und Monatszusammenfassungen unter storage/users/<user>/summaries/.
• Push-Subscriptions und Reminder-State liegen ebenfalls pro Nutzer unter storage/users/<user>/.

Tagesdateien und Zusammenfassungen koennen serverseitig verschluesselt gespeichert werden. Die Logik liegt in src/Support/EntryCrypto.php.

Sicherheitsrelevante Regeln

• Form-POSTs nutzen CSRF-Token via csrf_field() und App::enforceCsrf().
• JSON-POSTs nutzen App::enforceRequestCsrf().
• Auth-Logik liegt in src/Support/Auth.php.
• Security-Header werden zentral in App::sendSecurityHeaders() gesetzt.
• Aendere keine Auth-, Cookie-, CSRF- oder Reminder-Token-Logik leichtfertig.

Arbeitsregeln fuer Aenderungen

• Bevorzuge kleine, lokale Aenderungen. Die App ist bewusst simpel und frameworkfrei.
• Ziehe bestehende Hilfsfunktionen in src/helpers.php vor, statt neue Utility-Dateien einzufuehren.
• Wenn moeglich dem bestehenden Muster folgen: Daten lesen/schreiben in Repositories, Seiten in App, Ausgabe in Templates.
• Fuehre keine grossen Architekturumbauten ohne konkreten Bedarf ein. src/App.php ist zentral und gewollt monolithisch.
• Beruehre storage/ nur, wenn die Aufgabe das wirklich erfordert. Dort koennen echte Nutzerdaten liegen.
• Fuehre keine Massenformatierung oder kosmetische Grossumbauten ohne Anlass durch.

Frontend-Hinweise

• Das UI ist servergerendert; JavaScript erweitert nur interaktive Teile.
• Neue UI-Logik moeglichst in assets/js/app.js integrieren, statt neue Build-Schritte einzufuehren.
• Externe CDNs oder Frontend-Frameworks nicht einfuehren.

KI- und Push-Integrationen

• OpenAI-Zusammenfassungen laufen ueber src/Support/OpenAiSummaryService.php.
• Web Push und VAPID laufen ueber src/Support/WebPushService.php und src/Domain/NotificationRepository.php.
• Bei Aenderungen in diesen Bereichen besonders auf Datenschutz, Fehlerbehandlung und Rueckwaertskompatibilitaet der gespeicherten Daten achten.

Lokale Checks

Es gibt aktuell keine sichtbare Composer- oder PHPUnit-Konfiguration im Projekt.

Sinnvolle manuelle Checks:

• PHP-Syntax fuer geaenderte Dateien pruefen: php -l <datei>
• Setup/Login/Tracken/Archiv/Optionen im Browser kurz durchklicken
• Falls Push oder Reminder betroffen sind: relevante Endpunkte gezielt testen

Deployment-Annahmen

• Ziel ist klassisches Apache/LAMP bzw. Cloudron.
• .htaccess und Schreibrechte auf storage/ sind wichtig.
• Die App erwartet keinen Datenbankserver und keinen JS-Buildprozess.