feat(07): Spaced repetition study system (SM-2)

[tpaulshippy]

Roadmap 07: Spaced Repetition Study

Implements #59.

What changed

• Backend: SM-2 scheduling algorithm (srs.py), due_at/interval/ease/reps/lapses fields on Flashcard, FlashcardReview log model, POST .../review.json endpoint, GET .../study_queue.json with due filtering, deck annotations (due_count, last_studied_at)
• Frontend: Study mode with card flip animation, Again/Hard/Good/Easy ratings with 1d/3d/7d hints, progress tracking, completion summary, due badges on deck list
• Scheduling: Again→relearn (4h), Hard→interval×1.2, Good→1d→6d→interval×ease, Easy→×1.3 bonus; ease floored at 1.3
• Tests: 126 backend (44 new incl. table-driven SM-2 tests + timezone-aware due filtering), 55 frontend, e2e walkthrough
• Fixes since review: .json format-suffix actions now accept the format kwarg (study_queue/review 500d live); corrected /study_queue/.json → /study_queue.json URLs

Demo

1. Seed: manage.py seed_e2e_spaced_repetition → 8 Cell Bio cards (6 due)
2. Open deck → Study (6) → flip cards → rate Again/Hard/Good/Easy
3. Completion: summary shows reviewed count, next due time
4. Re-open: badge vanishes, study says 'Nothing due 🎉'

Evidence

pr49-spaced.mp4

[tpaulshippy]

Automated review — backwards-compat + tests

Backwards-compat: COMPATIBLE (one intended behavior change). All scheduling fields nullable/defaulted; old {front,back} payloads still validate; no renames. Pre-existing cards become immediately due (due_at defaults to now) — intended, call it out. Old study_queue callers get due-only results by default — intended.
Tests: GOOD (verified). test_srs.py + test_spaced_repetition_api.py 44 passed; test_flashcard_api.py 30 passed; test_chat.py 12 passed, same head. .json format-suffix 500 from PR body is addressed (format=None accepted).

MUST FIX

None blocking. Two should-fix items below are the closest.

SHOULD FIX

1. serializers/flashcard_serializer.py:27-28,51-52 + viewsets/flashcard_viewset.py:125-127 — due_count/last_studied_at exist only on annotated querysets; perform_create returns unannotated instance → create response may serialize wrong/error. allow_null/re-fetch annotated instance (same pre-existing pattern as card_count, now 2 more fields ride on it).
2. services/srs.py:hard — never advances reps, so all-hard cards loop and a later good still hits the reps==0 -> 1d branch. Increment reps on hard or document.

NICE TO HAVE

3. No review idempotency — double-tap applies SM-2 twice. Client debounce or dedupe window.
4. limit=0/-5 silently clamps to 1 while non-int 400s — inconsistent.
5. (process) drive-bys in this PR (02-pin-reauth.e2e.js selector, package.json --watchman=false) — split out next time.

[Copilot]

🟡 Changes recommended

There are a couple of concrete correctness issues (e2e URL typo and a broken __str__ on FlashcardReview) that can cause test/runtime failures and should be fixed before approval.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Implements Roadmap 07 spaced-repetition study (SM-2 style) across backend scheduling, review logging, API endpoints, and a new frontend study mode so decks can be studied by “due” cards with Again/Hard/Good/Easy ratings and progress/completion UI.

Changes:

• Backend: add SM-2 scheduling fields to Flashcard, implement pure scheduling function apply_sm2, add FlashcardReview log model, and expose review + study_queue API actions plus deck list annotations (due_count, last_studied_at).
• Frontend: add study-mode UI with flip animation + rating buttons, deck due badges / last-studied text, and API helpers for study_queue + review.
• Tests/tooling: add backend unit/API tests, frontend tests, e2e flow + deterministic seed command.

File summaries

