Post-Quiz Processing Workflow — Requirements Specification

EduOne AI Platform | Version 1.0

Field	Value
Document ID	EQ-RS-002
Version	1.0
Date	2026-07-17
Status	Approved
Owner	EduOne AI Platform Team

---

Table of Contents

1. Introduction & Objective
2. Functional Architecture
3. Objective Grading Logic
4. Evidence Generation & Anomaly Detection
5. Bayesian Updates & Mastery Calculations
6. Dependency Graph & Gap Detection
7. Ranking Next Activity
8. Cloudflare Workflows Design
9. Error States & Retry Requirements

---

1. Introduction & Objective

1.1 Document Purpose

This document defines the functional and non-functional requirements for the Post-Quiz Processing Workflow in the EduOne AI Platform. It describes the sequence of background steps executed immediately following a student's quiz submission.

1.2 Business Objective

When a student completes a quiz, the system must do more than simply calculate a numeric score. To support personalized learning, the platform must asynchronously analyze performance, isolate foundational gaps, update the student's mastery model, and recommend the optimal next learning activity.

By leveraging Cloudflare Workflows as an orchestrator, we ensure that this processing is:

• Resilient: Guarded against partial failures or transient database locks.
• Traceable: Auditable at each execution boundary.
• Consistent: Capable of ensuring that evidence, mastery, and recommendations are transactionally sound.

flowchart TD
    SUB[Student Submits Quiz] --> Grade[1. Objective Grading]
    Grade --> Evd[2. Evidence Generation]
    Evd --> Bayes[3. Bayesian Mastery Update]
    Bayes --> Graph[4. Dependency Graph / Gap Diagnosis]
    Graph --> Rec[5. Recommendation Generation]
    Rec --> Target[6. Active Remediation Recommendation]

---

2. Functional Architecture

The Post-Quiz Processing Workflow is triggered by a client submission to the /api/submissions endpoint. Instead of running the entire pipeline synchronously in a single HTTP request (which risks client timeout and database locking), the API immediately creates a workflow execution and returns a pending token. The execution of the pipeline is then offloaded to a stateful step-based orchestrator.

2.1 Core Processing Phases

Phase	Name	Input	Output	Responsible Component
Phase 1	Objective Grading	Raw answers, Quiz template	Scored answers, Score percentage, Duration	GradingEngine
Phase 2	Evidence Generation	Scored answers, Time spent	evd_evidence records	EvidenceProcessor
Phase 3	Bayesian Updates	Evidence records, Current model	Updated evd_learner_skill_states & evd_learner_models	MasteryCalculator
Phase 4	Gap Diagnosis	Updated skill states, Dependency graph	Ordered list of prerequisite gaps (root-causes)	DependencyGraphEngine
Phase 5	Ranking & Recs	Remediation candidates, Gaps list	Top recommendation saved to rec_recommendations	RecommendationEngine

2.2 Process Sequence Diagram

sequenceDiagram
    autonumber
    actor Learner as Learner Client
    participant API as Submission API
    participant WF as Cloudflare Workflows Orchestrator
    participant D1 as D1 Database
    participant DI as Diagnostic Engine
    participant RE as Recommendation Engine

    Learner->>API: POST /api/submissions (JSON Answers)
    API->>D1: Write Submission Record (Status: submitted)
    API->>WF: Dispatch post-quiz workflow execution
    API-->>Learner: 202 Accepted (Workflow ID + Submission ID)
    
    Note over WF: Workflow execution starts in background
    
    WF->>WF: Step 1: Grading (Calculate scores & duration)
    WF->>D1: Update Submission Score & Status (graded)
    
    WF->>WF: Step 2: Evidence Generation (Anomaly checking)
    WF->>D1: Write evd_evidence records
    
    WF->>WF: Step 3: Bayesian Update (Weighted Moving Average)
    WF->>D1: Update Learner Model & Skill States
    
    WF->>WF: Step 4: Gap Diagnosis (Upstream traversal)
    WF->>D1: Fetch dependencies & trace gaps
    
    WF->>WF: Step 5: Rank & Recommend (Remediation selection)
    WF->>D1: Write rec_recommendations (Status: pending)
    
    WF-->>API: Complete execution status
    
    Learner->>API: GET /api/submissions/:id/results (Polling)
    API->>D1: Read graded submission & recommendation
    API-->>Learner: Return results + next activity card

