Add a GraphQL surface alongside REST for the learner read path

Mounted at /graphql. Additive, not a migration: every REST route still works and there
are tests asserting they do.

WHY
The learn page has a measured five-round-trip waterfall on lesson completion. The POST
already returns {xp_gained, stats}; the client discards them and calls refreshStats(),
which fires four more GETs (stats, achievements, activity, completed lessons) against the
same SQLite file for the same repository. learnerDashboard collapses the four reads into
one request, and completeLesson returns the post-mutation dashboard inline so the refresh
is unnecessary.

BE PRECISE ABOUT THE BENEFIT
GraphQL does NOT reduce database work here, and measuring it disproved the intuitive
claim: the combined resolver issues MORE SQL statements than the four REST handlers
(6 vs 4 on an empty repo), because it performs the same four reads plus session
overhead. What it removes is four HTTP round trips, four dependency-injection cycles and
four session open/close pairs. The test and docstrings say this rather than claiming a
query-count win that does not exist.

THE STRAWBERRY LANDMINE
Strawberry documents that it "processes sync and async fields using the event loop, which
means that using a sync def will block the entire worker" -- unlike FastAPI there is no
automatic threadpool. dependencies.get_db hands out a synchronous SQLAlchemy Session, so
a single sync resolver would serialize blocking SQLite calls on the loop and stall
in-flight chat streams. Every resolver is therefore async and offloads via
run_in_threadpool, and two tests enforce it: one reflects over Query/Mutation asserting
no resolver is a sync def, the other asserts each blocking helper is only reached through
run_in_threadpool. AsyncSession is not the alternative -- a single AsyncSession is
documented as unsafe across concurrent tasks, which is how DataLoader batches, and
greenlet is not installed.

SCOPE
Chat deliberately stays REST/SSE. GraphQL incremental delivery (@defer/@stream) is not
ratified: absent from the September 2025 spec edition, RFC open since 2024-09-18, and
Strawberry's support is experimental requiring graphql-core>=3.3.0a9 against 3.2.11
stable. A test asserts the schema exposes no chat or stream field.

strawberry-graphql is pinned with an upper bound (>=0.240,<1.0) -- it is a
weekly-releasing 0.x with a documented breaking-change history, and this file otherwise
uses open lower bounds.

Resolvers reuse GamificationService rather than reimplementing anything, so GraphQL and
REST cannot diverge in behaviour.

ALSO: removed three iCloud-duplicated files ("neo4j_store 2.py", "__init__ 2.py",
"test_neo4j_graph_store 2.py") that macOS had created after the previous commit, and
added a .gitignore rule for the "* 2.*" pattern. The duplicated test file was being
collected by pytest as a second copy of the same 15 tests -- the suite reported 157 with
it present and 142 without, which is how it was caught.

Verified: 10 new tests, 142 total (132 + 10; the earlier 157 was the inflated count),
ruff clean, 43 routes, schema builds and mounts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: ShreeBohara

.gitignore

@@ -84,3 +84,12 @@ htmlcov/
 .cache/
 Documents/
 /repos/
+
+# -----------------------
+# macOS / iCloud duplicate artifacts
+# -----------------------
+# iCloud Drive appends " 2"/" 3" to filenames it duplicates. These are never real
+# source files, and a duplicated test_*.py would be collected by pytest as a second copy
+# of the same tests.
+* 2.*
+* 3.*

README.md

@@ -455,3 +455,43 @@ pnpm web:verify-css
 ## License
 
 MIT
