SQLite |

CogniVault Backend erklärt, Teil 4 · Study Tools, Fortschritt und die Privacy-Belege

Fri, 12 Jun 2026 00:00:00 +0000

Alle Abkürzungen werden im Anhang am Ende der Seite vollständig erklärt.

In haben wir eine Frage durch das hybride Retrieval und den Agenten-Loop bis hin zur zitierten Antwort verfolgt. In diesem letzten Teil wird dieselbe Maschinerie auf ein ganz anderes Ziel ausgerichtet: Dir etwas beizubringen — und dann schließen wir die Serie ab, indem wir das zentrale Versprechen des Projekts überprüfen: Nichts verlässt deinen Rechner.

Ein Rezept, vier Lerntools

CogniVault generiert Quizzes, mehrteilige Workshops, Karteikartendecks und Mindmaps aus deinen Dokumenten. Vier verschiedene Outputs — aber unter der Haube steckt ein gemeinsames Fünf-Schritte-Rezept:

Abrufen (Retrieve). Dieselbe hybride Suche wie aus Teil 3, aber statt deiner Frage lautet der Such-Prompt etwas Breitgefächertes wie “Schlüsselkonzepte, Definitionen, wichtige Fakten, Hauptideen”, eingeschränkt auf die von dir ausgewählten Dokumente. Bis zu 15 repräsentative Chunks kommen zurück.
Mit einem Template prompten. Die Anweisungen an Gemma sind nicht tief in Python vergraben — es sind editierbare Markdown-Dateien im Ordner backend/prompts/ (quiz.md, flashcards.md usw.). Legst du eine modifizierte Kopie in backend/prompts/custom/ ab, überschreibt sie die mitgelieferte Version beim allerersten Request danach. Kein Neustart, keine Code-Änderung. Prompt Engineering als reine Konfiguration.
Output erzwingen (Constrain). Ein kleines lokales Modell zu bitten, “bitte gib JSON zurück”, klappt in den meisten Fällen — und in den meisten Fällen bedeutet in Produktion schlichtweg einen Bug. CogniVault nutzt Ollamas grammatikgebundene Generierung (format="json"), was ungültiges JSON nicht nur unwahrscheinlich, sondern unmöglich macht, gepaart mit einer niedrigen Temperature für Konstanz. Die ganze Geschichte, wie man zuverlässige Strukturen aus einem 4-Milliarden-Parameter-Modell presst, findest du in .
Defensiv validieren. Jedes generierte Item wird Feld für Feld gecheckt. Fehlerhafte Items werden verworfen, statt den kompletten Batch crashen zu lassen. Kleine Modelle verhauen manchmal eine von zehn Fragen; ein Produkt sollte deswegen nicht gleich zusammenbrechen.
Persistieren. Alles landet in SQLite. Quizzes sind später fortsetzbar, Workshop-Fortschritte überleben Neustarts und der Status von Karteikarten wird pro Deck gespeichert.

Hier ist das Rezept für ein Quiz in Aktion:

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as Du participant F as Study Hub UI participant B as FastAPI participant V as VectorDB participant O as Ollama (gemma4:e4b) participant S as SQLite U->>F: Scope, Schwierigkeit, Fragenanzahl wählen F->>B: POST /api/study/quiz/generate B->>V: Hybride Suche, eingeschränkt auf deine Dokumente V-->>B: Bis zu 15 repräsentative Chunks B->>B: Render das quiz.md Prompt-Template B->>O: chat(format="json", niedrige Temperature) O-->>B: Grammatikgebundenes JSON B->>B: Jede Frage validieren, schlechte verwerfen B->>S: Quiz speichern (später fortsetzbar) B-->>F: Typisierte Antwort F-->>U: Spielen, einreichen, punkten — und vielleicht ein neues Badge

Die vier Tools unterscheiden sich nur in ihrem Template und ihrer Form: Quizzes produzieren Multiple-Choice- und Wahr/Falsch-Fragen mit Erklärungen; Workshops erstellen zuerst eine Gliederung und schreiben dann jede Lektion on demand, wenn du sie öffnest; Karteikarten liefern Vorder-/Rückseiten-Paare; Mindmaps generieren einen Themenbaum, den das Frontend als interaktives Diagramm rendert. (Dieser Renderer war übrigens sein eigenes kleines Abenteuer: .)