---

3. Objective Grading Logic

The grading step must score multi-choice questions objectively, calculate attempt counts, detect duplicates, and construct student-friendly local explanations.

3.1 Scoring Algorithm

1. Retrieval: Load quiz details (lrn_quizzes) and associated questions (lrn_questions).
2. Comparison: Map each answer submitted by the student to the correct question option (lrn_question_options).
3. Score Accumulation: $$\text{Total Score} = \sum_{q \in Q} \text{Points Obtained}(q)$$ $$\text{Max Score} = \sum_{q \in Q} \text{Max Points}(q)$$ $$\text{Percentage} = \frac{\text{Total Score}}{\text{Max Score}}$$
4. Attempt Resolution: Count previous attempts to assign attempt_number.
5. Duplicate Prevention: If there is an active in_progress submission, block or redirect to avoid redundant runs.
6. Explanation Enrichment: Construct automated localized explanations:
   • Correct: "Chính xác! Bạn đã trả lời đúng! ✅" (Correct! You answered correctly!)
   • Incorrect: "Đáp án đúng là: {CorrectOptionText}. Hãy xem lại nhé! 📝" (The correct answer is: {CorrectOptionText}. Please review!)

---

4. Evidence Generation & Anomaly Detection

Scored answers are translated into atomic learning events called Evidence. This decouples quiz events from the learner mastery profile.

4.1 Linkage to Curriculum

Each question must target a measurable indicator (cur_indicators) which maps to a specific skill (cur_skills).

• Question $\rightarrow$ indicator_id
• Indicator $\rightarrow$ skill_id

4.2 Anomaly & Speed Check

To prevent learners from gaming the system (e.g., clicking random answers rapidly to skip), the system implements an anomaly threshold:

• Rule: If the time spent on a question is less than 1.5 seconds, the evidence is flagged.
• Impact: The evidence weight and confidence are lowered from the default 1.0 to 0.2.
• D1 Field Mapping: evd_evidence.weight and evd_evidence.confidence.

---

5. Bayesian Updates & Mastery Calculations

EduOne maintains an active representation of learner proficiency across all skills using a Weighted Moving Average (WMA) that mimics a simplified Bayesian network updating process.

5.1 Math Formulation

The mastery score of a student on a specific skill $s$ after receiving new evidence $E$ is updated as:

$$M_{\text{new}} = \frac{M_{\text{old}} \cdot N_{\text{old}} + \sum_{e \in E} (\text{Score}e \cdot \text{Weight}e)}{N{\text{old}} + \sum{e \in E} \text{Weight}_e}$$

Where:

• $M_{\text{old}}$ is the previous mastery score ($0.0 \le M \le 1.0$)
• $N_{\text{old}}$ is the historical evidence count
• $\text{Score}_e$ is the normalized score of the new evidence ($0.0 \le \text{Score}_e \le 1.0$)
• $\text{Weight}_e$ is the evidence weight (adjusted by the speed anomaly detector)

5.2 Confidence Formulation

The system calculates confidence as a function of the total quantity of evidence gathered:

$$C_{\text{new}} = \min\left(1.0, \frac{N_{\text{new}}}{10}\right)$$

This guarantees that a user needs at least 10 evidence points to achieve maximum ($1.0$) confidence in their mastery score.

5.3 Mastery Thresholds & Trends

Mastery Range	State Label (Nhãn Trình Độ)	Description
$[0.0, 0.4)$	emerging (Mới bắt đầu)	The student shows severe gaps or is just starting.
$[0.4, 0.7)$	developing (Đang phát triển)	The student grasps basic concepts but lacks consistency.
$[0.7, 0.9)$	proficient (Thành thạo)	The student independently completes tasks successfully.
$[0.9, 1.0]$	advanced (Nâng cao)	The student exhibits deep fluency and transfer skills.

• Trend Analysis:
  • improving: $\Delta M > 0.01$
  • declining: $\Delta M < -0.01$
  • stable: otherwise

---

6. Dependency Graph & Gap Detection

