Architecture Decision Records (ADR)

AI-First Learner Intelligence Platform
Version: 1.0
Scope: Hackathon MVP và nền tảng mở rộng sau Hackathon
Status: Proposed Architecture Baseline

1. ADR Categories

Dưới đây là danh sách 40 quyết định kiến trúc cốt lõi được ghi nhận và phân loại theo 4 nhóm chính. Vui lòng nhấp vào từng mục để xem chi tiết bối cảnh (Context), quyết định (Decision), phương án thay thế (Alternatives), và hệ quả (Consequences).

Nhóm 1: Core & AI Principles (ADR-001 to ADR-008)

ADR-001 — Chọn kiến trúc AI-First

Xem chi tiết quyết định

• Status: Accepted
• Context: Hệ thống cần thu thập bằng chứng từ người học, suy luận mức độ thành thạo, cập nhật Learner Model, xác định thứ tự ưu tiên học tập và đề xuất bước học tiếp theo. AI không được chỉ là chatbot hoặc tính năng bổ sung. Nếu ngắt AI model, hệ thống phải mất khả năng thực hiện chức năng cốt lõi.
• Decision: Thiết kế hệ thống theo mô hình: Evidence ➔ Assessment ➔ Learner Model ➔ Decision ➔ Recommendation ➔ New Evidence. AI chịu trách nhiệm cho các hoạt động cần suy luận: diễn giải learner state, phân tích knowledge gap, xử lý uncertainty, lựa chọn learning strategy, và giải thích recommendation. Code deterministic chịu trách nhiệm cho: tính điểm đúng/sai, weighted aggregation, threshold, trend calculation, evidence count, coverage, và freshness.
• Alternatives Considered:
  • AI-enabled LMS: LMS truyền thống cộng thêm chatbot. Không chọn vì khi bỏ chatbot, hệ thống vẫn hoạt động bình thường.
  • Fully LLM-driven system: Cho LLM thực hiện cả phép tính, scoring và aggregation. Không chọn vì khó tái lập, khó audit, dễ sai số và chi phí cao.
• Consequences:
  • Positive: Thể hiện rõ tính AI-First, dễ giải thích với giám khảo, giữ được độ chính xác của các phép tính deterministic, và dễ thay thế model AI.
  • Negative: Phải phân định rõ ranh giới giữa AI reasoning và rule engine, kiến trúc phức tạp hơn chatbot đơn thuần.

ADR-002 — Evidence là Source of Truth

Xem chi tiết quyết định

• Status: Accepted
• Context: Learner Model là trạng thái suy luận động, không phải dữ liệu gốc. Rubric, scoring rule hoặc AI model có thể thay đổi theo thời gian. Nếu chỉ lưu Learner Model hiện tại, hệ thống không thể tái đánh giá hoặc audit khi luật thay đổi.
• Decision: Evidence là nguồn dữ liệu gốc bất biến. Pipeline: Raw Evidence ➔ Assessment Snapshot ➔ Learner Model. Không được sửa trực tiếp evidence đã được xác nhận. Nếu cần hiệu chỉnh: Old Evidence + Correction Record ➔ New Assessment Snapshot.
• Alternatives Considered:
  • Learner Model là Source of Truth: Không chọn vì Learner Model chỉ là belief state và có thể sai.
  • Chỉ lưu điểm tổng hợp: Không chọn vì mất traceability và không thể rebuild.
• Consequences:
  • Positive: Có thể chạy lại đánh giá (re-run assessment) khi đổi rubric hoặc model, dễ audit và điều tra nguyên nhân điểm số thay đổi.
  • Negative: Phải lưu thêm lịch sử và metadata, tăng yêu cầu storage và quản trị dữ liệu.

ADR-003 — Sử dụng Canonical Evidence Model

Xem chi tiết quyết định

• Status: Accepted
• Context: MVP chỉ có quiz evidence. Sau này hệ thống có thể nhận: assignment, project, source code, website, video, audio, mentor review, reflection. Nếu kiến trúc gắn chặt với quiz, việc mở rộng sẽ yêu cầu viết lại Assessment Engine.
• Decision: Tạo đối tượng thực thể chuẩn hóa duy nhất: Evidence. Quiz chỉ là một kiểu con: evidence_type = quiz. Mỗi evidence type có một Evidence Adapter tương ứng để chuyển đổi dữ liệu gốc sang canonical schema.
• Alternatives Considered:
  • Bảng riêng cho từng loại bằng chứng: Không chọn vì Assessment Engine sẽ bị phụ thuộc vào quá nhiều schema khác nhau.
  • Lưu mọi evidence trong một JSON không có contract: Không chọn vì khó validate và khó quản trị.
• Consequences:
  • Positive: Dễ thêm các loại bằng chứng mới, Assessment Engine hoạt động độc lập với nguồn gốc dữ liệu, data lineage nhất quán.
  • Negative: Cần xây dựng adapter cho từng loại bằng chứng, canonical schema phải được phiên bản hóa cẩn thận.

ADR-004 — Indicator là đơn vị đánh giá nhỏ nhất

Xem chi tiết quyết định

• Status: Accepted
• Context: Competency quá rộng để đánh giá trực tiếp. Skill vẫn có thể gồm nhiều hành vi khác nhau. Để phát hiện điểm yếu cụ thể và đưa ra gợi ý hành động chính xác, hệ thống cần một đơn vị nhỏ nhất, có thể quan sát (observable) và ánh xạ trực tiếp với bằng chứng.
• Decision: Thiết kế hệ thống phân cấp Khung năng lực: Domain ➔ Competency ➔ Skill ➔ Indicator. Indicator là đơn vị nhỏ nhất mà hệ thống thu thập bằng chứng, chấm điểm, tính toán xu hướng, lưu độ tự tin và xác định khoảng trống kiến thức. Skill và Competency được tổng hợp toán học từ các indicator con.
• Alternatives Considered:
  • Chấm trực tiếp Competency: Không chọn vì kết luận quá mơ hồ, không tạo được lộ trình cá nhân hóa.
  • Chấm trực tiếp Skill: Có thể dùng trong hệ thống đơn giản, nhưng không đủ chi tiết để tạo đề xuất học tập chính xác.
• Consequences:
  • Positive: Đề xuất học tập cụ thể, dễ truy vết điểm số, dễ phát hiện điểm nghẽn của học viên, và dễ thiết kế câu hỏi map.
  • Negative: Số lượng indicator có thể lớn, tăng chi phí thiết kế rubric và ngân hàng câu hỏi.

ADR-005 — Rubric được version hóa và liên kết với Indicator

Xem chi tiết quyết định

• Status: Accepted
• Context: AI assessment phải dựa trên tiêu chuẩn rõ ràng. Rubric có thể thay đổi theo cấp độ người học, khóa học, thời gian, và mục tiêu học tập. Nếu rubric bị ghi đè, hệ thống đánh giá cũ sẽ mất khả năng audit.
• Decision: Mỗi rubric bắt buộc có định danh rubric_id, phiên bản version, trạng thái status độc lập. Rubric liên kết với chỉ báo (indicator) và loại bài đánh giá (assessment type). Một khi đã công bố (published), rubric trở thành bất biến. Khi cần thay đổi, tạo phiên bản mới (v2.0 thay vì ghi đè).
• Alternatives Considered:
  • Hard-code rubric trong prompt: Không chọn vì khó quản lý phiên bản và khó bảo trì prompt.
  • Một rubric duy nhất cho mọi học viên: Không chọn vì thiếu linh hoạt với nhiều cấp độ.
