Files

T

Frank Schwenk 644b2304b3 docs: add Agent API docs, OpenAPI field descriptions, and project context files

2026-09-22 14:57:16 +02:00

9.6 KiB

Raw Blame History

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

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):

Erinnern — dezent um 8:00 und 12:00 (Europe/Berlin), silent, kein Alarm-Gebrüll
Erfassen — genommen / verpasst / snooze (+15/+30), inkl. Notification-Actions und Homescreen-Shortcuts
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

SOUL.md — du bist hier (Ton + Non-Goals)
README.md — Stack, API, Deploy, Entscheidungsprotokoll
meds.yaml — Slots und Medikamente (Single-User-Schedule)
messages.yaml — Humor-Pool (Reminder, Success, …)
frontend/ → python tools/build_frontend.py → public/
uvicorn server.app:app --reload --port 8000 oder docker compose up -d --build
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.

9.6 KiB Raw Blame History