Product Architecture: Synvia Learning Core

1. Product Thesis

Synvia Learning Core là lớp sản phẩm học tập thực chứng được xây trên nền Synvia hiện tại. Mục tiêu không phải thay Synvia bằng một nền tảng mới, mà là nâng Synvia từ một hệ thống vận hành trung tâm có AI chấm bài thành một hệ thống học tập có bằng chứng: biết người học đang học gì, nhận feedback nào, sửa ra sao, giáo viên can thiệp thế nào, AI có đáng tin không, và kết quả học tập có thật sự cải thiện không.

Product thesis:

> Synvia Learning Core giúp trung tâm đào tạo thiết kế, chấm, phản hồi, theo dõi và cải thiện học tập bằng AI có kiểm soát. Hệ thống bắt đầu từ nhiệm vụ học tập, giữ giáo viên trong vòng phán đoán, dùng dữ liệu tối thiểu nhưng có hành động, và đo hiệu quả theo người học, lớp học, kỹ năng, thời gian, chi phí và rủi ro.

Nguyên tắc sản phẩm:

1. Bắt đầu từ nhiệm vụ học tập, không từ tính năng. 2. Giảm ma sát thao tác, giữ ma sát nhận thức cần thiết. 3. Feedback phải dẫn đến hành động sửa bài, luyện lại hoặc can thiệp. 4. AI là thành phần trong vòng học tập, không phải người quyết định cuối. 5. Giáo viên có quyền thấy, sửa, phủ quyết và phản biện AI. 6. Dữ liệu học tập, dữ liệu sale và dữ liệu phụ huynh phải tách quyền truy cập. 7. Mỗi claim sản phẩm phải gắn với evidence hoặc hypothesis pilot.

2. Synvia Decision

Quyết định: làm từ Synvia hiện tại, không xây sản phẩm riêng từ đầu.

Lý do:

• Repo lms/ đã có Django monolith thật, app sy bao phủ LMS, sale, assignment bank, submission, AI grading, AI teacher, meeting, attendance, notification, payment và dashboard.
• Synvia đã chứa domain knowledge khó mua bằng thời gian: trung tâm tạo khóa học thế nào, học viên vào lớp ra sao, bài tập được giao thế nào, giáo viên/AI chấm bài thế nào, phụ huynh nhận thông tin gì, sale thu tiền ra sao.
• AI grading đã có nền: SyAITeacher, AIAssessmentRequest, AIAssessmentResult, AIGradingService, audio analysis và grammar analysis.
• Nếu xây mới, ta sẽ mất 6-12 tháng để tái tạo lại các workflow vận hành trước khi chạm được learning science.

Nhưng Synvia hiện tại không nên là nơi nhồi thêm toàn bộ Learning Core.

Rủi ro hiện tại:

• sy/models/lms.py quá lớn, chứa nhiều bounded context trong một file.
• Một số logic learning, meeting, AI, assignment và submission đang trộn trong cùng layer.
• Tài liệu review đã chỉ ra thiếu object-level permission, nguy cơ IDOR, denormalization và một số bottleneck.
• Secrets/API keys đang xuất hiện trong settings hoặc JSON key files, cần xử lý trước khi mở rộng production.
• Test nghiệp vụ sy còn mỏng so với độ rộng tính năng.

Chiến lược:

1. Giữ Synvia làm nền vận hành và doanh thu. 2. Tạo app mới trong repo lms/: learning_core hoặc sy_learning. 3. Learning Core phụ trách objective, skill, rubric version, structured feedback, revision loop, AI audit, teacher review, evidence metrics và intervention. 4. Synvia hiện tại gọi Learning Core qua adapter/service. 5. Chỉ sửa model/view cũ ở điểm tích hợp nhỏ, có test và không phá workflow hiện tại.

Khuyến nghị tên app: learning_core.

Lý do: tên này trung tính, không trộn thêm vào sy, giúp team nhìn rõ đây là lõi học tập thực chứng mới. Nếu muốn giữ branding nội bộ, có thể dùng sy_learning, nhưng vẫn phải giữ ranh giới module.

3. Target Users and Jobs-to-be-Done

Owner / Chủ trung tâm

Jobs-to-be-done:

• Biết trung tâm đang vận hành tốt không: lớp, chuyên cần, bài chờ chấm, doanh thu, công nợ.
• Biết chất lượng học tập có cải thiện không, không chỉ biết học viên có đăng nhập hay đóng tiền.
• Biết AI có giúp giảm tải hay tạo thêm rủi ro.
• Có bằng chứng để bán, giữ chân học viên và cải thiện chương trình.

Learning Core cung cấp:

• Evidence dashboard theo lớp/kỹ năng.
• Teacher workload metrics.
• Feedback turnaround metrics.
• AI quality report.
• Pilot report cho từng tính năng học tập.

Academic Manager

Jobs-to-be-done:

• Chuẩn hóa chương trình, rubric, objective và skill.
• Theo dõi lỗi phổ biến theo lớp/kỹ năng.
• Điều phối giáo viên dạy lại hoặc can thiệp.
• Kiểm soát chất lượng AI feedback.

Learning Core cung cấp:

• Objective/skill map.
• Rubric versioning.
• Error clustering.
• Teacher review queue.
• AI incident và prompt/model evaluation.

Teacher

Jobs-to-be-done:

• Chấm nhanh hơn nhưng không mất quyền phán đoán.
• Nhìn lỗi phổ biến của lớp.
• Biết học viên nào cần chú ý và vì sao.
• Sửa feedback AI, không phải chịu trách nhiệm cho output mình không kiểm soát.
• Dạy lại đúng điểm nghẽn.

Learning Core cung cấp:

• Review queue.
• Feedback editor.
• Error clusters có ví dụ bài làm thật.
• Student learning profile theo skill.
• Intervention actions.

Student

Jobs-to-be-done:

• Hiểu mình sai gì, vì sao sai, làm gì tiếp.
• Sửa bài và thấy tiến bộ.
• Không bị biến thành một nhãn "yếu".
• Dùng AI mà vẫn phải suy nghĩ, phản tư và chịu trách nhiệm.

Learning Core cung cấp:

• Feedback có next action.
• Revision loop.
• Reflection prompt.
• Skill progress.
• Spaced review queue ở giai đoạn sau.

Parent / Guardian

Jobs-to-be-done:

• Biết con đi học, nộp bài, tiến bộ và cần hỗ trợ gì.
• Nhận thông tin đủ rõ nhưng không gây áp lực sai.
• Không bị gửi nhãn học tập thô hoặc dữ liệu nhạy cảm không có ngữ cảnh.

Learning Core cung cấp:

• Parent summary có kiểm soát.
• Learning progress language an toàn.
• Tách thông báo học tập với thông báo tài chính.

Sales / Enrollment Staff

Jobs-to-be-done:

• Tư vấn khóa học, tạo đơn, ghi nhận thanh toán, xếp lớp.
• Không cần xem dữ liệu bài làm chi tiết hoặc learner weakness nhạy cảm.

Learning Core không mở dữ liệu học tập nhạy cảm cho sale theo mặc định.

4. Domain Map

Existing Synvia Domains

Các domain này giữ ở app sy, chỉ sửa khi cần tích hợp:

New Learning Core Domains

Các domain này nên đặt ở app mới learning_core:

5. Bounded Contexts

Bounded Context 1: Synvia Operations

Owner: app sy.

Bao gồm:

• Lớp học.
• Lịch học.
• Enrollment.
• Tài liệu.
• Meeting.
• Điểm danh.
• Sale/payment.
• Notification.

Nguyên tắc: không refactor lớn trong giai đoạn MVP Learning Core. Chỉ thêm integration hooks, links, buttons hoặc service calls khi cần.

Bounded Context 2: Learning Core

Owner: app learning_core.

Bao gồm:

• Learning objective.
• Skill.
• Rubric.
• Assessment result mới.
• Feedback item.
• Submission revision.
• Teacher review.
• Learning event.
• Error cluster.
• Intervention.
• AI run/audit.

Nguyên tắc: các model mới không nằm trong sy/models/lms.py. Khi cần dữ liệu cũ, dùng adapter.

Bounded Context 3: AI Orchestration

Owner: learning_core.ai.

Bao gồm:

• Prompt template versioning.
• Provider interface.
• Structured output schema.
• Guardrails.
• AIRun logging.
• AI incident capture.

Nguyên tắc: không gọi model trực tiếp từ view/template. Không gửi toàn bộ dữ liệu lớp/trung tâm vào prompt.