Sessions, die sich selbst tracken

Die meisten Lern-Apps zwingen dich, einen Start-Button zu drücken, und die meisten Leute vergessen es. CogniVault geht da einen anderen Weg: Lernsessions werden abgeleitet, nicht manuell gestartet.

Jede Chatnachricht verlängert entweder die aktuelle Session oder — nach einer 15-minütigen Pause — startet stillschweigend eine neue. Geh einen Kaffee holen, komm zurück, mach weiter: gleiche Session. Komm morgen wieder: neue Session. Keine Buttons, kein Vergessen.

Jede Nachricht speichert außerdem ein winziges Event (Zeitstempel, ob du einen Scope-Filter oder Dateianhänge genutzt hast) in progress.db — eine SQLite-Datenbank, also eine komplette relationale Datenbank in einer einzigen Datei. Elf Tabellen halten alles fest: Sessions, Nachrichten-Events, verdiente Badges, Quiz-Versuche und gespeicherte Quizzes, Workshops und Lektionen, Decks und Karten sowie Mindmaps.

Eine kleine Engineering-Note, die sich abzugucken lohnt: Der Tracking-Call im Chat-Endpoint ist so verpackt, dass er den Chat niemals blockieren oder abbrechen kann. Analytics müssen immer Beifahrer sein, niemals der Fahrer.

25 Badges, als Daten definiert

Die Achievements sind nicht als if-Statements im Code verstreut. Sie leben in einer einzigen JSON-Datei — 25 Einträge, jeder mit Code, Name, Icon, der Metrik, die er überwacht, und einem Zielwert. Nach jeder relevanten Aktion prüft ein Evaluator jede Definition gegen die Datenbank und speichert neu verdiente Badges. Einige Badges bilden Leitern und verweisen auf das nächste Level.

Deklarativ schlägt hier imperativ aus einem einfachen Grund: Badge Nummer 26 hinzuzufügen bedeutet einen JSON-Eintrag zu ergänzen, nicht neue Logik zu schreiben. Das Design hinter den Streaks (Serien), der Pausen-Regel und der 90-Tage-Heatmap hat einen eigenen Artikel bekommen: .

Spracheingabe, ganz ohne Cloud-Mikrofon

Der Mikrofon-Button wird von faster-whisper befeuert — OpenAIs Whisper Spracherkennungsmodell, neu implementiert auf einer schnelleren Inference-Engine. Es läuft auf deiner CPU mit int8-Quantisierung (8-Bit-Zahlen statt 32-Bit: kleiner, schneller, genau genug). Kein Ton verlässt jemals deinen Rechner.

Das Modell wird erst bei der ersten Transkription geladen (Lazy Loading), damit die App sofort startet. Und wenn faster-whisper gar nicht erst installiert ist, versteckt das Frontend den Mikrofon-Button einfach. Features sollten sanft degradieren, nicht explodieren.

Die Privacy-Belege

Die Serie begann mit einem Versprechen: Nichts verlässt deinen Rechner. Versprechen sind billig — hier ist das Audit. Jedes Byte, das CogniVault speichert, und wo genau es lebt:

Daten	Speicherort	Format
Deine hochgeladenen Dateien	Ordner `docs/`	Die Originaldateien
Suchvektoren	`vector_store.faiss`	FAISS Binär-Index
Chunk-Text und Metadaten	`vector_store.json`	JSON
Datei-zu-Kategorie-Zuweisung	`categories.json`	JSON
Chat-Sessions	`chat_history.json`	JSON
Sessions, Badges, Quizzes, Workshops, Decks, Mindmaps	`progress.db`	SQLite
Ingestion Checkpoints	PostgreSQL (lokales Docker-Volume)	DBOS Systemtabellen
Die KI-Modelle selbst	Ollamas lokaler Model-Store	Modell-Gewichte

