Gamification |

CogniVault Backend Explained, Part 4 · Study Tools, Progress, and the Privacy Receipts

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

All abbreviations are fully explained in the appendix at the bottom of the page.

In we followed a question through hybrid retrieval and the agent loop to a cited answer. In this final part, the same machinery gets pointed at a different goal: teaching you — and then we close the series by auditing the project’s central promise: nothing leaves your machine.

One recipe, four study tools

CogniVault generates quizzes, multi-lesson workshops, flashcard decks, and mindmaps from your documents. Four different outputs — but under the hood, one shared five-step recipe:

Retrieve. The same hybrid search from Part 3, but instead of your question, the probe is a broad query like “key concepts, definitions, important facts, main ideas”, scoped to the documents you selected. Up to 15 representative chunks come back.
Prompt from a template. The instructions sent to Gemma are not buried in Python — they’re editable Markdown files in backend/prompts/ (quiz.md, flashcards.md, and so on). Drop a modified copy into backend/prompts/custom/ and it overrides the shipped version on the very next request. No restart, no code change. Prompt engineering as configuration.
Constrain the output. Asking a small local model to “please return JSON” works most of the time — and most of the time is a production bug. CogniVault uses Ollama’s grammar-constrained generation (format="json"), which makes invalid JSON impossible rather than unlikely, plus low temperature for consistency. The full saga of getting reliable structure out of a 4-billion-parameter model is in .
Validate defensively. Every generated item is checked field by field, and malformed items are dropped rather than failing the whole batch. Small models occasionally fumble one question out of ten; a product shouldn’t collapse because of it.
Persist. Everything lands in SQLite, so quizzes are resumable, workshop progress survives restarts, and flashcard statuses are remembered per deck.

Here’s the recipe in motion for a quiz:

%%{init: {'sequence': {'actorFontSize': 28, 'messageFontSize': 24, 'loopTextFontSize': 22, 'noteFontSize': 22}}}%% sequenceDiagram actor U as You 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: Pick scope, difficulty, question count F->>B: POST /api/study/quiz/generate B->>V: Hybrid search, scoped to your documents V-->>B: Up to 15 representative chunks B->>B: Render the quiz.md prompt template B->>O: chat(format="json", low temperature) O-->>B: Grammar-constrained JSON B->>B: Validate each question, drop bad ones B->>S: Save quiz (resumable later) B-->>F: Typed response F-->>U: Play, submit, score — and maybe a new badge

The four tools differ only in their template and their shape: quizzes produce multiple-choice and true/false questions with explanations; workshops produce an outline first and then write each lesson on demand when you open it; flashcards produce front/back pairs; mindmaps produce a topic tree that the frontend renders as an interactive diagram. (That renderer is its own adventure: .)

Sessions that track themselves

Most study apps make you press a start button, and most people forget. CogniVault takes a different stance: study sessions are inferred, not declared.

Every chat message either extends the current session or — after a 15-minute idle gap — quietly starts a new one. Walk away for coffee, come back, keep working: same session. Come back tomorrow: new session. No buttons, no forgetting.

Each message also records a tiny event (timestamp, whether you used a scope filter or attachments) into progress.db — a SQLite database, which is a complete relational database living in a single file. Eleven tables hold everything: sessions, message events, earned badges, quiz attempts and saved quizzes, workshops and lessons, decks and cards, and mindmaps.

One engineering note worth copying: the tracking call inside the chat endpoint is wrapped so that it can never block or break the chat. Analytics must be a passenger, never a driver.

25 badges, defined as data

The achievements aren’t scattered through the code as if statements. They live in one JSON file — 25 entries, each with a code, a name, an icon, the metric it watches, and a target. After each relevant action, an evaluator checks every definition against the database and persists anything newly earned. Some badges form ladders, each pointing to its next level.

Declarative beats imperative here for a simple reason: adding badge number 26 means adding a JSON entry, not writing new logic. The design behind the streaks, the idle-gap rule, and the 90-day heatmap got its own post: .

Voice input, without a cloud microphone

The microphone button is powered by faster-whisper — OpenAI’s Whisper speech-recognition model re-implemented on a faster inference engine — running on your CPU with int8 quantisation (8-bit numbers instead of 32-bit: smaller, faster, accurate enough). No audio ever leaves the machine.

The model is lazy-loaded on the first transcription so app startup stays instant, and if faster-whisper isn’t installed at all, the frontend simply hides the mic button. Features should degrade, not detonate.

The privacy receipts

The series began with a promise: nothing leaves your machine. Promises are cheap — here’s the audit. Every byte CogniVault stores, and where it lives:

Data	Location	Format
Your uploaded files	`docs/` folder	The original files
Search vectors	`vector_store.faiss`	FAISS binary index
Chunk text and metadata	`vector_store.json`	JSON
File-to-category map	`categories.json`	JSON
Chat sessions	`chat_history.json`	JSON
Sessions, badges, quizzes, workshops, decks, mindmaps	`progress.db`	SQLite
Ingestion checkpoints	PostgreSQL (local Docker volume)	DBOS system tables
The AI models themselves	Ollama’s local model store	Model weights

Nothing in that table is on someone else’s computer. Inference goes to localhost. Embeddings go to localhost. The only outbound request the backend ever makes is the URL-import feature — at your explicit request, and guarded against fetching private addresses. The app even surfaces these stats live in its Privacy Vault Audit panel.

And because trust needs more than a table: the whole backend is covered by a pytest suite you can run yourself — the approach is documented in .

Series wrap-up

Four parts, one architecture:

— three processes, four layers, and a decoder ring for the jargon
— a durable, format-aware pipeline that turns any document into searchable vectors
— two retrievers covering each other’s blind spots, fused by rank, driven by an agent
Part 4 — the same machinery generating study materials, tracking progress without buttons, and a storage map with no cloud rows in it

If there’s one theme, it’s this: boring, verifiable choices in service of privacy. Exact search instead of approximate. SQLite files instead of hosted databases. Grammar-constrained JSON instead of hopeful parsing. Soft deletes instead of clever index surgery. Every piece is something you can open, read, and check — which is exactly the point.

Appendix: Abbreviations in this post

Abbreviation	Full form	Meaning
JSON	JavaScript Object Notation	The structured format the generators force the model to produce
SQLite / SQL	(SQL = Structured Query Language)	A complete relational database living in one file, `progress.db`
MCQ	Multiple-Choice Question	One of the two quiz question types (the other is true/false)
CPU	Central Processing Unit	Where Whisper runs — no graphics card required
int8	8-bit integer (quantisation)	Storing model weights as small integers: smaller, faster, accurate enough
AI	Artificial Intelligence	Software performing tasks that normally need human intelligence
API	Application Programming Interface	The endpoints the Study Hub and dashboard call
FAISS	Facebook AI Similarity Search	The vector index in the privacy-receipts table
DBOS	Database-Oriented Operating System	The durable-workflow library whose checkpoints live in PostgreSQL
SSRF	Server-Side Request Forgery	The attack class the URL importer guards against
PNG / PDF	Portable Network Graphics / Portable Document Format	Two of the mindmap export formats (plus Markdown)
SVG	Scalable Vector Graphics	The browser drawing format behind the interactive mindmap rendering

Next steps: clone and read along — the README maps the full architecture, and every claim in this series can be checked directly against the code in backend/. And if you want the deep-dive versions of these topics, the picks up where this tour ends.

Part 7 · Gamifying Learning: 25 Badges, Idle-Gap Sessions, and a 90-Day Heatmap

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

Part of a series on building . Previously: .

All abbreviations are fully explained in the appendix at the bottom of the page.

I taught secondary-school ICT for eight years before pivoting to full-stack development, and the most reliable lesson from that period was uncomfortably simple: students who showed up consistently learned. Students who didn’t, didn’t. Talent, prior knowledge, even motivation on any given day — all of it was downstream of attendance.

CogniVault’s “Dashboard” tab is a small attempt to engineer for that. It’s not a Duolingo streak panic machine. It’s three things:

Hero stats — total study time, total sessions, current streak.
25 achievement badges — auto-tracked across chat, quizzes, workshops, flashcards, mindmaps.
A 90-day activity heatmap — GitHub-style, five purple intensity levels.

The whole thing is a small SQLite table-set and a few React components. The interesting part isn’t the code, though — it’s the design calls.

Idle-gap sessions

The hardest question turned out to be the simplest-sounding: what counts as one study session?

The naive answer is “anything bookended by open/close of the app.” That’s wrong. People leave tabs open. People bounce away for an hour and come back. People open the app at 9am, do nothing, and check in at 2pm.

The answer I landed on: a session ends when you’ve been idle for 15 minutes. Ask a question, idle for 16 minutes — that’s one session. Come back, ask another — that starts a new one. The threshold is configurable via STUDY_SESSION_IDLE_GAP_SECONDS=900.

The clock keys off chat messages — the conversational core of studying in CogniVault. Every message either extends the open session (bumping its ended_at timestamp and message count) or, if the gap since the last activity exceeds the threshold, closes it implicitly and opens a new one:

# 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

Two writes per message. A session’s duration is ended_at - started_at, which means “total time” reflects engaged time, not “had a tab open.” Which is the only number that actually means anything. (Study Hub actions — quiz attempts, card flips, mindmap exports — are recorded as their own events and feed the badge metrics below; the session clock itself stays message-driven and honest.)

25 badges, not 250

Most gamified apps absolutely flood you with achievements. There’s a reason: more badges, more dopamine, more daily active users. The cost is that each badge means less — eventually the whole layer becomes wallpaper.

