Adaptive Learning Paths (prerequisites, mastery-based progression) & Smart Recommendations

### Summary

Introduce **Adaptive Learning Paths** so students unlock content based on mastery, not just linear order. Instructors define **prerequisites** (courses/lessons/quizzes), **rules** (min score, completion %, time limits), and **skills/tags**. The system computes a personalized **“Next best step”** and shows recommendations on the dashboard.

### Problem / Motivation

* Current flow appears mostly linear. Many LMS users expect:

* Prerequisite gating (e.g., “Score ≥ 80% on Quiz 1 to unlock Lesson 2”).
* Personalized recommendations (e.g., “Practice questions on Algebra → Difficulty: Medium”).
* Clear paths for different roles (self-paced tracks, instructor-curated sequences).
* This improves completion rates, reduces churn, and makes progress tracking more actionable.

### Goals

* Let instructors create **graph-based paths** with **DAG** validation (no cycles).
* Enforce **unlock rules** at runtime using existing progress/quiz data.
* Show each learner a **My Path** view with progress, locked/unlocked nodes, and **Next best step**.
* Provide **recommendations** based on recent performance, difficulty, and skills.

### Non-Goals

* Full ML personalization in v1 (can add later).
* External standards (SCORM/xAPI) in v1.

---

## High-Level Design

### Data Model (MongoDB)

New collections (suggested):

* `learning_paths`: `{ _id, title, description, owner_id, is_active, created_at }`
* `path_nodes`: `{ _id, path_id, type: "course"|"lesson"|"quiz", ref_id, position, skills: [string], difficulty: "easy"|"medium"|"hard" }`
* `prerequisites`: `{ _id, node_id, requires_node_id, rules: { min_score?, min_completion_pct?, within_days? } }`
* `recommendation_snapshots`: `{ _id, user_id, items: [{ node_id, reason, score }], generated_at }`

Indexes:

* `path_nodes(path_id)`, `prerequisites(node_id)`, `recommendation_snapshots(user_id, generated_at)`

### Backend (Django + DRF)

* **Rule evaluation service**:

* On progress/quiz updates, recompute unlock state for affected nodes.
* Use Redis for caching `{user_id,node_id} → unlocked:boolean`.
* Validate DAG on create/update (detect cycles).
* **Endpoints (v1)**:

* `GET /api/paths/` – list active paths (admin/instructor scoped).
* `POST /api/paths/` – create path; body includes nodes and prerequisites.
* `GET /api/paths/{id}/nodes/` – list nodes with lock/unlock state for the current user.
* `GET /api/paths/{id}/recommendations/?user_id=current` – top N recommended nodes.
* `POST /api/paths/{id}/validate/` – returns DAG validation result & rule conflicts.
* **Signals/Tasks**:

* On `progress.updated` and `quiz.result.created`, enqueue recompute (optional Celery with Redis).
* **OpenAPI (excerpt)**

```yaml
paths:
/api/paths/{id}/recommendations/:
get:
summary: Get personalized recommendations for current user
parameters:
- in: path
name: id
schema: { type: string }
required: true
responses:
"200":
description: OK
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
node_id: { type: string }
title: { type: string }
reason: { type: string }
score: { type: number, format: float }
```

### Frontend (Angular)

* New **My Path** page: `/my-path/:pathId`

* Graph/list hybrid UI showing nodes (locked/unlocked), progress chips, and required rules.
* “Next best step” card at top with quick-start action.
* Components:

* `PathOverviewComponent`, `PathNodeItemComponent`, `RecommendationCardComponent`.
* Guards:

* `PrereqGuard` to block navigation to locked routes with a friendly toast explaining required criteria.
* Services:

* `PathService` (paths/nodes/prereqs), `RecommendationService`.
* UX details:

* Show reasons *why* something is locked (e.g., “Need ≥80% on Quiz 2”).
* Accessible labels, keyboard navigation, and screen-reader friendly status for lock state.

### DevOps / CI/CD

* Feature flag: `ADAPTIVE_PATHS_ENABLED` (env + ConfigMap).
* Optional worker (Celery) deployment using existing Redis.
* Seed script updates: create sample path with 5–7 nodes and varied prerequisites.

### Security & Permissions

* Instructors can CRUD paths for their courses.
* Students read-only; only their own unlock states and recommendations.
* Validate references (`ref_id`) to existing course/lesson/quiz docs.

### Performance

* Cache unlock states per user/node in Redis; TTL invalidate on relevant events.
* Batch queries when computing recommendations.

### Analytics / Metrics

* Track funnel: **Nodes unlocked → Started → Completed**.
* Track path completion time, retries after failing a rule, recommendation CTR.

### Accessibility

* Ensure lock/unlock states have ARIA annotations and non-color indicators.

---

## Acceptance Criteria

* [ ] Instructor can create a path, add nodes, and define prerequisites in UI or via API.
* [ ] System rejects cycles and conflicting rules with a clear error.
* [ ] Student sees a **My Path** view with locked/unlocked nodes and reasons.
* [ ] Route guard prevents access to locked content and displays actionable guidance.
* [ ] **Next best step** renders within 200ms (when cached).
* [ ] Recommendations update after quiz submissions/progress changes.
* [ ] Seed data includes one demo path; e2e tests cover lock/unlock.
* [ ] Feature is toggleable via `ADAPTIVE_PATHS_ENABLED`.

---

## Rollout Plan

1. **Behind flag** in staging → instructor beta → all users.
2. Migrate seed and sample content.
3. Monitor metrics & logs; tune rules and caching.
4. Document authoring best practices (skills, difficulty, rules).

### Risks & Mitigations

* **Complex graphs / infinite loops** → DAG validation on save.
* **Over-restrictive rules** → Preview/validate mode before publish.
* **Cache staleness** → Event-driven invalidation on progress/quiz write.

### Open Questions

* Do we need **time-boxed** rules (e.g., “complete within 7 days of enrollment”) in v1?
* Should recommendations consider **engagement** (last active date) versus mastery only?
* Do we expose **skill-level** metadata in public APIs for 3rd-party clients?

---

## Tasks

**Backend**

* [ ] Schemas: `learning_paths`, `path_nodes`, `prerequisites`, `recommendation_snapshots`
* [ ] DAG validation + rule engine
* [ ] Endpoints + serializers + perms
* [ ] Redis caching; optional Celery worker
* [ ] OpenAPI updates + unit tests

**Frontend**

* [ ] New routes and components
* [ ] Prereq route guard + toasts
* [ ] Services & state management
* [ ] Accessibility pass
* [ ] Cypress e2e

**DevOps/Docs**

* [ ] Feature flag wiring (env, ConfigMap, README)
* [ ] Seed data & demo path
* [ ] Screenshots/gifs for README
* [ ] Observability (logs/metrics dashboards)

---

**Value**
This adds a high-impact, widely expected LMS capability using the current MAD stack primitives (MongoDB, Angular, Django, Redis) and fits neatly into existing CI/CD and PWA setup. It’s incremental (flagged), testable, and unlocks deeper personalization later (ML-powered ranking).