Nichts aus dieser Tabelle liegt auf dem Computer von jemand anderem. Inference geht an localhost. Embeddings gehen an localhost. Der einzige ausgehende Request, den das Backend jemals macht, ist der URL-Import — und das nur auf deinen ausdrücklichen Wunsch und geschützt davor, private Adressen abzurufen. Die App zeigt diese Statistiken sogar live im “Privacy Vault Audit”-Panel an.

Und weil Vertrauen mehr braucht als nur eine Tabelle: Das gesamte Backend ist von einer pytest-Suite abgedeckt, die du selbst ausführen kannst. Der Ansatz dazu ist in dokumentiert.

Fazit der Serie

Vier Teile, eine Architektur:

— Drei Prozesse, vier Schichten und ein Decoder-Ring für den Jargon
— Eine dauerhafte, formatbewusste Pipeline, die jedes Dokument in durchsuchbare Vektoren verwandelt
— Zwei Retriever, die gegenseitig ihre blinden Flecken abdecken, durch Rang fusioniert und von einem Agenten gesteuert werden
Teil 4 — Dieselbe Maschinerie, die Lernmaterialien generiert, Fortschritt ohne Buttons trackt, und eine Speichermap ohne Cloud-Abhängigkeiten

Wenn es ein Hauptthema gibt, dann das: Langweilige, verifizierbare Entscheidungen im Dienste der Privatsphäre. Exakte Suche statt Approximation. SQLite-Dateien statt gehosteter Datenbanken. Grammatikgebundenes JSON statt hoffnungsvollem Parsen. Soft-Deletes statt cleverer Index-Eingriffe. Jedes Puzzleteil ist etwas, das du öffnen, lesen und überprüfen kannst — und genau das ist der Punkt.

Anhang: Abkürzungen in diesem Post

Abkürzung	Volle Form	Bedeutung
JSON	JavaScript Object Notation	Das strukturierte Format, das die Generatoren vom Modell erzwingen
SQLite / SQL	(SQL = Structured Query Language)	Eine komplette relationale Datenbank, die in einer einzigen Datei lebt (`progress.db`)
MCQ	Multiple-Choice Question	Einer der beiden Quiz-Fragentypen (der andere ist Wahr/Falsch)
CPU	Central Processing Unit	Hier läuft Whisper — keine Grafikkarte notwendig
int8	8-bit integer (Quantisierung)	Modellgewichte als kleine Integer speichern: kleiner, schneller, genau genug
KI	Künstliche Intelligenz (AI)	Software, die Aufgaben ausführt, die normalerweise menschliche Intelligenz erfordern
API	Application Programming Interface	Die Endpunkte, die der Study Hub und das Dashboard aufrufen
FAISS	Facebook AI Similarity Search	Der Vektor-Index in der Privacy-Tabelle
DBOS	Database-Oriented Operating System	Die Durable-Workflow-Bibliothek, deren Checkpoints in PostgreSQL leben
SSRF	Server-Side Request Forgery	Die Art von Angriff, vor dem der URL-Importer schützt
PNG / PDF	Portable Network Graphics / Portable Document Format	Zwei der Export-Formate für Mindmaps (neben Markdown)
SVG	Scalable Vector Graphics	Das Zeichenformat im Browser, das hinter dem interaktiven Mindmap-Rendering steckt

Nächste Schritte: Klone und lies mit — die README skizziert die komplette Architektur, und jede Behauptung in dieser Serie kann direkt mit dem Code unter backend/ abgeglichen werden. Und falls du Lust auf die Deep-Dive-Versionen dieser Themen hast: Die knüpft genau da an, wo dieser Rundgang endet.

Teil 7 · Gamifying Learning: 25 Badges, Idle-Gap Sessions und eine 90-Tage-Heatmap

Wed, 20 May 2026 00:00:00 +0000

Teil einer Serie über die Entwicklung von . Zuvor: .

Alle Abkürzungen werden im Anhang unten auf der Seite vollständig erklärt.

Ich habe acht Jahre lang ICT an weiterführenden Schulen unterrichtet, bevor ich zum Full-Stack-Developer gewechselt bin. Die zuverlässigste Lektion aus dieser Zeit war unangenehm einfach: Schüler, die beständig da waren, haben gelernt. Die anderen nicht. Talent, Vorwissen, sogar die Motivation an einem bestimmten Tag – all das war der bloßen Anwesenheit nachgelagert.