Bounded Context 4: Evidence & Evaluation

Owner: learning_core.services.evidence_service.

Bao gồm:

• Pilot hypothesis.
• Feedback uptake.
• Revision quality.
• Teacher workload.
• AI error rate.
• Error recurrence.
• Delayed review nếu có.

Nguyên tắc: không kết luận hiệu quả từ login count, time-on-platform hoặc số lượt AI generation.

Bounded Context 5: Communication Boundary

Owner: app sy.notification, gọi bởi learning_core qua service.

Bao gồm:

• Parent summary.
• Teacher notification.
• Student reminder.

Nguyên tắc: Learning Core không tự gửi thẳng Zalo/Facebook/email; nó tạo nội dung và request, Notification domain gửi theo policy.

6. Core Workflows

Workflow 1: Gắn objective/rubric vào assignment hiện có

1. Academic manager mở assignment trong Synvia. 2. Learning Core hiển thị objective/skill map. 3. Manager gắn objective và rubric version. 4. Hệ thống lưu AssignmentObjectiveMap và rubric binding. 5. Từ thời điểm này, submission của assignment có thể được chấm/feedback theo rubric có version.

Điểm thiết kế: không tạo assignment model mới ở MVP. Tận dụng SyAssignment và SyClassActivity.

Workflow 2: Người học nộp bài, AI tạo feedback, giáo viên review

1. Student làm bài qua flow Synvia hiện có. 2. Synvia tạo SyActivitySubmission và SyQuestionSubmission. 3. Learning Core nhận submission id qua adapter. 4. AI orchestration tạo AIRun, gọi AIGradingService hiện có hoặc provider mới. 5. Output được validate theo schema structured feedback. 6. Learning Core tạo AssessmentResult, CriterionScore, FeedbackItem. 7. Nếu high-stakes hoặc confidence thấp, tạo TeacherReview ở trạng thái pending. 8. Teacher sửa/approve/reject. 9. Student thấy feedback có next action. 10. Event được ghi: feedback generated, teacher reviewed, student viewed.

Điểm thiết kế: AI output chưa teacher-approved phải được hiển thị rõ là AI draft nếu assignment có rủi ro cao.

Workflow 3: Revision loop

1. Student đọc feedback. 2. Hệ thống yêu cầu chọn 1-3 feedback item để sửa trước. 3. Student nộp revision và reflection. 4. Learning Core so sánh bản trước/sau theo rubric hoặc feedback item. 5. Event ghi started_revision, completed_revision. 6. Teacher xem revision quality nếu cần. 7. Evidence service tính feedback uptake.

Điểm thiết kế: feedback không dừng ở nhận xét; nó phải tạo vòng hành động.

Workflow 4: Error clustering cho lớp

1. Learning Core gom feedback items/submissions theo class/activity. 2. AI hoặc rule-based logic nhóm lỗi theo skill, criterion, misconception. 3. Teacher dashboard hiển thị cụm lỗi, ví dụ bài làm thật, mức phổ biến, gợi ý dạy lại. 4. Teacher chọn action: tạo mini lesson, giao bài luyện, nhắn học viên, đánh dấu bỏ qua. 5. Sau hoạt động tiếp theo, hệ thống đo lỗi có lặp lại không.

Điểm thiết kế: cluster phải dẫn tới action, không chỉ là biểu đồ.

Workflow 5: Parent summary có kiểm soát

1. Teacher hoặc academic manager chọn gửi summary. 2. Learning Core tạo bản tóm tắt tiến bộ bằng ngôn ngữ không nhãn hóa. 3. Teacher/admin review nếu có AI-generated text. 4. Notification domain gửi qua kênh phù hợp. 5. Parent link chỉ xem dữ liệu được phép.

Điểm thiết kế: không gửi "weakness labels" thô cho phụ huynh; phải có ngữ cảnh hỗ trợ.

Workflow 6: AI quality review

1. Teacher đánh dấu feedback AI là sai, quá chung, quá gắt, thiên lệch, làm hộ, hoặc unsafe. 2. Learning Core tạo AIIncident. 3. Incident gắn với AIRun, prompt version, model version, assignment/rubric. 4. Academic manager xem báo cáo lỗi. 5. Prompt/model/policy được cập nhật nếu cần.