+
+## GraphQL (optional, alongside REST)
+
+A GraphQL surface is mounted at `/graphql` **in addition to** the REST API — nothing was
+migrated, and every REST route still works.
+
+It exists for one measured reason: completing a lesson used to be five HTTP round trips
+(the POST already returned `{xp_gained, stats}`, the client discarded them and fired four
+more GETs for stats, achievements, activity and completed lessons). Two operations
+collapse that:
+
+```graphql
+query { learnerDashboard(repoId: "...") {
+  stats { totalXp level { level title } }
+  achievements { key unlocked }
+  activity { date count }
+  completedLessons
+} }
+
+mutation { completeLesson(repoId: "...", lessonId: "...", timeSpentSeconds: 120) {
+  xpGained { amount reason }
+  dashboard { stats { totalXp } completedLessons }   # post-mutation state inline
+} }
+```
+
+Two deliberate boundaries:
+
+- **Chat stays on REST/SSE.** GraphQL's incremental delivery (`@defer`/`@stream`) is not
+  ratified — absent from the September 2025 spec edition, RFC open since 2024-09-18, and
+  Strawberry's support is experimental requiring `graphql-core>=3.3.0a9` against 3.2.11
+  stable. Token streaming over GraphQL would mean betting on an unratified extension.
+- **Every resolver is `async` and offloads DB work via `run_in_threadpool`.** Strawberry
+  has no threadpool for sync resolvers (unlike FastAPI), and this app uses a synchronous
+  SQLAlchemy `Session` — one sync resolver would serialize blocking SQLite calls on the
+  event loop and stall in-flight chat streams. A test enforces this.
+
+Note on the benefit: GraphQL does **not** reduce database work here. Measured, the
+combined resolver issues slightly more SQL than the four REST handlers. What it removes
+is four network round trips, four dependency-injection cycles and four session
+open/close pairs.

apps/api/requirements.txt

@@ -46,6 +46,10 @@ tree-sitter-ruby>=0.21.0
 # HTTP Client
 httpx>=0.27.0
 
+# GraphQL surface, mounted alongside REST. Upper bound is deliberate: this is a
+# weekly-releasing 0.x with a documented breaking-change history.
+strawberry-graphql[fastapi]>=0.240,<1.0
+
 # Graph read model (optional; only imported when NEO4J_ENABLED=true)
 neo4j>=5.28
 

apps/api/src/api/graphql/__init__.py

@@ -0,0 +1 @@
+"""GraphQL surface, mounted alongside the REST routes (see schema.py for scope)."""

apps/api/src/api/graphql/schema.py