• Consequences:
  • Positive: Audit xuất sắc, có thể chạy thử nghiệm song song (A/B test) rubric, dễ tái lập đánh giá.
  • Negative: Phải quản lý vòng đời rubric chặt chẽ, có thể xuất hiện nhiều phiên bản hoạt động song song trong hệ thống.

ADR-006 — Quiz là evidence type đầu tiên

Xem chi tiết quyết định

• Status: Accepted
• Context: Hackathon diễn ra trong thời gian ngắn. Các bằng chứng dạng dự án, video hay mã nguồn đòi hỏi thời gian thiết kế công cụ chấm điểm AI rất phức tạp. Quiz trắc nghiệm có cấu trúc, dễ thu thập, dễ validate và map chỉ báo ngay lập tức.
• Decision: Trong phạm vi Hackathon MVP, hệ thống chỉ hỗ trợ bài thi trắc nghiệm (evidence_type = quiz). Mặc dù vậy, toàn bộ cấu trúc xử lý phía sau của hệ thống vẫn sử dụng thực thể canonical Evidence để sẵn sàng tích hợp các adapter khác về sau.
• Alternatives Considered:
  • Hỗ trợ nhiều dạng bằng chứng ngay từ MVP: Không chọn vì tăng rủi ro lỗi kỹ thuật trong 48 giờ.
  • Chỉ lưu điểm tổng bài Quiz: Không chọn vì mất khả năng phân tích chỉ báo.
• Consequences:
  • Positive: Hoàn toàn khả thi trong thời gian ngắn, dữ liệu có cấu trúc cao, dễ đo lường độ chính xác (accuracy) của AI.
  • Negative: Hạn chế trong việc đo lường các năng lực thực hành mang tính chất trình diễn hành vi.

ADR-007 — Một câu hỏi có một Primary Indicator

Xem chi tiết quyết định

• Status: Accepted for MVP
• Context: Một câu hỏi phức tạp có thể liên quan tới nhiều chỉ báo năng lực khác nhau. Tuy nhiên, việc gán một câu hỏi cho quá nhiều chỉ báo sẽ làm phức tạp hóa công thức tính toán điểm số, gây khó khăn cho việc giải thích và kiểm thử.
• Decision: Trong MVP, áp dụng quy tắc: Một câu hỏi ➔ Một chỉ báo năng lực chính (Primary Indicator). Có thể thiết lập các chỉ báo phụ (Secondary Indicators) để tham chiếu nhưng không dùng làm trọng số tính toán điểm số chính thức.
• Alternatives Considered:
  • Một câu hỏi ánh xạ nhiều chỉ báo có trọng số: Tốt cho production nhưng quá phức tạp cho MVP.
  • Không ánh xạ câu hỏi với chỉ báo: Không chọn vì hệ thống sẽ mất khả năng cập nhật Learner Model.
• Consequences:
  • Positive: Công thức chấm điểm tường minh, dễ giải thích logic với giám khảo, dễ truy vết.
  • Negative: Có thể làm đơn giản hóa quá mức một số câu hỏi tích hợp nhiều kỹ năng.

ADR-008 — Tách Assessment Snapshot khỏi Learner Model

Xem chi tiết quyết định

• Status: Accepted
• Context: Assessment là kết quả đo lường năng lực tại một thời điểm cố định. Learner Model là trạng thái tích lũy hiện tại được cập nhật liên tục từ nhiều bằng chứng khác nhau. Gộp hai thực thể này làm một sẽ làm mất lịch sử tiến bộ và không thể rebuild dữ liệu khi đổi luật.
• Decision: Tách biệt thành hai đối tượng độc lập:
  • Assessment Snapshot: Thực thể bất biến ghi nhận kết quả một lần đánh giá cụ thể (chứa liên kết evidence, điểm số chỉ báo/kỹ năng/năng lực tại thời điểm đó, rubric version, model metadata).
  • Learner Model: Trạng thái phái sinh hiện tại của học viên (chứa điểm số hiện tại, xu hướng trend, knowledge gaps, thứ tự ưu tiên học tập).
• Alternatives Considered:
  • Chỉ lưu trạng thái hiện tại của Learner Model: Không chọn vì mất hoàn toàn lịch sử tiến bộ.
  • Lưu lịch sử bằng cách ghi đè trực tiếp Learner Model: Không chọn vì không thể audit.
• Consequences:
  • Positive: Có lịch sử chi tiết phục vụ so sánh đối chiếu trước - sau can thiệp, dễ dàng chạy tiến trình rebuild Learner Model từ lịch sử snapshot.
  • Negative: Cần thêm logic xử lý đồng bộ và cập nhật từ snapshot sang current state.

Nhóm 2: Algorithmic & Logic Decisions (ADR-009 to ADR-016)

ADR-009 — Skill và Competency được tính bằng deterministic aggregation

Xem chi tiết quyết định

• Status: Accepted
• Context: Điểm số chỉ báo (Indicator scores) cần được tổng hợp lũy tiến thành điểm kỹ năng và năng lực tổng quát. LLM không phải là công cụ phù hợp để thực hiện các phép toán lặp lại đòi hỏi tính chính xác và nhất quán tuyệt đối.
• Decision: Việc tổng hợp (Aggregation) từ chỉ báo lên kỹ năng và năng lực bắt buộc phải sử dụng mã nguồn logic thông thường (deterministic code). Cơ chế này bao gồm tính trung bình có trọng số, áp dụng ngưỡng đạt (thresholds), kiểm tra điều kiện tiên quyết (prerequisite rules) và các ràng buộc cấp độ tối đa.
• Alternatives Considered:
  • Sử dụng LLM để suy luận điểm kỹ năng: Không chọn vì kết quả không nhất quán, khó audit và tốn tài nguyên.
  • Chỉ dùng trung bình cộng đơn giản: Không chọn vì bỏ qua vai trò của các chỉ báo bắt buộc (mandatory indicators).
• Consequences:
  • Positive: Kết quả nhất quán 100%, dễ kiểm thử, chi phí tài nguyên cực thấp.
  • Negative: Đòi hỏi nhà thiết kế học liệu phải cấu hình rõ ràng các bộ trọng số và quy tắc aggregation.

ADR-010 — Confidence không do LLM tự khai báo

Xem chi tiết quyết định

• Status: Accepted
• Context: LLM có thể sinh ra các câu trả lời chứa mức độ tự tin (ví dụ: "confidence = 90%") nhưng con số này hoàn toàn mang tính cảm tính và không được hiệu chuẩn khoa học.
• Decision: Chỉ số tự tin (Confidence Score) của hệ thống được tính toán thông qua một thuật toán riêng biệt (Confidence Engine) dựa trên các dữ kiện thực nghiệm: Số lượng bằng chứng (sufficiency), độ bao phủ (coverage), độ mới bằng chứng (freshness), chất lượng câu hỏi (item quality), độ ổn định (stability) và mức độ đồng thuận (agreement). AI có thể giải thích chỉ số này, nhưng không quyết định giá trị của nó.
• Alternatives Considered:
  • Lấy chỉ số tự tin tự khai báo từ LLM: Không chọn vì không đáng tin cậy.
  • Không sử dụng chỉ số tự tin: Không chọn vì hệ thống cần thể hiện sự không chắc chắn khi thiếu bằng chứng học tập.
• Consequences:
  • Positive: Chỉ số tự tin minh bạch và giải thích được, hỗ trợ hệ thống đưa ra cảnh báo "chưa đủ dữ liệu đánh giá".
  • Negative: Công thức ban đầu chỉ mang tính giả thuyết, cần điều chỉnh tham số sau khi có dữ liệu thật.