Điểm thiết kế: lỗi AI phải trở thành dữ liệu cải tiến, không biến thành gánh nặng âm thầm cho giáo viên.

7. Conceptual Data Model

Existing Model Adapters

New Models

LearningObjective

id

center_id optional

sy_course_id optional

sy_class_type_id optional

code

title

description

subject

level

status

Skill

id

center_id optional

name

parent_skill_id optional

description

ObjectiveSkill

id

objective_id

skill_id

AssignmentObjectiveMap

id

sy_assignment_id

objective_id

weight optional

Rubric

id

center_id optional

name

assessment_type

version

status

created_by_profile_id

RubricCriterion

id

rubric_id

skill_id optional

name

description

scale_json

weight

AssignmentRubricBinding

id

sy_assignment_id

rubric_id

ai_policy_id optional

active_from

AIRun

id

actor_profile_id

task_type

model_provider

model_name

model_version

prompt_template_id

prompt_version

data_scope_json

input_hash

output_text

output_json

token_usage_json

latency_ms

status

error

created_at

PromptTemplate

id

name

task_type

version

template

output_schema_json

status

AIPolicy

id

center_id optional

name

allowed_roles_json

allowed_data_scopes_json

human_review_required

max_autonomy_level

status

AIIncident

id

ai_run_id

reporter_profile_id

category

severity

description

resolution

status

AssessmentResult

id

sy_activity_submission_id

rubric_id

assessor_type

assessor_profile_id optional

ai_run_id optional

total_score

confidence

status

created_at

CriterionScore

id

assessment_result_id

criterion_id

score

rationale

confidence

FeedbackItem

id

assessment_result_id

criterion_id optional

skill_id optional

category

severity

evidence_text

feedback_text

next_action

status

TeacherReview

id

assessment_result_id

teacher_profile_id

decision

edited_score optional

edited_feedback_json optional

note

created_at

SubmissionRevision

id

sy_activity_submission_id

student_profile_id

revision_no

content_text

reflection_text

linked_feedback_items_json

created_at

LearningEvent

id

actor_profile_id

sy_class_id optional

object_type

object_id

verb

metadata_json

event_time

ErrorCluster

id

sy_class_id

sy_assignment_id optional

skill_id optional

title

description

example_submission_ids_json

confidence

status

Intervention

id

sy_class_id

student_profile_id optional

teacher_profile_id

reason

action

status

outcome

created_at

8. AI Capability Map

AI autonomy levels:

9. Teacher-in-the-loop Design

Teacher-in-the-loop trong Synvia Learning Core có bốn quyền:

1. Quyền thấy: giáo viên thấy bài làm, rubric, AI rationale, confidence, prompt/model version và dấu hiệu rủi ro. 2. Quyền sửa: giáo viên sửa điểm, feedback item, severity, next action. 3. Quyền phủ quyết: giáo viên reject AI result hoặc yêu cầu chạy lại. 4. Quyền phản biện: giáo viên mark AI error, tạo incident, góp dữ liệu cải tiến.

Màn hình cần có:

• Review queue: bài cần duyệt, sắp theo rủi ro/confidence/deadline.
• Submission review: bài làm, rubric, AI draft, feedback editor, history.
• Error cluster panel: top lỗi lớp, ví dụ bài làm, action.
• Student detail: submission history, feedback uptake, revision, skill progress.

Không làm:

• Không chỉ có nút "Approve all" mà không có summary rủi ro.
• Không ẩn AI confidence hoặc prompt/model version với tác vụ quan trọng.
• Không để giáo viên chịu trách nhiệm cho feedback AI mà không có quyền sửa.

10. Learner Experience Principles

Student experience phải làm người học tiến bộ, không chỉ nhận điểm.

Nguyên tắc:

1. Feedback phải có next action rõ. 2. Mỗi lần nhận feedback nên có cơ hội sửa hoặc phản tư. 3. Không hiển thị quá nhiều metric cùng lúc. 4. Không dùng nhãn cố định như "yếu", "nguy cơ cao" trong UI học viên/phụ huynh. 5. Khi AI hỗ trợ, UI phải nói rõ AI đang hỗ trợ ở vai trò nào: reviewer, coach, tutor hay tool. 6. Với bài luyện, giữ intentional friction: thử trước, dự đoán, giải thích, rồi mới xem gợi ý sâu. 7. Progress theo skill phải cho thấy khả năng cải thiện, không tạo cảm giác bản án.