@@ -0,0 +1,292 @@
+"""
+GraphQL schema, mounted alongside the REST routes rather than replacing them.
+
+WHY THIS EXISTS
+The learn page has a measured request waterfall. Completing a lesson is five round
+trips: the POST already returns {xp_gained, stats}, the client discards the stats and
+then calls refreshStats(), which fires four more GETs (stats, achievements, activity,
+completed lessons). Every one of those hits the same SQLite file for the same repository.
+`learnerDashboard` collapses the four reads into one request, and `completeLesson`
+returns the post-mutation dashboard inline so the client never needs the refresh.
+
+WHAT STAYS ON REST
+Chat. It is SSE token streaming (routes/chat.py), and GraphQL's incremental delivery
+(@defer/@stream) is not ratified -- it is absent from the September 2025 spec edition,
+its RFC has been open since 2024-09-18, and Strawberry's support is experimental and
+requires graphql-core>=3.3.0a9 while the installed stable is 3.2.11. Streaming tokens
+over GraphQL here would mean betting on an unratified extension for no gain.
+
+THE THREADING RULE -- READ BEFORE ADDING A RESOLVER
+Strawberry documents that it "processes sync and async fields using the event loop, which
+means that using a sync def will block the entire worker". Unlike FastAPI, there is NO
+automatic threadpool for sync resolvers. dependencies.get_db hands out a synchronous
+SQLAlchemy Session, so every resolver that touches the database MUST go through
+run_in_threadpool. A single sync resolver here would serialize blocking SQLite calls on
+the event loop and stall in-flight chat streams.
+
+Switching to AsyncSession is not the fix: a single AsyncSession is documented as unsafe
+across concurrent tasks, which is exactly how a DataLoader batches, and greenlet (which
+SQLAlchemy's async bridge requires) is not installed.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import strawberry
+from starlette.concurrency import run_in_threadpool
+
+from src.core.demo_mode import assert_demo_repo_access
+from src.dependencies import get_session_factory
+from src.models.database import Repository
+from src.services.gamification import GamificationService
+
+# --- types -----------------------------------------------------------------------
+
+@strawberry.type
+class Level:
+    level: int
+    title: str
+    icon: str
+    current_xp: int
+    xp_for_next_level: int
+    xp_progress: float
+
+
+@strawberry.type
+class Streak:
+    current: int
+    longest: int
+    active_today: bool
+
+
+@strawberry.type
+class UserStats:
+    total_xp: int
+    level: Level
+    streak: Streak
+    lessons_completed: int
+    quizzes_passed: int
+    challenges_completed: int
+    perfect_quizzes: int
+
+
+@strawberry.type
+class Achievement:
+    key: str
+    name: str
+    description: str
+    icon: str
+    category: str
+    xp_reward: int
+    unlocked: bool
+    requirement: Optional[int] = None
+
+
+@strawberry.type
+class ActivityDay:
+    """Activity history as a list rather than a map: GraphQL has no arbitrary-key type."""
+    date: str
+    count: int
+
+
+@strawberry.type
+class XPGain:
+    amount: int
+    reason: str
+    bonus: Optional[int] = None
+    bonus_reason: Optional[str] = None
+
+
+@strawberry.type
+class RepoSummary:
+    id: str
+    github_owner: str
+    github_name: str
+    status: str
+    total_files: int
+    total_chunks: int
+    primary_language: Optional[str] = None
+
+
+@strawberry.type
+class LearnerDashboard:
+    """
+    Everything the learn page needs after any progress event.
+
+    This is the shape that replaces four separate GETs. Keeping it one type (rather than
+    four top-level fields) means the mutation can return it inline, which is what removes
+    the fifth round trip.
+    """
+    repo_id: str
+    stats: UserStats
+    achievements: List[Achievement]
+    activity: List[ActivityDay]
+    completed_lessons: List[str]
+
+
+@strawberry.type
+class CompleteLessonResult:
+    xp_gained: XPGain
+    dashboard: LearnerDashboard
+
+
+# --- mapping from the existing service layer -------------------------------------
+# Deliberately reuses GamificationService so GraphQL and REST cannot diverge in
+# behaviour. These are pure functions over already-fetched data -- no I/O.
+
+def _to_stats(raw) -> UserStats:
+    d = raw if isinstance(raw, dict) else raw.model_dump()
+    lvl, stk = d["level"], d["streak"]
+    return UserStats(
+        total_xp=d["total_xp"],
+        level=Level(
+            level=lvl["level"], title=lvl["title"], icon=lvl["icon"],
+            current_xp=lvl["current_xp"], xp_for_next_level=lvl["xp_for_next_level"],
+            xp_progress=lvl["xp_progress"],
+        ),
+        streak=Streak(
+            current=stk["current"], longest=stk["longest"], active_today=stk["active_today"]
+        ),
+        lessons_completed=d["lessons_completed"],
+        quizzes_passed=d["quizzes_passed"],
+        challenges_completed=d["challenges_completed"],
+        perfect_quizzes=d["perfect_quizzes"],
+    )
+
+
+def _to_achievements(raw) -> List[Achievement]:
+    out = []
+    for a in raw:
+        d = a if isinstance(a, dict) else a.model_dump()
+        out.append(Achievement(
+            key=d["key"], name=d["name"], description=d["description"], icon=d["icon"],
+            category=d["category"], xp_reward=d["xp_reward"],
+            unlocked=bool(d.get("unlocked", False)), requirement=d.get("requirement"),
+        ))
+    return out
+
+
+def _to_activity(raw: Dict[str, int]) -> List[ActivityDay]:
+    return [ActivityDay(date=k, count=v) for k, v in sorted((raw or {}).items())]
+
+
+def _to_xp_gain(raw) -> XPGain:
+    d = raw if isinstance(raw, dict) else raw.model_dump()
+    return XPGain(
+        amount=d["amount"], reason=d["reason"],
+        bonus=d.get("bonus"), bonus_reason=d.get("bonus_reason"),
+    )
+
+
+# --- blocking work, always off the event loop ------------------------------------
+
+def _load_dashboard_sync(repo_id: str, persona: Optional[str]) -> LearnerDashboard:
+    """
+    All four reads in one session, on a worker thread.
+
+    A fresh Session per call, not a request-scoped one: Session is not thread-safe, and
+    this runs on a threadpool worker.
+    """
+    db = get_session_factory()()
+    try:
+        assert_demo_repo_access(db, repo_id)
+        service = GamificationService(db)
+        return LearnerDashboard(
+            repo_id=repo_id,
+            stats=_to_stats(service.get_user_stats(repo_id)),
+            achievements=_to_achievements(service.get_all_achievements(repo_id)),
+            activity=_to_activity(service.get_activity_history(repo_id)),
+            completed_lessons=list(service.get_completed_lessons(repo_id, persona=persona)),
+        )
+    finally:
+        db.close()
+
+
+def _complete_lesson_sync(
+    repo_id: str, lesson_id: str, time_spent_seconds: int,
+    persona: Optional[str], module_id: Optional[str],
+) -> CompleteLessonResult:
+    db = get_session_factory()()
+    try:
+        assert_demo_repo_access(db, repo_id)
+        service = GamificationService(db)
+        xp_gain = service.record_lesson_complete(
+            repo_id, lesson_id, time_spent_seconds, persona=persona, module_id=module_id
+        )
+        # Read the dashboard back in the SAME session, after the write, so the client
+        # cannot observe a state that predates its own mutation.
+        dashboard = LearnerDashboard(
+            repo_id=repo_id,
+            stats=_to_stats(service.get_user_stats(repo_id)),
+            achievements=_to_achievements(service.get_all_achievements(repo_id)),
+            activity=_to_activity(service.get_activity_history(repo_id)),
+            completed_lessons=list(service.get_completed_lessons(repo_id, persona=persona)),
+        )
+        return CompleteLessonResult(xp_gained=_to_xp_gain(xp_gain), dashboard=dashboard)
+    finally:
+        db.close()
+
+
+def _load_repo_sync(repo_id: str) -> Optional[RepoSummary]:
+    db = get_session_factory()()
+    try:
+        assert_demo_repo_access(db, repo_id)
+        repo = db.query(Repository).filter(Repository.id == repo_id).first()
+        if not repo:
+            return None
+        return RepoSummary(
+            id=repo.id,
+            github_owner=repo.github_owner,
+            github_name=repo.github_name,
+            status=repo.status.value if hasattr(repo.status, "value") else str(repo.status),
+            total_files=repo.total_files or 0,
+            total_chunks=repo.total_chunks or 0,
+            primary_language=repo.primary_language,
+        )
+    finally:
+        db.close()
+
+
+# --- schema ----------------------------------------------------------------------
+
+@strawberry.type
+class Query:
+    @strawberry.field(description="Repository summary.")
+    async def repo(self, repo_id: str) -> Optional[RepoSummary]:
+        return await run_in_threadpool(_load_repo_sync, repo_id)
+
+    @strawberry.field(
+        description=(
+            "Stats, achievements, activity and completed lessons in one request. "
+            "Replaces four separate REST GETs."
+        )
+    )
+    async def learner_dashboard(
+        self, repo_id: str, persona: Optional[str] = None
+    ) -> LearnerDashboard:
+        return await run_in_threadpool(_load_dashboard_sync, repo_id, persona)
+
+
+@strawberry.type
+class Mutation:
+    @strawberry.mutation(
+        description=(
+            "Complete a lesson and return the post-mutation dashboard inline, so the "
+            "client does not need a follow-up refresh."
+        )
+    )
+    async def complete_lesson(
+        self,
+        repo_id: str,
+        lesson_id: str,
+        time_spent_seconds: int = 0,
+        persona: Optional[str] = None,
+        module_id: Optional[str] = None,
+    ) -> CompleteLessonResult:
+        return await run_in_threadpool(
+            _complete_lesson_sync, repo_id, lesson_id, time_spent_seconds, persona, module_id
+        )
+
+
+schema = strawberry.Schema(query=Query, mutation=Mutation)

apps/api/src/main.py

@@ -119,6 +119,14 @@ async def lifespan(app: FastAPI):
 app.include_router(learning.router, prefix="/api/learning", tags=["learning"])
 app.include_router(platform.router, prefix="/api/platform", tags=["platform"])
 
+# GraphQL, additive rather than a migration: every REST route above still works.
+# Chat deliberately stays REST/SSE -- see src/api/graphql/schema.py.
+from strawberry.fastapi import GraphQLRouter  # noqa: E402
+
+from src.api.graphql.schema import schema as graphql_schema  # noqa: E402
+
+app.include_router(GraphQLRouter(graphql_schema), prefix="/graphql", tags=["graphql"])
+
 
 # Health check endpoint
 @app.get("/health")