ADR-011 — Trend cần tối thiểu ba data points

Xem chi tiết quyết định

• Status: Accepted
• Context: Một điểm dữ liệu đơn lẻ không thể tạo ra xu hướng. Hai điểm dữ liệu chỉ cho thấy sự thay đổi sơ bộ ban đầu, rất dễ gây nhiễu nếu bài test thứ hai quá dễ hoặc quá khó.
• Decision: Quy ước chặt chẽ về số lượng điểm dữ liệu để ước lượng xu hướng (Trend):
  • 1 lần đánh giá: Trạng thái insufficient_data.
  • 2 lần đánh giá: Trạng thái thay đổi sơ bộ (preliminary_change).
  • Từ 3 lần đánh giá trở lên: Ước lượng xu hướng tiến bộ (improving), ổn định (stable), hoặc sụt giảm (declining) dựa trên hệ số góc tuyến tính (slope) và trung bình động.
• Alternatives Considered:
  • Hiển thị xu hướng ngay sau 2 lần đánh giá: Không chọn vì dễ tạo ra kết luận vội vã, sai lệch.
  • Sử dụng LLM để tự ước lượng xu hướng: Không chọn vì thiếu cơ sở định lượng.
• Consequences:
  • Positive: Dashboard hiển thị trung thực, mang tính khoa học cao, hạn chế đánh giá sai lệch.
  • Negative: Học viên mới bắt đầu học sẽ chưa hiển thị xu hướng năng lực ngay lập tức.

ADR-012 — Knowledge Gap không đồng nghĩa với điểm thấp

Xem chi tiết quyết định

• Status: Accepted
• Context: Học viên có điểm chỉ báo thấp có thể do nhiều nguyên nhân khách quan: Thiếu bằng chứng đo lường, đề kiểm tra quá khó, câu hỏi thiết kế lỗi, học viên chưa học tới, hoặc do dữ liệu bị cũ. Nếu coi tất cả điểm thấp là lỗ hổng tri thức thì hệ thống sẽ đưa ra đề xuất học tập sai lệch.
• Decision: Phân hệ phát hiện lỗ hổng tri thức (Knowledge Gap Engine) phải đánh giá đồng thời nhiều khía cạnh: Độ nghiêm trọng của gap (Gap Severity), độ tin cậy dữ liệu (Confidence), độ phủ bằng chứng (Coverage), mức độ quan trọng của kỹ năng, và sự liên quan tới mục tiêu cá nhân. Hệ thống chỉ kích hoạt trạng thái Knowledge Gap hoạt động khi chỉ số độ phủ và độ tin cậy vượt qua ngưỡng tối thiểu.
• Alternatives Considered:
  • Chỉ chọn chỉ báo có điểm thấp nhất làm gap: Không chọn vì quá đơn giản và dễ gây sai lệch sư phạm.
• Consequences:
  • Positive: Gợi ý học tập chính xác, tránh kết luận vội vã khi thiếu dữ liệu nền tảng.
  • Negative: Đòi hỏi cấu hình thuật toán phức tạp hơn việc tìm giá trị tối thiểu (min score).

ADR-013 — Recommendation sử dụng Hybrid Decision Engine

Xem chi tiết quyết định

• Status: Accepted
• Context: Đề xuất học tập tiếp theo cần phải tuân thủ nghiêm ngặt các logic sư phạm (như kỹ năng tiên quyết, độ khó phù hợp) nhưng cũng cần cá nhân hóa ngữ cảnh cho từng học viên. Rule engine thuần túy rất tốt cho logic cứng, trong khi LLM rất mạnh về suy luận bối cảnh và sinh giải thích cá nhân hóa.
• Decision: Kiến trúc hóa công cụ đề xuất theo mô hình 2 tầng (Hybrid Decision Engine): Rule-based Candidate Ranking (Lọc cứng) ➔ LLM Reasoning & Personalization (AI cá nhân hóa và sinh diễn giải). Rule engine chịu trách nhiệm lọc ra danh sách các bài học hợp lệ dựa trên điều kiện tiên quyết và mức độ ưu tiên. LLM sẽ lựa chọn tác vụ phù hợp nhất trong danh sách đó và sinh lời giải thích sư phạm. LLM tuyệt đối không được tự ý sinh ra mã tác vụ không tồn tại trong thư viện.
• Alternatives Considered:
  • Để LLM tự sinh đề xuất học tập hoàn toàn: Không chọn vì rủi ro ảo tưởng (hallucination) bài học không tồn tại.
  • Chỉ sử dụng Rule engine: Không chọn vì lời khuyên khô khan, không cá nhân hóa được lời thoại.
• Consequences:
  • Positive: Đảm bảo tính khả thi 100% của đề xuất, loại bỏ hoàn toàn lỗi hallucination, giữ được sự linh hoạt và cá nhân hóa cao.
  • Negative: Đòi hỏi thiết kế hai tầng logic độc lập.

ADR-014 — Không triển khai Misconception Detection trong MVP

Xem chi tiết quyết định

• Status: Accepted
• Context: Học viên trong giai đoạn MVP chủ yếu là beginner. Việc phát hiện ngộ nhận tư duy có hệ thống (Misconception) đòi hỏi chuỗi bằng chứng lặp lại qua nhiều dạng bài làm khác nhau, phân tích mẫu sai lệch (distractor patterns) và phân tích định tính tự luận, vượt quá khả năng xử lý của MVP 48 giờ.
• Decision: MVP chỉ tập trung phân loại trạng thái năng lực cơ bản: Thiếu bằng chứng (insufficient_evidence), lỗ hổng tri thức (knowledge_gap), trình độ thấp (low_mastery), và các xu hướng tiến bộ/ổn định/giảm sút. Đẩy tính năng phát hiện ngộ nhận tư duy sâu xuống Phase 3 của lộ trình phát triển.
• Alternatives Considered:
  • Triển khai sơ bộ tính năng phát hiện ngộ nhận: Không chọn vì độ chính xác sẽ rất thấp do thiếu dữ liệu thực nghiệm kiểm chứng.
• Consequences:
  • Positive: Giữ cho MVP tập trung hoàn thành các tính năng cốt lõi chất lượng cao, giảm thiểu rủi ro overclaim hệ thống AI.
  • Negative: Hệ thống chưa phân biệt được giữa việc "chưa học/chưa biết" với việc "hiểu sai bản chất có hệ thống".

ADR-015 — Không triển khai Reinforcement Learning trong MVP

Xem chi tiết quyết định

• Status: Accepted
• Context: Học tăng cường (Reinforcement Learning) yêu cầu thiết lập rõ ràng về trạng thái (state), hành động (action), phần thưởng (reward), chính sách (policy) và đòi hỏi hàng nghìn vòng lặp dữ liệu thực nghiệm để tối ưu hóa chính sách đề xuất. MVP chưa thể thu thập đủ lượng dữ liệu này.
• Decision: MVP sử dụng cơ chế đề xuất tĩnh dựa trên trọng số ưu tiên kết hợp suy luận LLM (Rule-based Priority + LLM-assisted Recommendation). Học tăng cường chỉ được đưa vào thiết kế dưới dạng tính năng mở rộng trong tương lai sau khi đã tích lũy đủ dữ liệu vòng lặp can thiệp - kết quả cải thiện (Intervention-to-Outcome dataset).
• Alternatives Considered:
  • Giả lập thuật toán RL để demo: Không chọn vì dễ bị giám khảo chuyên môn phát hiện và chất vấn tính xác thực.