I capped CogniVault at 25, split across the five activity surfaces:

10 for chat & study habits (first question, 10 messages in a day, 100 total, an hour of total study, 3- and 7-day streaks, a 30-minute deep-dive session, night-owl and early-bird sessions, first use of the scope filter)
4 for quizzes (first quiz, a perfect score, passing on advanced difficulty, 10 quizzes)
4 for workshops (first outline, first completed lesson, first completed workshop, 5 completed)
4 for flashcards (first deck, 50 card flips, fully mastering a deck, 5 decks)
3 for mindmaps (first mindmap, first export, 5 mindmaps)

Each badge has a one-line unlock criterion that’s auto-evaluated on relevant events. Nothing manual, nothing the user has to “claim.” They just appear.

And the definitions aren’t code at all — they’re data. All 25 live in a single JSON file, each entry naming the metric it watches and the target to hit:

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

A single evaluator reads the current stats, compares every definition against its metric, diffs against already-earned badges, and inserts new unlocks into progress.db. Adding badge number 26 means adding a JSON entry, not writing new logic. Several badges form ladders — each knows which badge is its “next level,” which powers the detail view’s nudge toward the next goal.

The heatmap

The 90-day heatmap is the part I’m proudest of, and also the simplest. It’s a 13×7 grid of cells, one per day, coloured by total study time that day.

Five intensity levels:

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)

The data is conceptually one aggregation over the sessions table:

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;

The backend zero-fills the missing days so the frontend always receives exactly 90 entries, and a small client-side function bins each day’s total into the five levels. Click any cell and a DayDetailModal opens with that day’s numbers — study time, sessions, messages — plus any badges earned that day.

The reason I love this component: it makes the texture of a study habit visible. Streaks are great, but a streak is one number. A heatmap shows you that you study harder on weekends, or that you’ve been on a slow drift downward all month, or that the gap between your last “level 4 day” and today is longer than you thought. It reflects something the user can act on.

What I deliberately left out

Three things you’d find in most gamified apps, intentionally absent from CogniVault:

Streak panic. No “your streak is in danger!” pop-up. No streak freeze rules. No yellow exclamation marks. The streak is shown — that’s the entirety of the feedback loop. If a user breaks their streak, they break their streak. Adults don’t need shaming UX.
Leaderboards. This is a single-user, fully local app. There’s no global comparison. (And there shouldn’t be — leaderboards optimise the wrong thing for studying.)
Confetti, fanfare, push notifications. A newly earned badge shows up in the quiz results screen and on the dashboard grid. That’s the entire celebration. Anything bigger is theft of the user’s attention for the app’s benefit, not theirs.

The general principle: measure what matters, surface it without nagging. Notice that you came back. Reflect that back to you. Don’t pretend you care more than you do.

What the dashboard doesn’t try to optimise

A common trap with these dashboards is reverse-causation: the user starts gaming the metric instead of doing the underlying thing. A daily-question count, for instance, gets you users who ask one filler question per day to keep their streak alive.

So the bar is deliberately low in exactly one place and high everywhere else. There is one zero-effort badge — “First Question,” earned on your very first message — because every game needs an on-ramp that proves the system works. After that, the metrics get hard to game without doing the actual work:

Total study time — only accrues during active engagement, with idle-gap cutoffs.
Sessions — adding more requires actually starting separate work periods.
Badges — almost all require depth (100 messages, ace a quiz, master a deck, complete 5 workshops), not just touch.
Heatmap intensity — needs sustained engagement on a given day.

Implementation: small on purpose

The gamification core is three SQLite tables —

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 the JSON badge definitions, one evaluator module, and a handful of React components (SummaryCards, AchievementGrid, ActivityHeatmap, DayDetailModal). The same progress.db file has since grown more tables for the Study Hub’s saved quizzes, workshops, decks, and mindmaps — but the badge-and-session machinery itself remains a couple hundred lines.

There’s nothing fancy in any of it. The dashboard works because the design calls are right, not because the implementation is clever.

Takeaway

If you’re building a learning tool — or any tool that lives on user habit — gamify consciously. Pick the metrics that reflect what you actually want to encourage. Cap your achievement surface. Skip the streak-panic UX. Make the texture of usage visible without making the app desperate.

Or, more bluntly: don’t build Duolingo. Build a dashboard the user occasionally glances at and then closes, feeling slightly more inclined to keep going. That’s the whole job.

Appendix: Abbreviations in this post

Abbreviation	Full form	Meaning
UX	User Experience	How the product feels — the thing streak-panic mechanics sacrifice
ICT	Information and Communications Technology	The subject I taught for eight years before going full-stack
SQLite	(SQL = Structured Query Language)	A complete relational database living in one file, `progress.db`
JSON	JavaScript Object Notation	The data format the 25 badge definitions live in
UI	User Interface	The dashboard surface: stats, grid, heatmap

Next up: .