FOR_SMLFLG.md

StudyAgent — FOR_SMLFLG

Was ist das?

ADHS-freundlicher Study Buddy: Hilft Studenten mit ADHS durch ihr Semester. Keine starren Plaene — Micro-Steps, Buddy-Ton, Dopamin beim Start statt beim Abschluss.

Warum

Samuel IS die Zielgruppe. 569 ChatGPT + 232 Claude Sessions dokumentieren das Problem. Kern-Insight: Dopamin kommt beim Task-BEGINN, nicht beim Complete. Jeder Step = frischer Start.

Pain Points die das System loest

1. Lernplaene die nie halten — elastischer Plan, kein Guilt
2. WIP explodiert — max 2 Faecher gleichzeitig (hard enforcement in API)
3. Zeitdruck als Feature — Panik-Modus bei <48h
4. Routinedokumentation unmoeglich — Micro-Steps (je 5 Min)
5. Session-Memory — nie wieder bei Null anfangen

Architektur & Tech-Stack

StudyAgent/
├── main.py          # FastAPI app, alle Routes, htmx-Partials (~516 LOC)
├── agent.py         # MiniMax M2.5 API-Call, Fallback-Steps ohne Key
├── models.py        # SQLAlchemy Models (Subject, Deadline, MicroStep, StudySession)
├── database.py      # SQLite Setup, Session-Maker
├── requirements.txt
├── static/style.css # Warm palette, ADHS-friendly Design
├── templates/
│   ├── base.html
│   ├── index.html
│   └── partials/    # subject_card, deadline_item, micro_step_card,
│                    # elastic_plan, progress_journey, session_banner
└── study_agent.db   # auto-created

Tech: Python + FastAPI (async, lifespan) + SQLAlchemy + SQLite + htmx + Jinja2 + MiniMax M2.5 API

Starten / Nutzen

cd ~/Projekte/StudyAgent

# Erste Einrichtung
pip install -r requirements.txt
export MINIMAX_API_KEY=your-key-here   # optional — ohne Key laufen Fallback-Steps

# Starten
.venv/bin/uvicorn main:app --reload   # oder: uvicorn main:app --reload
# open http://localhost:8000

Was funktioniert (implementiert)

• Dashboard (GET /) — aktive Faecher, naechste Deadlines, naechster Step, Session-Banner, Panik-Indikatoren
• Faecher CRUD (POST/DELETE /subjects) — WIP-Limit 2 wird server-seitig enforced
• Deadlines anlegen (POST /deadlines) — auto-generiert sofort Micro-Steps via MiniMax M2.5
• Steps abschliessen/ueberspringen (POST /steps/{id}/complete|skip) — naechster Step wird inline geladen
• Elastischer Plan (GET /deadlines/{id}/plan) — auto-komprimiert wenn Steps die verbleibende Zeit uebersteigen
• Replan (POST /deadlines/{id}/replan) — loescht pending+skipped, generiert neu
• Session-Tracking — Sessions werden auto-gestartet, after 30 Min Inaktivitaet auto-geschlossen
• Panik-Modus (is_panic_mode()) — greift bei <48h, reduziert auf 3-4 wesentliche Steps
• AI-Fallback — ohne MINIMAX_API_KEY kommen sinnvolle Dummy-Steps (kein Absturz)

Was fehlt / bekannte Issues

• .env vorhanden (MINIMAX_API_KEY), in .gitignore geschuetzt. .env.example als Vorlage vorhanden.
• Browser-Test-Flow (Subject anlegen → Dashboard → Steps) noch nicht durchgespielt
• fi_date-aehnlicher Edge-Case: wenn due_date bereits vergangen ist, liefert is_panic_mode() False statt sinnvollen Zustand
• Kein Deployment-Setup (Fly.io geplant)
• Kein Auth (MVP-bewusste Entscheidung)

Entscheidungen & Lessons Learned

• htmx statt React — kein Build-Step, Partials direkt vom Server, funktioniert ohne JS-Framework
• Buddy-Ton in Code — "Kein Stress, machen wir anders." direkt in Responses, kein separates i18n
• Dummy-Steps als Fallback — API-Fehler oder fehlender Key darf nie das Feature brechen
• WIP-Limit server-seitig — nicht nur UI-Warnung, sondern echter HTTPException-Block im POST /subjects
• Auto-compress elastisch — 20% Buffer-Formel: wenn pending * 5min > hours_left * 0.8 * 60 → Replan

Next Steps (priorisiert)

1. MINIMAX_API_KEY in .env-File konfigurieren und testen
2. Browser-End-to-End-Test: Subject → Deadline → Steps → Complete/Skip
3. Edge-Case fixen: vergangene Deadlines richtig behandeln
4. Sprint 3: Panik-Modus visuell sichtbar machen (Banner, roten Rahmen)
5. Fly.io Deployment vorbereiten