• Consequences:
  • Positive: Mô tả công nghệ trung thực và chính xác, tránh hiện tượng overengineering hệ thống vô ích.
  • Negative: Hệ thống chưa có khả năng tự động tối ưu hóa chính sách đề xuất dựa trên phản hồi của học viên.

ADR-016 — Không triển khai Full Bayesian Knowledge Tracing trong MVP

Xem chi tiết quyết định

• Status: Accepted
• Context: Thuật toán Bayesian Knowledge Tracing (BKT) hoàn chỉnh đòi hỏi ước lượng chính xác 5 tham số xác suất (prior mastery, learning rate, guess rate, slip rate, forget rate) cho từng chỉ báo. Các tham số này rất khó cấu hình chính xác khi chưa có dữ liệu chạy thực tế.
• Decision: MVP áp dụng mô hình cập nhật năng lực đơn giản hóa dựa trên trọng số bằng chứng tích lũy, độ tự tin của AI và xu hướng biến đổi gần nhất. Cấu trúc bảng cơ sở dữ liệu vẫn được thiết kế đủ mở (chứa các trường prior/posterior) để sẵn sàng cắm module BKT vào về sau.
• Alternatives Considered:
  • Cố gắng chạy thuật toán BKT đầy đủ: Không chọn vì thiếu cơ sở khoa học để hiệu chuẩn (calibrate) các tham số xác suất ban đầu.
• Consequences:
  • Positive: Đảm bảo tính khả thi cao của dự án Hackathon, vẫn thể hiện được tư duy hướng Bayesian trong thiết kế mô hình dữ liệu.
  • Negative: Tiến trình cập nhật điểm số năng lực chưa đạt tới độ tối ưu toán học của mô hình Bayesian hoàn chỉnh.

Nhóm 3: Technology & Infrastructure (ADR-017 to ADR-027)

ADR-017 — Chọn TypeScript làm ngôn ngữ phát triển chính

Xem chi tiết quyết định

• Status: Accepted
• Context: Hệ thống được triển khai trên nền tảng Cloudflare Workers chạy runtime V8 cực nhanh. Thời gian phát triển Hackathon ngắn đòi hỏi sự đồng bộ cao giữa Frontend Client và Backend Server để giảm thiểu lỗi giao tiếp.
• Decision: Sử dụng duy nhất ngôn ngữ TypeScript trên toàn bộ stack công nghệ: Giao diện người dùng (React/Vite), API endpoint (Hono), logic tính toán, cấu phần AI Agents, và định dạng tệp tin cấu hình.
• Alternatives Considered:
  • Sử dụng Python làm backend: Phù hợp cho khoa học dữ liệu nhưng không tối ưu hóa tốt cho môi trường Serverless của Cloudflare Workers so với TypeScript.
• Consequences:
  • Positive: Toàn stack đồng bộ một ngôn ngữ, dễ dàng chia sẻ kiểu dữ liệu (Types) an toàn giữa Client và Server, tốc độ viết code cực nhanh.
  • Negative: Một số thư viện học máy/toán học chuyên sâu của Python sẽ khó sử dụng trực tiếp, đòi hỏi tự viết lại logic hoặc gọi qua API.

ADR-018 — Chọn Cloudflare làm nền tảng triển khai hạ tầng

Xem chi tiết quyết định

• Status: Accepted
• Context: Hệ thống cần cơ sở hạ tầng có khả năng deploy tức thì trong vài giây, serverless hoàn toàn không cần quản trị máy chủ, hỗ trợ lưu trữ dữ liệu SQL phân tán tại vùng biên (Edge), tích hợp sẵn các công cụ giám sát AI và workflow bền vững.
• Decision: Sử dụng toàn bộ hệ sinh thái của Cloudflare bao gồm: Cloudflare Pages (hosting frontend tĩnh), Cloudflare Workers (REST API Hono), Cloudflare D1 (lưu trữ SQL), Cloudflare R2 (lưu trữ file bằng chứng), Cloudflare KV (cache), Cloudflare Durable Objects (stateful coordination), Cloudflare Workflows (chạy tiến trình nền), và Cloudflare AI Gateway (giám sát LLM).
• Alternatives Considered:
  • AWS / Google Cloud: Rất mạnh mẽ nhưng cấu hình tài nguyên (VPC, IAM, ECS, RDS) quá phức tạp và mất nhiều thời gian trong khuôn khổ cuộc thi.
• Consequences:
  • Positive: Deploy cực nhanh, serverless tự động mở rộng (auto-scale), chi phí duy trì gần như bằng 0 trong giai đoạn đầu, kiến trúc đồng nhất.
  • Negative: Bị phụ thuộc vào hệ sinh thái của nhà cung cấp Cloudflare (vendor lock-in), phải tuân thủ các giới hạn kỹ thuật của Workers.

ADR-019 — Chọn Cloudflare Agents SDK làm Agent Runtime chính

Xem chi tiết quyết định

• Status: Accepted for MVP
• Context: Các tác tử AI (AI Agents) trong hệ thống cần quản lý bộ nhớ trạng thái có thời gian sống lâu dài (stateful), tương tác thời gian thực với Client, giao tiếp lẫn nhau và chạy trực tiếp trên hạ tầng Edge của Cloudflare.
• Decision: Sử dụng Cloudflare Agents SDK làm runtime chính để tổ chức và vận hành các tác tử. MVP giới hạn số lượng tác tử ở mức tối thiểu để dễ kiểm soát: LearnerAgent (Stateful Agent giữ kết nối WebSocket với học viên) và RecommendationAgent (Agent đưa ra đề xuất lộ trình).
• Alternatives Considered:
  • Tự viết runtime quản lý Agent: Không khả thi vì tốn thời gian thiết kế cơ chế lưu trữ bộ nhớ và đồng bộ WebSocket.
• Consequences:
  • Positive: Tận dụng tối đa sức mạnh của Cloudflare Durable Objects, hỗ trợ kết nối WebSocket thời gian thực tự nhiên, cô lập trạng thái của từng học viên.
  • Negative: Công nghệ mới của Cloudflare đang trong giai đoạn phát triển tích cực, tài liệu hướng dẫn còn hạn chế.

ADR-020 — Chưa sử dụng Mastra trong MVP

Xem chi tiết quyết định

• Status: Accepted
• Context: Mastra cung cấp các cấu phần xây dựng Agent rất mạnh mẽ (evaluations, memory, tool integration). Tuy nhiên, luồng xử lý dữ liệu của MVP hiện tại tương đối tuyến tính và đơn giản, việc đưa thêm một lớp framework điều phối AI có thể làm tăng độ phức tạp và rủi ro tích hợp.
• Decision: MVP ưu tiên sử dụng trực tiếp Cloudflare Agents SDK kết hợp với Cloudflare Workflows và các TypeScript services thuần túy. Mastra sẽ được giữ trong kế hoạch phát triển tương lai khi hệ thống yêu cầu điều phối đa tác tử phức tạp (multi-agent orchestration) hoặc cần bộ nhớ ngữ cảnh chuyên sâu.
• Alternatives Considered:
  • Sử dụng Mastra làm framework chủ đạo: Không chọn vì tăng rủi ro tương thích với Edge runtime của Cloudflare Workers.
