# MDA Learning & Assessment Domain Model

Owner: **Developer C** — Student Learning & Assessment Journey
Status: **Approved domain model** (no application code, no database tables — tables are a later phase)
Sources: `Documents/student/**` (15 modules, 60 feature groups), `Documents/parent/**`, `Documents/training_institute/**`, `Documents/super_admin/**` (assessment, SRS, curriculum, target exam, exam hall modules)

> Scope note: this model describes **concepts, relationships, rules, and data flows** only.
> Per the multi-database architecture, everything in this model that is *transactional student state*
> (progress, attempts, answers, SRS, bookmarks, notes, study plans, target exams, XP/streaks)
> belongs to the **`learning`** domain database. Catalog content, identity, and billing are
> consumed via `api_hub` — never joined across databases.

---

## 1. Student Learning Journey

```
Student ──access──▶ Course ──▶ Subject/Topic ──▶ Lesson ──▶ Content ──▶ Activity ──▶ Progress
```

### 1.1 The journey, step by step

1. **Student** (Identity) authenticates and holds an **Access Grant** (trial, subscription,
   purchased course, or institute assignment).
2. **Access** is checked against the **Catalog** hierarchy:
   - Academic: `Board → Grade → Subject → Course`
   - Professional: `Category → Sub Category → Course`
3. **Course** contains **Lessons** (ordered units). Each lesson maps to a **Topic/Chapter**
   in the curriculum (topics carry importance: high/medium/low, and prerequisite links).
4. **Content** is the consumable unit inside a lesson:
   - Video tutorial (with timestamp bookmarks, notes)
   - Podcast episode (with transcript where available)
   - Article / read-through (with highlights)
   - Resource (PDF, worksheet, formula sheet)
   - Flashcard deck (auto-generated from video or custom)
   - Mind map
5. **Activity** is anything the Student *does* with content:
   - Watch / listen / read (progress + resume position)
   - Bookmark, note, highlight
   - Take a quiz / exam / mock / past paper (attempt + answers)
   - Study flashcards (SRS review)
   - Complete a study-plan task
6. **Progress** is the durable outcome of activity:
   - Per-content status (not started / in progress / complete)
   - Per-course completion percentage
   - Time spent (per course, subject, day, week)
   - Topic mastery (derived from assessment + practice performance)
   - Streaks / consistency (feeds gamification)

### 1.2 Concept map (relationships, not tables)

```
Student (identity)
 ├── AccessGrant ──────────────▶ Course (catalog)
 │      (trial | subscription   │
 │       | purchase | institute) ├── Lesson ──▶ Topic (curriculum)
 │                                │        ├── Content (video | podcast | article | resource)
 │                                │        ├── FlashcardDeck ──▶ Card
 │                                │        └── MindMap
 │                                └── Assessment (quiz | exam | mock | past paper)
 │                                         └── Question (question bank, catalog)
 │
 ├── ContentProgress ──▶ Content        (status, resume position, time spent)
 ├── Bookmark ──▶ Content               (optional timestamp)
 ├── Note ──▶ Content | Course
 ├── Highlight ──▶ Article (text span)
 ├── Attempt ──▶ Assessment
 │      └── Answer ──▶ Question        (state, marks, explanation ref)
 ├── SRSItem ──▶ Card | Concept        (interval, due date, mastery)
 ├── TargetExam ──▶ Subject/Topic map  (date, target score, importance)
 │      ├── StudyPlan ──▶ PlanTask
 │      └── Prediction (score, confidence, accuracy history)
 ├── FlashcardDeck (owned) ──▶ Card
 ├── Streak / XP / Badge state
 └── ActivityEvent (append-only log of everything above)
```

---

## 2. Enrollment / Access Rules

### 2.1 When does a student gain access?

| Grant type | When access starts | What it unlocks |
|---|---|---|
| **Free trial** | On registration/onboarding (7-day full access) | All academic content for the trial scope |
| **Academic subscription** | Immediately on **successful payment** (activation) | All content of the plan's selected **subjects** (grade-wise + subject-wise pricing) |
| **Subscription upgrade / add subject** | Immediately (difference paid where applicable) | Expands to the new plan/subjects |
| **Professional course purchase** | Immediately on successful payment | Full access to that **one course**, added to the Student's library |
| **Institute assignment** (Training Institute) | When the institute enrolls/assigns the student (bulk import or individual) | Content assigned by the institute (bulk license) |
| **Sample content** | Always, no grant needed | Limited preview only (e.g., first 2 minutes of a video) |

