# 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.