Merge pull request #1037 from robertocarlous/feat/ai-learning-path-recommender

Author: Anuoluwapo25

server/src/controllers/recommendations.controller.ts

@@ -1,4 +1,4 @@
-import { type Response } from "express"
+import { type Request, type Response } from "express"
 import { logger } from "../lib/logger"
 import { type AuthRequest } from "../middleware/auth.middleware"
 import {
@@ -8,6 +8,11 @@ import {
 
 const log = logger.child({ module: "recommendations" })
 
+function parseLimit(value: unknown): number {
+	const limitParam = typeof value === "string" ? parseInt(value, 10) : 4
+	return !isNaN(limitParam) && limitParam > 0 ? limitParam : 4
+}
+
 export const getLearnerRecommendations = async (
 	req: AuthRequest,
 	res: Response,
@@ -19,10 +24,7 @@ export const getLearnerRecommendations = async (
 			return
 		}
 
-		const limitParam =
-			typeof req.query.limit === "string" ? parseInt(req.query.limit, 10) : 4
-		const limit = !isNaN(limitParam) && limitParam > 0 ? limitParam : 4
-
+		const limit = parseLimit(req.query.limit)
 		const recommendations = await getRecommendations(walletAddress, limit)
 
 		res.status(200).json({ data: recommendations })
@@ -32,6 +34,27 @@ export const getLearnerRecommendations = async (
 	}
 }
 
+export const getRecommendationsForAddress = async (
+	req: Request,
+	res: Response,
+): Promise<void> => {
+	try {
+		const address = req.params.address
+		if (!address) {
+			res.status(400).json({ error: "address is required" })
+			return
+		}
+
+		const limit = parseLimit(req.query.limit)
+		const recommendations = await getRecommendations(address, limit)
+
+		res.status(200).json({ data: recommendations })
+	} catch (error) {
+		log.error({ err: error }, "Failed to get recommendations for address")
+		res.status(500).json({ error: "Internal server error" })
+	}
+}
+
 export const engageRecommendation = async (
 	req: AuthRequest,
 	res: Response,

server/src/db/migrations/026_course_prerequisites_table.sql

@@ -0,0 +1,15 @@
+-- ============================================================
+-- Migration 026: Course prerequisite path rules (for recommendations)
+-- ============================================================
+
+-- Declares the recommended learning path between courses, e.g. Soroban
+-- requires Stellar Basics first. Distinct from the hard enrollment gate in
+-- courses.prerequisites — this table drives recommendation scoring/gating.
+CREATE TABLE IF NOT EXISTS course_prerequisites (
+    course_slug   TEXT NOT NULL REFERENCES courses(slug) ON DELETE CASCADE,
+    requires_slug TEXT NOT NULL REFERENCES courses(slug) ON DELETE CASCADE,
+    PRIMARY KEY (course_slug, requires_slug)
+);
+
+CREATE INDEX IF NOT EXISTS idx_course_prerequisites_course_slug
+    ON course_prerequisites (course_slug);

server/src/db/migrations/026_course_prerequisites_table.undo.sql

@@ -0,0 +1,5 @@
+-- ============================================================
+-- Undo Migration 026: Course prerequisite path rules
+-- ============================================================
+
+DROP TABLE IF EXISTS course_prerequisites;

server/src/lib/api-response-cache.ts

@@ -8,20 +8,28 @@ import Redis from "ioredis"
  * - /api/leaderboard: 300s
  * - /api/treasury/stats: 60s
  * - /api/courses: 600s
+ * - /api/recommendations/:address: 60s
  *
  * Cache keys are namespaced per endpoint type, and include the full URL
- * (path + query) to ensure distinct responses are cached separately.
+ * (path + query) to ensure distinct responses are cached separately. Since
+ * the learner address lives in the URL path, recommendations are naturally
+ * cached per learner.
  *
  * When `REDIS_URL` is not configured, this falls back to an in-process memory
  * cache (useful for local dev + unit tests).
  */
 
-export type ApiCacheType = "leaderboard" | "treasury_stats" | "courses"
+export type ApiCacheType =
+	| "leaderboard"
+	| "treasury_stats"
+	| "courses"
+	| "recommendations"
 
 export const API_RESPONSE_CACHE_TTLS: Record<ApiCacheType, number> = {
 	leaderboard: 300,
 	treasury_stats: 60,
 	courses: 600,
+	recommendations: 60,
 }
 
 const PREFIX = "learnvault:api-cache:"

server/src/routes/recommendations.routes.ts

@@ -1,16 +1,53 @@
 import { Router } from "express"
 import {
 	getLearnerRecommendations,
+	getRecommendationsForAddress,
 	engageRecommendation,
 } from "../controllers/recommendations.controller"
-import { createRequireAuth } from "../middleware/auth.middleware"
+import { apiResponseCache } from "../middleware/api-response-cache.middleware"
+import {
+	createOptionalAuth,
+	createRequireAuth,
+} from "../middleware/auth.middleware"
 import { type JwtService } from "../services/jwt.service"
 
 export const createRecommendationsRouter = (jwtService: JwtService): Router => {
 	const router = Router()
 	const authMiddleware = createRequireAuth(jwtService)
+	const optionalAuth = createOptionalAuth(jwtService)
 
 	router.get("/recommendations", authMiddleware, getLearnerRecommendations)
+
+	/**
+	 * @openapi
+	 * /api/recommendations/{address}:
+	 *   get:
+	 *     tags: [Recommendations]
+	 *     summary: Get personalized course recommendations for a learner
+	 *     description: Returns a ranked list of recommended next courses with a human-readable reason per item, based on completed courses, path rules, and co-occurrence with similar learners.
+	 *     parameters:
+	 *       - in: path
+	 *         name: address
+	 *         required: true
+	 *         schema: { type: string }
+	 *       - in: query
+	 *         name: limit
+	 *         schema: { type: integer }
+	 *     responses:
+	 *       200:
+	 *         description: Ranked recommendations
+	 *       400:
+	 *         $ref: '#/components/responses/BadRequestError'
+	 *       500:
+	 *         $ref: '#/components/responses/InternalServerError'
+	 */
+	router.get(
+		"/recommendations/:address",
+		optionalAuth,
+		apiResponseCache("recommendations"),
+		getRecommendationsForAddress,
+	)
+
 	router.post("/recommendations/engage", authMiddleware, engageRecommendation)
 
 	return router

server/src/services/credential.service.ts

@@ -1,5 +1,6 @@
 import { pool } from "../db/index"
 import { milestoneStore } from "../db/milestone-store"
+import { invalidateApiResponseCacheType } from "../lib/api-response-cache"
 import { pinJsonToIPFS } from "./pinata.service"
 import {
 	stellarContractService,
@@ -65,6 +66,12 @@ async function mintCertificateIfComplete(
 			 VALUES ($1, $2, $3, $4)`,
 			[mintResult.tokenId, scholarAddress, courseId, tokenUri],
 		)
+
+		// New completion invalidates cached recommendations so the learner's
+		// next fetch reflects their updated history.
+		await invalidateApiResponseCacheType("recommendations").catch(() => {
+			/* Non-fatal */
+		})
 	}
 
 	return {