• Consequences:
  • Positive: Kiến trúc tối giản, dễ gỡ lỗi (debug), giảm thiểu tối đa các tệp tin phụ thuộc (dependencies).
  • Negative: Đội ngũ phải tự viết tay một phần logic điều phối và tích hợp công cụ của Agent.

ADR-021 — Sử dụng Cloudflare Workflows cho pipeline chấm điểm

Xem chi tiết quyết định

• Status: Accepted
• Context: Quy trình đánh giá năng lực gồm nhiều bước liên tiếp: Validate bằng chứng ➔ Gọi LLM chấm điểm chỉ báo ➔ Aggregation kỹ năng ➔ Aggregation năng lực ➔ Cập nhật Learner Model ➔ Sinh đề xuất. Các cuộc gọi API LLM bên ngoài rất dễ bị lỗi mạng hoặc timeout. Nếu chạy trực tiếp trên Worker request thông thường, hệ thống sẽ bị sập và không thể khôi phục trạng thái.
• Decision: Sử dụng Cloudflare Workflows để bao bọc và vận hành toàn bộ pipeline đánh giá. Tiến trình Worker tiếp nhận bài nộp của học viên sẽ đẩy sự kiện vào Workflow chạy ngầm (asynchronous execution), tự động ghi nhận trạng thái từng bước (step state checkpointing) và tự động thử lại (retry) khi gặp sự cố mạng mà không làm mất dữ liệu của học viên.
• Alternatives Considered:
  • Chạy toàn bộ pipeline trong một Worker request đồng bộ (synchronous): Chỉ phù hợp với demo siêu nhỏ, rất dễ lỗi timeout và không thể tự phục hồi.
• Consequences:
  • Positive: Quy trình chạy cực kỳ bền bỉ, dễ dàng theo dõi tiến độ từng bước thông qua dashboard giám sát, tự động phục hồi lỗi.
  • Negative: Thời gian xử lý sẽ lâu hơn do chạy bất đồng bộ, Client phải xử lý trạng thái chờ (pending state) khi đợi kết quả cập nhật.

ADR-022 — Sử dụng Cloudflare D1 làm structured data store

Xem chi tiết quyết định

• Status: Accepted
• Context: Cơ sở dữ liệu của hệ thống đánh giá năng lực có mối quan hệ thực thể rất chặt chẽ (Learner ➔ Attempt ➔ Response ➔ Evidence ➔ Snapshot). Các truy vấn tính toán điểm số lũy tiến yêu cầu tính nhất quán dữ liệu cao và khả năng join bảng phức tạp.
• Decision: Sử dụng Cloudflare D1 (cơ sở dữ liệu SQL serverless dựa trên SQLite) làm cơ sở dữ liệu chính lưu trữ toàn bộ thông tin có cấu trúc của hệ thống.
• Alternatives Considered:
  • Sử dụng Cloudflare KV làm dữ liệu chính: Không chọn vì KV không hỗ trợ truy vấn quan hệ (relational queries) và không đảm bảo tính nhất quán giao dịch (ACID).
• Consequences:
  • Positive: Truy vấn SQL chuẩn, dễ quản lý schema quan hệ, tích hợp tự nhiên trong Cloudflare stack, hiệu năng đọc cực nhanh tại vùng biên.
  • Negative: Giới hạn kích thước tệp tin của D1 cần được quản lý tốt, phải viết các script migration schema cẩn thận.

ADR-023 — Không dùng Vectorize trong MVP

Xem chi tiết quyết định

• Status: Accepted
• Context: MVP của hệ thống chỉ sử dụng bằng chứng từ bài thi trắc nghiệm (quiz evidence) và các tiêu chí Rubric dạng ngưỡng số cố định. Do đó, hệ thống không phát sinh các nhu cầu tìm kiếm ngữ nghĩa (semantic search) quy mô lớn.
• Decision: Loại bỏ hoàn toàn Cloudflare Vectorize (vector database) ra khỏi phạm vi công nghệ của MVP để tối giản hạ tầng. Đưa Vectorize vào roadmap tương lai khi cần thực hiện tìm kiếm bằng chứng tương đồng, semantic rubric retrieval hoặc tìm kiếm bài mẫu trực quan.
• Alternatives Considered:
  • Triển khai Vectorize ngay từ MVP: Không chọn vì làm loãng sự tập trung và tăng thời gian tích hợp vô ích.
• Consequences:
  • Positive: Giảm thiểu một dịch vụ hạ tầng cần quản lý, quy trình build nhanh hơn.
  • Negative: Hệ thống chưa hỗ trợ các tính năng tìm kiếm ngữ nghĩa đối với tài liệu học liệu.

ADR-024 — Sử dụng AI Gateway làm control plane cho LLM traffic

Xem chi tiết quyết định

• Status: Accepted
• Context: Hệ thống AI-First gọi rất nhiều API đến các mô hình ngôn ngữ lớn (LLM). Kỹ sư cần có công cụ tập trung để theo dõi chi phí token, ghi nhận log lịch sử prompt, cache các kết quả trùng lặp để tiết kiệm tiền, và kiểm soát tần suất cuộc gọi (rate limiting).
• Decision: Tất cả các cuộc gọi API từ backend đến LLM bắt buộc phải đi qua Cloudflare AI Gateway đóng vai trò là lớp proxy kiểm soát trung tâm.
• Alternatives Considered:
  • Gọi trực tiếp API của từng nhà cung cấp (OpenAI, Anthropic): Không chọn vì mất khả năng cache tập trung và khó giám sát chi phí thời gian thực của toàn dự án.
• Consequences:
  • Positive: Tự động cache kết quả (giảm chi phí và tăng tốc độ phản hồi đáng kể), giám sát trực quan số lượng token và lỗi hệ thống tại một dashboard duy nhất.
  • Negative: Thêm một lớp trung gian trong mạng truyền thông tin, cần cấu hình đúng các endpoint định tuyến.

ADR-025 — OpenRouter là model marketplace tùy chọn

Xem chi tiết quyết định

• Status: Accepted as Optional
• Context: Trong quá trình thi Hackathon, đội ngũ phát triển cần thử nghiệm nhanh và so sánh chất lượng chấm điểm/đề xuất giữa nhiều dòng mô hình khác nhau (Claude 3.5 Sonnet, GPT-4o, Llama 3, Gemini 1.5 Pro). Việc tích hợp API SDK riêng lẻ của từng hãng sẽ tốn thời gian.
• Decision: Sử dụng OpenRouter làm cổng kết nối trung gian tùy chọn để truy cập vào kho mô hình đa dạng chỉ qua một cấu hình API thống nhất. Luồng đi: Backend ➔ Cloudflare AI Gateway ➔ OpenRouter ➔ Target LLM. Trong môi trường production thực tế, có thể bỏ OpenRouter và gọi thẳng tới các provider chính để tối ưu hóa độ trễ.
• Alternatives Considered:
  • Chỉ sử dụng mô hình Workers AI của Cloudflare: Rất tốt và rẻ nhưng các mô hình mã nguồn mở hiện tại trên Workers AI chưa đạt được năng lực suy luận sư phạm chuyên sâu như Claude 3.5 Sonnet.
• Consequences:
  • Positive: Hoán đổi mô hình kiểm thử lập tức chỉ bằng cách thay đổi biến cấu hình, một đầu mối thanh toán chi phí API duy nhất.
  • Negative: Thêm một bên trung gian thứ ba, độ trễ cuộc gọi tăng nhẹ.

ADR-026 — Chỉ một lớp duy nhất chịu trách nhiệm model fallback

Xem chi tiết quyết định

