feat: Spaced Repetition System (SRS) for card reviews

Cargo.lock

···
 name = "malfestio-core"
 version = "0.1.0"
 dependencies = [
+ "chrono",
  "serde",
  "serde_json",
  "thiserror",

crates/core/Cargo.toml

···
 edition = "2024"
 
 [dependencies]
+chrono = { version = "0.4", features = ["serde"] }
 serde = { version = "1.0.228", features = ["derive"] }
 serde_json = "1.0.148"
 thiserror = "2.0.17"

crates/core/src/lib.rs

···
 pub mod at_uri;
 pub mod error;
 pub mod model;
+pub mod srs;
 pub mod tid;
 
 pub use error::{Error, Result};
 pub use model::{Card, Deck, Note};
+pub use srs::{Grade, ReviewState, Sm2Config};

crates/core/src/srs.rs

···
+//! Spaced Repetition System (SM-2 Algorithm)
+//!
+//! Implements the SuperMemo 2 algorithm for scheduling card reviews.
+//! Parameters are designed to be user-configurable in the future.
+
+use chrono::{DateTime, Duration, Utc};
+use serde::{Deserialize, Serialize};
+
+/// Grade given by user during review (0-5 scale)
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(transparent)]
+pub struct Grade(pub u8);
+
+impl Grade {
+    pub const AGAIN: Grade = Grade(0);
+    pub const HARD: Grade = Grade(1);
+    pub const GOOD: Grade = Grade(3);
+    pub const EASY: Grade = Grade(4);
+    pub const PERFECT: Grade = Grade(5);
+
+    pub fn new(value: u8) -> Option<Self> {
+        if value <= 5 { Some(Grade(value)) } else { None }
+    }
+
+    pub fn is_passing(&self) -> bool {
+        self.0 >= 3
+    }
+}
+
+/// Default SM-2 parameters (user-configurable in future)
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Sm2Config {
+    /// Initial ease factor for new cards
+    pub initial_ease: f32,
+    /// Minimum ease factor (prevents cards from becoming too hard)
+    pub min_ease: f32,
+    /// First interval in days after initial correct answer
+    pub first_interval: i32,
+    /// Second interval in days
+    pub second_interval: i32,
+}
+
+impl Default for Sm2Config {
+    fn default() -> Self {
+        Self { initial_ease: 2.5, min_ease: 1.3, first_interval: 1, second_interval: 6 }
+    }
+}
+
+/// Current review state for a card
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReviewState {
+    /// Ease factor (multiplier for interval)
+    pub ease_factor: f32,
+    /// Current interval in days
+    pub interval_days: i32,
+    /// Number of consecutive correct reviews
+    pub repetitions: i32,
+    /// When the card is due
+    pub due_at: DateTime<Utc>,
+}
+
+impl Default for ReviewState {
+    fn default() -> Self {
+        Self { ease_factor: 2.5, interval_days: 0, repetitions: 0, due_at: Utc::now() }
+    }
+}
+
+impl ReviewState {
+    /// Create a new review state for a fresh card
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Calculate next review state based on grade using SM-2 algorithm
+    pub fn schedule(&self, grade: Grade, config: &Sm2Config) -> Self {
+        let q = grade.0 as f32;
+
+        // TODO: move to separate fn
+        // EF' = EF + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02))
+        let new_ease = self.ease_factor + (0.1 - (5.0 - q) * (0.08 + (5.0 - q) * 0.02));
+        let new_ease = new_ease.max(config.min_ease);
+
+        if grade.is_passing() {
+            let (new_interval, new_reps) = match self.repetitions {
+                0 => (config.first_interval, 1),
+                1 => (config.second_interval, 2),
+                _ => {
+                    let interval = (self.interval_days as f32 * new_ease).round() as i32;
+                    (interval.max(1), self.repetitions + 1)
+                }
+            };
+
+            Self {
+                ease_factor: new_ease,
+                interval_days: new_interval,
+                repetitions: new_reps,
+                due_at: Utc::now() + Duration::days(new_interval as i64),
+            }
+        } else {
+            Self { ease_factor: new_ease, interval_days: 0, repetitions: 0, due_at: Utc::now() + Duration::minutes(10) }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_grade_validation() {
+        assert!(Grade::new(0).is_some());
+        assert!(Grade::new(5).is_some());
+        assert!(Grade::new(6).is_none());
+    }
+
+    #[test]
+    fn test_grade_passing() {
+        assert!(!Grade::AGAIN.is_passing());
+        assert!(!Grade::HARD.is_passing());
+        assert!(Grade::GOOD.is_passing());
+        assert!(Grade::EASY.is_passing());
+        assert!(Grade::PERFECT.is_passing());
+    }
+
+    #[test]
+    fn test_new_card_first_review_correct() {
+        let config = Sm2Config::default();
+        let state = ReviewState::new();
+
+        let next = state.schedule(Grade::GOOD, &config);
+
+        assert_eq!(next.interval_days, 1);
+        assert_eq!(next.repetitions, 1);
+        assert!(next.ease_factor >= 2.3 && next.ease_factor <= 2.7);
+    }
+
+    #[test]
+    fn test_new_card_first_review_incorrect() {
+        let config = Sm2Config::default();
+        let state = ReviewState::new();
+
+        let next = state.schedule(Grade::AGAIN, &config);
+
+        assert_eq!(next.interval_days, 0);
+        assert_eq!(next.repetitions, 0);
+        let diff = next.due_at - Utc::now();
+        assert!(diff.num_minutes() <= 15);
+    }
+
+    #[test]
+    fn test_second_review_correct() {
+        let config = Sm2Config::default();
+        let state = ReviewState { ease_factor: 2.5, interval_days: 1, repetitions: 1, due_at: Utc::now() };
+        let next = state.schedule(Grade::GOOD, &config);
+
+        assert_eq!(next.interval_days, 6);
+        assert_eq!(next.repetitions, 2);
+    }
+
+    #[test]
+    fn test_mature_card_interval_grows() {
+        let config = Sm2Config::default();
+        let state = ReviewState { ease_factor: 2.5, interval_days: 10, repetitions: 5, due_at: Utc::now() };
+        let next = state.schedule(Grade::GOOD, &config);
+
+        assert!(next.interval_days >= 20);
+        assert_eq!(next.repetitions, 6);
+    }
+
+    #[test]
+    fn test_ease_factor_minimum() {
+        let config = Sm2Config::default();
+        let state = ReviewState { ease_factor: 1.4, interval_days: 5, repetitions: 3, due_at: Utc::now() };
+        let next = state.schedule(Grade::GOOD, &config);
+
+        assert!(next.ease_factor >= config.min_ease);
+    }
+
+    #[test]
+    fn test_easy_increases_ease() {
+        let config = Sm2Config::default();
+        let state = ReviewState::new();
+
+        let next = state.schedule(Grade::PERFECT, &config);
+
+        assert!(next.ease_factor > 2.5);
+    }
+
+    #[test]
+    fn test_hard_decreases_ease() {
+        let config = Sm2Config::default();
+        let state = ReviewState { ease_factor: 2.5, interval_days: 10, repetitions: 5, due_at: Utc::now() };
+        let next = state.schedule(Grade::HARD, &config);
+
+        assert!(next.ease_factor < 2.5);
+    }
+
+    #[test]
+    fn test_30_day_simulation() {
+        let config = Sm2Config::default();
+        let mut state = ReviewState::new();
+
+        state = state.schedule(Grade::GOOD, &config);
+        assert_eq!(state.interval_days, 1);
+
+        state = state.schedule(Grade::GOOD, &config);
+        assert_eq!(state.interval_days, 6);
+
+        state = state.schedule(Grade::GOOD, &config);
+        assert!(state.interval_days >= 12 && state.interval_days <= 20);
+
+        state = state.schedule(Grade::GOOD, &config);
+        assert!(state.interval_days >= 20);
+        assert_eq!(state.repetitions, 4);
+        assert!(state.ease_factor >= config.min_ease);
+    }
+}

crates/server/src/api/mod.rs

···
 pub mod importer;
 pub mod note;
 pub mod oauth;
+pub mod review;

crates/server/src/api/review.rs

···
+use crate::middleware::auth::UserContext;
+use crate::repository::review::ReviewRepoError;
+use crate::state::SharedState;
+
+use axum::{
+    Json,
+    extract::{Extension, Query, State},
+    http::StatusCode,
+    response::IntoResponse,
+};
+use malfestio_core::srs::Grade;
+use serde::{Deserialize, Serialize};
+use serde_json::json;
+
+#[derive(Deserialize)]
+pub struct DueCardsQuery {
+    deck_id: Option<String>,
+    #[serde(default = "default_limit")]
+    limit: i64,
+}
+
+fn default_limit() -> i64 {
+    20
+}
+
+#[derive(Deserialize)]
+pub struct SubmitReviewRequest {
+    card_id: String,
+    grade: u8,
+}
+
+#[derive(Serialize)]
+pub struct SubmitReviewResponse {
+    ease_factor: f32,
+    interval_days: i32,
+    repetitions: i32,
+    due_at: String,
+}
+
+/// GET /api/review/due - Get cards due for review
+pub async fn get_due_cards(
+    State(state): State<SharedState>, ctx: Option<Extension<UserContext>>, Query(query): Query<DueCardsQuery>,
+) -> impl IntoResponse {
+    let user = match ctx {
+        Some(Extension(user)) => user,
+        None => return (StatusCode::UNAUTHORIZED, Json(json!({"error": "Unauthorized"}))).into_response(),
+    };
+
+    let result = state
+        .review_repo
+        .get_due_cards(&user.did, query.deck_id.as_deref(), query.limit)
+        .await;
+
+    match result {
+        Ok(cards) => Json(cards).into_response(),
+        Err(ReviewRepoError::InvalidArgument(msg)) => {
+            (StatusCode::BAD_REQUEST, Json(json!({"error": msg}))).into_response()
+        }
+        Err(e) => {
+            tracing::error!("Failed to get due cards: {:?}", e);
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(json!({"error": "Failed to get due cards"})),
+            )
+                .into_response()
+        }
+    }
+}
+
+/// POST /api/review/submit - Submit a review grade
+pub async fn submit_review(
+    State(state): State<SharedState>, ctx: Option<Extension<UserContext>>, Json(payload): Json<SubmitReviewRequest>,
+) -> impl IntoResponse {
+    let user = match ctx {
+        Some(Extension(user)) => user,
+        None => return (StatusCode::UNAUTHORIZED, Json(json!({"error": "Unauthorized"}))).into_response(),
+    };
+
+    let grade = match Grade::new(payload.grade) {
+        Some(g) => g,
+        None => return (StatusCode::BAD_REQUEST, Json(json!({"error": "Grade must be 0-5"}))).into_response(),
+    };
+
+    let result = state
+        .review_repo
+        .submit_review(&user.did, &payload.card_id, grade)
+        .await;
+
+    match result {
+        Ok(new_state) => Json(SubmitReviewResponse {
+            ease_factor: new_state.ease_factor,
+            interval_days: new_state.interval_days,
+            repetitions: new_state.repetitions,
+            due_at: new_state.due_at.to_rfc3339(),
+        })
+        .into_response(),
+        Err(ReviewRepoError::InvalidArgument(msg)) => {
+            (StatusCode::BAD_REQUEST, Json(json!({"error": msg}))).into_response()
+        }
+        Err(e) => {
+            tracing::error!("Failed to submit review: {:?}", e);
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(json!({"error": "Failed to submit review"})),
+            )
+                .into_response()
+        }
+    }
+}
+
+/// GET /api/review/stats - Get user study statistics
+pub async fn get_stats(State(state): State<SharedState>, ctx: Option<Extension<UserContext>>) -> impl IntoResponse {
+    let user = match ctx {
+        Some(Extension(user)) => user,
+        None => return (StatusCode::UNAUTHORIZED, Json(json!({"error": "Unauthorized"}))).into_response(),
+    };
+
+    let result = state.review_repo.get_stats(&user.did).await;
+
+    match result {
+        Ok(stats) => Json(stats).into_response(),
+        Err(e) => {
+            tracing::error!("Failed to get stats: {:?}", e);
+            (
+                StatusCode::INTERNAL_SERVER_ERROR,
+                Json(json!({"error": "Failed to get stats"})),
+            )
+                .into_response()
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::repository::card::mock::MockCardRepository;
+    use crate::repository::note::mock::MockNoteRepository;
+    use crate::repository::oauth::mock::MockOAuthRepository;
+    use crate::repository::review::mock::MockReviewRepository;
+    use crate::repository::review::{ReviewCard, ReviewRepository};
+    use crate::state::AppState;
+    use chrono::Utc;
+    use std::sync::Arc;
+
+    fn create_test_state_with_review(review_repo: Arc<dyn ReviewRepository>) -> SharedState {
+        let pool = crate::db::create_mock_pool();
+        let card_repo = Arc::new(MockCardRepository::new()) as Arc<dyn crate::repository::card::CardRepository>;
+        let note_repo = Arc::new(MockNoteRepository::new()) as Arc<dyn crate::repository::note::NoteRepository>;
+        let oauth_repo = Arc::new(MockOAuthRepository::new()) as Arc<dyn crate::repository::oauth::OAuthRepository>;
+
+        Arc::new(AppState { pool, card_repo, note_repo, oauth_repo, review_repo })
+    }
+
+    #[tokio::test]
+    async fn test_get_due_cards_unauthorized() {
+        let review_repo = Arc::new(MockReviewRepository::new()) as Arc<dyn ReviewRepository>;
+        let state = create_test_state_with_review(review_repo);
+
+        let response = get_due_cards(State(state), None, Query(DueCardsQuery { deck_id: None, limit: 20 }))
+            .await
+            .into_response();
+
+        assert_eq!(response.status(), StatusCode::UNAUTHORIZED);
+    }
+
+    #[tokio::test]
+    async fn test_get_due_cards_success() {
+        let cards = vec![ReviewCard {
+            review_id: "review-1".to_string(),
+            card_id: "card-1".to_string(),
+            deck_id: "deck-1".to_string(),
+            deck_title: "Test Deck".to_string(),
+            front: "What is 2+2?".to_string(),
+            back: "4".to_string(),
+            media_url: None,
+            hints: vec![],
+            due_at: Utc::now(),
+        }];
+        let review_repo = Arc::new(MockReviewRepository::with_cards(cards)) as Arc<dyn ReviewRepository>;
+        let state = create_test_state_with_review(review_repo);
+
+        let user = UserContext { did: "did:plc:test".to_string(), handle: "test.handle".to_string() };
+        let response = get_due_cards(
+            State(state),
+            Some(Extension(user)),
+            Query(DueCardsQuery { deck_id: None, limit: 20 }),
+        )
+        .await
+        .into_response();
+
+        assert_eq!(response.status(), StatusCode::OK);
+    }
+
+    #[tokio::test]
+    async fn test_submit_review_success() {
+        let review_repo = Arc::new(MockReviewRepository::new()) as Arc<dyn ReviewRepository>;
+        let state = create_test_state_with_review(review_repo);
+
+        let user = UserContext { did: "did:plc:test".to_string(), handle: "test.handle".to_string() };
+        let payload = SubmitReviewRequest { card_id: "card-1".to_string(), grade: 3 };
+
+        let response = submit_review(State(state), Some(Extension(user)), Json(payload))
+            .await
+            .into_response();
+
+        assert_eq!(response.status(), StatusCode::OK);
+    }
+
+    #[tokio::test]
+    async fn test_submit_review_invalid_grade() {
+        let review_repo = Arc::new(MockReviewRepository::new()) as Arc<dyn ReviewRepository>;
+        let state = create_test_state_with_review(review_repo);
+
+        let user = UserContext { did: "did:plc:test".to_string(), handle: "test.handle".to_string() };
+        let payload = SubmitReviewRequest { card_id: "card-1".to_string(), grade: 10 };
+
+        let response = submit_review(State(state), Some(Extension(user)), Json(payload))
+            .await
+            .into_response();
+
+        assert_eq!(response.status(), StatusCode::BAD_REQUEST);
+    }
+
+    #[tokio::test]
+    async fn test_get_stats_success() {
+        let review_repo = Arc::new(MockReviewRepository::new()) as Arc<dyn ReviewRepository>;
+        let state = create_test_state_with_review(review_repo);
+
+        let user = UserContext { did: "did:plc:test".to_string(), handle: "test.handle".to_string() };
+        let response = get_stats(State(state), Some(Extension(user))).await.into_response();
+
+        assert_eq!(response.status(), StatusCode::OK);
+    }
+}

crates/server/src/lib.rs

···
         .route("/decks/{id}/publish", post(api::deck::publish_deck))
         .route("/notes", post(api::note::create_note))
         .route("/cards", post(api::card::create_card))
+        .route("/review/due", get(api::review::get_due_cards))
+        .route("/review/submit", post(api::review::submit_review))
+        .route("/review/stats", get(api::review::get_stats))
         .layer(axum_middleware::from_fn(middleware::auth::auth_middleware));
 
     let optional_auth_routes = Router::new()

crates/server/src/repository/mod.rs

···
 pub mod card;
 pub mod note;
 pub mod oauth;
+pub mod review;

crates/server/src/repository/review.rs

···
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use malfestio_core::srs::{Grade, ReviewState, Sm2Config};
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug)]
+pub enum ReviewRepoError {
+    DatabaseError(String),
+    NotFound(String),
+    InvalidArgument(String),
+}
+
+/// Card with review state for study sessions
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ReviewCard {
+    pub review_id: String,
+    pub card_id: String,
+    pub deck_id: String,
+    pub deck_title: String,
+    pub front: String,
+    pub back: String,
+    pub media_url: Option<String>,
+    pub hints: Vec<String>,
+    pub due_at: DateTime<Utc>,
+}
+
+/// User study statistics
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct StudyStats {
+    pub due_count: i64,
+    pub current_streak: i32,
+    pub longest_streak: i32,
+    pub reviewed_today: i64,
+    pub total_reviews: i64,
+}
+
+#[async_trait]
+pub trait ReviewRepository: Send + Sync {
+    /// Get cards due for review, optionally filtered by deck
+    async fn get_due_cards(
+        &self, user_did: &str, deck_id: Option<&str>, limit: i64,
+    ) -> Result<Vec<ReviewCard>, ReviewRepoError>;
+
+    /// Submit a review grade for a card
+    async fn submit_review(&self, user_did: &str, card_id: &str, grade: Grade) -> Result<ReviewState, ReviewRepoError>;
+
+    /// Get study statistics for a user
+    async fn get_stats(&self, user_did: &str) -> Result<StudyStats, ReviewRepoError>;
+}
+
+pub struct DbReviewRepository {
+    pool: crate::db::DbPool,
+    config: Sm2Config,
+}
+
+impl DbReviewRepository {
+    pub fn new(pool: crate::db::DbPool) -> Self {
+        Self { pool, config: Sm2Config::default() }
+    }
+}
+
+#[async_trait]
+impl ReviewRepository for DbReviewRepository {
+    async fn get_due_cards(
+        &self, user_did: &str, deck_id: Option<&str>, limit: i64,
+    ) -> Result<Vec<ReviewCard>, ReviewRepoError> {
+        let client = self
+            .pool
+            .get()
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to get connection: {}", e)))?;
+
+        let now = Utc::now();
+
+        let rows = if let Some(deck_id) = deck_id {
+            let deck_uuid = uuid::Uuid::parse_str(deck_id)
+                .map_err(|_| ReviewRepoError::InvalidArgument("Invalid deck ID".to_string()))?;
+
+            client
+                .query(
+                    r#"
+                    SELECT
+                        cr.id as review_id,
+                        c.id as card_id,
+                        c.deck_id,
+                        d.title as deck_title,
+                        c.front,
+                        c.back,
+                        c.media_url,
+                        cr.due_at
+                    FROM cards c
+                    JOIN decks d ON c.deck_id = d.id
+                    LEFT JOIN card_reviews cr ON c.id = cr.card_id AND cr.user_did = $1
+                    WHERE c.deck_id = $2
+                      AND (cr.due_at IS NULL OR cr.due_at <= $3)
+                    ORDER BY COALESCE(cr.due_at, '1970-01-01'::timestamptz) ASC
+                    LIMIT $4
+                    "#,
+                    &[&user_did, &deck_uuid, &now, &limit],
+                )
+                .await
+        } else {
+            client
+                .query(
+                    r#"
+                    SELECT
+                        cr.id as review_id,
+                        c.id as card_id,
+                        c.deck_id,
+                        d.title as deck_title,
+                        c.front,
+                        c.back,
+                        c.media_url,
+                        cr.due_at
+                    FROM cards c
+                    JOIN decks d ON c.deck_id = d.id
+                    LEFT JOIN card_reviews cr ON c.id = cr.card_id AND cr.user_did = $1
+                    WHERE d.owner_did = $1
+                      AND (cr.due_at IS NULL OR cr.due_at <= $2)
+                    ORDER BY COALESCE(cr.due_at, '1970-01-01'::timestamptz) ASC
+                    LIMIT $3
+                    "#,
+                    &[&user_did, &now, &limit],
+                )
+                .await
+        };
+
+        let rows = rows.map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to query cards: {}", e)))?;
+
+        let mut cards = Vec::new();
+        for row in rows {
+            let review_id: Option<uuid::Uuid> = row.get("review_id");
+            let card_id: uuid::Uuid = row.get("card_id");
+            let deck_id: uuid::Uuid = row.get("deck_id");
+            let due_at: Option<DateTime<Utc>> = row.get("due_at");
+
+            cards.push(ReviewCard {
+                review_id: review_id.map(|id| id.to_string()).unwrap_or_default(),
+                card_id: card_id.to_string(),
+                deck_id: deck_id.to_string(),
+                deck_title: row.get("deck_title"),
+                front: row.get("front"),
+                back: row.get("back"),
+                media_url: row.get("media_url"),
+                // TODO: Load hints when stored in DB
+                hints: vec![],
+                due_at: due_at.unwrap_or_else(Utc::now),
+            });
+        }
+
+        Ok(cards)
+    }
+
+    async fn submit_review(&self, user_did: &str, card_id: &str, grade: Grade) -> Result<ReviewState, ReviewRepoError> {
+        let client = self
+            .pool
+            .get()
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to get connection: {}", e)))?;
+
+        let card_uuid = uuid::Uuid::parse_str(card_id)
+            .map_err(|_| ReviewRepoError::InvalidArgument("Invalid card ID".to_string()))?;
+
+        let existing = client
+            .query_opt(
+                "SELECT id, ease_factor, interval_days, repetitions, due_at FROM card_reviews WHERE card_id = $1 AND user_did = $2",
+                &[&card_uuid, &user_did],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to query review: {}", e)))?;
+
+        let current_state = existing
+            .map(|row| ReviewState {
+                ease_factor: row.get::<_, f32>("ease_factor"),
+                interval_days: row.get::<_, i32>("interval_days"),
+                repetitions: row.get::<_, i32>("repetitions"),
+                due_at: row.get("due_at"),
+            })
+            .unwrap_or_default();
+
+        let new_state = current_state.schedule(grade, &self.config);
+        let now = Utc::now();
+
+        client
+            .execute(
+                r#"
+                INSERT INTO card_reviews (id, card_id, user_did, ease_factor, interval_days, repetitions, due_at, last_reviewed_at, total_reviews)
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8, 1)
+                ON CONFLICT (card_id, user_did) DO UPDATE SET
+                    ease_factor = $4,
+                    interval_days = $5,
+                    repetitions = $6,
+                    due_at = $7,
+                    last_reviewed_at = $8,
+                    total_reviews = card_reviews.total_reviews + 1
+                "#,
+                &[
+                    &uuid::Uuid::new_v4(),
+                    &card_uuid,
+                    &user_did,
+                    &new_state.ease_factor,
+                    &new_state.interval_days,
+                    &new_state.repetitions,
+                    &new_state.due_at,
+                    &now,
+                ],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to update review: {}", e)))?;
+
+        let today = now.date_naive();
+        client
+            .execute(
+                r#"
+                INSERT INTO user_study_stats (id, user_did, current_streak, longest_streak, last_study_date, total_cards_reviewed)
+                VALUES ($1, $2, 1, 1, $3, 1)
+                ON CONFLICT (user_did) DO UPDATE SET
+                    current_streak = CASE
+                        WHEN user_study_stats.last_study_date = $3 THEN user_study_stats.current_streak
+                        WHEN user_study_stats.last_study_date = $3 - INTERVAL '1 day' THEN user_study_stats.current_streak + 1
+                        ELSE 1
+                    END,
+                    longest_streak = GREATEST(user_study_stats.longest_streak,
+                        CASE
+                            WHEN user_study_stats.last_study_date = $3 THEN user_study_stats.current_streak
+                            WHEN user_study_stats.last_study_date = $3 - INTERVAL '1 day' THEN user_study_stats.current_streak + 1
+                            ELSE 1
+                        END
+                    ),
+                    last_study_date = $3,
+                    total_cards_reviewed = user_study_stats.total_cards_reviewed + 1
+                "#,
+                &[&uuid::Uuid::new_v4(), &user_did, &today],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to update stats: {}", e)))?;
+
+        Ok(new_state)
+    }
+
+    async fn get_stats(&self, user_did: &str) -> Result<StudyStats, ReviewRepoError> {
+        let client = self
+            .pool
+            .get()
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to get connection: {}", e)))?;
+
+        let now = Utc::now();
+        let today = now.date_naive();
+
+        let due_row = client
+            .query_one(
+                r#"
+                SELECT COUNT(*) as due_count FROM cards c
+                JOIN decks d ON c.deck_id = d.id
+                LEFT JOIN card_reviews cr ON c.id = cr.card_id AND cr.user_did = $1
+                WHERE d.owner_did = $1
+                  AND (cr.due_at IS NULL OR cr.due_at <= $2)
+                "#,
+                &[&user_did, &now],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to count due cards: {}", e)))?;
+
+        let due_count: i64 = due_row.get("due_count");
+
+        let reviewed_row = client
+            .query_one(
+                r#"
+                SELECT COUNT(*) as reviewed_count FROM card_reviews
+                WHERE user_did = $1 AND DATE(last_reviewed_at) = $2
+                "#,
+                &[&user_did, &today],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to count reviews: {}", e)))?;
+
+        let reviewed_today: i64 = reviewed_row.get("reviewed_count");
+
+        let stats_row = client
+            .query_opt(
+                "SELECT current_streak, longest_streak, total_cards_reviewed FROM user_study_stats WHERE user_did = $1",
+                &[&user_did],
+            )
+            .await
+            .map_err(|e| ReviewRepoError::DatabaseError(format!("Failed to get stats: {}", e)))?;
+
+        let (current_streak, longest_streak, total_reviews) = stats_row
+            .map(|row| {
+                (
+                    row.get::<_, i32>("current_streak"),
+                    row.get::<_, i32>("longest_streak"),
+                    row.get::<_, i32>("total_cards_reviewed") as i64,
+                )
+            })
+            .unwrap_or((0, 0, 0));
+
+        Ok(StudyStats { due_count, current_streak, longest_streak, reviewed_today, total_reviews })
+    }
+}
+
+#[cfg(test)]
+pub mod mock {
+    use super::*;
+    use std::sync::{Arc, Mutex};
+
+    #[derive(Clone)]
+    pub struct MockReviewRepository {
+        pub cards: Arc<Mutex<Vec<ReviewCard>>>,
+        pub should_fail: Arc<Mutex<bool>>,
+    }
+
+    impl MockReviewRepository {
+        pub fn new() -> Self {
+            Self { cards: Arc::new(Mutex::new(Vec::new())), should_fail: Arc::new(Mutex::new(false)) }
+        }
+
+        pub fn with_cards(cards: Vec<ReviewCard>) -> Self {
+            Self { cards: Arc::new(Mutex::new(cards)), should_fail: Arc::new(Mutex::new(false)) }
+        }
+
+        #[allow(dead_code)]
+        pub fn set_should_fail(&self, should_fail: bool) {
+            *self.should_fail.lock().unwrap() = should_fail;
+        }
+    }
+
+    impl Default for MockReviewRepository {
+        fn default() -> Self {
+            Self::new()
+        }
+    }
+
+    #[async_trait]
+    impl ReviewRepository for MockReviewRepository {
+        async fn get_due_cards(
+            &self, _user_did: &str, deck_id: Option<&str>, limit: i64,
+        ) -> Result<Vec<ReviewCard>, ReviewRepoError> {
+            if *self.should_fail.lock().unwrap() {
+                return Err(ReviewRepoError::DatabaseError("Mock failure".to_string()));
+            }
+
+            let cards = self.cards.lock().unwrap();
+            let filtered: Vec<_> = cards
+                .iter()
+                .filter(|c| deck_id.is_none_or(|id| c.deck_id == id))
+                .take(limit as usize)
+                .cloned()
+                .collect();
+            Ok(filtered)
+        }
+
+        async fn submit_review(
+            &self, _user_did: &str, _card_id: &str, grade: Grade,
+        ) -> Result<ReviewState, ReviewRepoError> {
+            if *self.should_fail.lock().unwrap() {
+                return Err(ReviewRepoError::DatabaseError("Mock failure".to_string()));
+            }
+
+            let state = ReviewState::default();
+            Ok(state.schedule(grade, &Sm2Config::default()))
+        }
+
+        async fn get_stats(&self, _user_did: &str) -> Result<StudyStats, ReviewRepoError> {
+            if *self.should_fail.lock().unwrap() {
+                return Err(ReviewRepoError::DatabaseError("Mock failure".to_string()));
+            }
+
+            Ok(StudyStats {
+                due_count: self.cards.lock().unwrap().len() as i64,
+                current_streak: 5,
+                longest_streak: 10,
+                reviewed_today: 3,
+                total_reviews: 100,
+            })
+        }
+    }
+}

crates/server/src/state.rs

···
 use crate::repository::card::{CardRepository, DbCardRepository};
 use crate::repository::note::{DbNoteRepository, NoteRepository};
 use crate::repository::oauth::{DbOAuthRepository, OAuthRepository};
+use crate::repository::review::{DbReviewRepository, ReviewRepository};
 use std::sync::Arc;
 
 pub type SharedState = Arc<AppState>;
···
     pub card_repo: Arc<dyn CardRepository>,
     pub note_repo: Arc<dyn NoteRepository>,
     pub oauth_repo: Arc<dyn OAuthRepository>,
+    pub review_repo: Arc<dyn ReviewRepository>,
 }
 
 impl AppState {
···
         let card_repo = Arc::new(DbCardRepository::new(pool.clone())) as Arc<dyn CardRepository>;
         let note_repo = Arc::new(DbNoteRepository::new(pool.clone())) as Arc<dyn NoteRepository>;
         let oauth_repo = Arc::new(DbOAuthRepository::new(pool.clone())) as Arc<dyn OAuthRepository>;
+        let review_repo = Arc::new(DbReviewRepository::new(pool.clone())) as Arc<dyn ReviewRepository>;
 
-        Arc::new(Self { pool, card_repo, note_repo, oauth_repo })
+        Arc::new(Self { pool, card_repo, note_repo, oauth_repo, review_repo })
     }
 
     #[cfg(test)]
···
         pool: DbPool, card_repo: Arc<dyn CardRepository>, note_repo: Arc<dyn NoteRepository>,
         oauth_repo: Arc<dyn OAuthRepository>,
     ) -> SharedState {
-        Arc::new(Self { pool, card_repo, note_repo, oauth_repo })
+        let review_repo =
+            Arc::new(crate::repository::review::mock::MockReviewRepository::new()) as Arc<dyn ReviewRepository>;
+        Arc::new(Self { pool, card_repo, note_repo, oauth_repo, review_repo })
     }
 }

docs/todo.md

···
 - **(Done) Milestone E**: Internal component library/UI Foundation + Animations.
 - **(Done) Milestone F**: Content Authoring (Notes + Cards + Deck Builder).
 
-### Milestone G - Study Engine (SRS) + Daily Review UX
-
-#### Deliverables
-
-- SRS scheduler (SM-2 baseline)
-    - grade 0–5, EF, interval, repetition count
-- Review queue generation rules
-- Study session UI:
-    - keyboard-first review loop
-    - quick edit card during review
-- Progress views (private):
-    - due count, retention proxy, streaks
-
-#### Acceptance
-
-- 30-day simulated study test produces stable, believable intervals.
-
-#### Notes
-
-- SM-2 reference behavior is well documented; start there and iterate.
+- **(Done) Milestone G**: Study Engine (SRS) + Daily Review UX.
+    - SM-2 spaced repetition scheduler.
+    - Review repository with due card queries and stats tracking.
+    - API endpoints: `/review/due`, `/review/submit`, `/review/stats`.
+    - StudySession component with keyboard-first review.
+    - ReviewStats component for progress display.
 
 ### Milestone H - Social Layer v1 (Follow, Feed, Fork, Comments)
 

docs/user-flows.md

···
+# User Flows
+
+User experience pathways for Malfestio.
+
+## Authentication
+
+### Login
+
+1. Navigate to `/login`
+2. Enter Bluesky handle and app password
+3. Submit → redirected to Library
+
+### Logout
+
+1. Click avatar in header → "Logout"
+2. → redirected to Landing page
+
+## Deck Management
+
+### Create Deck
+
+1. Library (`/`) → "Create Deck"
+2. Fill: title, description, tags
+3. Set visibility (Private/Unlisted/Public/SharedWith)
+4. Add cards (front/back, optional hints, card type)
+5. Submit → deck created, redirected to Library
+
+### View Deck
+
+1. Library → click deck card
+2. View title, description, tags, card list
+3. Options: Edit, Study, Back to Library
+
+### Study Deck
+
+1. Deck View → "Study Deck"
+2. Study session with keyboard controls
+3. Grade cards (1-5), view progress
+4. Session complete → return to deck
+
+## Note Management
+
+### Create Note
+
+1. Header → "Notes" → "New Note"
+2. Fill: title, body (markdown), tags
+3. Add wikilinks with `[[Note Title]]`
+4. Set visibility
+5. Submit → note created
+
+### View Notes
+
+1. Header → "Notes"
+2. Browse notes with backlink navigation
+
+## Content Import
+
+### Import Article
+
+1. Header → "Import"
+2. Enter article URL
+3. Submit → article parsed, deck/note created
+
+### Import Lecture
+
+1. Import page → "Lecture Import" tab
+2. Enter lecture URL
+3. Submit → lecture content extracted
+
+## Study Session
+
+### Daily Review
+
+1. Navigate to `/review` or click "Review" in header
+2. View study stats: due count, streak, reviewed today
+3. Click "Start Study Session"
+4. Card front shown → press **Space** to flip
+5. View answer → grade with **1-5** keys
+6. Repeat until all due cards complete
+7. View completion message and updated stats
+
+### Deck-Specific Review
+
+1. Navigate to deck view (`/decks/:id`)
+2. Click "Study Deck"
+3. Review only cards from that deck
+4. Same keyboard controls apply
+
+### Progress Tracking
+
+- **Due count**: Cards needing review today
+- **Streak**: Consecutive days studied
+- **Reviewed today**: Cards completed this session
+- **Interval growth**: SM-2 algorithm increases intervals for mastered cards
+
+### Keyboard Shortcuts
+
+| Key   | Action         |
+| ----- | -------------- |
+| Space | Flip card      |
+| 1     | Grade: Again   |
+| 2     | Grade: Hard    |
+| 3     | Grade: Good    |
+| 4     | Grade: Easy    |
+| 5     | Grade: Perfect |
+| E     | Quick edit     |
+| Esc   | Exit session   |

migrations/004_2025_12_30_srs_reviews.sql

···
+-- SRS (Spaced Repetition System) schema
+--
+-- Tracks per-user review state for each card
+
+CREATE TABLE card_reviews (
+    id UUID PRIMARY KEY,
+    card_id UUID NOT NULL REFERENCES cards(id) ON DELETE CASCADE,
+    user_did TEXT NOT NULL,
+    -- SM-2 algorithm fields
+    ease_factor REAL NOT NULL DEFAULT 2.5,
+    interval_days INTEGER NOT NULL DEFAULT 0,
+    repetitions INTEGER NOT NULL DEFAULT 0,
+    -- Scheduling
+    due_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    last_reviewed_at TIMESTAMPTZ,
+    -- Stats
+    total_reviews INTEGER NOT NULL DEFAULT 0,
+    -- Timestamps
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    -- Each user has one review state per card
+    UNIQUE(card_id, user_did)
+);
+
+CREATE INDEX idx_card_reviews_user_due ON card_reviews(user_did, due_at);
+CREATE INDEX idx_card_reviews_card_id ON card_reviews(card_id);
+
+CREATE TRIGGER update_card_reviews_updated_at BEFORE UPDATE ON card_reviews
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();
+
+CREATE TABLE user_study_stats (
+    id UUID PRIMARY KEY,
+    user_did TEXT NOT NULL UNIQUE,
+    current_streak INTEGER NOT NULL DEFAULT 0,
+    longest_streak INTEGER NOT NULL DEFAULT 0,
+    last_study_date DATE,
+    total_cards_reviewed INTEGER NOT NULL DEFAULT 0,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_user_study_stats_did ON user_study_stats(user_did);
+
+CREATE TRIGGER update_user_study_stats_updated_at BEFORE UPDATE ON user_study_stats
+    FOR EACH ROW EXECUTE FUNCTION update_updated_at_column();

web/src/App.tsx

···
 import Login from "$pages/Login";
 import NoteNew from "$pages/NoteNew";
 import NotFound from "$pages/NotFound";
+import Review from "$pages/Review";
 import { Route, Router } from "@solidjs/router";
 import type { Component } from "solid-js";
 import { Show } from "solid-js";
···
       <Route path="/decks/:id" component={() => <ProtectedRoute component={DeckView} />} />
       <Route path="/import" component={() => <ProtectedRoute component={Import} />} />
       <Route path="/import/lecture" component={() => <ProtectedRoute component={LectureImport} />} />
+      <Route path="/review" component={() => <ProtectedRoute component={Review} />} />
+      <Route path="/review/:deckId" component={() => <ProtectedRoute component={Review} />} />
       <Route path="*" component={() => <ProtectedRoute component={NotFound} />} />
     </Router>
   );

web/src/components/ReviewStats.tsx

···
+import { fadeIn } from "$lib/animations";
+import { api } from "$lib/api";
+import type { ReviewCard, StudyStats } from "$lib/store";
+import { Skeleton } from "$ui/Skeleton";
+import type { Component } from "solid-js";
+import { Motion } from "solid-motionone";
+
+type ReviewStatsProps = { stats: StudyStats | null; loading?: boolean };
+
+export const ReviewStats: Component<ReviewStatsProps> = (props) => {
+  return (
+    <Motion.div {...fadeIn} class="bg-gray-900 rounded-xl p-6 border border-gray-800">
+      {/* TODO: use solid conditional components instead of ternary */}
+      {props.loading
+        ? (
+          <div class="space-y-4">
+            <Skeleton class="h-6 w-32" />
+            <Skeleton class="h-4 w-48" />
+            <Skeleton class="h-4 w-40" />
+          </div>
+        )
+        : props.stats
+        ? (
+          <div class="space-y-4">
+            <div class="flex items-center justify-between">
+              <h3 class="text-lg font-semibold text-white">Study Progress</h3>
+              {/* TODO: fire icon */}
+              <span class="text-2xl">🔥 {props.stats.current_streak} day streak</span>
+            </div>
+
+            <div class="grid grid-cols-3 gap-4 text-center">
+              <div class="bg-gray-800 rounded-lg p-4">
+                <p class="text-3xl font-bold text-blue-400">{props.stats.due_count}</p>
+                <p class="text-sm text-gray-400">Due Today</p>
+              </div>
+              <div class="bg-gray-800 rounded-lg p-4">
+                <p class="text-3xl font-bold text-green-400">{props.stats.reviewed_today}</p>
+                <p class="text-sm text-gray-400">Reviewed</p>
+              </div>
+              <div class="bg-gray-800 rounded-lg p-4">
+                <p class="text-3xl font-bold text-purple-400">{props.stats.total_reviews}</p>
+                <p class="text-sm text-gray-400">Total</p>
+              </div>
+            </div>
+
+            {props.stats.longest_streak > 0 && (
+              <p class="text-sm text-gray-500 text-center">Longest streak: {props.stats.longest_streak} days</p>
+            )}
+          </div>
+        )
+        : <p class="text-gray-400">No stats available</p>}
+    </Motion.div>
+  );
+};
+
+// TODO: move this to api.ts
+export async function fetchStudyStats(): Promise<StudyStats | null> {
+  try {
+    const response = await api.getStats();
+    if (response.ok) {
+      return response.json();
+    }
+  } catch (err) {
+    console.error("Failed to fetch stats:", err);
+  }
+  return null;
+}
+
+// TODO: move this to api.ts
+export async function fetchDueCards(deckId?: string): Promise<ReviewCard[]> {
+  try {
+    const response = await api.getDueCards(deckId);
+    if (response.ok) {
+      return response.json();
+    }
+  } catch (err) {
+    console.error("Failed to fetch due cards:", err);
+  }
+  return [];
+}

web/src/components/StudySession.test.tsx

···
+import type { ReviewCard } from "$lib/store";
+import { cleanup, fireEvent, render, screen } from "@solidjs/testing-library";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { StudySession } from "./StudySession";
+
+vi.mock(
+  "$lib/api",
+  () => ({ api: { submitReview: vi.fn().mockResolvedValue({ ok: true, json: () => Promise.resolve({}) }) } }),
+);
+
+const mockCards: ReviewCard[] = [{
+  review_id: "review-1",
+  card_id: "card-1",
+  deck_id: "deck-1",
+  deck_title: "Test Deck",
+  front: "What is 2+2?",
+  back: "4",
+  media_url: undefined,
+  hints: [],
+  due_at: new Date().toISOString(),
+}, {
+  review_id: "review-2",
+  card_id: "card-2",
+  deck_id: "deck-1",
+  deck_title: "Test Deck",
+  front: "What is the capital of France?",
+  back: "Paris",
+  media_url: undefined,
+  hints: ["It's a famous city"],
+  due_at: new Date().toISOString(),
+}];
+
+describe("StudySession", () => {
+  afterEach(cleanup);
+
+  it("renders card front initially", () => {
+    const onComplete = vi.fn();
+    const onExit = vi.fn();
+
+    render(() => <StudySession cards={mockCards} onComplete={onComplete} onExit={onExit} />);
+
+    expect(screen.getByText("What is 2+2?")).toBeInTheDocument();
+    expect(screen.getByText("Press Space or click to reveal")).toBeInTheDocument();
+  });
+
+  it("shows progress indicator", () => {
+    const onComplete = vi.fn();
+    const onExit = vi.fn();
+
+    render(() => <StudySession cards={mockCards} onComplete={onComplete} onExit={onExit} />);
+
+    expect(screen.getByText(/Card 1 of 2/i)).toBeInTheDocument();
+  });
+
+  it("flips card on click", async () => {
+    const onComplete = vi.fn();
+    const onExit = vi.fn();
+
+    render(() => <StudySession cards={mockCards} onComplete={onComplete} onExit={onExit} />);
+
+    expect(screen.getByText("What is 2+2?")).toBeInTheDocument();
+
+    const cardElement = screen.getByText("What is 2+2?").closest("div[class*='cursor-pointer']");
+    if (cardElement) {
+      fireEvent.click(cardElement);
+    }
+
+    expect(await screen.findByText("How well did you know this?")).toBeInTheDocument();
+  });
+
+  it("shows keyboard hints", () => {
+    const onComplete = vi.fn();
+    const onExit = vi.fn();
+
+    render(() => <StudySession cards={mockCards} onComplete={onComplete} onExit={onExit} />);
+
+    expect(screen.getByText("Space: Flip")).toBeInTheDocument();
+    expect(screen.getByText("1-5: Grade")).toBeInTheDocument();
+    expect(screen.getByText("E: Edit")).toBeInTheDocument();
+    expect(screen.getByText("Esc: Exit")).toBeInTheDocument();
+  });
+
+  it("calls onExit when exit button is clicked", () => {
+    const onComplete = vi.fn();
+    const onExit = vi.fn();
+
+    render(() => <StudySession cards={mockCards} onComplete={onComplete} onExit={onExit} />);
+
+    const exitButton = screen.getByRole("button", { name: /✕ Exit/i });
+    fireEvent.click(exitButton);
+
+    expect(onExit).toHaveBeenCalled();
+  });
+});

web/src/components/StudySession.tsx

···
+import { scaleIn, slideInUp } from "$lib/animations";
+import { api } from "$lib/api";
+import type { Grade, ReviewCard } from "$lib/store";
+import { Button } from "$ui/Button";
+import { Dialog } from "$ui/Dialog";
+import { ProgressBar } from "$ui/ProgressBar";
+import { type Component, createEffect, createSignal, For, onCleanup, onMount, Show } from "solid-js";
+import { Motion } from "solid-motionone";
+
+type StudySessionProps = { cards: ReviewCard[]; onComplete: () => void; onExit: () => void };
+
+const GRADE_LABELS: { [key in Grade]: { label: string; color: string; key: string } } = {
+  0: { label: "Again", color: "bg-red-600 hover:bg-red-500", key: "1" },
+  1: { label: "Hard", color: "bg-orange-600 hover:bg-orange-500", key: "2" },
+  2: { label: "Okay", color: "bg-yellow-600 hover:bg-yellow-500", key: "3" },
+  3: { label: "Good", color: "bg-green-600 hover:bg-green-500", key: "4" },
+  4: { label: "Easy", color: "bg-emerald-600 hover:bg-emerald-500", key: "5" },
+  5: { label: "Perfect", color: "bg-cyan-600 hover:bg-cyan-500", key: "5" },
+};
+
+export const StudySession: Component<StudySessionProps> = (props) => {
+  const [currentIndex, setCurrentIndex] = createSignal(0);
+  const [isFlipped, setIsFlipped] = createSignal(false);
+  const [isSubmitting, setIsSubmitting] = createSignal(false);
+  const [showEditDialog, setShowEditDialog] = createSignal(false);
+
+  const currentCard = () => props.cards[currentIndex()];
+  const progress = () => ((currentIndex() + 1) / props.cards.length) * 100;
+  const isComplete = () => currentIndex() >= props.cards.length;
+
+  const handleFlip = () => {
+    if (!isFlipped()) {
+      setIsFlipped(true);
+    }
+  };
+
+  const handleGrade = async (grade: Grade) => {
+    const card = currentCard();
+    if (!card || isSubmitting()) return;
+
+    setIsSubmitting(true);
+    try {
+      const response = await api.submitReview(card.card_id, grade);
+      if (response.ok) {
+        await response.json();
+        setIsFlipped(false);
+        setCurrentIndex((i) => i + 1);
+      }
+    } catch (err) {
+      console.error("Failed to submit review:", err);
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (showEditDialog()) return;
+
+    switch (e.key) {
+      case " ":
+        e.preventDefault();
+        handleFlip();
+        break;
+      case "1":
+        if (isFlipped()) handleGrade(0);
+        break;
+      case "2":
+        if (isFlipped()) handleGrade(1);
+        break;
+      case "3":
+        if (isFlipped()) handleGrade(3);
+        break;
+      case "4":
+        if (isFlipped()) handleGrade(4);
+        break;
+      case "5":
+        if (isFlipped()) handleGrade(5);
+        break;
+      case "e":
+      case "E":
+        setShowEditDialog(true);
+        break;
+      case "Escape":
+        props.onExit();
+        break;
+    }
+  };
+
+  onMount(() => {
+    window.addEventListener("keydown", handleKeyDown);
+  });
+
+  onCleanup(() => {
+    window.removeEventListener("keydown", handleKeyDown);
+  });
+
+  // Check for completion
+  createEffect(() => {
+    if (isComplete()) {
+      props.onComplete();
+    }
+  });
+
+  return (
+    <div class="min-h-screen bg-gray-950 flex flex-col items-center justify-center p-4">
+      {/* Progress Header */}
+      <div class="w-full max-w-2xl mb-8">
+        <div class="flex items-center justify-between mb-2">
+          <span class="text-gray-400 text-sm">Card {currentIndex() + 1} of {props.cards.length}</span>
+          <button onClick={() => props.onExit()} class="text-gray-400 hover:text-white text-sm flex items-center gap-1">
+            ✕ Exit <span class="text-xs text-gray-500">(Esc)</span>
+          </button>
+        </div>
+        <ProgressBar value={progress()} color="green" size="md" />
+      </div>
+
+      {/* Card */}
+      <Show when={currentCard()}>
+        {(card) => (
+          <Motion.div {...scaleIn} class="w-full max-w-2xl">
+            <div
+              onClick={handleFlip}
+              class="relative min-h-[400px] rounded-2xl cursor-pointer perspective-1000"
+              style={{ "transform-style": "preserve-3d" }}>
+              {/* Front */}
+              <div
+                class={`absolute inset-0 rounded-2xl bg-gradient-to-br from-gray-800 to-gray-900 border border-gray-700 p-8 flex flex-col items-center justify-center backface-hidden transition-transform duration-400 ${
+                  isFlipped() ? "rotate-y-180" : ""
+                }`}
+                style={{ "backface-visibility": "hidden" }}>
+                <span class="text-xs text-gray-500 mb-4">{card().deck_title}</span>
+                <p class="text-2xl text-white text-center font-medium">{card().front}</p>
+                <Show when={!isFlipped()}>
+                  <p class="text-gray-500 mt-8 text-sm">Press Space or click to reveal</p>
+                </Show>
+              </div>
+
+              {/* Back */}
+              <div
+                class={`absolute inset-0 rounded-2xl bg-gradient-to-br from-gray-800 to-gray-900 border border-gray-700 p-8 flex flex-col items-center justify-center backface-hidden transition-transform duration-400 ${
+                  isFlipped() ? "" : "rotate-y-180"
+                }`}
+                style={{ "backface-visibility": "hidden", transform: "rotateY(180deg)" }}>
+                <span class="text-xs text-gray-500 mb-4">Answer</span>
+                <p class="text-2xl text-white text-center font-medium">{card().back}</p>
+                <Show when={card().hints.length > 0}>
+                  <div class="mt-4 text-sm text-gray-400">
+                    <For each={card().hints}>{(hint) => <p class="italic">💡 {hint}</p>}</For>
+                  </div>
+                </Show>
+              </div>
+            </div>
+          </Motion.div>
+        )}
+      </Show>
+
+      {/* Grade Buttons */}
+      <Show when={isFlipped()}>
+        <Motion.div {...slideInUp} class="w-full max-w-2xl mt-8">
+          <p class="text-center text-gray-400 text-sm mb-4">How well did you know this?</p>
+          <div class="grid grid-cols-5 gap-2">
+            <For each={[0, 1, 3, 4, 5] as Grade[]}>
+              {(grade) => (
+                <button
+                  onClick={() => handleGrade(grade)}
+                  disabled={isSubmitting()}
+                  class={`py-3 px-2 rounded-lg text-white font-medium transition-colors ${
+                    GRADE_LABELS[grade].color
+                  } disabled:opacity-50`}>
+                  <span class="block text-lg">{GRADE_LABELS[grade].label}</span>
+                  <span class="block text-xs opacity-75">({GRADE_LABELS[grade].key})</span>
+                </button>
+              )}
+            </For>
+          </div>
+        </Motion.div>
+      </Show>
+
+      {/* Keyboard Hints */}
+      <div class="fixed bottom-4 left-1/2 -translate-x-1/2 text-gray-600 text-xs flex gap-4">
+        <span>Space: Flip</span>
+        <span>1-5: Grade</span>
+        <span>E: Edit</span>
+        <span>Esc: Exit</span>
+      </div>
+
+      {/* Edit Dialog */}
+      <Dialog open={showEditDialog()} onClose={() => setShowEditDialog(false)} title="Edit Card">
+        <Show when={currentCard()}>
+          {(card) => (
+            <div class="space-y-4">
+              <div>
+                <label class="block text-sm text-gray-400 mb-1">Front</label>
+                <p class="text-white bg-gray-800 p-3 rounded">{card().front}</p>
+              </div>
+              <div>
+                <label class="block text-sm text-gray-400 mb-1">Back</label>
+                <p class="text-white bg-gray-800 p-3 rounded">{card().back}</p>
+              </div>
+              <p class="text-gray-500 text-sm">Full editing coming soon.</p>
+              <Button onClick={() => setShowEditDialog(false)} variant="secondary" class="w-full">Close</Button>
+            </div>
+          )}
+        </Show>
+      </Dialog>
+    </div>
+  );
+};

web/src/lib/animations.ts

···
 
 /** Stagger delay for list items */
 export const staggerDelay = (index: number, baseDelay = 0.05) => index * baseDelay;
+
+/** Card flip animation (3D) */
+export const cardFlip: MotionOptions = {
+  initial: { rotateY: 0 },
+  animate: { rotateY: 180 },
+  transition: { duration: 0.4, easing: easeOut },
+};
+
+/** Slide out left (for card dismissal) */
+export const slideOutLeft: MotionOptions = {
+  initial: { opacity: 1, x: 0 },
+  animate: { opacity: 0, x: -100 },
+  transition: { duration: 0.25, easing: easeOut },
+};
+
+/** Bounce in (for success feedback) */
+export const bounceIn: MotionOptions = {
+  initial: { opacity: 0, scale: 0.8 },
+  animate: { opacity: 1, scale: 1 },
+  transition: { duration: 0.3, easing: [0.34, 1.56, 0.64, 1] },
+};

web/src/lib/api.ts

···
 export const api = {
   get: (path: string) => apiFetch(path, { method: "GET" }),
   post: (path: string, body: unknown) => apiFetch(path, { method: "POST", body: JSON.stringify(body) }),
+  getDueCards: (deckId?: string, limit = 20) => {
+    const params = new URLSearchParams({ limit: String(limit) });
+    if (deckId) params.set("deck_id", deckId);
+    return apiFetch(`/review/due?${params}`, { method: "GET" });
+  },
+  submitReview: (cardId: string, grade: number) =>
+    apiFetch("/review/submit", { method: "POST", body: JSON.stringify({ card_id: cardId, grade }) }),
+  getStats: () => apiFetch("/review/stats", { method: "GET" }),
 };

web/src/lib/store.ts

···
   visibility: Visibility;
   cards: Card[];
 };
+
+export type Grade = 0 | 1 | 2 | 3 | 4 | 5;
+
+export type ReviewCard = {
+  review_id: string;
+  card_id: string;
+  deck_id: string;
+  deck_title: string;
+  front: string;
+  back: string;
+  media_url?: string;
+  hints: string[];
+  due_at: string;
+};
+
+export type StudyStats = {
+  due_count: number;
+  current_streak: number;
+  longest_streak: number;
+  reviewed_today: number;
+  total_reviews: number;
+};
+
+export type ReviewResponse = { ease_factor: number; interval_days: number; repetitions: number; due_at: string };

web/src/pages/Review.tsx

···
+import { fetchDueCards, fetchStudyStats, ReviewStats } from "$components/ReviewStats";
+import { StudySession } from "$components/StudySession";
+import { fadeIn } from "$lib/animations";
+import type { ReviewCard, StudyStats as StudyStatsType } from "$lib/store";
+import { Button } from "$ui/Button";
+import { Skeleton } from "$ui/Skeleton";
+import { useNavigate, useParams } from "@solidjs/router";
+import { type Component, createSignal, onMount, Show } from "solid-js";
+import { Motion } from "solid-motionone";
+
+const Review: Component = () => {
+  const params = useParams<{ deckId?: string }>();
+  const navigate = useNavigate();
+
+  const [cards, setCards] = createSignal<ReviewCard[]>([]);
+  const [stats, setStats] = createSignal<StudyStatsType | null>(null);
+  const [loading, setLoading] = createSignal(true);
+  const [sessionActive, setSessionActive] = createSignal(false);
+  const [sessionComplete, setSessionComplete] = createSignal(false);
+
+  onMount(async () => {
+    const [statsData, cardsData] = await Promise.all([fetchStudyStats(), fetchDueCards(params.deckId)]);
+    setStats(statsData);
+    setCards(cardsData);
+    setLoading(false);
+  });
+
+  const startSession = () => {
+    if (cards().length > 0) {
+      setSessionActive(true);
+      setSessionComplete(false);
+    }
+  };
+
+  const handleComplete = async () => {
+    setSessionActive(false);
+    setSessionComplete(true);
+    const newStats = await fetchStudyStats();
+    setStats(newStats);
+  };
+
+  const handleExit = () => {
+    setSessionActive(false);
+    navigate("/");
+  };
+
+  return (
+    <Show
+      when={!sessionActive()}
+      fallback={<StudySession cards={cards()} onComplete={handleComplete} onExit={handleExit} />}>
+      <Motion.div {...fadeIn} class="max-w-4xl mx-auto py-8 px-4">
+        <h1 class="text-3xl font-bold text-white mb-8">{params.deckId ? "Deck Review" : "Daily Review"}</h1>
+
+        <ReviewStats stats={stats()} loading={loading()} />
+
+        <div class="mt-8 bg-gray-900 rounded-xl p-6 border border-gray-800">
+          <Show
+            when={!loading()}
+            fallback={
+              <div class="space-y-4">
+                <Skeleton class="h-8 w-48" />
+                <Skeleton class="h-12 w-full" />
+              </div>
+            }>
+            <Show
+              when={cards().length > 0}
+              fallback={
+                <div class="text-center py-8">
+                  <p class="text-4xl mb-4">🎉</p>
+                  <h2 class="text-xl font-semibold text-white mb-2">
+                    {sessionComplete() ? "Session Complete!" : "All Caught Up!"}
+                  </h2>
+                  <p class="text-gray-400 mb-6">
+                    {sessionComplete()
+                      ? "Great job! You've reviewed all your due cards."
+                      : "You have no cards due for review right now."}
+                  </p>
+                  <Button onClick={() => navigate("/")} variant="secondary">Back to Library</Button>
+                </div>
+              }>
+              <div class="text-center py-4">
+                <p class="text-lg text-white mb-2">
+                  You have <span class="font-bold text-blue-400">{cards().length}</span> cards due
+                </p>
+                <p class="text-gray-400 text-sm mb-6">Use keyboard shortcuts for faster reviews</p>
+                <Button onClick={startSession} class="px-8 py-3 text-lg">Start Study Session</Button>
+              </div>
+            </Show>
+          </Show>
+        </div>
+
+        <div class="mt-8 bg-gray-900/50 rounded-xl p-6 border border-gray-800/50">
+          <h3 class="text-sm font-semibold text-gray-400 mb-4">Keyboard Shortcuts</h3>
+          <div class="grid grid-cols-2 md:grid-cols-4 gap-4 text-sm">
+            <div class="flex items-center gap-2">
+              <kbd class="px-2 py-1 bg-gray-800 rounded text-gray-300">Space</kbd>
+              <span class="text-gray-400">Flip card</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <kbd class="px-2 py-1 bg-gray-800 rounded text-gray-300">1-5</kbd>
+              <span class="text-gray-400">Grade answer</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <kbd class="px-2 py-1 bg-gray-800 rounded text-gray-300">E</kbd>
+              <span class="text-gray-400">Edit card</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <kbd class="px-2 py-1 bg-gray-800 rounded text-gray-300">Esc</kbd>
+              <span class="text-gray-400">Exit session</span>
+            </div>
+          </div>
+        </div>
+      </Motion.div>
+    </Show>
+  );
+};
+
+export default Review;