When a learner's mastery of a skill drops into the emerging range ($< 0.4$), the diagnostic engine must perform a root-cause analysis by traversing the dependency graph.

6.1 Traversal Logic

The graph is directed and acyclic (DAG). Nodes represent skills; edges represent dependencies (cur_skill_dependencies).

graph TD
    A[Root: Machine Learning] -->|depends on| B[Linear Algebra]
    A -->|depends on| C[Basic Calculus]
    B -->|depends on| D[Matrix Arithmetic]
    C -->|depends on| E[Functions & Graphs]

1. Trigger: Identify target skill $s$ with mastery $< 0.4$.
2. DFS/BFS Traversal: Traverse incoming dependency edges (upstream dependencies) of $s$.
3. Evaluation: For each prerequisite skill $p$:
   • Check if $M_p < 0.7$ (not proficient).
   • If $M_p < 0.7$, mark it as an active prerequisite gap.
4. Ordering: Order the gaps starting from the most foundational nodes (leaves of the dependency tree) up to the target skill.

6.2 Remediation Path Selection

The system uses the ordered gaps to prioritize remedial content. The goal is to repair the base of the learning hierarchy before attempting the higher-level target skill again.

---

7. Ranking Next Activity

Once gaps are detected, the recommendation engine filters and ranks course content to present the single best activity card to the student.

7.1 Recommendation Categories

Code	Type	Priority	Description
remediation	Remediation	High (9)	Targets foundational prerequisite gaps (mastery $< 0.4$).
practice	Practice	Medium (7)	Targets skills in the developing zone ($0.4 \le M < 0.7$).
next_lesson	Progression	Normal (5)	Standard curriculum content for mastered prerequisites.
enrichment	Enrichment	Low (3)	Extension tasks for advanced learners ($M \ge 0.9$).

7.2 Ranking Algorithm (Multi-Factor Scoring)

Candidates are scored using a weighted ranking formula:

$$\text{Rank Score} = W_{\text{gap}} \cdot G + W_{\text{difficulty}} \cdot D + W_{\text{type}} \cdot T$$

Where:

• $G$ represents the gap score (higher if the content targets a foundational prerequisite gap).
• $D$ is the difficulty alignment score (matches student's pace and historical success rates).
• $T$ represents the activity type weight (e.g., interactive exercises scored higher than long videos).

---

8. Cloudflare Workflows Design

To ensure execution safety and durability, we partition the post-quiz pipeline into discrete, idempotent steps managed by Cloudflare Workflows.

8.1 Step Sequence

stateDiagram-v2
    [*] --> Init: Trigger Workflow
    Init --> Step_Grading: step.run('Grade Submission')
    Step_Grading --> Step_Evidence: step.run('Process Evidence')
    Step_Evidence --> Step_Mastery: step.run('Calculate Mastery')
    Step_Mastery --> Step_Diagnosis: step.run('Run Gap Diagnosis')
    Step_Diagnosis --> Step_Recommendation: step.run('Generate Recommendation')
    Step_Recommendation --> [*]: Finish & Save Results

8.2 Execution Guarantees

• Checkpoints: At the completion of each step.run(), the workflow automatically serializes and stores the state. If the Cloudflare Worker restarts, execution resumes from the last successfully completed step, bypassing previously executed steps.
• Idempotency: All steps are designed such that repeating them (e.g., on a connection failure) will not double-insert records. For example, evidence inserts use UPSERT or check for the existence of submissionId first.

---

9. Error States & Retry Requirements

The orchestrator must handle network issues, database locks, and external API timeouts gracefully.

9.1 Retry Configurations

Each step must adhere to the following fallback policies:

• Exponential Backoff:
  • Initial delay: 2 seconds
  • Backoff factor: 2.0
  • Max delay: 60 seconds
• Max Retries: 3 attempts per step.
• Timeout: Each step has a maximum runtime of 30 seconds.

9.2 Human Intervention & State Recovery

If a workflow exhausts all 3 retries, the status shifts to failed and writes to ops_workflows.error_details.

• Alerting: The system logs a critical warning.
• Manual Resumability: Admins must be able to trigger a retry command targeting the failed workflow, resuming it exactly from the failing checkpoint once the underlying issue (e.g., database lock) is resolved.