Màn hình student MVP:

• Bài đã nộp.
• Feedback theo rubric.
• Việc cần sửa tiếp theo.
• Revision editor.
• Reflection prompt.
• Skill progress đơn giản.

11. Privacy, Governance and Safety

Việc phải xử lý trước khi mở rộng

1. Dọn secrets/API keys khỏi repo và settings hard-code. 2. Tạo object-level permission cho SyClass, SyActivitySubmission, parent report, assessment result. 3. Audit webhook Sepay/Zalo signature và idempotency. 4. Rate limit AI endpoints. 5. Không gửi dữ liệu vượt scope vào LLM.

Permission rules

AI governance rules

1. Mọi AI output quan trọng phải tạo AIRun. 2. AIRun lưu model, prompt version, input hash, output, latency, token/cost nếu có. 3. AI output high-stakes phải có human review. 4. AI output phải có structured schema, không chỉ free text. 5. AI incident phải được review định kỳ. 6. Prompt templates phải versioned. 7. Không bật emotion recognition, biometric, webcam inference trong MVP.

12. Evidence and Evaluation Plan

MVP hypotheses

Hypothesis 1:

AI feedback có structured rubric + teacher review sẽ giảm thời gian phản hồi mà không làm giảm chất lượng nhận xét.

Hypothesis 2:

Revision loop sẽ làm người học sửa bài nhiều hơn và giảm lỗi lặp lại theo skill.

Hypothesis 3:

Error clustering giúp giáo viên chọn đúng nội dung dạy lại và giảm workload phân tích bài làm.

Hypothesis 4:

AI audit + teacher incident marking giúp cải thiện prompt/rubric qua từng chu kỳ.

Metrics

Không dùng các metric này làm bằng chứng học tập chính:

• Số lần login.
• Time-on-platform.
• Số lượt AI generation.
• Số bài tập AI tạo.
• Satisfaction đứng một mình.

Pilot design

Pilot 1: IELTS Writing hoặc Speaking ở 2-3 lớp thật.

Duration: 4-8 tuần.

Baseline:

• Thời gian chấm/feedback trước Learning Core.
• Tỷ lệ học viên sửa bài.
• Lỗi lặp lại ở 2-3 assignment gần nhất.

Evaluation:

• So sánh trước/sau về feedback turnaround, revision quality, teacher workload.
• Phỏng vấn ngắn giáo viên.
• Thu 5-10 case feedback AI bị sửa nhiều để cải thiện prompt/rubric.

Decision:

• Expand nếu giảm workload hoặc tăng feedback quality mà không tăng AI incident nghiêm trọng.
• Iterate nếu AI feedback dùng được nhưng quá chung/sai rubric.
• Stop nếu giáo viên phải sửa quá nhiều, học viên ít sửa bài hơn, hoặc privacy/permission chưa ổn.

13. MVP Scope

In scope

1. Tạo app learning_core. 2. Adapter với model Synvia hiện có. 3. Objective/skill map cho writing/speaking. 4. Rubric versioning. 5. AI feedback wrapper quanh AIGradingService. 6. Structured feedback items. 7. Teacher review queue. 8. Student revision/reflection loop. 9. Error clustering theo lớp/assignment. 10. Learning events và pilot metrics. 11. Permission helpers và audit cho resource nhạy cảm.

Out of scope

1. Xây LMS mới. 2. Xây sale/CRM mới. 3. Thay thế toàn bộ AI grading hiện có. 4. AI tutor chat tự do. 5. Adaptive path tự động toàn phần. 6. Proctoring. 7. Emotion recognition. 8. Marketplace nội dung. 9. Full interoperability LTI/OneRoster. 10. Mobile app riêng.

First vertical

First vertical nên là language center writing/speaking assessment.

Lý do:

• Synvia đã có writing/speaking metrics.
• Trung tâm ngoại ngữ là thị trường hiện tại rõ nhất.
• Feedback và revision loop tạo giá trị thấy ngay.
• Rủi ro thấp hơn so với AI tutor tự do hoặc predictive risk.

14. Roadmap

Phase 0: Safety and readiness

Thời lượng: 1-2 tuần.