Der “Dashboard”-Tab in CogniVault ist ein kleiner Versuch, genau das zu fördern. Es ist keine Duolingo-Streak-Panikmaschine. Es sind drei Dinge:

Hero-Statistiken – gesamte Lernzeit, gesamte Sessions, aktueller Streak.
25 Erfolgs-Badges – automatisch erfasst über Chat, Quizzes, Workshops, Flashcards und Mindmaps hinweg.
Eine 90-Tage-Aktivitäts-Heatmap – im GitHub-Stil, mit fünf lila Intensitätsstufen.

Das Ganze besteht nur aus einem kleinen Satz von SQLite-Tabellen und ein paar React-Komponenten. Der interessante Teil ist aber nicht der Code – es sind die Designentscheidungen.

Idle-Gap Sessions

Die schwerste Frage klang eigentlich am einfachsten: Was zählt als eine Lern-Session?

Die naive Antwort ist: “Alles, was zwischen dem Öffnen und Schließen der App passiert.” Aber das ist falsch. Leute lassen Tabs offen. Leute gehen für eine Stunde weg und kommen dann wieder. Leute öffnen die App um 9 Uhr morgens, machen nichts und schauen um 14 Uhr wieder rein.

Die Antwort, bei der ich gelandet bin: Eine Session endet, wenn du 15 Minuten lang inaktiv warst. Stellst du eine Frage und bist dann 16 Minuten inaktiv – das ist eine Session. Kommst du zurück und stellst eine weitere Frage – beginnt eine neue. Der Schwellenwert ist über STUDY_SESSION_IDLE_GAP_SECONDS=900 konfigurierbar.

Die Uhr richtet sich nach den Chat-Nachrichten – dem konversationellen Kern des Lernens in CogniVault. Jede Nachricht verlängert entweder die offene Session (indem sie den ended_at-Zeitstempel und die Nachrichtenanzahl erhöht) oder, falls die Pause seit der letzten Aktivität den Schwellenwert überschreitet, schließt sie diese implizit ab und eröffnet eine neue:

# Simplified from backend/services/progress_tracker.py
def record_message(now: float, idle_gap: int):
 last = most_recent_session()
 if last and (now - last.ended_at) <= idle_gap:
 extend(last, ended_at=now) # same session continues
 else:
 open_session(started_at=now, ended_at=now) # new session begins

Zwei Schreibvorgänge pro Nachricht. Die Dauer einer Session ist ended_at - started_at, was bedeutet, dass “Gesamtzeit” die aktive Zeit widerspiegelt, nicht “hatte einen Tab offen”. Das ist die einzige Zahl, die wirklich etwas aussagt. (Aktionen im Study Hub – Quizversuche, Karteikarten umdrehen, Mindmap-Exporte – werden als eigene Events erfasst und fließen in die Badge-Metriken unten ein; die Session-Uhr selbst bleibt nachrichtengetrieben und ehrlich.)

25 Badges, nicht 250

Die meisten gamifizierten Apps überfluten dich regelrecht mit Erfolgen. Es gibt einen Grund dafür: mehr Badges, mehr Dopamin, mehr täglich aktive Nutzer. Der Preis dafür ist, dass jedes Badge weniger bedeutet – irgendwann wird die ganze Schicht nur noch zur Tapete.

Ich habe CogniVault auf 25 limitiert, aufgeteilt auf die fünf Aktivitätsbereiche:

10 für Chat & Lerngewohnheiten (erste Frage, 10 Nachrichten an einem Tag, 100 insgesamt, eine Stunde Gesamtlernzeit, 3- und 7-Tage-Streaks, eine 30-minütige Deep-Dive-Session, Night-Owl- und Early-Bird-Sessions, erste Nutzung des Scope-Filters)
4 für Quizzes (erstes Quiz, perfektes Ergebnis, Bestehen auf fortgeschrittenem Schwierigkeitsgrad, 10 Quizzes)
4 für Workshops (erste Outline, erste abgeschlossene Lektion, erster abgeschlossener Workshop, 5 abgeschlossen)
4 für Flashcards (erstes Deck, 50 umgedrehte Karten, ein Deck komplett gemeistert, 5 Decks)
3 für Mindmaps (erste Mindmap, erster Export, 5 Mindmaps)