### 2.2 What grants access?

- An **active subscription** (plan + selected subjects) — the single source of truth for
  academic access.
- A **completed purchase** of a professional course.
- An **active trial** period.
- An **institute enrollment/assignment** (bulk license).
- Access is *checked at content-open time* against the subscription status; locked content
  shows an "Upgrade to unlock" prompt.

### 2.3 What removes access?

- **Cancellation** — stops future renewals; access is **retained until the end of the paid period**.
- **Lapse / expiry** — period ends without renewal → access ends.
- **Failed renewal** → **grace period** (length set by platform); if payment is not fixed,
  access is **suspended** when the grace period ends.
- **Reactivation** restores access immediately.
- **Dropping a course** (student-initiated, with confirmation) removes it from "My courses"
  but **preserves prior progress** for re-enrollment.
- **Account deletion** (with cooling-off period) — all learning data removed per privacy rules.

### 2.4 What happens when a subscription ends?

- Access to subscription-gated content ends at period end (or grace-period end).
- **Progress, attempts, results, notes, bookmarks are NOT deleted** — they are retained as
  permanent records (see §5) and remain visible in history.
- **Downloads/offline content**: access to downloaded items is subject to the platform's
  download security & expiry rules (offline module).
- **Purchased professional courses** remain in the library (purchase is not a subscription).
- **Re-enrollment** restores access and prior progress.
- Renewal **restores access** and the status returns to active.

**OPEN DECISION — D1:** After a subscription lapses, can the student still *view* their own
past results/notes (read-only history) or is the entire learning area locked? (Docs imply
history is retained; the exact read-only surface is unspecified.)

**OPEN DECISION — D2:** Does a lapsed subscription pause or reset the study streak and
SRS due queue? (Streak rules mention a grace rule; interaction with subscription lapse is
unspecified.)

**OPEN DECISION — D3:** Is access for institute-assigned students governed by the institute's
bulk license expiry, and what happens to student progress when the institute license ends?

**OPEN DECISION — D4:** Trial scope — "7-day full access" — does full access include
professional courses, or only academic content?

---

## 3. Progress Model

### 3.1 What counts as progress?

Progress is recorded at the **content level** and aggregated upward:

- **Per-content status**: `not started → in progress → complete`
  (videos, podcast episodes; lessons complete when their required content is done).
- **Course progress %** = percentage of **required** content completed.
  Optional content does **not** block completion.
- **Time spent** — accumulated from active study sessions; broken down per course,
  subject, day, week.
- **Topic mastery** — derived (not directly recorded) from assessment accuracy +
  practice performance per topic; drives strengths/weaknesses, SRS, and AI features.
- **Study-plan task completion** — planned tasks marked done update plan progress.
- **SRS reviews** — items reviewed and their interval/mastery updates.

### 3.2 What is completion?

- **Video/episode complete** = watched/listened to the end **or past a completion threshold**.
- **Lesson complete** = its required content is complete.
- **Course complete** = all **required** content done → status `completed`;
  completion feeds **certificates** and analytics.
- **Re-watching a completed item does not revert its status.**
- **Exam/quiz complete** = submitted (manually or auto-submit at time expiry);
  unanswered questions are recorded as *unanswered*, not zero-marked.

**OPEN DECISION — D5:** The exact completion threshold for videos (e.g., 90% watched?
must reach the final frame? minimum watch-time?) is not specified in the docs.

**OPEN DECISION — D6:** Are certificates issued automatically on course completion, and
what is their format/verification? (Docs say completion "feeds certificates" but the
certificate model itself is not specified.)

### 3.3 What is time spent?

- Accumulated from **active study sessions** (watching, listening, reading, practicing).
- Dimensions: total, per course, per subject, per day, per week; trends and period comparison.
- Tracked on both web and mobile; mobile time is included.
- Time spent is an **input to AI score prediction and the study planner**.

**OPEN DECISION — D7:** Does background audio playback (mobile) count as study time while
the app is backgrounded? What is the inactivity timeout that ends a "session"?

### 3.4 What is a resume position?

- A **saved playback position per content item** (per video, per episode).
- Saved on pause/close; resume returns the student to the saved position.
- "Continue learning" / "Continue where you left off" = the next incomplete item in the
  course, entered at its saved position.
- **Synchronized across web and mobile** for the same account.
- Offline activity syncs back when online (sync queue, in order; conflicts resolved
  **latest-change-wins** with merge where possible).

