How Learner Progress Is Tracked and What the Review Queue Is in AI Engineering From Scratch

The AI Engineering From Scratch curriculum tracks learner progress entirely in the browser using a localStorage-based system exposed as window.AIFSProgress, while the "review queue" is a tutor-managed markdown log that captures lessons scoring below 70% for targeted re-teaching.

The rohitg00/ai-engineering-from-scratch repository implements a privacy-first, serverless learning architecture where every quiz interaction and checkpoint completion is stored locally. This self-contained approach eliminates network dependencies while providing granular visibility into the learning journey, complemented by a structured review mechanism that automatically surfaces concepts requiring reinforcement.

Browser-Only Progress Architecture

The curriculum eschews server-side state management in favor of a lightweight, client-side tracking system defined in site/progress.js. This design ensures that learning data remains private and accessible offline.

The localStorage Data Model

At the core of the tracking system is a structured JSON object stored under the key aifs:progress:v2. The schema version 2 structure captures every meaningful interaction a learner has with the curriculum:

{
  schemaVersion: 2,
  lessons: {
    "<lesson-path>": {
      answers: {
        "<qid>": {
          picked: string,    // Learner's choice
          correct: boolean,  // Whether it was correct
          t: number          // Timestamp
        }
      },
      quizPassedAt: number | null,
      checkpoints: {
        readAt: number | null,     // Read lesson text
        builtAt: number | null,    // Built code from scratch
        ranAt: number | null,      // Ran implementation
        evidenceAt: number | null  // Submitted evidence
      },
      completedAt: number | null,
      completionSource: string,    // e.g., 'learner', 'migrated-v1'
      visitedAt: number
    }
  },
  updatedAt: number
}

The lesson path serves as the primary key, using relative paths like phases/05-nn/01-backprop/ extracted from URLs via the internal extractPath function. Each lesson maintains its own state object tracking when the learner first visited, answered quiz questions, passed assessments, and completed four distinct hands-on checkpoints.

Core API Methods for Tracking Progress

The global window.AIFSProgress object exposes a minimal API for mutating the progress state. All methods handle the localStorage persistence automatically:

• recordVisit(path) – Logs visitedAt timestamp when a learner opens a lesson page.
• recordAnswer(path, qid, picked, correct) – Stores individual quiz responses with correctness flags.
• markQuizPassed(path) – Sets quizPassedAt if not already recorded.
• setCheckpoint(path, checkpoint, complete) – Updates one of four milestone timestamps (readAt, builtAt, ranAt, evidenceAt).
• markLessonComplete(path, source) – Finalizes the lesson by setting completedAt and documenting who marked it complete.
• reset() – Clears both v2 and legacy v1 storage keys, effectively wiping all progress.

Because these operations write directly to localStorage, there is no network traffic, no user accounts, and no external database—the progress is completely private to the learner's browser.

The Review Queue Mechanism

While the progress tracker captures what the learner did, the review queue determines what they need to redo. This concept is defined in skills/learn/SKILL.md (Step 4) and addresses the pedagogical requirement for mastery-based progression.

Automatic Queueing Logic

After any lesson quiz concludes, the tutor calculates the score as a ratio (N/M). The review queue logic follows a strict threshold:

If the score is less than 70%, the tutor adds the lesson to the review queue along with the specific missed topic(s).

The queue itself persists in the learner's LEARNING.md file—a simple markdown log that the tutor reads and appends to. Entries follow a pipe-delimited format:

2024-03-15 | phases/07-transformers/14-build-a-transformer-capstone | 4/5 | attention-mask confusion

Each row contains the date, lesson path, score ratio, and a brief description of the knowledge gap.

Working the Review Queue

When a learner completes all lessons in the curriculum, Step 0 of the tutor flow offers the option to "work the Review queue." The tutor reads the LEARNING.md file, parses the queued entries, and re-introduces those specific lessons for focused re-teaching. This ensures learners revisit weak spots before claiming full curriculum completion.

Because the queue lives in a human-readable markdown file rather than a database, learners can manually edit their LEARNING.md to add topics they want to review or remove entries they feel confident about.

Practical Implementation Examples

The following patterns demonstrate how the progress API and review queue interact in practice:

// Log that the learner opened the backpropagation lesson
AIFSProgress.recordVisit('phases/05-nn/01-backprop');

// Record a quiz answer where the learner chose 'B' incorrectly
AIFSProgress.recordAnswer(
  'phases/05-nn/01-backprop',
  'q3',        // Question ID from quiz.json
  'B',         // Learner's selection
  false        // Incorrect answer
);

// Mark hands-on checkpoints as completed
AIFSProgress.setCheckpoint('phases/05-nn/01-backprop', 'readAt', Date.now());
AIFSProgress.setCheckpoint('phases/05-nn/01-backprop', 'builtAt', Date.now());

// Finalize the lesson after passing the quiz
AIFSProgress.markLessonComplete('phases/05-nn/01-backprop', 'learner');

// Retrieve current state for UI rendering
const progress = AIFSProgress.getLessonProgress('phases/05-nn/01-backprop');
console.log(progress.completedAt); // Timestamp or null

When a quiz scores below the 70% threshold, the tutor automatically appends an entry to LEARNING.md:

<!-- Example entry created by the tutor -->
2024-03-15 | phases/07-transformers/14-build-a-transformer-capstone | 4/5 | attention-mask confusion

Summary

• Progress tracking in rohitg00/ai-engineering-from-scratch uses a browser-only localStorage implementation in site/progress.js, exposing the AIFSProgress API for recording visits, quiz answers, and four distinct hands-on checkpoints.
• The review queue is a pedagogical mechanism defined in skills/learn/SKILL.md that automatically logs lessons scoring below 70% into a LEARNING.md file for later re-teaching.
• All learner data remains local to the browser, requiring no server infrastructure or user accounts while maintaining a complete audit trail of learning activity.
• The integration between these systems ensures that learners cannot complete the curriculum without addressing identified knowledge gaps.

Frequently Asked Questions

Where is my progress stored if there is no server?

All progress data lives in your browser's localStorage under the key aifs:progress:v2. The site/progress.js module serializes the state object to localStorage on every mutation, meaning your data persists across browser sessions but never leaves your device. If you clear your browser data or use incognito mode, your progress will be reset.

What triggers a lesson to enter the review queue?

A lesson enters the review queue when the tutor detects a quiz score below 70%. Specifically, after calculating the ratio of correct answers (N/M), if the percentage is less than 70, the tutor appends a row to LEARNING.md containing the lesson path, score, and topic description. This threshold is hard-coded in the tutor logic within skills/learn/SKILL.md.

Can I manually add lessons to the review queue?

Yes. Because the review queue persists as plain text in your LEARNING.md file, you can manually append entries following the pipe-delimited format: YYYY-MM-DD | lesson-path | score | topic. The tutor will read these entries during the "work the Review queue" phase regardless of whether it created them or you did.

How do I reset my progress and start over?

Invoke the reset() method on the global AIFSProgress object. This method clears both the current v2 storage key and any legacy v1 keys, returning the curriculum to a pristine state. Alternatively, you can delete the aifs:progress:v2 key directly from your browser's developer tools localStorage panel.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}