feat(wave3): telemetry and content-loader hardening for ai-ml-fundamentals probe (#158)

Author: OpenSauce

backend/app/api/analytics.py

@@ -225,6 +225,43 @@ def analytics_summary(
         """)
     ).all()
 
+    # Per-category quiz completions
+    category_quizzes = session.exec(
+        text("""
+            SELECT q.category, COUNT(*) AS completions
+            FROM userquizattempt uqa
+            JOIN quiz q ON q.id = uqa.quiz_id
+            WHERE q.category IS NOT NULL
+            GROUP BY q.category
+            ORDER BY completions DESC
+        """)
+    ).all()
+
+    # Per-category anonymous lesson views (from event table)
+    category_anon_lesson_views = session.exec(
+        text("""
+            SELECT payload->>'category' AS cat, COUNT(*) AS cnt
+            FROM event
+            WHERE event_type = 'lesson_view'
+              AND user_id IS NULL
+              AND payload->>'category' IS NOT NULL
+            GROUP BY cat
+            ORDER BY cnt DESC
+        """)
+    ).all()
+
+    # Per-category flashcard reviews (sum review repetitions proxy via userflashcard + flashcard join)
+    category_flashcard_reviews = session.exec(
+        text("""
+            SELECT f.category, SUM(uf.repetitions) AS reviews
+            FROM userflashcard uf
+            JOIN flashcard f ON f.id = uf.flashcard_id
+            WHERE f.category IS NOT NULL
+            GROUP BY f.category
+            ORDER BY reviews DESC
+        """)
+    ).all()
+
     return {
         "total_sessions": total_sessions,
         "anonymous_sessions": anonymous_sessions,
@@ -259,4 +296,7 @@ def analytics_summary(
             "users_with_problem_reviews": problem_user_row[0] or 0,
         },
         "category_problem_submissions": {r[0]: r[1] for r in category_problems},
+        "quiz_completions_by_category": {r[0]: r[1] for r in category_quizzes},
+        "anon_lesson_views_by_category": {r[0]: r[1] for r in category_anon_lesson_views},
+        "flashcard_reviews_by_category": {r[0]: int(r[1]) for r in category_flashcard_reviews},
     }

backend/app/api/users.py

@@ -1,6 +1,7 @@
 # app/api/users.py
 
 import os
+import uuid
 from datetime import datetime, timedelta, timezone
 from typing import Optional
 
@@ -13,7 +14,7 @@
 
 from ..database import get_session
 from ..limiter import limiter
-from ..models import StreakOut, StudySession, Token, User, UserCreate
+from ..models import Event, StreakOut, StudySession, Token, User, UserCreate
 
 # ─── CONFIG ──────────────────────────────────────────────────────────────
 
@@ -137,6 +138,16 @@ def signup(
         hashed_password=get_password_hash(data.password),
     )
     session.add(user)
+    session.flush()
+
+    session_id = request.cookies.get("session_id") or str(uuid.uuid4())
+    event = Event(
+        session_id=session_id,
+        user_id=user.id,
+        event_type="signup",
+        payload={"referrer_category": data.referrer_category},
+    )
+    session.add(event)
     session.commit()
     access_token = create_access_token({"sub": data.username})
     return Token(access_token=access_token)

backend/app/loader.py

@@ -73,7 +73,28 @@ def load_yaml_flashcards() -> None:
             if not isinstance(data, list):
                 logger.warning("Skipping %s: root is %s, not list", file, type(data).__name__)
                 continue
-            for raw in data:
+            for idx, raw in enumerate(data):
+                if not isinstance(raw, dict):
+                    logger.warning(
+                        "Skipping card %d in %s: expected dict, got %s",
+                        idx,
+                        file,
+                        type(raw).__name__,
+                    )
+                    continue
+                missing_key = None
+                for required in ("title", "Front", "Back"):
+                    if required not in raw:
+                        missing_key = required
+                        break
+                if missing_key is not None:
+                    logger.warning(
+                        "Skipping card %d in %s: missing required field '%s'",
+                        idx,
+                        file,
+                        missing_key,
+                    )
+                    continue
                 card = Flashcard(
                     title=raw["title"],
                     front=raw["Front"],

backend/app/models.py

@@ -21,6 +21,7 @@
     "docker": "Docker",
     "linux": "Linux",
     "networking": "Networking",
+    "ai-ml-fundamentals": "AI/ML Fundamentals",
 }
 
 
@@ -56,6 +57,20 @@ class User(SQLModel, table=True):
 class UserCreate(BaseModel):
     username: str = PydanticField(min_length=3, pattern=r'^[a-zA-Z0-9_]+$')
     password: str = PydanticField(min_length=8)
+    referrer_category: Optional[str] = PydanticField(default=None, max_length=64)
+
+    @field_validator("referrer_category")
+    @classmethod
+    def normalize_referrer_category(cls, value: Optional[str]) -> Optional[str]:
+        if value is None:
+            return None
+        normalized = value.strip().lower()
+        if not normalized or len(normalized) > 64:
+            return None
+        parts = normalized.split("-")
+        if any(not part or not part.isalnum() for part in parts):
+            return None
+        return normalized
 
 
 class Token(BaseModel):

backend/tests/api/test_analytics.py

@@ -7,7 +7,16 @@
 from app.api.analytics import summary_router
 from app.api.users import router as user_router
 from app.database import get_session
-from app.models import CodingProblem, Event, UserCodingProblem
+from app.models import (
+    CodingProblem,
+    Event,
+    Flashcard,
+    Lesson,
+    Quiz,
+    UserCodingProblem,
+    UserFlashcard,
+    UserQuizAttempt,
+)
 
 
 @pytest.fixture(name="app")
@@ -235,6 +244,96 @@ def test_summary_with_problem_metrics(client, session, create_user, get_token):
     assert data["category_problem_submissions"]["data-structures"] == 3
 
 
+def test_per_category_breakdowns(client, session, create_user, get_token):
+    """quiz_completions_by_category, anon_lesson_views_by_category, and
+    flashcard_reviews_by_category are all present and correctly counted."""
+    admin = create_user(is_admin=True)
+    token = get_token(client, "user", "password")
+
+    # Seed two categories
+    lesson_a = Lesson(
+        title="Lesson A",
+        slug="lesson-a",
+        category="cat-a",
+        content="Content",
+        summary="Summary",
+        reading_time_minutes=1,
+        order=0,
+    )
+    lesson_b = Lesson(
+        title="Lesson B",
+        slug="lesson-b",
+        category="cat-b",
+        content="Content",
+        summary="Summary",
+        reading_time_minutes=1,
+        order=0,
+    )
+    session.add(lesson_a)
+    session.add(lesson_b)
+    session.commit()
+    session.refresh(lesson_a)
+    session.refresh(lesson_b)
+
+    quiz_a = Quiz(title="Quiz A", slug="quiz-a", category="cat-a", lesson_slug="lesson-a")
+    quiz_b = Quiz(title="Quiz B", slug="quiz-b", category="cat-b", lesson_slug="lesson-b")
+    session.add(quiz_a)
+    session.add(quiz_b)
+    session.commit()
+    session.refresh(quiz_a)
+    session.refresh(quiz_b)
+
+    # 2 quiz completions for cat-a, 1 for cat-b
+    session.add(UserQuizAttempt(user_id=admin.id, quiz_id=quiz_a.id, score=4, total=5))
+    session.commit()
+    second_user = create_user(username="user2")
+    session.add(UserQuizAttempt(user_id=second_user.id, quiz_id=quiz_a.id, score=3, total=5))
+    session.add(UserQuizAttempt(user_id=second_user.id, quiz_id=quiz_b.id, score=5, total=5))
+    session.commit()
+
+    # Anon lesson views: 3 for cat-a, 1 for cat-b
+    for _ in range(3):
+        session.add(Event(
+            session_id="anon-s",
+            user_id=None,
+            event_type="lesson_view",
+            payload={"category": "cat-a", "slug": "lesson-a"},
+        ))
+    session.add(Event(
+        session_id="anon-s2",
+        user_id=None,
+        event_type="lesson_view",
+        payload={"category": "cat-b", "slug": "lesson-b"},
+    ))
+    session.commit()
+
+    # Flashcard reviews: seed a card in cat-a with repetitions=5, cat-b with repetitions=2
+    card_a = Flashcard(title="Card A", front="Q", back="A", category="cat-a", tags=[])
+    card_b = Flashcard(title="Card B", front="Q", back="A", category="cat-b", tags=[])
+    session.add(card_a)
+    session.add(card_b)
+    session.commit()
+    session.refresh(card_a)
+    session.refresh(card_b)
+
+    session.add(UserFlashcard(user_id=admin.id, flashcard_id=card_a.id, repetitions=5))
+    session.add(UserFlashcard(user_id=admin.id, flashcard_id=card_b.id, repetitions=2))
+    session.commit()
+
+    resp = client.get("/analytics/summary", headers={"Authorization": f"Bearer {token}"})
+    assert resp.status_code == 200
+    data = resp.json()
+
+    assert data["quiz_completions_by_category"]["cat-a"] == 2
+    assert data["quiz_completions_by_category"]["cat-b"] == 1
+
+    assert data["anon_lesson_views_by_category"]["cat-a"] == 3
+    assert data["anon_lesson_views_by_category"]["cat-b"] == 1
+
+    assert data["flashcard_reviews_by_category"]["cat-a"] == 5
+    assert data["flashcard_reviews_by_category"]["cat-b"] == 2
+
+
 def test_users_me_returns_is_admin_false(client, session, create_user, get_token):
     create_user(is_admin=False)
     token = get_token(client, "user", "password")

backend/tests/api/test_quizzes.py

@@ -7,7 +7,7 @@
 from app.api.users import get_current_user, get_optional_user
 from app.api.users import router as user_router
 from app.database import get_session
-from app.models import UserQuizAttempt
+from app.models import Flashcard, Lesson, UserFlashcard, UserQuizAttempt
 from tests.conftest import get_test_session
 
 
@@ -246,3 +246,52 @@ def test_submit_quiz_zero_score(client, create_quiz, create_quiz_question):
     for r in data["results"]:
         assert "correct_index" in r
         assert "explanation" in r
+
+
+def test_seed_flashcards_fresh_category(client, session, create_user, create_quiz, create_quiz_question):
+    """Submitting a quiz for a fresh category seeds UserFlashcard rows for all linked flashcards."""
+    create_user(username="user", password="password")
+    lesson_slug = "ai-foundations"
+    category = "ai-ml-fundamentals"
+
+    lesson = Lesson(
+        title="AI Foundations",
+        slug=lesson_slug,
+        category=category,
+        content="Content",
+        summary="Summary",
+        reading_time_minutes=5,
+        order=0,
+    )
+    session.add(lesson)
+    session.commit()
+
+    quiz = create_quiz(slug="ai-foundations", category=category, lesson_slug=lesson_slug)
+    q1 = create_quiz_question(quiz_id=quiz.id, correct_index=0, order=0)
+
+    for i in range(10):
+        card = Flashcard(
+            title=f"AI Card {i}",
+            front=f"Q{i}",
+            back=f"A{i}",
+            category=category,
+            lesson_slug=lesson_slug,
+            tags=[],
+        )
+        session.add(card)
+    session.commit()
+
+    response = client.post(
+        f"/quizzes/{quiz.slug}/submit",
+        json={"answers": {str(q1.id): 0}},
+    )
+    assert response.status_code == 200
+
+    uf_rows = session.exec(
+        select(UserFlashcard).where(UserFlashcard.user_id == FakeUser.id)
+    ).all()
+    assert len(uf_rows) == 10
+    for uf in uf_rows:
+        flashcard = session.get(Flashcard, uf.flashcard_id)
+        assert flashcard is not None
+        assert flashcard.lesson_slug == lesson_slug

backend/tests/api/test_users.py

@@ -3,11 +3,13 @@
 from fastapi.testclient import TestClient
 from slowapi import _rate_limit_exceeded_handler
 from slowapi.errors import RateLimitExceeded
+from sqlmodel import select
 
 from app.api.users import ALGORITHM, SECRET_KEY, User, get_password_hash
 from app.api.users import router as user_router
 from app.database import get_session
 from app.limiter import limiter
+from app.models import Event
 from tests.conftest import get_test_session
 
 
@@ -123,3 +125,31 @@ def test_login_sets_last_login(session):
 
     session.refresh(user)
     assert user.last_login is not None
+
+
+def test_signup_referrer_category_emits_event(session):
+    """Signing up with a referrer_category stores a signup Event with that value."""
+    client = TestClient(anon_app(session))
+    resp = client.post(
+        "/signup",
+        json={"username": "referred_user", "password": "pass1234", "referrer_category": "ai-ml-fundamentals"},
+    )
+    assert resp.status_code == 201
+
+    events = session.exec(select(Event).where(Event.event_type == "signup")).all()
+    assert len(events) == 1
+    assert events[0].payload["referrer_category"] == "ai-ml-fundamentals"
+
+
+def test_signup_no_referrer_category_emits_event_with_none(session):
+    """Signing up without referrer_category emits a signup Event with null value."""
+    client = TestClient(anon_app(session))
+    resp = client.post(
+        "/signup",
+        json={"username": "no_referral_user", "password": "pass1234"},
+    )
+    assert resp.status_code == 201
+
+    events = session.exec(select(Event).where(Event.event_type == "signup")).all()
+    assert len(events) == 1
+    assert events[0].payload["referrer_category"] is None