### 3.5 Bookmarks, notes, highlights (progress-adjacent personal state)

- **Timestamp bookmark** — tied to a video + timestamp, optional note; private; does not
  affect completion.
- **Content bookmark ("Saved")** — any content item bookmarked once; filterable by course
  and type; syncs across devices.
- **Personal note** — attached to a content item or course; autosave; character limit;
  private; syncs across devices.
- **Highlight** — text span in an article + color + optional note; private.
- All four are **private to the student**, event-logged, and survive course drop
  (they reference catalog items, not the enrollment).

---

## 4. Assessment Model

### 4.1 Assessment (the container)

Assessment types in the domain:

| Type | Characteristics | Retakes |
|---|---|---|
| **Adaptive exam** (video-wise / topic) | AI selects next question from subject/topic pool; difficulty adjusts to correctness; fixed question count or time; ability estimate updated per answer (hidden from student) | Per exam retake rules |
| **Standard exam** | Fixed question set, timer, auto-submit at expiry, manual early submit with unanswered confirmation | Per exam retake rules |
| **Practice quiz** | Shorter; modes: timed / untimed / **focus** (auto-targets weak topics); optional immediate feedback | **Unlimited** |
| **Daily practice set** | Generated once per day; adapts to weak topics; completion increments streak | Once per day |
| **Mock exam** | Real conditions: fixed time, real question mix, **no immediate feedback**, single submission within the configured window | Single per window |
| **Past paper** | Browse/preview/download (where allowed) + marking scheme; self-assessed or attempted | n/a (reference material) |
| **Exam Hall simulation** (admin-configured) | Timed, no pausing/hints, realistic scoring, stress training | Per schedule |

Assessment configuration (from Super Admin): passing score, retake rules, adaptive
parameters, exam pattern (question counts, marks, duration), AI grading for
short-answer/essay, per-question explanations.

### 4.2 Question

- Lives in the **question bank** (Catalog domain — authored/curated by Super Admin,
  including AI-generated questions from video content).
- Types: multiple choice, multiple select, true/false, fill-in-the-blank (text match with
  tolerance), numeric (match with tolerance), short answer (rubric-based), essay.
- Attributes: difficulty tag, Bloom's taxonomy alignment, subject/topic mapping,
  marks, correct answer(s), explanation, related-content links.
- Questions are **referenced** by assessments; the learning domain never mutates them.

### 4.3 Attempt

- One **Attempt** = one student sitting one assessment.
- States: `in progress → submitted (auto or manual) → graded → result published`.
- Records: start time, submission time, time taken, mode (adaptive/timed/untimed/focus),
  per-question navigation state (answered / flagged / unanswered), auto-submit flag.
- **Unanswered questions are recorded as unanswered** (distinct from wrong).
- Practice quizzes create a **new attempt per retake** — history retains all attempts.
- Mock exams: single submission within the configured window.
- Offline attempts (offline quiz/exam practice) sync and are graded when back online.

### 4.4 Answer

- One **Answer** per (Attempt, Question).
- Records: the student's raw response, state (answered / unanswered / flagged),
  marks awarded, correctness, and (for review) the correct answer.
- Auto-graded types (MCQ, multi-select, T/F, fill-in, numeric) grade **immediately**.
- Short answer / essay grade via **AI grading** (rubric-based) — result available after grading.

### 4.5 Score / Result

- **Overall score** (marks + percentage), **pass/fail** against the configured pass mark,
  **time taken**, **section-wise breakdown**.
- **Results history** — all attempts retained, listable and re-viewable.
- **Mock exam result** adds: time-management analysis (time per section vs available),
  **readiness score** for the linked target exam, topics needing urgent revision,
  recommended study focus, mock-score trend over time.
- **Quiz result**: score %, per-question correct/incorrect + correct answer + brief
  explanation; updates topic practice statistics (attempts, average score).

### 4.6 Explanation & wrong-answer review

- Every question carries a **detailed explanation**: why the correct answer is correct,
  why the student's answer was wrong, reference to the relevant concept/topic, and a
  **link to related learning content** (video/article) for revision.
- Available immediately for auto-graded questions; after grading for short answers.
- Accessible from the results page **and** the results history.
- **Wrong answers feed**: weak-topic identification, focus-mode quiz selection, SRS
  resurfacing, common-error-pattern insights, and the AI Study Companion.