Jedes Badge hat ein einzeiliges Freischaltkriterium, das bei relevanten Events automatisch ausgewertet wird. Nichts Manuelles, nichts, was der Nutzer “einfordern” muss. Sie tauchen einfach auf.

Und die Definitionen sind gar kein Code – sie sind Daten. Alle 25 leben in einer JSON-Datei. Jeder Eintrag benennt die Metrik, die er beobachtet, und das zu erreichende Ziel:

{
 "code": "card_reviewer",
 "name": "Card Reviewer",
 "icon": "🃏",
 "metric": "total_card_flips",
 "target": 50
}

Ein einzelner Evaluator liest die aktuellen Statistiken aus, vergleicht jede Definition mit ihrer Metrik, gleicht sie mit bereits verdienten Badges ab und fügt neue Freischaltungen in die progress.db ein. Ein 26. Badge hinzuzufügen, bedeutet, einen JSON-Eintrag hinzuzufügen, nicht neue Logik zu schreiben. Mehrere Badges bilden Leitern – jedes weiß, welches Badge das “nächste Level” ist, was den Schubs in der Detailansicht zum nächsten Ziel antreibt.

Die Heatmap

Auf die 90-Tage-Heatmap bin ich am meisten stolz, und sie ist gleichzeitig das Einfachste. Es ist ein 13×7-Raster aus Zellen, eine pro Tag, farblich markiert nach der Gesamtlernzeit an diesem Tag.

Fünf Intensitätsstufen:

level 0 — no activity
level 1 — under 15 minutes (a quick check-in)
level 2 — 15-60 minutes (a focused session)
level 3 — 1-3 hours (substantial study)
level 4 — 3+ hours (a marathon)

Die Daten sind konzeptionell eine einzige Aggregation über die Sessions-Tabelle:

SELECT date(started_at) AS day,
 SUM(ended_at - started_at) AS seconds
FROM study_sessions
WHERE started_at >= date('now', '-90 days')
GROUP BY day;

Das Backend füllt die fehlenden Tage mit Nullen auf, sodass das Frontend immer genau 90 Einträge erhält. Eine kleine clientseitige Funktion ordnet die Tagessummen in die fünf Level ein. Wenn du auf eine beliebige Zelle klickst, öffnet sich ein DayDetailModal mit den Zahlen dieses Tages – Lernzeit, Sessions, Nachrichten – sowie allen Badges, die an diesem Tag verdient wurden.

Der Grund, warum ich diese Komponente liebe: Sie macht die Textur einer Lerngewohnheit sichtbar. Streaks sind toll, aber ein Streak ist nur eine Zahl. Eine Heatmap zeigt dir, dass du am Wochenende härter lernst, oder dass du den ganzen Monat über langsam abgebaut hast, oder dass die Lücke zwischen deinem letzten “Level 4-Tag” und heute größer ist, als du dachtest. Sie spiegelt etwas wider, worauf der Nutzer reagieren kann.

Was ich bewusst weggelassen habe

Drei Dinge, die du in den meisten gamifizierten Apps finden würdest, fehlen in CogniVault absichtlich:

Streak-Panik. Kein “Dein Streak ist in Gefahr!"-Popup. Keine Regeln für Streak-Freezes. Keine gelben Ausrufezeichen. Der Streak wird angezeigt – das ist der gesamte Feedback-Loop. Wenn ein Nutzer seinen Streak bricht, dann bricht er ihn eben. Erwachsene brauchen keine Shaming-UX.
Leaderboards. Das ist eine lokale Einzelnutzer-App. Es gibt keinen globalen Vergleich. (Und den sollte es auch nicht geben – Leaderboards optimieren beim Lernen das Falsche.)
Konfetti, Fanfaren, Push-Benachrichtigungen. Ein neu verdientes Badge taucht auf dem Quiz-Ergebnisbildschirm und im Dashboard-Raster auf. Das ist die ganze Feier. Alles, was größer ist, stiehlt dem Nutzer die Aufmerksamkeit zum Nutzen der App, nicht zu seinem eigenen.