Deliverables:

• Secrets/config audit.
• Object-level permission helpers cho class/submission.
• Test nền cho permission.
• Architecture note cho learning_core.
• Adapter skeleton.

Exit criteria:

• Không mở rộng AI/learning data khi secrets còn hard-code hoặc permission chưa có.

Phase 1: Feedback evidence loop

Thời lượng: 3-5 tuần.

Deliverables:

• Objective/skill model.
• Rubric model.
• Assignment-objective/rubric binding.
• AIRun + prompt template.
• AI feedback wrapper.
• AssessmentResult + FeedbackItem.
• Teacher review.
• Student feedback view.

Exit criteria:

• Một lớp writing/speaking có thể chạy từ submission đến feedback review.

Phase 2: Revision and teacher workbench

Thời lượng: 3-4 tuần.

Deliverables:

• SubmissionRevision.
• Reflection prompt.
• Feedback uptake events.
• Error clusters.
• Teacher workbench class panel.
• Intervention actions.

Exit criteria:

• Giáo viên thấy lỗi phổ biến, tạo action và xem người học có sửa không.

Phase 3: Pilot evaluation

Thời lượng: 4-8 tuần pilot thật.

Deliverables:

• Pilot dashboard.
• Teacher workload metrics.
• AI incident review.
• Revision quality report.
• Decision log: expand/iterate/stop.

Exit criteria:

• Có bằng chứng đủ để quyết định mở rộng hoặc sửa.

Phase 4: Personalisation and curriculum depth

Thời lượng: sau MVP.

Deliverables:

• Skill mastery estimate.
• Spaced review queue.
• Asset-based learner notes.
• Adaptive practice có giải thích và override.

Exit criteria:

• Cá nhân hóa tăng agency và giảm lỗi lặp, không khóa người học vào nhãn.

15. Risks and Open Questions

Technical risks

1. Legacy model complexity: sy/models/lms.py lớn, dễ tạo coupling nếu chạm trực tiếp. 2. Permission risk: thiếu object-level permission có thể lộ dữ liệu lớp/bài làm. 3. Secrets risk: API keys/settings hard-code phải xử lý trước production expansion. 4. AI reliability risk: Gemini output có thể sai schema, sai rubric, hoặc quá tự tin. 5. Data duplication risk: nếu copy dữ liệu Synvia sang Learning Core quá sớm, sẽ lệch nguồn sự thật. 6. Test gap: nghiệp vụ sy cần test trước khi refactor.

Product risks

1. Giáo viên thấy AI review queue là thêm việc nếu UI không tốt. 2. Học viên có thể đọc feedback nhưng không sửa nếu revision loop yếu. 3. Owner có thể muốn dashboard đẹp hơn evidence thật. 4. Sale có thể muốn dùng learner weakness để upsell, cần guardrail rõ. 5. Parent summary có thể gây áp lực nếu ngôn ngữ quá tiêu cực.

Research/open questions

1. AI feedback có cải thiện revision quality hay chỉ làm bài trông mượt hơn? 2. Error clustering có thật sự dẫn đến dạy lại không? 3. Giáo viên sửa AI nhiều ở tiêu chí nào? 4. Học viên yếu có được hỗ trợ tốt hơn hay bị gắn nhãn hơn? 5. Rubric chung theo trung tâm có đủ hay cần rubric theo giáo viên/lớp? 6. Chi phí AI trên mỗi bài nộp có bền không? 7. Khi nào có thể cho AI feedback formative gửi trực tiếp không cần review từng bài?

Decision Summary

Quyết định kiến trúc chính:

1. Không xây sản phẩm riêng từ đầu. 2. Không nhồi Learning Core vào sy/models/lms.py. 3. Tạo app mới learning_core. 4. Dùng adapter để đọc/ghi từ Synvia hiện tại. 5. MVP tập trung vào AI assessment, feedback, teacher review, revision và evidence. 6. Xử lý secrets, object-level permission và AI audit trước khi scale.

Hình thái sản phẩm mong muốn:

> Synvia vẫn là hệ thống vận hành trung tâm. Synvia Learning Core là lớp học tập thực chứng chạy bên trong nó, biến bài nộp, feedback, revision, teacher review và dữ liệu lớp thành một vòng cải thiện học tập có kiểm soát.