**OPEN DECISION — D8:** Is AI grading of short answers/essays final, or is there a
human-review/override path (e.g., student appeal or admin re-grade)? If re-graded, does
the attempt's score history keep both values?

**OPEN DECISION — D9:** Retake policy defaults — max attempts per exam, cooldown between
retakes, and whether the *best* or *latest* attempt counts for analytics/mastery.

**OPEN DECISION — D10:** Do practice quiz and daily-set results count toward topic
mastery and the AI score prediction, or only formal exams/mocks? (Docs say practice
feeds weak-topic identification; weighting vs formal exams is unspecified.)

---

## 5. Learning History

### 5.1 Events MDA must remember

Every learning action is event-logged (item + timestamp + account) and audit-logged.
The full event vocabulary:

**Access/enrollment:** trial activated, subscribed, upgraded, subject added, course
purchased, enrolled, dropped, re-enrolled, cancelled, grace entered/ended, reactivated,
renewed.

**Content consumption:** playback start/pause/complete/speed-change, episode
start/pause/complete, video/episode status change, resume position saved, download
started/completed/deleted, offline sync started/completed, conflict detected/resolved.

**Personal study state:** bookmark add/edit/remove, note create/edit/delete,
highlight create/edit/remove, flashcard deck created, card added/edited/deleted,
flashcard session started/ratings/completed, SRS item reviewed/interval updated,
mind map created/shared.

**Assessment:** exam/quiz/mock start, each answer, flag, timer events, submission
(manual/auto), grading completed, result viewed, retake started, review viewed,
past paper viewed/downloaded.

**Planning & goals:** target exam created/edited/paused/archived, subject/topic mapped,
priority/time-split set, study plan generated/regenerated, plan task completed/rescheduled,
check-in prompted/acknowledged/adjusted, actual result recorded, prediction computed/updated.

**Engagement:** streak incremented/reset, daily set completed, points awarded,
badge earned, recommendation generated/acted on, activity log viewed.

### 5.2 Permanent records (must never be lost)

- **Enrollment history** (all grants, activations, lapses, cancellations) — needed for
  billing disputes and access forensics.
- **All attempts and answers** — the student's academic record; feeds results history,
  analytics, prediction accuracy, and institute/parent reporting.
- **Graded results and scores** (including mock results and recorded actual exam results).
- **Course completion records** — feed certificates; completion is a permanent fact.
- **Certificates** (once issued).
- **Consent/audit trail** — audit logs of access and actions (account + item + timestamp).
- **Prediction accuracy history** (predicted vs actual per target exam).

### 5.3 Merely activity events (log-level, may be aggregated/retired)

- Playback start/pause/speed-change ticks, seek events, resume-position saves.
- Browsing events (course viewed, plan viewed/compared, dashboard viewed, results viewed).
- Bookmark/note/highlight create-edit-remove churn (the *current state* is permanent;
  the edit history is activity).
- Reminder sent, countdown viewed, activity-log viewed.
- Sync queue item added/retried/cleared.
- These feed the **activity log** (chronological, read-only, filterable by type/date)
  and analytics; they do not need to be retained individually forever.

**OPEN DECISION — D11:** Retention policy — how long are raw activity events kept before
aggregation/purging, and is the student-facing activity log bounded (e.g., last 90 days)?

**OPEN DECISION — D12:** Data portability/export — the privacy module mentions data
portability; which learning-history records are included in an export?

---

## 6. Dependencies

### 6.1 From **Catalog** (read-only references — never mutated by learning)

- Curriculum hierarchy: Boards, Grades, Subjects, Categories, Sub Categories,
  Topics/Chapters (with importance + prerequisite links).
- Courses, lessons, and content items (video/podcast/article/resource metadata;
  media binaries live in object storage).
- **Question bank**: questions, types, difficulty, Bloom's tags, correct answers,
  explanations, related-content links.
- Past papers (subject/year/exam type, sections, marking schemes, download permission).
- Exam/quiz definitions and configuration (pass mark, retake rules, adaptive config,
  exam pattern, AI grading config).
- SRS platform configuration (intervals, Ebbinghaus parameters, recall adjustment
  rules, mastery graduation rules).
- Grade-level **benchmarks** per subject (for benchmark comparison).
- Flashcard auto-generation source (video key concepts), community deck library.
- Target exam types/templates (school, board, competitive, professional).

### 6.2 From **Identity**

- The Student account (all roles), authentication/session, minor status + **parent
  consent** (required for minors).
