I07 — Quiz Module

sequenceDiagram autonumber participant B as Browser participant MW as Middleware participant C as Controller participant FR as FormRequest participant SVC as Service participant QE as QuestionEngineService participant REPO as Repository participant DB as Moodle DB participant Q as Queue participant M as Moodle Plugin Note over B,M: POST /api/v1/quizzes/{quizId}/attempts B->>MW: POST /attempts + Bearer token MW->>MW: Sanctum auth + moodle.active MW->>FR: StartAttemptRequest authorize() + validate() FR->>REPO: check enrollment REPO->>DB: SELECT quiz_overrides, enrolments DB-->>FR: enrolled = true FR-->>C: validated C->>SVC: AttemptStartService::start(StartAttemptDTO) SVC->>REPO: OverrideRepository findUserOverride + findGroupOverrides REPO->>DB: SELECT quiz_overrides DB-->>SVC: effective settings SVC->>REPO: QuizAttemptRepository findInProgress REPO->>DB: SELECT quiz_attempts WHERE state=inprogress DB-->>SVC: null SVC->>DB: BEGIN TRANSACTION SVC->>REPO: QuizAttemptRepository create REPO->>DB: INSERT quiz_attempts DB-->>SVC: attempt_id SVC->>QE: bootstrapAttempt(quiz, attempt, slots, contextId) QE->>REPO: createUsage REPO->>DB: INSERT question_usages loop For each slot QE->>REPO: createAttempt REPO->>DB: INSERT question_attempts QE->>REPO: createStep(state=todo) REPO->>DB: INSERT question_attempt_steps end SVC->>DB: COMMIT SVC->>Q: dispatch QuizAttemptStarted async Q-->>M: ForwardEventToMoodle POST REST API SVC-->>C: attempt + page data C-->>B: 201 JSON attempt_id, page, navigation Note over B,M: POST /api/v1/quiz-attempts/{id}/save B->>C: POST /save page + responses C->>FR: SaveAnswersRequest validate C->>SVC: AttemptSaveService::save(SaveAnswersDTO) SVC->>SVC: overdue check timelimit + overduehandling SVC->>QE: savePageAnswers(attempt, page, responses) loop For each slot with response QE->>REPO: getLatestStep REPO->>DB: SELECT max sequencenumber QE->>REPO: createStep(seq+1, complete) REPO->>DB: INSERT question_attempt_steps QE->>REPO: createStepData(stepId, kv pairs) REPO->>DB: INSERT question_attempt_step_data end REPO->>DB: UPDATE quiz_attempts currentpage timemodified SVC->>Q: dispatch QuizAttemptAnswersSaved async C-->>B: 200 JSON navigation time_remaining Note over B,M: POST /api/v1/quiz-attempts/{id}/finish B->>C: POST /finish page + responses C->>SVC: AttemptFinishService::finish(FinishAttemptDTO) SVC->>QE: savePageAnswers final page SVC->>DB: BEGIN TRANSACTION loop For each question_attempt SVC->>REPO: QuestionRepository findById findAnswers REPO->>DB: SELECT question question_answers SVC->>SVC: GradingService grade per QuestionType SVC->>REPO: createStep graded state + fraction REPO->>DB: INSERT question_attempt_steps end SVC->>REPO: QuizAttemptRepository finalize sumgrades timefinish REPO->>DB: UPDATE quiz_attempts state=finished SVC->>REPO: QuizGradeRepository upsert grade REPO->>DB: INSERT ON DUPLICATE KEY UPDATE quiz_grades SVC->>DB: COMMIT SVC->>Q: dispatch QuizAttemptFinished async C-->>B: 200 JSON grade grade_feedback can_review_now

flowchart TD A([POST /attempts]) --> B{Authenticated?} B -- No --> B1[401 Unauthenticated] B -- Yes --> C{Enrolled in course?} C -- No --> C1[403 Forbidden] C -- Yes --> D{Quiz open?} D -- No --> D1[409 QUIZ_NOT_OPEN 5002] D -- Yes --> E{Password required?} E -- wrong --> E1[422 QUIZ_PASSWORD_REQUIRED 5004] E -- OK --> F{Attempts exhausted?} F -- Yes --> F1[409 ATTEMPTS_EXHAUSTED 5003] F -- No --> G{Existing inprogress\nattempt?} G -- Yes --> H[Resume 200 OK] G -- No --> I[INSERT quiz_attempts\nbootstrap question engine\nDB transaction] I --> I1[INSERT question_usages] I1 --> I2[INSERT question_attempts x slots] I2 --> I3[INSERT question_attempt_steps state=todo] I3 --> J[dispatch QuizAttemptStarted async] J --> K[201 Created — page 0 + navigation] K --> L([POST /save]) L --> M{Attempt inprogress?} M -- No --> M1[409 ATTEMPT_ALREADY_FINISHED 5006] M -- Yes --> N{Time limit exceeded?} N -- autosubmit --> N1[auto-finish 200 finished state] N -- graceperiod --> N2[409 ATTEMPT_OVERDUE 5009] N -- autoabandon --> N3[409 ATTEMPT_ABANDONED 5010] N -- No limit --> O{Valid page?} O -- No --> O1[422 INVALID_PAGE 5011] O -- Yes --> P{Sequential nav\npage jump?} P -- Violation --> P1[422 SEQUENTIAL_NAV_VIOLATION 5012] P -- OK --> Q[INSERT question_attempt_steps\n+ step_data per slot] Q --> R[UPDATE quiz_attempts.currentpage] R --> S[dispatch QuizAttemptAnswersSaved async] S --> T[200 OK navigation + time_remaining] T --> U([POST /finish]) U --> V[Save final page answers] V --> W{Grade each slot} W --> W1[multichoice truefalse\nfraction from answers] W --> W2[shortanswer pattern match\nnumerical tolerance] W --> W3[essay — needsgrading\nfraction=null] W --> W4[match correct/total] W1 & W2 & W3 & W4 --> X[INSERT graded steps] X --> Y[sumgrades = sum of maxmark x fraction] Y --> Z[UPDATE quiz_attempts state=finished] Z --> AA[UPSERT quiz_grades\nhighest/average/first/last] AA --> AB[dispatch QuizAttemptFinished async] AB --> AC[200 OK grade + grade_feedback] AC --> AD([GET /review]) AD --> AE{Attempt finished?} AE -- No --> AE1[403 ATTEMPT_NOT_FINISHED 5007] AE -- Yes --> AF{Review bitmask\npermits current context?} AF -- No --> AF1[403 REVIEW_NOT_PERMITTED 5015] AF -- Yes --> AG[Build per-question review\ngated by reviewmarks\nreviewrightanswer etc] AG --> AH[dispatch QuizAttemptReviewed async] AH --> AI[200 OK full review payload] style B1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style C1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style D1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style E1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style F1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style M1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style N1 fill:#1a2a1a,stroke:#34d399,color:#6ee7b7 style N2 fill:#3f2a00,stroke:#f59e0b,color:#fcd34d style N3 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style O1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style P1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style AE1 fill:#3f1111,stroke:#ef4444,color:#fca5a5 style AF1 fill:#3f1111,stroke:#ef4444,color:#fca5a5