Spaced Repetition App

Local-first spaced repetition studio

Local-first spaced repetition studio built with Next.js, Tailwind CSS, and Zustand to help learners plan, review, and track subjects.

Live Demo Source Issue Tracker

Overview

What it solves

Offline-first Next.js 14 experience: Today queue, dashboards, planners, and settings live in a single navigation shell.

Zustand stores persist every change to localStorage; demo data from src/data/demo-seed-data.json makes onboarding instant.

Experience

Flat, accessible UI with keyboard navigation, high-contrast states, and light/dark themes tuned for readability.

Derived selectors keep renders fast; migrations guard older snapshots as features evolve.

Forgetting Curve Model

Retention model

R (t) = exp (- \frac{t}{S})

$t$ = elapsed days since last review; $S$ = stability (days).
Next review scheduled when $R (t)$ hits target $R^{*}$ (default $0.7$ ).

Δ = - S ln (R^{*})

Examples with $R^{*} = 0.7$ :

$S = 1$ -> $Δ \approx 0.36 d$ (8.6h); $S = 2$ -> $Δ \approx 0.71 d$ (17.1h); $S = 5$ -> $Δ \approx 1.78 d$ (42.8h).

With $R^{*} = 0.8$ : $S = 2$ -> $Δ \approx 0.45 d$ (10.7h). With $R^{*} = 0.6$ : $S = 1$ -> $Δ \approx 0.51 d$ (12.3h).

We render piecewise exponential segments per review; a live marker recomputes

R (t)

each minute and surfaces

t_{zero} = S \cdot ln (100)

(when retention would drop near 1% if untouched).

Stability update

S_{new} = clamp (S_{old} (1 + α (q - 0.5)), S_{m i n}, S_{m a x})

Defaults:

a lp ha = 1

S_{min} = 0.25, d

S_{ma x} = 3650, d

q in [0, 1]

Subject difficulty scales stability:

S_{eff} = S^{d}, d \in [0.5, 1.5]

Scheduling flow

Δ = - S_{eff} ln (R^{*})

If an exam date exists, clamp to $Δ = min (Δ, exam_date - now)$ ; apply load smoothing (+/- 1-2 days if heavy); persist $next_review_at$ and redraw timeline.

Scheduling uses UTC; "today" boundaries use the learner timezone.

Stored data

Topic

stability, retrievabilityTarget, lastReviewedAt, nextReviewDate, reviewsCount, subjectDifficultyModifier, events[]

Event (review)

at, reviewQuality, reviewKind, resultingStability, targetRetrievability, nextReviewAt, intervalDays

Event (skip)

at, reviewKind, nextReviewAt

Subject

examDate, difficultyModifier, color, icon

Risk scoring (daily ordering)

score = 0.55 (1 - R_{now}) + 0.25 overdue + 0.15 exam + 0.05 difficulty

$R_{now} = e^{- \frac{Δ t}{S _{eff}}}$ ; $overdue = min (1, \frac{overdue_days}{3})$ ; $exam = min (1, \frac{1}{m a x ( 1 , days_to_exam )})$ ; difficulty boosts low-quality streaks and early cards.

Interval growth sanity

Successful recalls increase S, so Delta = -S ln(R*) grows unless capped by exams or smoothing. Each review persists intervalDays for QA and the timeline stitches back to ~100% before the next decay segment.

I0 -> I1 -> I2   (expected t2 > t1 > t0)

Daily state machine

AvailableToday -> Completed (review once per day)
AvailableToday -> Skipped (manual or auto at local midnight)

Topics appear in Today at most once per local day; skips respect exam dates.

Smoothing & safeguards

Load smoothing nudges low-risk items +/- 1-2 days (daily cap ~20) while keeping exam constraints.
Midnight auto-skip rolls unfinished items to the next light day with a banner summary.
Early reviews can stretch future intervals or keep the original plan.

References

Exponential forgetting curve and code: src/lib/forgetting-curve.ts; docs/core/ALGORITHMS_FORGETTING_CURVE.md
Spaced repetition overview (SM-2, FSRS) in project docs and linked Wikipedia sources.
Scheduling diagrams and flows captured in docs/core notes.

Screenshots & Visuals

Today

Shows subjects with the lowest retention first so learners triage what matters.

1 / 5

Key Features

Adaptive Today queue with retention scoring, difficulty overrides, and guards that prevent multiple same-day reviews per topic.
Dashboard and Reviews tables with risk badges, streak tracking, and filters backed by computeRiskScore and calendar summaries.
Interactive timeline visualizations with zoom/pan, per-subject grids, and SVG/PNG exports.
Calendar planner with subject-aware filters, daily sheets, and quick revise actions that respect the once-per-day lock.
Subjects admin for branding, exam targets, and retroactive history edits with replayed forgetting curves.
Settings for adaptive parameters (review trigger, growth alpha/beta), notifications, and appearance overlays.
Automatic rollover that bumps unfinished cards into the upcoming queue at local midnight via useAutoSkipOverdue.

Architecture / Design Overview

Framework: Next.js 14 App Router with a persistent layout wiring global theme tokens and toast provider.
State: modular Zustand stores persisted to localStorage with per-store migrations.
Scheduling: forgetting-curve and adaptive scheduler modules drive retention and intervals.
Derivation: selectors and calendar helpers produce summaries, heatmaps, and exportable curves.
UI: Tailwind utilities, Radix primitives, Lucide icons, and Framer Motion animations.
Docs: start with docs/DOCS_INDEX.md plus architecture and algorithm deep dives in docs/core.

Modules & Docs

Stores: src/stores/topics.ts, src/stores/profile.ts, src/stores/review-preferences.ts, src/stores/timeline-preferences.ts
Scheduling: src/lib/forgetting-curve.ts, src/lib/adaptive-scheduler.ts
Derivations: src/selectors/curves.ts and helpers in src/lib/calendar.ts
UI shell: src/app/layout.tsx with global tokens in src/styles/theme.css and src/styles/globals.css
Docs entrypoints: docs/DOCS_INDEX.md, docs/core/ARCHITECTURE.md, docs/core/ALGORITHMS_FORGETTING_CURVE.md, docs/ui/UI_GUIDELINES.md

Mermaid Diagrams Overview

Carousel of all diagrams from the documentation, with a consistent stage size and fullscreen toggle.

System Context

Diagram 1 of 27