System Design Document (SDD)

AI-First Learner Intelligence System
Version: 1.0 (Hackathon Architecture)

1. Overview

Objective

Thiết kế và kiến trúc một hệ thống AI-First có khả năng: Thu thập bằng chứng học tập (learning evidence), đánh giá năng lực học viên, cập nhật mô hình người học (Learner Model - Digital Twin), và đề xuất chiến lược học tập thích ứng để tạo thành một vòng lặp học tập khép kín (closed learning loop). AI đóng vai trò là hạt nhân điều hành trung tâm của toàn bộ hệ thống.

2. High-Level Architecture

Sơ đồ khối luồng thông tin giao tiếp tổng quát của hệ thống:

                      Web Frontend (Client)
                               │
                               ▼
                        Cloudflare Pages
                               │
                               ▼
                     Cloudflare Workers API
                               │
                     Cloudflare Agents SDK
                               │
 ┌─────────────────────────────┼─────────────────────────────┐
 │                             │                             │
 ▼                             ▼                             ▼
Evidence Agent           Assessment Agent            Recommendation Agent
 │                             │                             │
 └─────────────┬───────────────┴───────────────┬─────────────┘
               ▼                               ▼
         Learner Model Agent             Explanation Agent
               │
               ▼
         Cloudflare D1 ➔ Learner Model Database Store

3. Technology Stack

• Frontend: React, Vite, TailwindCSS, Cloudflare Pages.
• Backend: Cloudflare Workers, Hono Web Framework, Cloudflare Agents SDK, TypeScript.
• AI Infrastructure: Cloudflare AI Gateway, OpenRouter, Claude 3.5 Sonnet / GPT-4o / Gemini 1.5 Pro.
• Storage:
  • Cloudflare D1 (Lưu trữ dữ liệu có cấu trúc - Structured Data SQL).
  • Cloudflare KV (Lưu trữ cache).
  • Cloudflare R2 (Lưu trữ các tệp tin bằng chứng vật lý).
  • Cloudflare Vectorize (Phục vụ tìm kiếm ngữ nghĩa trong tương lai).
• Workflow & Durable Execution:
  • Cloudflare Workflows (Sử dụng cho pipeline chấm điểm nhiều bước, chạy nền bền vững và tự động retry khi gặp sự cố mạng).

4. Core Architecture Layers

Hệ thống được tổ chức phân rã thành 6 tầng kiến trúc chặt chẽ:

Presentation Layer (Giao diện React/Vite Dashboard)
      │
      ▼
API Layer (Hono Router trên Workers)
      │
      ▼
AI Agent Layer (Các Agents có trạng thái - Durable Objects)
      │
      ▼
Learner Intelligence Layer (Các công cụ tính toán logic toán học)
      │
      ▼
Data Layer (Cloudflare D1, R2, KV, SQLite)
      │
      ▼
Infrastructure Layer (Hạ tầng mạng toàn cầu của Cloudflare)

5. AI Agent Layer

Evidence Agent

• Nhiệm vụ: Tiếp nhận kết quả từ Quiz/Task nộp lên, kiểm tra tính hợp lệ dữ liệu (schema validation), và lưu trữ bằng chứng gốc.
• Input: Dữ liệu thô bài nộp (Quiz Results / File Upload).
• Output: Bản ghi bằng chứng được chuẩn hóa (Evidence Record).

Assessment Agent

• Nhiệm vụ: Đọc bằng chứng học tập, tải barem tiêu chí (Rubric), gọi mô hình LLM để thực hiện suy luận chấm điểm chỉ báo năng lực, sinh diễn giải sư phạm.
• Input: Evidence Record, Rubric Definition.
• Output: Điểm số chỉ báo (Indicator Scores), độ tự tin (Confidence) và diễn giải chi tiết.

Learner Model Agent

• Nhiệm vụ: Cập nhật mô hình số của học viên. Đây là nơi các thuật toán Bayesian update và Knowledge Tracing được áp dụng để tính toán tích lũy cấp độ năng lực và kỹ năng từ dữ liệu chỉ báo mới nộp.

Recommendation Agent

• Nhiệm vụ: Phân tích các lỗ hổng năng lực (knowledge gaps), sắp xếp thứ tự ưu tiên học tập, chọn lựa bài học/nhiệm vụ tối ưu tiếp theo cho học viên, và gọi LLM để tạo lời giải thích sư phạm cho đề xuất đó.

Explanation Agent

• Nhiệm vụ: Tạo ra các lập luận, diễn giải chi tiết cho kết quả đánh giá hoặc đề xuất học tập mà không làm thay đổi điểm số gốc.

6. Learner Intelligence Layer

Phân hệ chịu trách nhiệm xử lý các thuật toán và logic nghiệp vụ toán học phi LLM để tối ưu chi phí và tăng tốc độ xử lý:

• Indicator Engine: Nhận dữ liệu từ Assessment Agent để ghi nhận điểm chỉ báo.
• Skill Engine: Tổng hợp điểm từ các chỉ báo thành điểm kỹ năng thông qua cơ chế tính toán trọng số trung bình (weighted aggregation) hoặc các luật tiên quyết (prerequisite rules) mà không cần sử dụng LLM.
• Competency Engine: Tổng hợp điểm kỹ năng thành điểm năng lực tổng quát (không cần LLM).
• Knowledge Gap Engine: Phân tích Learner Model để tìm ra các năng lực yếu dựa trên sự kết hợp giữa điểm số thấp, độ tự tin của AI và mức độ quan trọng của năng lực.
• Trend Engine: Đo lường xu hướng phát triển năng lực bằng các thuật toán Trung bình động (Moving Average) hoặc Trung bình động lũy thừa (Exponential Moving Average).
• Confidence Engine: Tính toán mức độ tin cậy của AI dựa trên: Số lượng bằng chứng thu thập, mức độ đa dạng nguồn bằng chứng, độ phủ của bài test, độ mới của bằng chứng, và mức độ đồng thuận giữa các lần đánh giá.

7. LLM Inference Strategy

Mô hình ngôn ngữ lớn (LLM) chỉ được sử dụng ở các bài toán thực sự đòi hỏi khả năng suy luận ngữ cảnh và diễn giải:

Evidence ➔ Assessment Agent (LLM) ➔ Chạy Prompt Rubric ➔ So sánh sản phẩm ➔ Sinh điểm chỉ báo + Diễn giải (Reasoning)

TIP

AI được sử dụng trong Assessment Agent để chấm điểm tự luận/sản phẩm thực hành và Recommendation Agent để sinh lời giải thích đề xuất. Không lạm dụng LLM cho các tác vụ tính toán trung bình cộng, tính toán xu hướng, đo lường độ tự tin và tổng hợp kỹ năng. Các tác vụ này phải được xử lý bằng code logic thông thường (Rule Engine) để đảm bảo tốc độ và tiết kiệm chi phí.

8. Bayesian & Machine Learning Area

Các mô hình xác suất học máy không phân bổ trên toàn hệ thống mà chỉ được đóng gói trong các module chuyên biệt của Learner Model Agent:

Learner Model State ➔ Bayesian Update ➔ Knowledge Tracing ➔ Trend Prediction

• Ví dụ luồng cập nhật Bayesian: $$\text{Prior Probability (Năng lực cũ)} = 0.55 \xrightarrow{Evidence\ mới} \text{Posterior Probability (Năng lực mới)} = 0.63$$
• Các thuật toán định hướng phát triển:
  • Bayesian Knowledge Tracing (BKT): Đo lường xác suất học viên làm chủ một kỹ năng qua chuỗi câu hỏi.
  • Deep Knowledge Tracing (DKT): Sử dụng mạng Recurrent Neural Network (RNN) để dự báo năng lực.

9. Data Flow

Học viên hoàn thành Quiz 
   │
   ▼
Evidence Store (Lưu trữ bằng chứng)
   │
   ▼
Assessment Agent (LLM suy luận chấm điểm)
   │
   ▼
Indicator Scores (Điểm số chỉ báo)
   │
   ▼
Skill Engine (Tổng hợp kỹ năng)
   │
   ▼
Competency Engine (Tổng hợp năng lực)
   │
   ▼
Learner Model Update (Cập nhật Dynamic Twin)
   │
   ▼
Knowledge Gap Engine (Phát hiện khoảng cách)
   │
   ▼
Recommendation Agent (Đề xuất Next Best Action)
   │
   ▼
Học viên nhận bài tập mới ➔ Tạo ra bằng chứng mới

10. Database Schema Design

Table: Evidence

• evidence_id (Primary Key - UUID)
• learner_id (Foreign Key)
• type (TEXT - e.g., 'quiz', 'project', 'reflection')
• payload (JSON - dữ liệu bài làm của học viên)
• timestamp (DATETIME)

Table: AssessmentSnapshot

• assessment_id (Primary Key - UUID)
• evidence_id (Foreign Key)
• rubric_version (VARCHAR)
• model_version (VARCHAR - ví dụ: 'claude-3-5-sonnet')
• indicator_scores (JSON - danh sách điểm các chỉ báo)
• confidence (REAL - mức độ tự tin từ 0.0 đến 1.0)
• explanation (TEXT - giải thích lý do chấm điểm của AI)

Table: LearnerModel

• learner_id (Primary Key - UUID)
• competencies (JSON - lưu trữ điểm năng lực)
• skills (JSON - lưu trữ điểm kỹ năng)
• indicators (JSON - lưu trữ điểm chỉ báo tích lũy)
• trend (JSON - lưu trữ thông số xu hướng phát triển)
• priority (JSON - các kỹ năng đang được ưu tiên cải thiện)
• last_updated (DATETIME)

Table: Recommendation