File	Description
front/package.json	Disables Watchman in Jest test script.
front/e2e/07-spaced-repetition.e2e.js	Adds Detox e2e walkthrough for study flow using seeded backend state.
front/app/flashcards/study.tsx	Reworks study UI to fetch due queue, flip card, rate, and show completion summary.
front/app/flashcards/deck.tsx	Adds “Study (N)” label and testID for study button.
front/app/flashcards.tsx	Shows deck due badge + “last studied” metadata and adds testIDs for deck rows.
front/app/tests/study-test.tsx	Updates study tests to use study queue + review API and new UI flow.
front/app/tests/deck-test.tsx	Updates deck detail test for new study route params.
front/api/flashcards.ts	Adds types + client functions for study_queue and review endpoints and scheduling fields.
front/tests/api/flashcards.test.ts	Adds API tests/mocks covering fetchStudyQueue and reviewFlashcard.
back/bots/viewsets/flashcard_viewset.py	Adds review action on flashcards, study_queue action on decks, and deck annotations for due/last-studied.
back/bots/tests/test_srs.py	Adds table-driven unit tests for the pure SM-2 scheduling function.
back/bots/tests/test_spaced_repetition_api.py	Adds integration tests for review + study queue + deck annotations.
back/bots/services/srs.py	Implements pure SM-2-like scheduling function and constants.
back/bots/serializers/flashcard_serializer.py	Serializes scheduling fields and deck due/last-studied annotations.
back/bots/models/flashcard.py	Adds scheduling fields (due_at/interval/ease/reps/lapses/last_reviewed_at).
back/bots/models/flashcard_review.py	Adds review log model for rating history.
back/bots/models/init.py	Exports FlashcardReview from models package.
back/bots/migrations/0050_flashcard_due_at_flashcard_ease_and_more.py	Migrates scheduling fields + creates FlashcardReview table.
back/bots/management/commands/seed_e2e_spaced_repetition.py	Adds deterministic seed command for the spaced repetition e2e flow.

Review details

• Files reviewed: 19/25 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Critical issues remain in scheduling writes, concurrent reviews, and failed review handling.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (2)

back/bots/viewsets/flashcard_viewset.py:210

