System Design Document (SDD): Learner Adaptive Loop

1. System Architecture & Flows

The Learner Adaptive Loop runs on a decoupled layer structure separating the storage, diagnostic inference, and planning logic.

graph TD
    Profile[Learner Profile Table] -->|Input Priors| ModelEngine[Model Compiler]
    Evidence[evd_evidence Table] -->|Assessments & Behaviors| ModelEngine
    ModelEngine -->|Compile| LearnerModel[Learner Model API]
    
    LearnerModel -->|Current State| NeedEngine[Need Inference Engine]
    Goal[Goal Model Target] -->|Target State| NeedEngine
    Graph[Competency Prerequisite Graph] -->|Prerequisites| NeedEngine
    
    NeedEngine -->|Generate| NeedsModel[Learning Need Model Table]
    
    NeedsModel -->|Prioritized Needs| PlanEngine[Planning Engine]
    Catalog[Content Catalog / Course Index] -->|Resource Matching| PlanEngine
    
    PlanEngine -->|Generate| Plan[Learning Plan Table]

---

2. Database Schema Design

Three new relational SQLite tables are introduced:

lrn_learner_profiles

Stores the student's self-reported characteristics and preferences.

CREATE TABLE lrn_learner_profiles (
  student_id        TEXT NOT NULL PRIMARY KEY REFERENCES iam_users(id) ON DELETE CASCADE,
  grade             INTEGER NOT NULL,
  goal              TEXT NOT NULL,
  target_competition TEXT NOT NULL,
  prior_experience  TEXT NOT NULL, -- JSON array of strings e.g. ["Scratch", "Python"]
  available_time    TEXT NOT NULL, -- JSON object: { minutesPerDay: number, daysPerWeek: number }
  preferences       TEXT NOT NULL, -- JSON object: { projectBased: boolean, codingExercises: boolean, challengeLevel: string }
  created_at        TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

lrn_learning_needs

Stores the results of the dynamic diagnostic run.

CREATE TABLE lrn_learning_needs (
  id                TEXT NOT NULL PRIMARY KEY,
  student_id        TEXT NOT NULL REFERENCES iam_users(id) ON DELETE CASCADE,
  type              TEXT NOT NULL CHECK (type IN ('knowledge_gap', 'prerequisite_gap', 'practice_need', 'retention_need', 'insufficient_evidence', 'transfer_need', 'goal_specific_need')),
  target_skill_id   TEXT REFERENCES cur_skills(id) ON DELETE SET NULL,
  priority          TEXT NOT NULL CHECK (priority IN ('low', 'medium', 'high')),
  severity          REAL NOT NULL, -- normalized 0.0 - 1.0
  goal_relevance    REAL NOT NULL, -- normalized 0.0 - 1.0
  confidence        REAL NOT NULL, -- normalized 0.0 - 1.0
  reason            TEXT NOT NULL,
  supporting_evidence TEXT NOT NULL, -- JSON array of evidence IDs or strings
  created_at        TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE INDEX idx_needs_student ON lrn_learning_needs(student_id);

lrn_learning_plans

Stores the actionable timeline and schedules generated by the planner.

CREATE TABLE lrn_learning_plans (
  id                TEXT NOT NULL PRIMARY KEY,
  student_id        TEXT NOT NULL REFERENCES iam_users(id) ON DELETE CASCADE,
  goal              TEXT NOT NULL,
  duration_weeks    INTEGER NOT NULL,
  weekly_time_minutes INTEGER NOT NULL,
  priority_needs    TEXT NOT NULL, -- JSON array of need IDs
  sequence          TEXT NOT NULL, -- JSON array of week activities: [{ week: number, focus: string, activities: string[], successCriteria: object }]
  status            TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'completed', 'paused', 'archived')),
  created_at        TEXT NOT NULL DEFAULT (datetime('now')),
  updated_at        TEXT NOT NULL DEFAULT (datetime('now'))
) STRICT;

CREATE INDEX idx_plans_student ON lrn_learning_plans(student_id);

---

3. API Endpoint Specifications

Profile Management

• GET /api/student/profile
  • Retrieves the learner profile details.
  • Status Codes: 200 OK.
• POST /api/student/profile
  • Saves or updates profile configuration.
  • Request Body: JSON matching the lrn_learner_profiles fields.
  • Status Codes: 200 OK, 400 Bad Request.

Learner Model Compilation

• GET /api/student/model
  • Returns the compiled Learner Model combining:
    1. Static context from lrn_learner_profiles.
    2. Real mastery indices from evd_learner_skill_states.
    3. Simulated behavioral indicators (e.g. Persistence, Average Attempts, Completion Rate).

Need Inference Engine

• GET /api/student/needs
  • Performs the diagnostic analysis.
  • Algorithm:
    1. Fetches current skill mastery.
    2. Identifies target competencies required for their profile goal (e.g. "Tin học trẻ" requires Computational Thinking and Programming Fundamentals).
    3. Traces prerequisite relationships in cf_skill_dependencies.
    4. Records gaps (Mastery < 75%) and marks them as PREREQUISITE_GAP if they block other target skills, or KNOWLEDGE_GAP otherwise.

Planning Engine

• GET /api/student/plan
  • Structures the weekly learning roadmap.
  • Algorithm:
    1. Reads active learning needs.
    2. Sorts needs by priority (severity × goal relevance).
    3. Distributes needs across an 8-week schedule.
    4. Mapped activities are chosen based on the student's study preferences (coding exercises vs. projects).