StudyHelper — AI Spaced Repetition Learning Tool

Background

The goal was to build every tool needed for CS study in one place. Existing flashcard services offered structural analysis of markdown material, AI-driven concept extraction, and adaptive review as separate products. Structuring multiple markdown files in a single LLM call repeatedly produced missing topics, misclassified files, and illogical ordering. The extracted concept lists also varied in quality. What was needed was a structure that guaranteed a floor on concept quality while keeping studying and note-taking inside the same interface.

System architecture

Five layers: app/ (HTTP routes) → application/ (use cases) → workflows/ (LLM pipelines) → infrastructure/ (repositories, LLM, parser) → core/ (domain models).
LLM gateway abstraction: infrastructure/llm/gateway.ts switches between the Anthropic API and the Claude CLI provider at runtime. generateAndValidate<T>() has Zod schema validation and automatic retry built in.
Workflow engine: workflows/import-project/{engine, steps} drives a four-step prompt chain of topic extraction → file classification → chapter assembly → validation.
Seven repositories: project, chapter, study, import-job, learn-job, annotation, user-note.

How it was built

Four-day MVP plus clean architecture. Day 1 shipped a working MVP in a single commit and refactored it into five layers (app / application / workflows / infrastructure / core) the same day. API routes handle only HTTP entry and validation; domain logic moved to application/, the LLM pipeline to workflows/, and Prisma repositories to infrastructure/db/repositories/.

Four-step prompt chaining. One complex judgment was split into topic extraction → file classification → chapter assembly → validation, with each step taking the previous step's structured output as input. Multi-file chapters add a two-step concept analysis chain, and a fallback cascade between steps drops down to heading-based results on failure.

LLM gateway with Zod auto-retry. Both the Claude API and the Claude CLI sit behind the LLMGateway abstraction, and callers use a single generateAndValidate<T>(prompt, schema) that returns only schema-validated results. On a schema mismatch it augments the prompt and retries automatically.

Automatic concept quality assurance. A three-stage quality pipeline holds the floor on LLM output: automatic scoring across five metrics (total count, supporting-concept ratio, Bloom-level uniformity, and others), a conditional LLM repair pass, and a quality comparison against the heading-based fallback.

SM-2 spaced repetition. After a study session, lib/spaced-repetition/sm2.ts takes a quality score from 0 to 5 and computes the next review date. Below 3 counts as a failure and resets repetitions to 0 so the item resurfaces the next day. At 3 or above the interval goes 1 day, then 3 days, then the previous interval × ease factor, and EF moves up or down with quality on every review (floor 1.3). An EF below 1.5 or two consecutive failures pushes the item into the relearning queue.

Background prefetching. A DB-backed job queue (the LearnJob table) and an in-process background worker generate the remaining concept content while the user studies the first concept. A cache hit loads instantly.

Annotation system. Text-selection inline highlights and notes, color coding, filtering and sorting, and a per-chapter notebook view are unified into one annotation UI. Studying and note-taking finish on the same screen.

Results

Five-layer clean architecture on Next.js 15 + Prisma + SQLite, with 10 Prisma models, 7 repositories, and 13 API routes.
Four-step prompt chaining plus automatic concept quality scoring and repair to guarantee a floor on LLM output quality.
LLM gateway abstraction for runtime switching between the Anthropic API and the Claude CLI provider.
Background prefetching so already-generated concepts load instantly and study flow is not interrupted.
Annotation highlights, notes, filters, and notebook view providing one combined interface for studying and note-taking.