- Parent ↔ child account linking (drives parent monitoring access to this domain's data).
- Institute enrollment/roster (which students an institute's license covers).
- Account deletion / cooling-off (triggers learning-data deletion).
- Notification preferences (quiet hours, reminder opt-ins).

### 6.3 From **Billing**

- Subscription state: plan, selected subjects/courses, status (active/expiring/lapsed),
  expiry date, auto-renewal flag, next renewal date/amount.
- Trial state (start, 7-day window, scope).
- Purchases: professional course ownership.
- Payment outcomes (success/failure/pending) — **activation happens on successful payment**.
- Grace period state (entered, ends, payment fixed).
- Bulk licenses (institute).
- **The learning domain never stores money or payment data** — it consumes an
  "access is granted/revoked" signal and the subscription scope.

**Cross-domain rule:** no cross-database joins. Learning queries reference
`identity_billing.users.id` and catalog IDs as plain indexed columns; anything needing
both billing and learning data is merged in PHP or exposed via an `analytics` aggregate.

---

## 7. Downstream Consumers (what this domain feeds)

| Consumer | What it consumes from this domain |
|---|---|
| **Reporting / Analytics** (analytics DB, via queued jobs) | Attempts, answers, scores, time spent, completion, streaks, engagement events → performance rollups, parent/institute dashboards, funnel analytics |
| **Parent dashboard** | Real-time activity feed, course progress, time spent, streak, assessment scores, performance trends, upcoming tests/deadlines |
| **Training Institute** | Student progress, assessment results, completion certificates, engagement reports, path completion/performance |
| **SRS** | Wrong answers, flashcard recall ratings, concept mastery → due-review queue, intervals, retention estimates |
| **AI score prediction** | Historical exam/practice performance, video completion rates, time per topic, accuracy trends, study consistency, current mastery, exam difficulty, time remaining |
| **AI study planner** | Prediction + target gap, weak topics, available time, exam dates, plan adherence |
| **AI Study Companion** | Strengths/weaknesses, error patterns, learning velocity, mood context, chapter summaries |
| **Gamification** | Points (videos, quizzes, exams, streaks, content), badges (milestones, streaks, mastery, challenges), leaderboards, challenges |
| **Notifications** | Study reminders, streak-preservation alerts, due-review reminders, achievement notifications, renewal/grace alerts |
| **Recommendations** | "What to study next", resource recommendations, improvement suggestions |
| **Benchmarks** | Student accuracy vs grade-level benchmarks (percentile, gap) |

---

## 8. Open Business Decisions (consolidated)

| ID | Decision | Context |
|---|---|---|
| **D1** | Read-only access to own history after subscription lapse? | §2.4 |
| **D2** | Does lapse pause/reset streaks and SRS due queue? | §2.4 |
| **D3** | Institute license expiry → student access & progress fate | §2.3 |
| **D4** | Trial scope: academic only or includes professional courses? | §2.1 |
| **D5** | Exact video/episode completion threshold | §3.2 |
| **D6** | Certificate issuance model (auto? format? verification?) | §3.2 |
| **D7** | Background audio as study time; session inactivity timeout | §3.3 |
| **D8** | AI grading finality / human re-grade path | §4.5 |
| **D9** | Retake defaults (max attempts, cooldown, best-vs-latest for analytics) | §4.3 |
| **D10** | Weighting of practice/daily results vs formal exams for mastery & prediction | §4.5 |
| **D11** | Raw activity-event retention & activity-log window | §5.3 |
| **D12** | Data portability export scope for learning history | §5.3 |

---

## Appendix A — Domain placement (per multi-DB architecture, no tables)

- **`learning` DB owns (this model's transactional state):** content progress & resume
  positions, attempts, answers, SRS schedules, XP/streaks/badges, bookmarks, notes,
  highlights, study plans, target exams + predictions, AI companion state, activity events.
- **`catalog` DB owns (referenced, read-only):** curriculum hierarchy, courses/lessons/
  content metadata, question bank, past papers, exam definitions, SRS platform config,
  benchmarks.
- **`identity_billing` DB owns (referenced, read-only):** student accounts, parent links,
  consents, subscriptions, trials, purchases, grace state, bulk licenses.
- **`engagement` DB owns (fed by events):** notifications, study groups, live sessions,
  leaderboards/challenges, referral events.
- **`analytics` DB owns (fed via queued jobs):** all aggregates for reporting — never
  read back by transactional domains.