Das allgemeine Prinzip: Miss, was wichtig ist, mach es sichtbar, aber ohne zu nerven. Registriere, dass du wiedergekommen bist. Spiegele dir das wider. Tu nicht so, als ob es dich mehr interessiert, als es das tatsächlich tut.

Was das Dashboard nicht zu optimieren versucht

Eine häufige Falle bei diesen Dashboards ist die umgekehrte Kausalität: Der Nutzer fängt an, die Metrik zu spielen, anstatt die eigentliche Sache zu tun. Ein täglicher Fragenzähler zum Beispiel führt dazu, dass Nutzer eine irrelevante Frage pro Tag stellen, um ihren Streak am Leben zu halten.

Deshalb ist die Hürde absichtlich an genau einer Stelle sehr niedrig und überall sonst hoch. Es gibt ein Badge, das keinen Aufwand erfordert – “Erste Frage”, das man für die allererste Nachricht bekommt –, weil jedes Spiel eine Einstiegsrampe braucht, die beweist, dass das System funktioniert. Danach werden die Metriken schwer zu manipulieren, ohne die eigentliche Arbeit zu tun:

Gesamtlernzeit – sammelt sich nur während aktiver Nutzung an, mit Idle-Gap-Abschaltungen.
Sessions – um mehr hinzuzufügen, muss man tatsächlich separate Arbeitsphasen starten.
Badges – fast alle erfordern Tiefe (100 Nachrichten, ein Quiz meistern, ein Deck perfekt beherrschen, 5 Workshops abschließen), nicht nur oberflächliches Antippen.
Heatmap-Intensität – erfordert anhaltendes Engagement an einem bestimmten Tag.

Implementierung: bewusst klein

Der Gamification-Kern besteht aus drei SQLite-Tabellen –

study_sessions (id, started_at, ended_at, message_count)
message_events (id, sent_at, session_id, had_scope_filter, had_attachments)
achievements_earned (code, earned_at)

— plus die JSON-Badge-Definitionen, ein Evaluator-Modul und eine Handvoll React-Komponenten (SummaryCards, AchievementGrid, ActivityHeatmap, DayDetailModal). Die gleiche progress.db-Datei hat mittlerweile weitere Tabellen für die gespeicherten Quizzes, Workshops, Decks und Mindmaps des Study Hubs bekommen – aber die Badge-und-Session-Maschinerie selbst ist nur ein paar hundert Zeilen lang geblieben.

Daran ist nichts Ausgefallenes. Das Dashboard funktioniert, weil die Designentscheidungen richtig sind, nicht weil die Implementierung raffiniert ist.

Fazit

Wenn du ein Lern-Tool baust – oder ein beliebiges Tool, das von den Gewohnheiten der Nutzer lebt –, dann setze Gamification bewusst ein. Wähle die Metriken, die das widerspiegeln, was du wirklich fördern willst. Begrenze die Anzahl der Erfolge. Verzichte auf die Streak-Panik-UX. Mach die Textur der Nutzung sichtbar, ohne dass die App verzweifelt wirkt.

Oder direkter gesagt: Bau kein Duolingo. Bau ein Dashboard, auf das der Nutzer ab und zu schaut und das er dann wieder schließt, mit dem leichten Gefühl, weitermachen zu wollen. Das ist der ganze Job.

Anhang: Abkürzungen in diesem Beitrag

Abkürzung	Vollform	Bedeutung
UX	User Experience	Wie sich das Produkt anfühlt – genau das, was durch Streak-Panik-Mechaniken geopfert wird
ICT	Information and Communications Technology	Das Fach, das ich acht Jahre lang unterrichtet habe, bevor ich zum Full-Stack gewechselt bin
SQLite	(SQL = Structured Query Language)	Eine komplette relationale Datenbank in einer einzigen Datei, `progress.db`
JSON	JavaScript Object Notation	Das Datenformat, in dem die 25 Badge-Definitionen liegen
UI	User Interface	Die Dashboard-Oberfläche: Statistiken, Raster, Heatmap

Als Nächstes: .