docs: add Agent API docs, OpenAPI field descriptions, and project context files

2026-09-22 14:57:16 +02:00
parent 88bdf6f34b
commit 644b2304b3
12 changed files with 1451 additions and 25 deletions
@@ -0,0 +1,203 @@
+# SOUL — TakeYourMeds
+
+> Herzstück des Projekts: **wofür** die App existiert und **wie** wir daran arbeiten.  
+> Persönliche Medikamenten-PWA — nicht Produkt, nicht Arztberatung, sondern ein Werkzeug für ein ADHS-Gehirn mit Humor-Schutzschicht.
+
+---
+
+## Was dieses Projekt ist
+
+**TakeYourMeds** (UI-Kurzname: **Medis**) ist eine **Single-User-PWA** für Medikamenten-Erinnerungen, Einnahme-Logging und leichte Compliance-Übersicht — mit Push, Offline-Sync und bewusst übertriebenem Sarkasmus.
+
+**Tagline (Login):** *Dein Gehirn. Deine Medis. Unser Sarkasmus.*
+
+**Der 3-Sekunden-Test:** *„Ah, Erinnerung an Medis — aber nicht so ein nerviger Gesundheits-App-Vibe."*  
+**Nicht:** *„Noch eine sterile Pillen-Tracker-App mit Mindset-Quotes."*
+
+**Domain:** [medis.schwenk.online](https://medis.schwenk.online)
+
+**Das ist nicht:**
+- Kein SaaS, kein Multi-User-Produkt, keine öffentliche Registrierung
+- Keine medizinische Beratung, keine Dosierungs-„Optimierung“ durch die App
+- Kein Ersatz für Therapeut:in oder Neurolog:in — nur **Merken + Loggen + Erinnern**
+
+**Kernrollen (mehr nicht):**
+1. **Erinnern** — dezent um 8:00 und 12:00 (`Europe/Berlin`), `silent`, kein Alarm-Gebrüll
+2. **Erfassen** — genommen / verpasst / snooze (+15/+30), inkl. Notification-Actions und Homescreen-Shortcuts
+3. **Motivieren ohne nerven** — Dopamin-Momente, Streak, Heatmap, Easter Eggs — **Spaß als Compliance-Hack**, nicht als Gamification-Zwang
+
+Alles andere (Agent-API, KI-Roast, Badges) ist **Erweiterung für Automatisierung und Laune**, nicht der Hauptzweck.
+
+---
+
+## Vision
+
+ADHS bedeutet: Erinnerungen kommen zu spät, zu früh oder gar nicht — und Schuldgefühle sind gratis. TakeYourMeds existiert, damit **eine feste Routine (Morgens/Mittags)** mit minimaler Friction am Handy hängen bleibt: ein Tap, ein Log, ein Push der nicht schreit.
+
+Die App soll **ehrlich über Vergessen** sein (Humor statt Moralpredigt), aber **zuverlässig im Hintergrund** (Server-Push, Scheduler, SQLite, Migrationen ohne Datenverlust). Karenzzeit (`reminder_window_minutes`, typisch 90 Min) ist bewusst **ADHS-realistisch** — nicht um 08:01 schon „verpasst“.
+
+---
+
+## Zielgruppe
+
+| Wer | Erwartung |
+|-----|-----------|
+| **Primär: Fränky** | Ein Nutzer, ein Gerät, PIN + lange Session (90 Tage), Meds in `meds.yaml` |
+| **ADHS-Kontext** | Kurze Wege, große Buttons, Dopamin-Feedback, Snooze ohne Drama |
+| **Technisch** | PWA installierbar, offline-tolerant, Push auf Android/iOS-Browser wo möglich |
+
+Keine generische „Patient:in“-Persona — Texte in `messages.yaml` sind **persönlich-sarkastisch** und dürfen roh sein. Neue UI-Texte sollen in dieselbe Schublade passen.
+
+---
+
+## Stimme & Ton
+
+Wie die App in UI, Toasts, Fehlern, Push und `messages.yaml` spricht:
+
+- **Sprache:** Deutsch (UI, Notifications, Humor-Pool). Code/Kommentare/README: wie im Repo (oft Deutsch).
+- **Ansprache:** **Du**, locker, direkt — kein Sie, kein Klinik-Broschüren-Deutsch.
+- **Voice:** Freundlich-sarkastisch, selbstironisch, **ADHS-interner Monolog** — Filter gegen Scham, nicht gegen Ernst.
+- **Fehler:** Ehrlich + kurz; Nutzer nicht beschuldigen („Falscher PIN. Dein Gehirn auch.“ ist Stil, nicht Mobbing).
+- **Push:** Dezent, `silent` — **kein** Alarm-Charakter, kein „VERPASST!!!“-Panic.
+- **Verboten:** Wellness-Influencer-Sprech („self-care journey“, „du schaffst das“-Platitüden), Corporate-Health („Synergien“, „Leverage“), falsche Klinik-Sicherheit („wir garantieren…“).
+
+### Wording-Beispiele
+
+| Kontext | Gut | Schlecht |
+|---------|-----|----------|
+| Erfolg | „Genommen! Dein Gehirn gibt dir einen langsamen High-Five.“ | „Einnahme erfolgreich protokolliert.“ |
+| Fehler Login | „Falscher PIN. Dein Gehirn auch.“ | „Authentifizierung fehlgeschlagen (401).“ |
+| Leer / Laden | „Dein Gehirn ist nicht kaputt. Es wartet nur auf den richtigen Treiber.“ | „Bitte warten…“ |
+| Push-Hinweis (Settings) | „Push-Erinnerungen um 8:00 und 12:00 — dezent, kein Alarm.“ | „Aktivieren Sie Benachrichtigungen für optimale Therapieadhärenz.“ |
+
+Motivation-Karte im Dashboard: bewusst **absurd-meta** („ADHD live, laugh, toaster bath motivational“) — das ist Markenfarbe, nicht Bug.
+
+---
+
+## Visuelle DNA
+
+| Element | Ja | Nö |
+|---------|----|----|
+| Dark UI, Mobile-first (max ~480px), portrait PWA | ✓ | |
+| Akzent `#F12F12` (schwenk-Familie), Fredoka | ✓ | |
+| Dopamin-Animation, Confetti, Streak 🔥 | ✓ | |
+| Bunte Akzente (Gelb/Cyan/Lila) auf dunklem Grund | ✓ | |
+| Klinisches Weiß, Stock-Foto-Wellness | | ✓ |
+| Informationsüberladung auf „Heute“ | | ✓ |
+| Englische UI-Labels ohne Grund | | ✓ |
+
+**Feel:** Spielerisch-utilitarisch — **ernste Funktion** (Medis nicht vergessen) in **unernstem Outfit**.
+
+---
+
+## Technische DNA
+
+Philosophie: **KISS, ein Container, eine SQLite-Datei**, schnelle Iteration ohne Frontend-Framework-Ballast.
+
+| Element | Ja | Nö |
+|---------|----|----|
+| FastAPI + uvicorn (API + Static in einem Prozess) | ✓ | |
+| SQLite `data/medis.sqlite` + versionierte SQL-Migrationen | ✓ | |
+| Vanilla JS, `python tools/build_frontend.py` → `public/` | ✓ | |
+| Web Push (VAPID) + APScheduler (8:00, 12:00, 21:00 Check) | ✓ | |
+| Docker Compose + Traefik auf boka | ✓ | |
+| OpenRouter nur für Roast/Motivation (mit `messages.yaml`-Fallback) | ✓ | |
+| Agent-API `/agent/*` mit separatem `AGENT_TOKEN` | ✓ | |
+| Postgres, Microservices, React-Build-Pflicht | | ✓ |
+| Alembic-Overhead für dieses Schema | | ✓ |
+| User-PIN hashen „weil Best Practice“ ohne Bedarf | | ✓ (bewusst: Single-User, `.env`) |
+
+**Daten heilig:** `./data` Volume, Backups (`tools/backup_db.py`), nie `docker compose down -v` auf Prod-Daten. Migrationen additive, schema_version-tracked.
+
+**Konfiguration lebt in Dateien:** `meds.yaml` (Slots, Meds), `messages.yaml` (~95 Texte) — editierbar ohne Code-Deploy für Texte (Container-Neustart für YAML-Reload).
+
+---
+
+## Non-Goals
+
+Was dieses Projekt **nicht** werden soll:
+
+- **Kein** öffentlicher Medikamenten-Tracker für Fremde (kein Sign-up, kein Marketing)
+- **Keine** Medizin-App mit Dosierungs-Empfehlungen, Wechselwirkungs-Checks oder „AI Doctor“
+- **Kein** Engagement-Bait (daily login rewards, Social Feed, Leaderboards mit Fremden)
+- **Keine** lauten/alarmierenden Notifications — Vertrauen in den Reminder zerstört den Zweck
+- **Kein** Feature-Bloat der den „Heute“-Screen überlädt (Shortcuts und Agent-API ja; Dashboard-Explosion nein)
+- **Kein** Tracking/Drittanbieter-Analytics — Privacy by „es ist eh nur ich“
+
+---
+
+## Anti-Manifest
+
+- Steriler Pillen-Tracker mit generischen Icons
+- „Du bist genug“-Wellness ohne Witz
+- Schuld-Trips schlimmer als Vergessen selbst
+- Komplexer Stack für ein persönliches Habit-Tool
+- Datenverlust beim Deploy (unverzeihlich hier)
+
+---
+
+## Project-Specific Rules
+
+- **`reminder_window_minutes`** respektieren — Business-Logik für pending/overdue/missed, nicht „optimieren“ ohne Absprache
+- **Streak** zählt nur Tage, an denen **alle** Slots `taken` sind — nicht umbiegen für „bessere“ Stats
+- **Badge am Icon = Streak**, nicht offene Dosen (bewusste Dopamin-Wahl)
+- **Humor** neue Texte → `messages.yaml` oder gleicher Ton in UI; KI-Roast bleibt optional, Fallback muss gut sein
+- **PWA-Updates:** Build-Hash / `version.json` / SW-Cache-Strategie laut `docs/PWA-STRATEGY.md` — keine halben Deploys
+- **Health-Daten:** minimal loggen, keine PII in Logs/Chat; `.env` und DB nie committen
+
+---
+
+## Wie wir zusammenarbeiten
+
+| Aktion | Default |
+|--------|---------|
+| Code ändern | ✅ Agent |
+| Dependencies | ✅ Agent (sinnvoll, KISS halten) |
+| Docs / README | ✅ Agent wenn Aufgabe es braucht |
+| `meds.yaml` / `messages.yaml` Inhalt | ⚠️ Fränky oder explizit — echte Med-Daten |
+| Git commit / push | 🚫 Nur auf explizite Anweisung |
+| Deploy prod (boka) | 🚫 Fränky, unless Chat sagt anders |
+| Diese Datei ändern | ⚠️ Vorschlagen oder explizit |
+
+### Prioritäten bei Konflikten
+
+```
+Zuverlässigkeit (Push, DB, Migrationen) > neues Feature
+ADHS-Friction (weniger Taps) > mehr Statistik
+Ehrlicher Humor > klinisch korrekt klingend
+Daten erhalten > schneller Refactor
+KISS-Stack > „modernster“ Stack
+```
+
+**Verification:** Nach nicht-trivialen Änderungen `python -m pytest tests/ -v` und bei Frontend-Touch `python tools/build_frontend.py`. Smoke: lokal `uvicorn` oder Compose-Health.
+
+---
+
+## Infrastructure (project-local)
+
+| | |
+|---|---|
+| **Repo (lokal)** | `~/git/froxxxy/takeyourmeds` |
+| **Server (boka)** | `/home/frank/medis.schwenk.online` |
+| **Domain** | `medis.schwenk.online` → Container :8000, Traefik `websecure` + `myresolver` |
+| **Daten** | `./data/medis.sqlite`, Backups unter `data/backups/` |
+| **Git remote** | Gitea `froxxxy/takeyourmeds` (siehe `INFRASTRUCTURE.md`) |
+| **Lokal** | http://localhost:8000 nach venv + `.env` + optional VAPID |
+
+---
+
+## Für Agents: Quick Start
+
+1. [`SOUL.md`](SOUL.md) — du bist hier (Ton + Non-Goals)
+2. [`README.md`](README.md) — Stack, API, Deploy, Entscheidungsprotokoll
+3. [`meds.yaml`](meds.yaml) — Slots und Medikamente (Single-User-Schedule)
+4. [`messages.yaml`](messages.yaml) — Humor-Pool (Reminder, Success, …)
+5. [`frontend/`](frontend/) → `python tools/build_frontend.py` → [`public/`](public/)
+6. `uvicorn server.app:app --reload --port 8000` oder `docker compose up -d --build`
+7. UI-Texte und neue Toasts gegen **Stimme & Ton** prüfen
+
+---
+
+## Ein Satz zum Mitnehmen
+
+**TakeYourMeds** ist Fränkys ADHS-freundlicher Medis-Sidekick: zuverlässig im Hintergrund, lautlos im Push, im UI ein sarkastischer Freund der dich an die Kapsel erinnert — ohne so zu tun, als wäre Vergessen ein moralisches Versagen.