SchuldownDetector

SchuldownDetector ist ein interaktives Dashboard, das WebUntis-Stundenpläne analysiert und detaillierte Statistiken über stattgefundene und ausgefallene Unterrichtsstunden liefert.

Lade deine WebUntis-Daten sicher und in Echtzeit, um genau zu sehen, wie hoch deine Ausfallquote ist, wie viel Zeit du gespart hast und welche Fächer am stärksten vom Unterrichtsausfall betroffen sind.

Features

• Persönlicher Login: Sicherer Login direkt mit deinen WebUntis-Zugangsdaten (ohne Hardcoding im Code).
• Globale Übersicht: Zeigt die gesamte Unterrichtszeit, gesparte Stunden und die Gesamtausfallquote deines Schuljahres.
• Dynamische Fächer-Erkennung: Das System liest automatisch alle deine belegten Fächer aus WebUntis aus.
• Fachspezifische Statistiken: Detaillierte Ansicht für jedes Fach inkl. Historie der letzten Stunden.
• Privacy First & Sicherheit: Daten werden nur lokal für die Session-Dauer auf dem Server verarbeitet. Inklusive Rate-Limiting gegen Brute-Force-Angriffe und sicheren HttpOnly-Cookies.
• Dark Mode / Light Mode: Modernes und voll responsives UI, basierend auf Tailwind CSS.

Tech Stack

• Frontend: React, React Router, Tailwind CSS, Lucide Icons, shadcn/ui
• Backend: Python 3.13, FastAPI, python-webuntis, itsdangerous, slowapi
• Infrastruktur: Docker & Docker Compose

Installation & Setup

Die einfachste Methode, um den SchuldownDetector lokal oder auf einem Server auszuführen, ist über Docker Compose.

1. Voraussetzungen

• Docker und Docker Compose müssen installiert sein.
• Git (optional, zum Klonen des Repositories)

2. Projekt klonen

git clone <dein-repo-url>
cd SchuldownDetector

3. Umgebungsvariablen konfigurieren (Optional, aber empfohlen)

Im backend-Verzeichnis oder in der docker-compose.yml können folgende Umgebungsvariablen angepasst werden, um die Sicherheit für ein Produktions-Deployment zu erhöhen:

# Backend Security Config
SESSION_SECRET=dein_sehr_langes_und_sicheres_geheimnis
SESSION_TTL_HOURS=12
REMEMBER_ME_TTL_DAYS=30
ALLOWED_ORIGINS=http://localhost:3000,https://deinedomain.de
COOKIE_SECURE=false # Auf 'true' setzen, wenn HTTPS (SSL/TLS) in Produktion genutzt wird!

# Rate Limiting
LOGIN_RATE_LIMIT_MAX_ATTEMPTS=5
LOGIN_RATE_LIMIT_WINDOW_SECONDS=60

4. Container starten

Baue und starte die Docker-Container im Hintergrund:

docker compose up --build -d

Das Frontend ist nun unter http://localhost:3000 erreichbar. Das Backend-API läuft unter http://localhost:8000.

Nutzung

1. Öffne die App im Browser (http://localhost:3000).
2. Bestätige den Datenschutzhinweis.
3. Gib den WebUntis Server-Präfix (z.B. mpg), deine Schule (füllt sich oft automatisch), deinen Benutzernamen, dein Passwort und deine Klasse (z.B. 10b) ein.
4. Nach dem Login wird dein Stundenplan analysiert und die Statistiken auf dem Dashboard dargestellt!

Datenschutz & Sicherheit

Dieses Projekt fragt sensible WebUntis-Zugangsdaten ab. Es wurde mit folgenden Sicherheitsstandards gebaut:

• Passwörter werden nicht im Klartext oder in Datenbanken gespeichert.
• Die Session-Daten werden mit itsdangerous verschlüsselt und signiert im Browser des Nutzers als HttpOnly-Cookie abgelegt.
• Es findet kein Tracking von Nutzerdaten durch Dritte statt.
• Ein konfigurierbarer Rate-Limiter (Brute-Force-Schutz) sichert den Login-Endpoint (/api/login) ab.

Hinweis: Wenn du diese App öffentlich hostest, verwende zwingend einen Reverse Proxy mit HTTPS/TLS (z.B. Nginx oder Traefik) und setze COOKIE_SECURE=true.

Entwickelt von

Matti Dechant (@mjo2804)