• Status: Accepted
• Context: Khi xảy ra sự cố lỗi API LLM, cả Workflow, AI Gateway, OpenRouter và mã nguồn ứng dụng đều hỗ trợ cấu hình tự động thử lại (retry) hoặc chuyển đổi mô hình dự phòng (fallback). Nếu tất cả các lớp cùng đồng thời kích hoạt retry, một lỗi đơn lẻ sẽ nhân lũy thừa thành hàng chục cuộc gọi trùng lặp, gây nghẽn mạng, tăng độ trễ và đội chi phí.
• Decision: Quy định phân nhiệm rõ ràng về xử lý lỗi:
  • Cloudflare Workflows: Chịu trách nhiệm retry lỗi hệ thống vật lý (step failure) ở cấp độ quy trình bền vững.
  • OpenRouter (hoặc AI Gateway): Chịu trách nhiệm duy nhất cho việc tự động fallback sang mô hình dự phòng khi mô hình chính bị sập API.
  • Mã nguồn Backend: Không tự động viết các vòng lặp retry API thủ công.
• Consequences:
  • Positive: Tránh hiện tượng nhân bản cuộc gọi lỗi, kiểm soát chi phí token chính xác, dễ dàng khoanh vùng debug lỗi.
  • Negative: Đòi hỏi cấu hình chính xác cơ chế fallback ở tầng gateway.

ADR-027 — Lưu đầy đủ Model Metadata trong Assessment Snapshot

Xem chi tiết quyết định

• Status: Accepted
• Context: Kết quả đánh giá của AI (LLM output) phụ thuộc rất nhiều vào biến số tại thời điểm chạy: Phiên bản prompt, loại mô hình, tham số nhiệt độ (temperature) và dữ liệu đầu vào. Nếu chỉ lưu điểm số thô, hệ thống sẽ không có cách nào tái lập hoặc giải trình được nguyên nhân tại sao AI lại chấm như vậy khi có khiếu nại.
• Decision: Bất kỳ dữ liệu nào do AI sinh ra khi lưu vào AssessmentSnapshot đều bắt buộc đi kèm metadata đầy đủ: Định danh mô hình sử dụng, phiên bản prompt, tham số nhiệt độ, request ID của AI Gateway, mốc thời gian, và liên kết bằng chứng đầu vào.
• Alternatives Considered:
  • Chỉ lưu điểm số và lời phê của AI: Không chọn vì vi phạm nguyên tắc minh bạch và giải trình sư phạm.
• Consequences:
  • Positive: Khả năng tái lập kết quả đánh giá 100%, phục vụ tốt công tác nghiên cứu sư phạm và tinh chỉnh prompt về sau.
  • Negative: Dung lượng lưu trữ của bảng snapshot sẽ tăng nhanh hơn.

Nhóm 4: Operations & Strategy Decisions (ADR-028 to ADR-040)

ADR-028 — Mọi đề xuất học tập phải bị giới hạn bởi Thư viện tác vụ

Xem chi tiết quyết định

• Status: Accepted
• Context: Mô hình ngôn ngữ lớn (LLM) khi tự do đề xuất bài tập rất dễ gặp hiện tượng ảo tưởng (hallucination) - tự nghĩ ra các bài học hoặc mã tác vụ không có thực trong hệ thống, dẫn đến lỗi link 404 cho học viên.
• Decision: Thuật toán đề xuất chỉ cho phép LLM lựa chọn và xếp hạng các tác vụ cụ thể lấy từ Thư viện tác vụ chuẩn (Task Library) do Admin cấu hình sẵn. AI được tự do cá nhân hóa câu từ giải thích lý do sư phạm (rationale), nhưng tuyệt đối không được tự ý sinh mã task_id mới nằm ngoài danh sách candidate được cấp.
• Alternatives Considered:
  • Cho LLM tự do sinh đề xuất: Không chọn vì không kiểm soát được tính khả thi và chất lượng học liệu.
• Consequences:
  • Positive: Loại bỏ 100% lỗi liên kết hỏng, đảm bảo tất cả bài học gợi ý đều sẵn sàng để học viên thực hiện ngay lập tức.
  • Negative: Tính đa dạng của đề xuất bị giới hạn bởi độ phong phú của Thư viện tác vụ đầu vào.

ADR-029 — Mentor Correction được lưu dưới dạng Validation Data

Xem chi tiết quyết định

• Status: Accepted
• Context: Trong giai đoạn đầu, các đánh giá chỉ báo năng lực bằng AI có thể gặp sai lệch. Việc cho phép Mentor chấm lại (override) điểm số của AI là bắt buộc để bảo vệ quyền lợi học viên. Tuy nhiên, nếu chỉ ghi đè điểm mà không lưu lại lịch sử, hệ thống sẽ mất đi nguồn dữ liệu huấn luyện vô giá để tự cải tiến.
• Decision: Khi Mentor thực hiện hiệu chỉnh điểm số, sửa lời phê hoặc thay đổi đề xuất của AI, hệ thống không ghi đè trực tiếp lên Snapshot gốc của AI. Thay vào đó, ghi nhận một bản ghi hiệu chỉnh riêng biệt (MentorCorrectionRecord). Bản ghi này vừa dùng để cập nhật trạng thái hiển thị của học viên, vừa được gắn nhãn làm dữ liệu chuẩn (Gold/Validation Dataset) để tinh chỉnh AI model về sau.
• Consequences:
  • Positive: Tích lũy tự động tập dữ liệu huấn luyện chất lượng cao có nhãn của chuyên gia con người, hỗ trợ đo lường độ đồng thuận AI-human (agreement rate).
  • Negative: Phải thiết kế thêm cấu trúc bảng lưu trữ và giao diện hiệu chỉnh cho Mentor.

ADR-030 — Dữ liệu giả lập chỉ dùng để Bootstrap và Testing

Xem chi tiết quyết định

• Status: Accepted
• Context: Trong thời gian thi Hackathon, hệ thống chưa có người dùng thật để sinh ra lượng bằng chứng đa dạng qua nhiều ngày nhằm chứng minh các thuật toán vẽ biểu đồ xu hướng (Trend) hay đo độ tự tin (Confidence).
• Decision: Xây dựng bộ tạo dữ liệu giả lập (Synthetic Data Generator) để bootstrap hệ thống và chạy thử nghiệm. Tuy nhiên, trong slide thuyết trình và bài pitch giới thiệu sản phẩm với ban giám khảo, phải ghi rõ đây là dữ liệu giả lập phục vụ mô phỏng tính năng, không tự nhận là dữ liệu thực tế từ người dùng thật.
• Alternatives Considered:
  • Trình bày dữ liệu giả lập như dữ liệu người dùng thật: Vi phạm đạo đức phát triển sản phẩm, dễ bị chuyên gia phát hiện khi chất vấn sâu.
• Consequences:
  • Positive: Có dữ liệu phong phú để demo tất cả các trạng thái biểu đồ năng lực cực đẹp mắt ngay tại sân khấu, đảm bảo tính trung thực kỹ thuật.
  • Negative: Cần viết thêm code script generator để tạo dữ liệu giả lập hợp lý.

ADR-031 — Validation được thiết kế thành một phân hệ độc lập

Xem chi tiết quyết định