• The queue can return up to 200 cards, but FlashcardSerializer.deck is a SlugRelatedField that dereferences the FK for each object. Starting from deck.flashcards.all() leaves that relation uncached, so a full queue performs an extra query per card. Use select_related('deck') here to keep queue loading bounded.

        queryset = deck.flashcards.all()
        if mode == 'due':
            queryset = queryset.filter(due_at__lte=timezone.now())

        queryset = queryset.order_by(

front/api/flashcards.ts:159

• request() converts every non-401/network failure into its fallback [] (see the shared request helper). Study then treats that array as a successful empty queue and renders “Nothing due”, so a 500/offline response is presented as caught up. This endpoint needs to surface failure and the screen needs a separate error state instead of conflating it with an empty queue.

  request<Flashcard[]>(
    `/decks/${deckId}/study_queue.json?mode=${mode}&limit=${limit}`,
    { method: "GET" },
    []
  );

• Files reviewed: 19/19 changed files
• Comments generated: 9
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

Critical E2E failures and unresolved frontend authentication and error-handling issues remain.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (4)

back/bots/tests/test_spaced_repetition_api.py:341

• The test name says an unstudied deck has zero due cards, but the assertion is 1 because new cards are intentionally due immediately. Rename the test so its name matches the scheduling behavior and does not mislead future changes.

    def test_unstudied_deck_has_zero_due_count_and_no_last_studied(self, auth_client, deck):

back/bots/viewsets/flashcard_viewset.py:212

• FlashcardSerializer serializes the deck slug for every queue item, but this reverse-manager queryset does not select_related('deck'). With the 200-card cap, serializing a queue can issue one extra database query per card; select the related deck on this queryset to avoid an N+1 on each study session.

        queryset = deck.flashcards.all()

front/app/flashcards/study.tsx:106

• requestRaw rethrows UnauthorizedError after refresh failure, but this catch treats it as an ordinary load error and never invokes the repository's handleUnauthorized flow. An expired session will remain on this study screen showing Retry instead of clearing credentials and redirecting to login; handle unauthorized errors separately before setting the generic error state.

      } catch (error) {
        Sentry.captureException(error);
        setLoadError(true);
      } finally {

front/app/flashcards/study.tsx:187

• The review path has the same authentication failure bug: a rethrown UnauthorizedError is converted into “Failed to save your review,” leaving the user in the session with an invalid token. Call handleUnauthorized(error, router) before showing the save alert so expired sessions are cleared and redirected consistently.

      } catch (error) {
        Sentry.captureException(error);
        Alert.alert("Error", "Failed to save your review");
        return;

• Files reviewed: 19/19 changed files
• Comments generated: 3
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Unresolved moderate issues remain in seed reset behavior, API route coverage, and the study summary.

Review details

Suppressed comments (9)

back/bots/management/commands/seed_e2e_spaced_repetition.py:93

• Resetting these card fields does not reset the new FlashcardReview rows. After rerunning the documented seed, the cards look fresh but retain every prior rating, so consumers of profile.flashcard_reviews see duplicated/unbounded activity and the seed is not deterministic. Clear the review rows for this deck (or recreate the cards) when resetting it.

            # Reset scheduling every run so repeated seeds converge.
            card.back = back
            card.order = order
            card.ease = 2.5
            card.interval_days = 0
            card.reps = 0
            card.lapses = 0
            card.last_reviewed_at = None

back/bots/management/commands/seed_e2e_spaced_repetition.py:55

• Profile supports soft deletion, and the profiles API only returns rows with deleted_at=None (back/bots/viewsets/profile_viewset.py:38-42). If a prior run or cleanup soft-deletes E2E Test Profile, get_or_create finds that row but leaves it deleted, so this seed reports success while getSeedState cannot find the profile and the E2E flow fails. Reactivate an existing row when seeding (for example, use update_or_create with defaults={'deleted_at': None}).

        profile, _ = Profile.objects.get_or_create(user=user, name='E2E Test Profile')

back/bots/management/commands/seed_e2e_spaced_repetition.py:75

• The cleanup only removes cards whose front is absent from CARDS. Because Flashcard.front is not unique, a duplicate of one of the eight known fronts survives; get_or_create then reuses one copy and the deck still has more than eight cards, so the documented idempotent reset can leave extra due cards in the study queue. Deduplicate each known front (or clear/recreate the seed deck's cards) before the upsert loop.

        Flashcard.objects.filter(deck=deck).exclude(
            front__in=[front for front, _, _ in CARDS]
        ).delete()

back/bots/management/commands/seed_e2e_spaced_repetition.py:62

• Bots are also soft-deleted and BotViewSet excludes deleted_at rows (back/bots/viewsets/bot_viewset.py:20-25). If E2E Test Bot already exists but is soft-deleted, get_or_create returns it without reactivating it; getSeedState then may inject an unrelated bot or hit bots.results[0] with no result. Seed the bot with update_or_create(..., defaults={'ai_model': ai_model, 'deleted_at': None}) (and preferably select it by name in the E2E helper).

        bot, _ = Bot.objects.get_or_create(
            user=user,
            name='E2E Test Bot',
            defaults={'ai_model': ai_model},
        )

back/bots/viewsets/flashcard_viewset.py:74

• The format-suffix fix is only exercised by the Detox spec: all backend API tests call /review/ and /study_queue/, while CI runs pytest rather than Detox. A regression in the .json routes used by the frontend would therefore pass the required test suite; add .json requests for both actions (including the queue query parameters).

    def review(self, request, deck_pk=None, flashcardId=None, format=None):

back/bots/viewsets/flashcard_viewset.py:195

• Please regenerate the checked-in API contract for this new action. front/api/schema.yaml still has no study_queue or review path and its Flashcard/Deck schemas omit the scheduling and annotation fields; front/__mocks__/handlers.ts also has no handlers for these requests. The repository's OpenAPI contract guidance requires updating those artifacts when viewsets or serializers change, otherwise /api/docs and mock-backed consumers remain on the pre-SRS contract.

    @action(detail=True, methods=['get'], url_path='study_queue')

front/app/flashcards/study.tsx:370

• backfaceVisibility only hides pixels; the answer text under this always-mounted animated face remains exposed to VoiceOver/TalkBack before the user flips the card. Hide this face from accessibility until isFlipped (and expose it after the flip), otherwise the front→reveal interaction is bypassed for screen-reader users.

        <Animated.View
          style={[
            styles.cardFace,
            { transform: [{ rotateY: backRotate }] },
          ]}
        >

front/app/flashcards/study.tsx:393

• These controls render white 15/12px text on tintColor and Again's #d9534f. The light theme defines tintColor as #00a4c9 (front/constants/Colors.ts:6,13), and both combinations are below WCAG AA contrast for the primary rating controls, making the labels and hints difficult to read. Use darker theme-specific button backgrounds or a contrasting text color.

              style={({ pressed }) => [
                styles.ratingButton,
                { backgroundColor: rating === "again" ? "#d9534f" : tintColor },
                pressed && styles.ratingButtonPressed,

front/app/flashcards/study.tsx:294

• The completion summary reports the total reviewed and Again count, but never displays the correct-ish rate required by issue #59's success criteria. Add an explicit percentage (and define which ratings count as correct) so the session outcome is visible rather than inferred from the raw counts.

          <ThemedText style={styles.completionSubtitle}>
            You reviewed {cards.length} card{cards.length === 1 ? "" : "s"}.
          </ThemedText>
          {againCount > 0 ? (
            <ThemedText style={[styles.completionStat, { color: iconColor }]}>

• Files reviewed: 19/19 changed files
• Comments generated: 0 new
• Review effort level: Lite

[tpaulshippy]

Addressed all 9 suppressed comments from the latest Copilot review (c77e5c4) — each verified valid before fixing:

Seed determinism (4)

• Review rows now cleared on reseed: the deck's cards are recreated each run, cascading to FlashcardReview. Verified live (planted review + duplicate + soft-deleted rows → 8 cards, 0 reviews).
• Soft-deleted E2E Test Profile reactivated via update_or_create(defaults={deleted_at: None}).
• Duplicate fronts can't survive: full recreate replaces the upsert loop.
• Soft-deleted E2E Test Bot reactivated the same way; e2e helper now selects the bot by name with a hard fail.

API coverage + contract (2)

• New backend tests hit /review.json and /study_queue.json?mode=all&limit=2 directly.
• Regenerated front/api/schema.yaml per OPENAPI_CONTRACT_TESTING.md (now includes the review/study_queue paths, scheduling fields, deck annotations) and added MSW handlers for both endpoints.

Study screen (3)

• Card faces hidden from VoiceOver/TalkBack until shown (accessibilityElementsHidden + importantForAccessibility).
• Rating/solid buttons use new studyRating/studyAgain theme colors (light #00708c/#b52a25, dark tint/#b52a25) — all ≥4.5:1 with white text (old #00a4c9 was 2.9, #d9534f 3.9).
• Completion shows correct rate per 07 — Spaced Repetition Study #59 ('X% correct (Y of Z)', correct = anything but Again), with tests for 100% and 50%.

Verified: backend 83 passed, ruff clean, eslint 0 errors, tsc clean, study suite 7 passed.

[Copilot]

🟡 Changes recommended

Unresolved schema, authentication handling, performance, and study-animation issues remain.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

front/app/flashcards/study.tsx:145

• resetFlip can race the spring started in flipCard: the rating buttons become tappable before that spring necessarily finishes, and setValue(0) does not stop the in-flight animation. A quick rating can therefore leave the next card visually flipped even though isFlipped is false. Stop the animation before resetting the value.

    flipAnim.setValue(0);

front/app/flashcards/study.tsx:107

• requestRaw deliberately rethrows UnauthorizedError, but this catch treats every error as a queue outage and swallows it. If the access and refresh tokens expire while opening study mode, the existing handleUnauthorized flow is never called, so the user remains on a dead screen instead of being redirected to login; handle/rethrow auth errors before setting the load-error state (and apply the same handling to the all-mode catch).

      } catch (error) {
        Sentry.captureException(error);
        setLoadError(true);

front/app/flashcards/study.tsx:192

• The review API also propagates UnauthorizedError, but this catch swallows it and shows “Failed to save your review”. An expired session can therefore leave the user stuck on the study screen without the app's established logout/redirect flow; handle auth errors with handleUnauthorized(error, router) before showing the generic save error.

      } catch (error) {
        Sentry.captureException(error);
        Alert.alert("Error", "Failed to save your review");
        return;

• Files reviewed: 22/22 changed files
• Comments generated: 6
• Review effort level: Lite

[tpaulshippy]

Addressed the 3 new suppressed comments from the latest Copilot review (224a2ae), all verified valid:

• Flip race — resetFlip now calls flipAnim.stopAnimation() before setValue(0), so a quick rating can't leave the next card visually flipped while isFlipped is false.
• Swallowed auth errors (queue + all-mode) — both catches now await handleUnauthorized(error, router) first (the established chatList pattern), so expired sessions redirect to login instead of rendering the load-error card.
• Swallowed auth error (rating) — same routing before the generic save alert, so an expired session can't strand the user on the study screen.

Added a study-screen test proving expired queue loads delegate to handleUnauthorized with no error card. Verified: eslint 0 errors, tsc clean, study+deck suites 12 passed.