Data Model

​

Overview

​

Core Interfaces

​

Term Interface

export interface Term {
  id: number;
  term: string;
  definition: string;
  eli5Definition?: string; // Optional "Explain Like I'm 5" simplified definition
  category: string;
  example?: string; // Optional ASCII/text visual example
}

• id - Unique numeric identifier for the term
• term - The vocabulary word or phrase
• definition - Standard technical definition
• eli5Definition - Optional simplified explanation for beginners
• category - Category ID this term belongs to
• example - Optional ASCII art or text-based visual example

​

Achievement Interface

export interface Achievement {
  id: string;
  title: string;
  description: string;
  icon: string;
  category?: CategoryId;
  isHidden?: boolean;
  condition: (stats: UserStats) => boolean;
}

• id - Unique string identifier
• title - Display name of the achievement
• description - What the user did to earn it
• icon - Material icon name
• category - Optional category this achievement relates to
• isHidden - Whether this is a secret achievement
• condition - Function that returns true when achievement is unlocked

​

UserStats Interface

export interface UserStats {
  totalCardsViewed: number;
  unlockedAchievements: string[];
  categoryProgress: Record<string, number>;
  streak: number;
  logoClicks?: number;
  lastStudyTime?: number;
}

• totalCardsViewed - Total number of flashcards viewed
• unlockedAchievements - Array of achievement IDs that have been unlocked
• categoryProgress - Object mapping category IDs to number of mastered terms
• streak - Current consecutive days of studying
• logoClicks - Optional counter for logo clicks (easter egg)
• lastStudyTime - Optional timestamp of last study session

​

Spaced Repetition Structures

​

SRSCard Interface

export interface SRSCard {
  termId: number;
  easeFactor: number;      // How easy this card is (starts at 2.5)
  interval: number;        // Days until next review
  repetitions: number;     // Number of successful reviews in a row
  nextReviewDate: string;  // ISO date string
  lastReviewDate: string | null;
  quality: number;         // Last quality rating
}

• termId - References the Term.id this card is for
• easeFactor - Difficulty multiplier (default 2.5, minimum 1.3)
• interval - Number of days until the next review is due
• repetitions - Consecutive successful reviews (resets to 0 on failure)
• nextReviewDate - ISO date string (YYYY-MM-DD) when card is next due
• lastReviewDate - ISO date string of last review, or null if never reviewed
• quality - Last quality rating (0-5 scale)

​

SRSData Interface

export interface SRSData {
  cards: Record<number, SRSCard>;
  version: number;
}

• cards - Object mapping term IDs to their SRS card data
• version - Schema version number for migration support

​

Type Unions

​

TermStatus

type TermStatus = 'known' | 'learning' | 'unseen';

• known - User has mastered this term
• learning - User is currently learning this term
• unseen - User has not studied this term yet

​

Progress Interface

interface Progress {
  [termId: number]: TermStatus;
}

​

Categories

export const categories = [
  { 
    id: "foundation", 
    name: "Foundation", 
    subtitle: "Core Concepts", 
    icon: "architecture", 
    abbrev: "FDN", 
    colorClass: "bg-category-yellow" 
  },
  // ... 23 more categories
] as const;

export type CategoryId = typeof categories[number]["id"];

• id - Unique identifier used in Term.category
• name - Display name
• subtitle - Short descriptor
• icon - Material Icons name
• abbrev - Short abbreviation for compact displays
• colorClass - Tailwind CSS class for category color

​

Quality Ratings

​

SM-2 Quality Scale

// Quality ratings:
// 0 - Complete blackout, no recall
// 1 - Incorrect, but upon seeing the answer, remembered
// 2 - Incorrect, but the answer seemed easy to recall
// 3 - Correct with serious difficulty
// 4 - Correct with some hesitation
// 5 - Perfect response, instant recall

​

Simplified Ratings

export const SIMPLE_RATINGS = [
  { value: 1, label: "Again", sm2Quality: 1, color: "bg-red-500", icon: "replay" },
  { value: 2, label: "Hard", sm2Quality: 3, color: "bg-orange-500", icon: "sentiment_dissatisfied" },
  { value: 3, label: "Good", sm2Quality: 4, color: "bg-green-500", icon: "check" },
  { value: 4, label: "Easy", sm2Quality: 5, color: "bg-emerald-500", icon: "bolt" },
] as const;

​

Mastery Levels

'new' | 'learning' | 'reviewing' | 'mastered'

• new - Never reviewed (repetitions = 0)
• learning - Interval < 7 days
• reviewing - Interval 7-20 days
• mastered - Interval ≥ 21 days