• Status: Accepted
• Context: Câu hỏi quan trọng nhất của hội đồng giám khảo công nghệ giáo dục luôn là: "Làm sao bạn chứng minh được thuật toán chấm điểm và đề xuất của AI là chính xác và khoa học?".
• Decision: Thiết kế một phân hệ đo lường độc lập (Validation Module) hiển thị trên dashboard của Data Ops đo lường trực quan 3 nhóm chỉ số kỹ thuật:
  • Assessment Validation: exact agreement rate, MAE, weighted kappa, và serious error rate của AI Grader so với Mentor.
  • Prediction Validation: Độ chính xác dự báo câu trả lời tiếp theo, chỉ số hiệu chuẩn (calibration curve).
  • Recommendation Validation: Tỷ lệ hoàn thành tác vụ gợi ý, giá trị marginal learning gain thực tế của người học.
• Consequences:
  • Positive: Đưa ra câu trả lời thuyết phục bằng số liệu định lượng trực quan cho ban giám khảo, kiểm soát được chất lượng thuật toán sư phạm.
  • Negative: Đòi hỏi phải chuẩn bị một tập dữ liệu đối chiếu chuẩn (Gold Standard Dataset).

ADR-032 — Thiết kế ưu tiên bảo mật dữ liệu (Privacy by Design)

Xem chi tiết quyết định

• Status: Accepted
• Context: Dữ liệu học tập và đánh giá năng lực của cá nhân là thông tin nhạy cảm. Quá trình gửi dữ liệu lên mô hình LLM bên ngoài có nguy cơ rò rỉ thông tin định danh cá nhân (PII).
• Decision: Áp dụng cơ chế ẩn danh hóa ngay từ tầng API (Pseudonymization). Toàn bộ pipeline đánh giá năng lực ở backend và prompt gửi sang LLM chỉ sử dụng mã định danh ngẫu nhiên (learner_id), tuyệt đối không gửi các trường dữ liệu tên thật, email, số điện thoại hay thông tin cá nhân của học viên sang mô hình AI bên ngoài.
• Consequences:
  • Positive: Đảm bảo tính riêng tư an toàn dữ liệu tuyệt đối, tuân thủ các chuẩn mực bảo mật quốc tế.
  • Negative: Cần duy trì một bảng map định danh bảo mật riêng ở cơ sở dữ liệu nội bộ khi cần hiển thị tên học viên trên màn hình.

ADR-033 — Nhật ký kiểm toán là Append-only

Xem chi tiết quyết định

• Status: Accepted
• Context: Để đảm bảo tính minh bạch sư phạm, ngăn chặn việc gian lận sửa điểm số hoặc can thiệp trái phép vào cấu trúc khung năng lực của hệ thống.
• Decision: Cơ sở dữ liệu nhật ký kiểm toán (Audit Logs) được thiết kế theo cơ chế chỉ cho phép ghi thêm (Append-only). Hệ thống không cung cấp bất kỳ API hay quyền hạn nào cho phép cập nhật (Update) hoặc xóa (Delete) các bản ghi lịch sử kiểm toán đã tạo.
• Consequences:
  • Positive: Đảm bảo tính toàn vẹn dữ liệu tuyệt đối, phục vụ hoàn hảo cho việc thanh tra chất lượng đào tạo.
  • Negative: Kích thước bảng log sẽ tăng liên tục theo thời gian, cần thiết kế chính sách lưu trữ dài hạn phù hợp.

ADR-034 — Phân quyền truy cập dựa trên vai trò chuyên biệt (RBAC)

Xem chi tiết quyết định

• Status: Accepted
• Context: Hệ thống phục vụ nhiều đối tượng tương tác khác nhau trong một cơ sở giáo dục. Việc không phân quyền hoặc phân quyền quá rộng sẽ gây rủi ro bảo mật nghiêm trọng (như học viên tự sửa Rubrics hoặc xem điểm của học viên khác).
• Decision: Triển khai phân quyền truy cập chặt chẽ (Role-Based Access Control) cho 6 vai trò:
  • Learner: Chỉ được xem bằng chứng và mô hình năng lực của chính mình.
  • Mentor: Xem được học viên trong lớp phụ trách, override điểm, duyệt recommendation.
  • Assessment Designer: Quản lý ngân hàng câu hỏi, khung năng lực và tiêu chí Rubrics.
  • Program Manager: Xem báo cáo tổng hợp chất lượng đào tạo.
  • AI Engineer: Giám sát AIOps và dữ liệu validation ẩn danh.
  • System Admin: Cấu hình hệ thống chung.
• Consequences:
  • Positive: Bảo mật hệ thống vững chắc, phân định rõ ràng trách nhiệm của từng nhóm người dùng.
  • Negative: Tăng độ phức tạp khi thiết kế ma trận phân quyền (permission matrix) ở tầng API.

ADR-035 — Hackathon ưu tiên lát cắt sản phẩm hoàn chỉnh (Vertical Slice)

Xem chi tiết quyết định

• Status: Accepted
• Context: Thời gian thi Hackathon chỉ có 48 giờ. Việc cố gắng xây dựng một hệ thống quản lý học tập (LMS) khổng lồ chứa hàng trăm tính năng phụ trợ (như thanh toán, chat, diễn đàn) sẽ làm loãng sản phẩm, dễ gặp lỗi crash và không làm nổi bật được nhân lõi trí tuệ AI.
• Decision: Tập trung nguồn lực xây dựng một lát cắt dọc hoàn chỉnh và chất lượng cao (Vertical Slice) đi qua toàn bộ các bước của vòng lặp: Học viên làm Quiz đầu vào ➔ AI tự động chấm điểm chỉ báo ➔ Tổng hợp kỹ năng/năng lực ➔ Cập nhật Learner Model ➔ Phát hiện gap ➔ AI đề xuất bài học tiếp theo ➔ Học viên làm bài reassessment ➔ Outcome cải thiện. Giới hạn quy mô dữ liệu thử nghiệm ở mức nhỏ nhưng sâu sắc: 1 khung năng lực mẫu, 2 competencies, 6 skills, 12 indicators, và 30 câu hỏi chuẩn mực.
• Consequences:
  • Positive: Demo chạy cực kỳ mượt mà, câu chuyện sản phẩm sắc nét và tập trung, nêu bật được năng lực xử lý thông minh của AI.
  • Negative: Sản phẩm trông sẽ ít tính năng bề nổi hơn các hệ thống LMS thông thường.

ADR-036 — Thiết lập hai Test Learners đại diện cho hai trạng thái năng lực

Xem chi tiết quyết định

• Status: Accepted
• Context: Khi trình diễn demo cho ban giám khảo, nếu tất cả tài khoản thử nghiệm đều hiển thị một kết quả hoặc đưa ra gợi ý giống hệt nhau, hệ thống sẽ thất bại trong việc chứng minh khả năng cá nhân hóa (personalization) của AI.
• Decision: Chuẩn bị sẵn dữ liệu lịch sử cho hai tài khoản học viên thử nghiệm đại diện cho hai tình huống điển hình:
  • Learner A (Advanced): Đã có điểm số nền tảng tốt, chỉ bị hổng duy nhất chỉ báo năng lực "Identify Pains", hệ thống có độ tin cậy đánh giá cao ➔ Gợi ý thẳng bài tập thực hành nâng cao để bù đắp gap.
  • Learner B (Beginner): Người mới bắt đầu, dữ liệu bằng chứng thu thập rất ít, độ tin cậy đánh giá của AI thấp ➔ Hệ thống gợi ý bài thi chuẩn đoán cơ bản ban đầu để thu thập thêm dữ liệu nền tảng trước khi kết luận.