• recommendation_id (Primary Key - UUID)
• learner_id (Foreign Key)
• priority_list (JSON - danh sách các kỹ năng ưu tiên học tiếp)
• next_task_id (VARCHAR - mã bài tập được gợi ý)
• explanation (TEXT - giải thích lý do sư phạm của AI)

11. Event Flow

1. Học viên nộp bài Quiz ➔ Hệ thống kích hoạt sự kiện LEARNER_COMPLETED_QUIZ.
2. Tạo bản ghi Evidence mới trong cơ sở dữ liệu.
3. Kích hoạt Assessment Agent để gọi LLM chấm điểm theo Rubrics.
4. Ghi nhận Assessment Snapshot và cập nhật thông số năng lực mới nhất vào Learner Model.
5. Kích hoạt Recommendation Agent để tính toán khoảng cách kiến thức và đề xuất bài tập mới.
6. Đẩy dữ liệu cập nhật thời gian thực về Dashboard của học viên thông qua kết nối WebSocket bền vững của Agents SDK.

12. Cloudflare Components Deployment

• Cloudflare Pages: Đảm nhận hosting và phân phối mã nguồn frontend client tĩnh (React/Vite app).
• Cloudflare Workers: REST API endpoint xử lý định tuyến (routing) và kiểm soát bảo mật.
• Cloudflare Agents SDK: Quản lý vòng đời và lưu trữ bộ nhớ trạng thái (RAM/SQLite) của các Agent thời gian thực.
• Cloudflare Workflows: Vận hành quy trình chạy chấm điểm và cập nhật năng lực dài kỳ một cách an toàn, có khả năng tự khôi phục khi sập hệ thống mạng.
• Cloudflare D1: Cơ sở dữ liệu SQL phân tán lưu trữ toàn bộ dữ liệu có cấu trúc của hệ thống.
• Cloudflare R2: Object Storage lưu trữ các file bằng chứng lớn (mã nguồn, báo cáo, tài liệu).
• Cloudflare AI Gateway: Quản lý, cache, rate limit và giám sát chi phí tất cả các cuộc gọi API đến các mô hình LLM bên ngoài.

13. Security & Governance

• Authentication & Authorization: Quản lý truy cập bằng JWT thông qua Hono middleware.
• Learner Isolation: Mỗi Learner Agent chạy trên một Durable Object cô lập hoàn toàn về mặt bộ nhớ và tiến trình thực thi, ngăn chặn việc rò rỉ dữ liệu giữa các học viên.
• Audit Logging: Ghi chép đầy đủ lịch sử cuộc gọi AI bao gồm prompt sử dụng, kết quả trả về, phiên bản mô hình và phiên bản Rubric để phục vụ công tác thanh tra chất lượng sư phạm.

14. Scalability & High Availability

Hệ thống được thiết kế theo kiến trúc hướng sự kiện (Event-Driven Architecture) và Serverless hoàn toàn:

• Không có chi phí duy trì máy chủ khi không có người sử dụng.
• Việc tính toán của một học viên này không làm ảnh hưởng đến hiệu năng xử lý của học viên khác nhờ cơ chế phân tán của Agents SDK (Durable Objects).
• Các quy trình đánh giá (Assessment) được xử lý song song và bất đồng bộ giúp hệ thống chịu tải cực tốt khi có số lượng lớn học viên nộp bài cùng lúc.

15. Future Architecture Roadmap

• Version 2: Bổ sung hỗ trợ đánh giá bài tự phản hồi (Reflection) và chấm sản phẩm thực hành dự án lớn thông qua R2 và các script chạy sandbox.
• Version 3: Áp dụng mô hình toán học Bayesian Learner Modeling và các thuật toán Knowledge Tracing đầy đủ trong Learner Model Agent. Tích hợp phân hệ phát hiện và xử lý ngộ nhận tư duy (Misconceptions).
• Version 4: Áp dụng học tăng cường (Reinforcement Learning) để tối ưu hóa chính sách đề xuất (Recommendation Policy) dựa trên phản hồi hành vi của người học.

16. Design Principles

1. Reasoning belongs to AI, Determinism belongs to Rules: AI chỉ xử lý các tác vụ đòi hỏi sự suy luận và hiểu ngữ cảnh. Các tác vụ tổng hợp điểm số, tính trung bình cộng bắt buộc phải xử lý bằng Rule Engine thông thường để đảm bảo tính nhất quán và tối ưu hóa chi phí.
2. Evidence is the Source of Truth: Bằng chứng thực tế là nguồn dữ liệu gốc duy nhất có giá trị kiểm chứng năng lực.
3. Decoupled LLM Layer: Thiết kế giao tiếp LLM qua lớp trừu tượng ModelProvider để dễ dàng hoán đổi nhà cung cấp (Claude, GPT, Llama) mà không cần thay đổi kiến trúc hệ thống.
4. Event-Driven & Micro-Agent Architecture: Các tác tử AI hoạt động độc lập, có bộ nhớ và trạng thái riêng, giao tiếp chặt chẽ thông qua các sự kiện bất đồng bộ.