• Consequences:
  • Positive: Minh họa trực quan và tương phản rõ nét khả năng thích ứng thông minh của thuật toán đối với từng bối cảnh người học khác nhau.
  • Negative: Phải cấu hình dữ liệu đầu vào và các kịch bản tương tác cẩn thận trước buổi demo.

ADR-037 — Phân tách hiển thị dữ liệu theo vai trò người dùng

Xem chi tiết quyết định

• Status: Accepted
• Context: Việc hiển thị quá nhiều thông số kỹ thuật (như coverage percentage, model versions, entropy, token costs) lên màn hình của học viên sẽ gây quá tải thông tin (information overload) và làm loãng trải nghiệm học tập của họ.
• Decision: Thiết kế giao diện hiển thị dữ liệu phân lớp rõ ràng:
  • Giao diện Học viên: Chỉ hiển thị điểm số, cấp độ Rubric, xu hướng mũi tên đơn giản, kỹ năng ưu tiên và hành động tiếp theo kèm lời giải thích ngắn gọn.
  • Giao diện Mentor: Hiển thị thêm số lượng bằng chứng, độ phủ câu hỏi, và các lý do sư phạm chi tiết của AI.
  • Giao diện Kỹ thuật (Ops): Hiển thị đầy đủ log cuộc gọi LLM, độ tin cậy chi tiết, chi phí token và biểu đồ validation.
• Consequences:
  • Positive: UX cực kỳ thân thiện và phù hợp với từng đối tượng mục tiêu, giữ được tính minh bạch mà không gây bối rối cho học viên.
  • Negative: Đòi hỏi phát triển nhiều giao diện hiển thị biểu đồ khác nhau cho cùng một nguồn dữ liệu gốc.

ADR-038 — Tất cả điểm số năng lực bắt buộc đi kèm trạng thái dữ liệu

Xem chi tiết quyết định

• Status: Accepted
• Context: Khi một học viên mới tham gia hệ thống và chưa thực hiện bất kỳ bài đánh giá nào cho kỹ năng X, việc hiển thị điểm số kỹ năng X bằng 0 là hoàn toàn sai lệch về mặt sư phạm (học viên chưa làm bài khác với việc học viên có năng lực yếu kém).
• Decision: Trạng thái năng lực của học viên đối với từng chỉ báo luôn đi kèm một trường trạng thái dữ liệu cụ thể: Chưa quan sát (not_observed), chưa đủ bằng chứng (insufficient_evidence), đã đánh giá (assessed), dữ liệu bị cũ (stale), hoặc bằng chứng mâu thuẫn (conflicting_evidence). Điểm số (Score) được phép nhận giá trị rỗng (null).
• Consequences:
  • Positive: Phản ánh trung thực trạng thái năng lực, giúp công cụ đề xuất đưa ra hành động thu thập bằng chứng thay vì vội vàng kết luận học viên yếu kém.
  • Negative: Giao diện đồ thị phải xử lý khéo léo các trạng thái rỗng để không bị vỡ giao diện.

ADR-039 — Outcome Tracking là thành phần bắt buộc trong kiến trúc

Xem chi tiết quyết định

• Status: Accepted
• Context: Một hệ thống đề xuất học tập (Recommendation System) nếu chỉ đưa ra gợi ý mà không có cơ chế đo lường kết quả thực tế đạt được sau khi học viên hoàn thành gợi ý đó sẽ trở thành một hệ thống một chiều, không thể tự đánh giá hiệu quả của chính mình.
• Decision: Kiến trúc dữ liệu bắt buộc phải định nghĩa thực thể Outcome để ghi nhận sự thay đổi năng lực (Learning Gain) của học viên: Điểm số trước can thiệp ➔ Thực hiện tác vụ gợi ý ➔ Làm bài đánh giá lại (Reassessment) ➔ Ghi nhận điểm số sau can thiệp ➔ Tính toán Learning Gain. Mặc dù trong MVP chỉ demo kịch bản đơn giản, cơ chế này là bắt buộc để chuẩn bị cho việc huấn luyện học máy tối ưu hóa chính sách đề xuất về sau.
• Consequences:
  • Positive: Chứng minh được hiệu quả cải thiện thực tế của nền tảng đối với năng lực học viên, tạo tiền đề nâng cấp thuật toán thông minh.
  • Negative: Đòi hỏi học viên phải hoàn thành thêm bài test reassessment để hệ thống có dữ liệu đối chiếu.

ADR-040 — Ghi nhận và cập nhật liên tục quyết định kiến trúc (ADR)

Xem chi tiết quyết định

• Status: Accepted
• Context: Kiến trúc hệ thống sẽ liên tục tiến hóa sau kỳ thi Hackathon để phục vụ thương mại hóa Startup thật. Nếu không ghi chép lại lý do đưa ra các quyết định kỹ thuật cốt lõi, đội ngũ sẽ rất dễ rơi vào các cuộc tranh luận lặp đi lặp lại hoặc thay đổi mã nguồn thiếu tính nhất quán.
• Decision: Thiết lập tài liệu ADR này làm kim chỉ nam kỹ thuật cho toàn dự án. Mọi thay đổi lớn về công nghệ hoặc thiết kế dữ liệu đều phải tạo mới hoặc cập nhật trạng thái của ADR tương ứng (Proposed ➔ Accepted ➔ Deprecated ➔ Superseded) kèm theo sự đồng thuận của đội ngũ kỹ sư.
• Consequences:
  • Positive: Đồng bộ tư duy kỹ thuật trong đội ngũ, giảm thiểu thời gian chuyển giao công nghệ cho kỹ sư mới (onboarding), giữ vững tính nhất quán của hệ thống.
  • Negative: Đòi hỏi tính kỷ luật cao của đội ngũ trong việc duy trì và viết tài liệu kỹ thuật đi kèm code.

2. Architecture Baseline Summary

Dựa trên 40 quyết định kiến trúc được thông qua, hệ thống Hanoi Agents thiết lập nền tảng kỹ thuật và luồng dữ liệu chuẩn như sau:

Học viên nộp bài Quiz 
   │
   ▼
Tạo lập Bằng chứng bất biến (Canonical Evidence)
   │
   ▼
Kích hoạt Workflow ngầm bền vững (Cloudflare Workflows)
   │
   ▼
AI suy luận chấm điểm chỉ báo (LLM Grader + Rubrics v1.0)
   │
   ▼
Tổng hợp toán học điểm kỹ năng & năng lực (Deterministic aggregation)
   │
   ▼
Kết xuất bản chụp snapshot bất biến (Assessment Snapshot)
   │
   ▼
Cập nhật mô hình người học (Learner Model - Digital Twin)
   │
   ▼
Tính toán độ tự tin & xu hướng phát triển (Confidence & Trend calculation)
   │
   ▼
Định vị lỗ hổng tri thức thực tế (Knowledge Gap Engine)
   │
   ▼
Đề xuất tác vụ thích ứng tiếp theo (Hybrid Recommendation Engine)
   │
   ▼
Giao hành động học tập mới ➔ Đo lường Outcome cải thiện

Hạ tầng triển khai:

• Frontend Hosting: Cloudflare Pages (React / Vite SPA).
• API Gateway & Routing: Cloudflare Workers + Hono framework + AI Gateway.
• Agent Runtime: Cloudflare Agents SDK (Stateful Durable Objects).
• Workflow Engine: Cloudflare Workflows.
• Database & Cache: Cloudflare D1 (SQL) + Cloudflare KV (Cache) + Cloudflare R2 (Evidence files).
• LLM Engine: Claude 3.5 Sonnet / GPT-4o (gọi thông qua AI Gateway & OpenRouter).