Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes

2026-04-29T02:33:46Z

Amejari:

== Expertiza Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source peer review platform built on '''Ruby on Rails''' and maintained at '''North Carolina State University'''. It is used across multiple courses at NCSU and other universities to facilitate structured peer feedback, team-based assignments, and multi-round review workflows.

In Expertiza, instructors define assignments that walk students through a sequence of tasks — submitting work, reviewing peers, taking quizzes, and providing feedback. The system tracks participants, teams, response maps, and responses across all of these activities.

The ongoing '''reimplementation effort''' modernizes the Expertiza codebase into a clean Rails JSON API backend and a React SPA frontend, with a focus on proper separation of concerns, RESTful conventions, and comprehensive test coverage. Each semester, CSC 517 students contribute targeted reimplementations of specific subsystems as part of their graduate coursework in object-oriented design.

== Project Description ==

This project — '''E2601: Reimplement Student Quizzes''' — focused on the backend infrastructure that governs how students interact with quiz tasks within an assignment workflow. Quizzes in Expertiza are not standalone — they are one task type within a larger ordered sequence that may also include submission, peer review, and feedback stages.

For quizzes to work correctly in this context, three backend systems were built:

* '''A task ordering engine''' — a dedicated <code>TaskOrdering</code> module that knows the correct sequence of tasks for a participant and determines whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' — a <code>StudentTasksController</code> that surfaces the current state of a student's task queue, including which tasks are complete, which is next, and how to start a quiz task
* '''A response management API''' — a <code>ResponsesController</code> that handles the creation and updating of quiz responses with proper authentication, ownership checks, and queue-order enforcement

Without all three of these systems working correctly together, a student could take a quiz before completing required prerequisite tasks, or be blocked from taking a quiz they were legitimately eligible for.

=== Why We Are Refactoring ===

After completing the initial implementation, feedback was received that the <code>TaskOrdering</code> module introduced unnecessary complexity. The module spans five separate files and a dedicated namespace — <code>BaseTask</code>, <code>ReviewTask</code>, <code>QuizTask</code>, <code>TaskFactory</code>, and <code>TaskQueue</code> — yet its logic is only ever called from two controllers. This level of abstraction is harder to trace and maintain than the problem warrants.

The planned refactor will '''remove the <code>TaskOrdering</code> namespace entirely''' and move all sequencing logic directly into <code>StudentTasksController</code> as private methods, supported by two polymorphic inner classes. Every existing API endpoint, response payload shape, and status code will remain unchanged. The refactor is purely an internal structural simplification.

The sections below describe '''what we built first''' and, within each section, '''how it will change''' after the refactor.

== What We Built ==

=== Task Ordering Engine (Current Implementation) ===

We built a self-contained <code>TaskOrdering</code> module under <code>app/models/task_ordering/</code> that encapsulates all logic for determining task eligibility and sequence. This module is intentionally decoupled from controllers — it knows nothing about HTTP requests or responses, only about assignments, participants, and response maps.

The module consists of five classes:

{| class="wikitable"
! Class !! Role
|-
| <code>BaseTask</code> || Abstract base defining the shared interface: <code>complete?</code> and <code>map_id</code>
|-
| <code>ReviewTask</code> || Concrete task for <code>ReviewResponseMap</code> — complete when <code>is_submitted</code> is true
|-
| <code>QuizTask</code> || Concrete task for quiz response maps — the central task type for this project
|-
| <code>TaskFactory</code> || Factory that instantiates the correct task class given a response map
|-
| <code>TaskQueue</code> || Orchestrator that builds and queries the ordered task list for a participant
|}

The <code>TaskQueue</code> is the primary interface that controllers use. Given an assignment and a <code>TeamsParticipant</code>, it answers three questions:

* Is this map part of the participant's task queue? (<code>map_in_queue?</code>)
* Have all tasks before this one been completed? (<code>prior_tasks_complete_for?</code>)
* What is the next task the student should work on? (<code>next_incomplete_task</code>)

==== What Changed ====

The <code>TaskOrdering</code> namespace was removed from the application code. Its orchestration responsibilities now live on <code>StudentTask</code> as shared class methods used by both <code>StudentTasksController</code> and <code>ResponsesController</code>.

<code>BaseTask</code> was replaced by <code>StudentTask::BaseTaskItem</code>. <code>QuizTask</code> and <code>ReviewTask</code> were replaced by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>, implemented as model classes that inherit from <code>StudentTask::BaseTaskItem</code>.

<code>TaskFactory</code> and <code>TaskQueue</code> were eliminated. Their former responsibilities are now handled by <code>StudentTask.build_tasks</code>, <code>StudentTask.find_task_for_map</code>, <code>StudentTask.prior_tasks_complete?</code>, and <code>StudentTask.ensure_response_objects!</code>.

The inner classes will share the following interface via <code>BaseTaskItem</code>:

{| class="wikitable"
! Method !! Purpose
|-
| <code>response_map</code> || Returns the associated response map (creates one for <code>QuizTaskItem</code> if needed)
|-
| <code>ensure_response_map!</code> || Guarantees a response map record exists
|-
| <code>ensure_response!</code> || Creates or finds the <code>Response</code> record (<code>round: 1</code>, <code>is_submitted: false</code> by default)
|-
| <code>completed?</code> || Returns true when a submitted response exists for this map
|-
| <code>to_h</code> || Serializes the task to the same stable JSON payload shape as today
|}

<code>QuizTaskItem</code> will implement <code>response_map</code> as follows: first return a cached map if already loaded; otherwise look for an existing <code>QuizResponseMap</code> by reviewer and reviewee; if none exists and a quiz questionnaire is present, create one with <code>save!(validate: false)</code>; if no questionnaire exists either, return <code>nil</code>. <code>ReviewTaskItem</code> simply returns the <code>ReviewResponseMap</code> it was initialized with.

=== Student Tasks API (Current Implementation) ===

We implemented <code>StudentTasksController</code> with five endpoints that give students full visibility into their task workload:

{| class="wikitable"
! Endpoint !! Method !! What It Returns
|-
| <code>/student_tasks/list</code> || GET || All tasks for the current user across their assignments
|-
| <code>/student_tasks/view</code> || GET || Detailed information for a specific participant task
|-
| <code>/student_tasks/queue</code> || GET || The full ordered task queue for a given assignment
|-
| <code>/student_tasks/next_task</code> || GET || The next incomplete task the student should work on
|-
| <code>/student_tasks/start_task</code> || POST || Attempts to start a task — blocked if prerequisites are incomplete
|}

Currently, every endpoint that involves task ordering resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records and then constructs a <code>TaskQueue</code> instance to answer eligibility questions.

==== What Will Change ====

The <code>list</code>, <code>view</code>, and <code>show</code> actions will remain as-is. The <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions will be refactored to call private controller methods instead of <code>TaskQueue</code>.

'''<code>queue</code> after refactor:'''
# Call <code>resolve_context_for_assignment(params[:assignment_id])</code> to obtain participant, team membership, assignment, and duty. Return 404 if the participant cannot be found.
# Call <code>build_tasks(context)</code> to construct the ordered task list.
# Call <code>ensure_response_objects!(tasks)</code> to guarantee response maps and response records exist for every task.
# Render <code>tasks.map(&:to_h)</code> as JSON.

'''<code>next_task</code> after refactor:'''
# Resolve context and build tasks as above.
# Find the first task where <code>completed?</code> returns false.
# Render that task's <code>to_h</code> payload, or render <code>{ message: "All tasks completed" }</code> if all tasks are done.

'''<code>start_task</code> after refactor:'''
# Find the <code>ResponseMap</code> by <code>params[:response_map_id]</code>. Return 404 if not found.
# Verify <code>map.reviewer.user_id == current_user.id</code>. Return 403 if not.
# Call <code>resolve_context_for_participant(map.reviewer)</code> to build the context.
# Call <code>build_tasks(context)</code> and locate the task for this map via <code>find_task_for_map(tasks, map.id)</code>. Return 404 if the map is not in the participant's queue.
# Call <code>prior_tasks_complete?(tasks, current_task)</code>. Return 403 with "Complete previous task first" if any earlier task is still incomplete.
# Call <code>current_task.ensure_response!</code> and render the task payload.

The key private methods introduced are:

{| class="wikitable"
! Method !! Role
|-
| <code>StudentTask.resolve_context_for_assignment(user, assignment_id)</code> || Finds the participant for the current user and assignment, then resolves the team participant and duty
|-
| <code>StudentTask.resolve_context_for_participant(participant)</code> || Builds the same task context starting from a known participant
|-
| <code>StudentTask.build_tasks(context)</code> || Builds the ordered quiz/review task list
|-
| <code>StudentTask.ensure_response_objects!(tasks)</code> || Ensures response maps and response records exist
|-
| <code>StudentTask.find_task_for_map(tasks, map_id)</code> || Finds the task associated with a response map
|-
| <code>StudentTask.prior_tasks_complete?(tasks, current_task)</code> || Checks whether all earlier tasks are submitted
|}

Task ordering rules in <code>build_tasks</code> will be: if review maps exist, append a <code>QuizTaskItem</code> first (when duty allows and a quiz questionnaire or existing quiz map is present) then a <code>ReviewTaskItem</code> (when duty allows); if no review maps exist, append a quiz-only <code>QuizTaskItem</code> when duty allows and a questionnaire exists. Duty permissions are resolved as: <code>duty_allows_quiz?</code> is true for participant, reader, and mentor roles; <code>duty_allows_review?</code> is true for participant, reader, reviewer, and mentor roles.

=== Response Management API (Current Implementation) ===

We implemented <code>ResponsesController</code> with three endpoints that handle quiz and review response lifecycle:

{| class="wikitable"
! Endpoint !! Method !! What It Does
|-
| <code>/responses</code> || POST || Creates a new response for a quiz or review map
|-
| <code>/responses/:id</code> || GET || Retrieves a specific response
|-
| <code>/responses/:id</code> || PATCH || Updates an existing response
|}

Response creation currently enforces two layers of protection before any data is written:

# '''Ownership check''' — the requesting user must be the reviewer assigned to the response map
# '''Queue order check''' — <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

==== What Changed ====

The <code>GET</code> endpoint is unaffected. The <code>POST</code> and <code>PATCH</code> endpoints now both call <code>enforce_task_order!</code>, which reuses the shared <code>StudentTask</code> task-building and prerequisite-checking methods.
== Technical Deep Dive ==

=== How Task Ordering Works (Current) ===

When a student attempts to start a quiz task or create a response today, the following sequence occurs:

<pre>
StudentTasksController or ResponsesController
|
| TaskQueue.new(assignment, teams_participant)
v
TaskQueue
→ fetches all ResponseMaps for this participant
→ calls TaskFactory.build(map) for each
→ builds ordered array of BaseTask subclass instances
|
| queue.prior_tasks_complete_for?(map_id)
v
→ iterates tasks in order
→ for each task before the target, calls task.complete?
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

=== How Task Sequencing Will Work After the Refactor ===

The same logical flow will execute, but entirely inside the controller with no external module:

<pre>
StudentTasksController or ResponsesController
|
| resolve_context_for_assignment(assignment_id)
v
→ finds AssignmentParticipant by current_user + assignment_id
→ finds TeamsParticipant by participant_id
→ resolves duty (team_participant.duty_id fallback to participant.duty_id)
|
| build_tasks(context)
v
→ queries ReviewResponseMaps for this participant
→ loads quiz questionnaire via assignment.quiz_questionnaire_for_review_flow
→ checks for existing QuizResponseMaps
→ instantiates QuizTaskItem / ReviewTaskItem in correct order
|
| prior_tasks_complete?(tasks, current_task)
v
→ iterates tasks before the target
→ calls task.completed? on each
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

The outcome for every request — which status codes are returned, which tasks are blocked, what JSON is rendered — is identical to today. Only the internal path through the code changes.

=== How Authentication and Authorization Are Layered ===

This layer is unchanged by the refactor. All requests pass through two concerns registered in <code>ApplicationController</code> before reaching any controller logic:

<pre>
Incoming Request
|
v
JwtToken concern → authenticate_request!
→ reads Authorization: Bearer <token> header
→ decodes token using RSA public key
→ sets @current_user via User.find(auth_token[:id])
→ halts with 401 if token missing, expired, or invalid
|
v
Authorization concern → authorize
→ calls all_actions_allowed?
→ checks super-admin privileges OR action_allowed?
→ halts with 403 if not permitted
|
v
Controller before_actions (e.g. find_and_authorize_map_for_create)
→ map-level ownership checks using current_user
|
v
Controller action
</pre>

The critical constraint is that <code>find_and_authorize_map_for_create</code> must remain a standard <code>before_action</code> — not a <code>prepend_before_action</code> — so that <code>current_user</code> is always populated by the time ownership checks run.

=== Round-Aware Response Handling ===

This behavior is unchanged by the refactor. When a response is created, the controller scopes its lookup by both <code>map_id</code> and <code>round</code>:

<pre>
Response.where(map_id: @map.id, round: round)
.order(:created_at)
.last || Response.new(map_id: @map.id, round: round)
</pre>

If a response already exists for this map and round, it is updated in place. If none exists, a new one is initialized. This supports quiz retakes and multi-round review scenarios.

== Design Decisions ==

=== Original Design: Separation of Task Logic into a Dedicated Module ===

The initial implementation encapsulated all task sequencing and eligibility logic within the <code>TaskOrdering</code> module, entirely decoupled from controllers. The reasoning was that controllers should only handle HTTP concerns, while task logic should be independently testable as a pure domain model.

The <code>TaskFactory</code> was introduced so that the correct task class could be instantiated from any response map type without conditional logic in controllers. The <code>TaskQueue</code> served as the single orchestration point so that the same ordering rules were guaranteed to apply whether a student was viewing their queue, starting a task, or submitting a response.

=== Why the Design Is Being Simplified ===

In practice, the <code>TaskOrdering</code> module is only ever called from <code>StudentTasksController</code> and <code>ResponsesController</code>. There are no background jobs, rake tasks, or alternative interfaces that reuse it. The five-file namespace therefore adds indirection without providing the reuse benefits that would justify it.

The refactor recognizes that '''polymorphism belongs where it helps''' — quiz and review tasks genuinely behave differently, so inner classes are still the right tool. But '''orchestration does not need its own namespace''' — a set of private controller methods is simpler to read, easier to test through the request layer, and just as correct.

=== Refactored Design: Controller-Owned Orchestration with Inner Classes ===

After the refactor, the design will follow these principles:

* '''Single orchestration owner''' — all task sequencing decisions flow through one set of private methods in <code>StudentTasksController</code>. <code>ResponsesController</code> will reuse the same logic via a shared concern or equivalent private methods.
* '''Polymorphism without over-engineering''' — <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> are inner classes that share a <code>BaseTaskItem</code> interface. The difference in behavior is encapsulated; the orchestration logic treats both identically.
* '''No extra namespace''' — everything lives in <code>app/controllers/student_tasks_controller.rb</code>. A developer reading the <code>queue</code> action can follow the entire flow without opening any other file.
* '''High cohesion''' — task lifecycle behavior (response map creation, response initialization, completion detection, serialization) is grouped with the task objects themselves.
* '''Low coupling''' — the controller works against the shared <code>BaseTaskItem</code> interface, so adding a new task type requires only a new inner class with no changes to orchestration methods.

=== Layered Authorization and Validation ===

This decision is unchanged. Validation is enforced at three distinct layers: JWT authentication globally in <code>ApplicationController</code>, role-level authorization via the <code>authorize</code> concern, and map-level ownership checks as controller <code>before_action</code> callbacks. Task-order enforcement is the final layer, applied inside the action itself. This defense-in-depth approach remains intact after the refactor.

=== Round-Aware Response Handling ===

Unchanged. Responses continue to be scoped by <code>map_id</code> and <code>round</code>, with update-in-place semantics for existing records.

=== Emphasis on RESTful and Stateless Design ===

Unchanged. All endpoints remain resource-based with JWT authentication, compatible with the React frontend and stateless horizontal scaling.

== Test Coverage ==

=== Current Test Suite ===

The initial implementation is covered by 77 passing examples across model and request specs:

{| class="wikitable"
! File !! Key Scenarios Tested
|-
| <code>spec/models/task_ordering/base_task_spec.rb</code> || Default <code>complete?</code> behavior, <code>map_id</code> delegation, interface contract
|-
| <code>spec/models/task_ordering/review_task_spec.rb</code> || Completion based on <code>is_submitted</code>, incomplete when not submitted
|-
| <code>spec/models/task_ordering/quiz_task_spec.rb</code> || Quiz-specific completion detection and eligibility
|-
| <code>spec/models/task_ordering/task_factory_spec.rb</code> || Correct class returned for each map type, error on unknown type
|-
| <code>spec/models/task_ordering/task_queue_spec.rb</code> || Queue ordering, <code>map_in_queue?</code>, <code>prior_tasks_complete_for?</code>, <code>next_incomplete_task</code>
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task — response codes 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST, GET, PATCH /responses — response codes 201, 200, 401, 403, 404
|}

To run the current suite:

<pre>
bundle exec rspec \
spec/requests/api/v1/student_tasks_controller_spec.rb \
spec/requests/api/v1/responses_controller_spec.rb \
spec/models/task_ordering/base_task_spec.rb \
spec/models/task_ordering/review_task_spec.rb \
spec/models/task_ordering/quiz_task_spec.rb \
spec/models/task_ordering/task_factory_spec.rb \
spec/models/task_ordering/task_queue_spec.rb
</pre>

Expected result: '''77 examples, 0 failures'''

=== Planned Test Suite After Refactor ===

The five <code>spec/models/task_ordering/*</code> files will be deleted alongside the source files they test. They will be replaced by the following:

{| class="wikitable"
! File !! What It Will Cover
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> (extended) || Queue order — quiz before review when both exist; quiz-only when no review maps; review-only when duty disallows quiz; empty queue; <code>next_task</code> returns first incomplete task, then review after quiz submitted, then completion message; <code>start_task</code> blocks when prior task incomplete, rejects map not in queue, rejects map owned by another user, returns 404 for nonexistent map
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> (extended) || POST blocked when prior task incomplete; POST allowed when prerequisites complete; PATCH blocked/allowed under same conditions; ownership checks preserved
|-
| <code>spec/controllers/student_tasks_controller_task_items_spec.rb</code> (new) || <code>QuizTaskItem</code>: reuses existing quiz map for reviewer/reviewee; creates quiz map when questionnaire exists and none is present; returns nil map when questionnaire absent and no existing map; <code>ensure_response!</code> creates record with <code>round: 1</code> and <code>is_submitted: false</code>. <code>ReviewTaskItem</code>: returns the given review map; <code>completed?</code> is true only when a submitted response exists. Shared: <code>to_h</code> always includes the stable payload keys
|}

The following payload keys must remain present and unchanged across all student task endpoints:

* <code>task_type</code>
* <code>assignment_id</code>
* <code>response_map_id</code>
* <code>response_map_type</code>
* <code>reviewee_id</code>
* <code>team_participant_id</code>

Response code contracts that must not regress:

{| class="wikitable"
! Endpoint Group !! Status Codes
|-
| Student Tasks (list, view, queue, next_task, start_task) || 200, 401, 403, 404, 500
|-
| Responses (POST, GET, PATCH) || 201, 200, 401, 403, 404
|}

== Migration Plan ==

The refactor will proceed in four phases to avoid breaking the working implementation at any intermediate step.

=== Phase 1 — Add Inner Task Classes ===

Implement <code>BaseTaskItem</code>, <code>QuizTaskItem</code>, and <code>ReviewTaskItem</code> as inner classes inside <code>StudentTasksController</code>. The existing <code>TaskOrdering</code> module remains untouched. No controller behavior changes in this phase — the new classes exist but are not yet wired in.

=== Phase 2 — Move Orchestration Logic into the Controller ===

Add the private controller methods (<code>resolve_context_for_assignment</code>, <code>resolve_context_for_participant</code>, <code>build_tasks</code>, <code>ensure_response_objects!</code>, <code>find_task_for_map</code>, <code>prior_tasks_complete?</code>) to <code>StudentTasksController</code>. Refactor the <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions to call these methods instead of <code>TaskQueue</code>. Update <code>ResponsesController#enforce_task_order!</code> to use the same logic. Run the full test suite to confirm no regressions before proceeding.

=== Phase 3 — Remove the Legacy Layer ===

Delete:
* <code>app/models/task_ordering/base_task.rb</code>
* <code>app/models/task_ordering/review_task.rb</code>
* <code>app/models/task_ordering/quiz_task.rb</code>
* <code>app/models/task_ordering/task_factory.rb</code>
* <code>app/models/task_ordering/task_queue.rb</code>
* <code>spec/models/task_ordering/base_task_spec.rb</code>
* <code>spec/models/task_ordering/review_task_spec.rb</code>
* <code>spec/models/task_ordering/quiz_task_spec.rb</code>
* <code>spec/models/task_ordering/task_factory_spec.rb</code>
* <code>spec/models/task_ordering/task_queue_spec.rb</code>

=== Phase 4 — Update Tests and Documentation ===

Write the new request specs and the <code>student_tasks_controller_task_items_spec.rb</code> unit spec as described in the [[#Planned Test Suite After Refactor|Planned Test Suite]] section. Update this wiki page to move the "Planned Refactor" content into the past tense once the work is complete.

=== Definition of Done ===

* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.
* Sequencing and gating logic lives in shared <code>StudentTask</code> class methods.
* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>.
* Legacy <code>app/models/task_ordering</code> source files have been removed.

== Demo Video ==

'''Demo Video for Old Implementation:''' https://youtu.be/Zg-fQmIUCSc
'''Demo Video for Refactor:''' https://youtu.be/fhK0roDhT7k

The demo walks through the current (pre-refactor) implementation:
* The <code>TaskOrdering</code> engine enforcing sequential task completion for quiz tasks
* Live API calls to the student tasks endpoints showing queue state and next task resolution
* Response creation flow including JWT authentication, map ownership verification, and task queue enforcement
* Full RSpec test suite run showing all 77 passing examples

== Future Work ==

* Extend <code>build_tasks</code> to support deadline-aware ordering — tasks past their due date could be automatically skipped or flagged
* Add per-question completion tracking for quiz responses, rather than treating a response as binary submitted/not-submitted
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Add new inner task classes to <code>StudentTasksController</code> to support additional response map types as new workflow stages are added to Expertiza
* Add admin endpoints to inspect or manually override a participant's queue state for debugging and support purposes

== References ==

* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* [https://guides.rubyonrails.org Ruby on Rails Guides]
* [https://rspec.info RSpec Documentation]
* [https://github.com/rswag/rswag Rswag GitHub Repository]
* [https://github.com/jwt/ruby-jwt JWT Ruby Gem]

== Team ==

'''Members:'''
* Akhil Kumar
* Dev Patel
* Arnav Mejari

'''Mentor:'''
* Vihar Manojkumar Shah

----
''Last updated: April 2026 | CSC 517, Spring 2026, NCSU''

CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes

2026-04-29T02:29:17Z

Amejari: /* Demo Video */

== Expertiza Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source peer review platform built on '''Ruby on Rails''' and maintained at '''North Carolina State University'''. It is used across multiple courses at NCSU and other universities to facilitate structured peer feedback, team-based assignments, and multi-round review workflows.

In Expertiza, instructors define assignments that walk students through a sequence of tasks — submitting work, reviewing peers, taking quizzes, and providing feedback. The system tracks participants, teams, response maps, and responses across all of these activities.

The ongoing '''reimplementation effort''' modernizes the Expertiza codebase into a clean Rails JSON API backend and a React SPA frontend, with a focus on proper separation of concerns, RESTful conventions, and comprehensive test coverage. Each semester, CSC 517 students contribute targeted reimplementations of specific subsystems as part of their graduate coursework in object-oriented design.

== Project Description ==

This project — '''E2601: Reimplement Student Quizzes''' — focused on the backend infrastructure that governs how students interact with quiz tasks within an assignment workflow. Quizzes in Expertiza are not standalone — they are one task type within a larger ordered sequence that may also include submission, peer review, and feedback stages.

For quizzes to work correctly in this context, three backend systems were built:

* '''A task ordering engine''' — a dedicated <code>TaskOrdering</code> module that knows the correct sequence of tasks for a participant and determines whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' — a <code>StudentTasksController</code> that surfaces the current state of a student's task queue, including which tasks are complete, which is next, and how to start a quiz task
* '''A response management API''' — a <code>ResponsesController</code> that handles the creation and updating of quiz responses with proper authentication, ownership checks, and queue-order enforcement

Without all three of these systems working correctly together, a student could take a quiz before completing required prerequisite tasks, or be blocked from taking a quiz they were legitimately eligible for.

=== Why We Are Refactoring ===

After completing the initial implementation, feedback was received that the <code>TaskOrdering</code> module introduced unnecessary complexity. The module spans five separate files and a dedicated namespace — <code>BaseTask</code>, <code>ReviewTask</code>, <code>QuizTask</code>, <code>TaskFactory</code>, and <code>TaskQueue</code> — yet its logic is only ever called from two controllers. This level of abstraction is harder to trace and maintain than the problem warrants.

The planned refactor will '''remove the <code>TaskOrdering</code> namespace entirely''' and move all sequencing logic directly into <code>StudentTasksController</code> as private methods, supported by two polymorphic inner classes. Every existing API endpoint, response payload shape, and status code will remain unchanged. The refactor is purely an internal structural simplification.

The sections below describe '''what we built first''' and, within each section, '''how it will change''' after the refactor.

== What We Built ==

=== Task Ordering Engine (Current Implementation) ===

We built a self-contained <code>TaskOrdering</code> module under <code>app/models/task_ordering/</code> that encapsulates all logic for determining task eligibility and sequence. This module is intentionally decoupled from controllers — it knows nothing about HTTP requests or responses, only about assignments, participants, and response maps.

The module consists of five classes:

{| class="wikitable"
! Class !! Role
|-
| <code>BaseTask</code> || Abstract base defining the shared interface: <code>complete?</code> and <code>map_id</code>
|-
| <code>ReviewTask</code> || Concrete task for <code>ReviewResponseMap</code> — complete when <code>is_submitted</code> is true
|-
| <code>QuizTask</code> || Concrete task for quiz response maps — the central task type for this project
|-
| <code>TaskFactory</code> || Factory that instantiates the correct task class given a response map
|-
| <code>TaskQueue</code> || Orchestrator that builds and queries the ordered task list for a participant
|}

The <code>TaskQueue</code> is the primary interface that controllers use. Given an assignment and a <code>TeamsParticipant</code>, it answers three questions:

* Is this map part of the participant's task queue? (<code>map_in_queue?</code>)
* Have all tasks before this one been completed? (<code>prior_tasks_complete_for?</code>)
* What is the next task the student should work on? (<code>next_incomplete_task</code>)

==== What Changed ====

The <code>TaskOrdering</code> namespace was removed from the application code. Its orchestration responsibilities now live on <code>StudentTask</code> as shared class methods used by both <code>StudentTasksController</code> and <code>ResponsesController</code>.

<code>BaseTask</code> was replaced by <code>StudentTask::BaseTaskItem</code>. <code>QuizTask</code> and <code>ReviewTask</code> were replaced by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>, implemented as model classes that inherit from <code>StudentTask::BaseTaskItem</code>.

<code>TaskFactory</code> and <code>TaskQueue</code> were eliminated. Their former responsibilities are now handled by <code>StudentTask.build_tasks</code>, <code>StudentTask.find_task_for_map</code>, <code>StudentTask.prior_tasks_complete?</code>, and <code>StudentTask.ensure_response_objects!</code>.

The inner classes will share the following interface via <code>BaseTaskItem</code>:

{| class="wikitable"
! Method !! Purpose
|-
| <code>response_map</code> || Returns the associated response map (creates one for <code>QuizTaskItem</code> if needed)
|-
| <code>ensure_response_map!</code> || Guarantees a response map record exists
|-
| <code>ensure_response!</code> || Creates or finds the <code>Response</code> record (<code>round: 1</code>, <code>is_submitted: false</code> by default)
|-
| <code>completed?</code> || Returns true when a submitted response exists for this map
|-
| <code>to_h</code> || Serializes the task to the same stable JSON payload shape as today
|}

<code>QuizTaskItem</code> will implement <code>response_map</code> as follows: first return a cached map if already loaded; otherwise look for an existing <code>QuizResponseMap</code> by reviewer and reviewee; if none exists and a quiz questionnaire is present, create one with <code>save!(validate: false)</code>; if no questionnaire exists either, return <code>nil</code>. <code>ReviewTaskItem</code> simply returns the <code>ReviewResponseMap</code> it was initialized with.

=== Student Tasks API (Current Implementation) ===

We implemented <code>StudentTasksController</code> with five endpoints that give students full visibility into their task workload:

{| class="wikitable"
! Endpoint !! Method !! What It Returns
|-
| <code>/student_tasks/list</code> || GET || All tasks for the current user across their assignments
|-
| <code>/student_tasks/view</code> || GET || Detailed information for a specific participant task
|-
| <code>/student_tasks/queue</code> || GET || The full ordered task queue for a given assignment
|-
| <code>/student_tasks/next_task</code> || GET || The next incomplete task the student should work on
|-
| <code>/student_tasks/start_task</code> || POST || Attempts to start a task — blocked if prerequisites are incomplete
|}

Currently, every endpoint that involves task ordering resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records and then constructs a <code>TaskQueue</code> instance to answer eligibility questions.

==== What Will Change ====

The <code>list</code>, <code>view</code>, and <code>show</code> actions will remain as-is. The <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions will be refactored to call private controller methods instead of <code>TaskQueue</code>.

'''<code>queue</code> after refactor:'''
# Call <code>resolve_context_for_assignment(params[:assignment_id])</code> to obtain participant, team membership, assignment, and duty. Return 404 if the participant cannot be found.
# Call <code>build_tasks(context)</code> to construct the ordered task list.
# Call <code>ensure_response_objects!(tasks)</code> to guarantee response maps and response records exist for every task.
# Render <code>tasks.map(&:to_h)</code> as JSON.

'''<code>next_task</code> after refactor:'''
# Resolve context and build tasks as above.
# Find the first task where <code>completed?</code> returns false.
# Render that task's <code>to_h</code> payload, or render <code>{ message: "All tasks completed" }</code> if all tasks are done.

'''<code>start_task</code> after refactor:'''
# Find the <code>ResponseMap</code> by <code>params[:response_map_id]</code>. Return 404 if not found.
# Verify <code>map.reviewer.user_id == current_user.id</code>. Return 403 if not.
# Call <code>resolve_context_for_participant(map.reviewer)</code> to build the context.
# Call <code>build_tasks(context)</code> and locate the task for this map via <code>find_task_for_map(tasks, map.id)</code>. Return 404 if the map is not in the participant's queue.
# Call <code>prior_tasks_complete?(tasks, current_task)</code>. Return 403 with "Complete previous task first" if any earlier task is still incomplete.
# Call <code>current_task.ensure_response!</code> and render the task payload.

The key private methods introduced are:

{| class="wikitable"
! Method !! Role
|-
| <code>StudentTask.resolve_context_for_assignment(user, assignment_id)</code> || Finds the participant for the current user and assignment, then resolves the team participant and duty
|-
| <code>StudentTask.resolve_context_for_participant(participant)</code> || Builds the same task context starting from a known participant
|-
| <code>StudentTask.build_tasks(context)</code> || Builds the ordered quiz/review task list
|-
| <code>StudentTask.ensure_response_objects!(tasks)</code> || Ensures response maps and response records exist
|-
| <code>StudentTask.find_task_for_map(tasks, map_id)</code> || Finds the task associated with a response map
|-
| <code>StudentTask.prior_tasks_complete?(tasks, current_task)</code> || Checks whether all earlier tasks are submitted
|}

Task ordering rules in <code>build_tasks</code> will be: if review maps exist, append a <code>QuizTaskItem</code> first (when duty allows and a quiz questionnaire or existing quiz map is present) then a <code>ReviewTaskItem</code> (when duty allows); if no review maps exist, append a quiz-only <code>QuizTaskItem</code> when duty allows and a questionnaire exists. Duty permissions are resolved as: <code>duty_allows_quiz?</code> is true for participant, reader, and mentor roles; <code>duty_allows_review?</code> is true for participant, reader, reviewer, and mentor roles.

=== Response Management API (Current Implementation) ===

We implemented <code>ResponsesController</code> with three endpoints that handle quiz and review response lifecycle:

{| class="wikitable"
! Endpoint !! Method !! What It Does
|-
| <code>/responses</code> || POST || Creates a new response for a quiz or review map
|-
| <code>/responses/:id</code> || GET || Retrieves a specific response
|-
| <code>/responses/:id</code> || PATCH || Updates an existing response
|}

Response creation currently enforces two layers of protection before any data is written:

# '''Ownership check''' — the requesting user must be the reviewer assigned to the response map
# '''Queue order check''' — <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

==== What Changed ====

The <code>GET</code> endpoint is unaffected. The <code>POST</code> and <code>PATCH</code> endpoints now both call <code>enforce_task_order!</code>, which reuses the shared <code>StudentTask</code> task-building and prerequisite-checking methods.
== Technical Deep Dive ==

=== How Task Ordering Works (Current) ===

When a student attempts to start a quiz task or create a response today, the following sequence occurs:

<pre>
StudentTasksController or ResponsesController
|
| TaskQueue.new(assignment, teams_participant)
v
TaskQueue
→ fetches all ResponseMaps for this participant
→ calls TaskFactory.build(map) for each
→ builds ordered array of BaseTask subclass instances
|
| queue.prior_tasks_complete_for?(map_id)
v
→ iterates tasks in order
→ for each task before the target, calls task.complete?
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

=== How Task Sequencing Will Work After the Refactor ===

The same logical flow will execute, but entirely inside the controller with no external module:

<pre>
StudentTasksController or ResponsesController
|
| resolve_context_for_assignment(assignment_id)
v
→ finds AssignmentParticipant by current_user + assignment_id
→ finds TeamsParticipant by participant_id
→ resolves duty (team_participant.duty_id fallback to participant.duty_id)
|
| build_tasks(context)
v
→ queries ReviewResponseMaps for this participant
→ loads quiz questionnaire via assignment.quiz_questionnaire_for_review_flow
→ checks for existing QuizResponseMaps
→ instantiates QuizTaskItem / ReviewTaskItem in correct order
|
| prior_tasks_complete?(tasks, current_task)
v
→ iterates tasks before the target
→ calls task.completed? on each
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

The outcome for every request — which status codes are returned, which tasks are blocked, what JSON is rendered — is identical to today. Only the internal path through the code changes.

=== How Authentication and Authorization Are Layered ===

This layer is unchanged by the refactor. All requests pass through two concerns registered in <code>ApplicationController</code> before reaching any controller logic:

<pre>
Incoming Request
|
v
JwtToken concern → authenticate_request!
→ reads Authorization: Bearer <token> header
→ decodes token using RSA public key
→ sets @current_user via User.find(auth_token[:id])
→ halts with 401 if token missing, expired, or invalid
|
v
Authorization concern → authorize
→ calls all_actions_allowed?
→ checks super-admin privileges OR action_allowed?
→ halts with 403 if not permitted
|
v
Controller before_actions (e.g. find_and_authorize_map_for_create)
→ map-level ownership checks using current_user
|
v
Controller action
</pre>

The critical constraint is that <code>find_and_authorize_map_for_create</code> must remain a standard <code>before_action</code> — not a <code>prepend_before_action</code> — so that <code>current_user</code> is always populated by the time ownership checks run.

=== Round-Aware Response Handling ===

This behavior is unchanged by the refactor. When a response is created, the controller scopes its lookup by both <code>map_id</code> and <code>round</code>:

<pre>
Response.where(map_id: @map.id, round: round)
.order(:created_at)
.last || Response.new(map_id: @map.id, round: round)
</pre>

If a response already exists for this map and round, it is updated in place. If none exists, a new one is initialized. This supports quiz retakes and multi-round review scenarios.

== Design Decisions ==

=== Original Design: Separation of Task Logic into a Dedicated Module ===

The initial implementation encapsulated all task sequencing and eligibility logic within the <code>TaskOrdering</code> module, entirely decoupled from controllers. The reasoning was that controllers should only handle HTTP concerns, while task logic should be independently testable as a pure domain model.

The <code>TaskFactory</code> was introduced so that the correct task class could be instantiated from any response map type without conditional logic in controllers. The <code>TaskQueue</code> served as the single orchestration point so that the same ordering rules were guaranteed to apply whether a student was viewing their queue, starting a task, or submitting a response.

=== Why the Design Is Being Simplified ===

In practice, the <code>TaskOrdering</code> module is only ever called from <code>StudentTasksController</code> and <code>ResponsesController</code>. There are no background jobs, rake tasks, or alternative interfaces that reuse it. The five-file namespace therefore adds indirection without providing the reuse benefits that would justify it.

The refactor recognizes that '''polymorphism belongs where it helps''' — quiz and review tasks genuinely behave differently, so inner classes are still the right tool. But '''orchestration does not need its own namespace''' — a set of private controller methods is simpler to read, easier to test through the request layer, and just as correct.

=== Refactored Design: Controller-Owned Orchestration with Inner Classes ===

After the refactor, the design will follow these principles:

* '''Single orchestration owner''' — all task sequencing decisions flow through one set of private methods in <code>StudentTasksController</code>. <code>ResponsesController</code> will reuse the same logic via a shared concern or equivalent private methods.
* '''Polymorphism without over-engineering''' — <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> are inner classes that share a <code>BaseTaskItem</code> interface. The difference in behavior is encapsulated; the orchestration logic treats both identically.
* '''No extra namespace''' — everything lives in <code>app/controllers/student_tasks_controller.rb</code>. A developer reading the <code>queue</code> action can follow the entire flow without opening any other file.
* '''High cohesion''' — task lifecycle behavior (response map creation, response initialization, completion detection, serialization) is grouped with the task objects themselves.
* '''Low coupling''' — the controller works against the shared <code>BaseTaskItem</code> interface, so adding a new task type requires only a new inner class with no changes to orchestration methods.

=== Layered Authorization and Validation ===

This decision is unchanged. Validation is enforced at three distinct layers: JWT authentication globally in <code>ApplicationController</code>, role-level authorization via the <code>authorize</code> concern, and map-level ownership checks as controller <code>before_action</code> callbacks. Task-order enforcement is the final layer, applied inside the action itself. This defense-in-depth approach remains intact after the refactor.

=== Round-Aware Response Handling ===

Unchanged. Responses continue to be scoped by <code>map_id</code> and <code>round</code>, with update-in-place semantics for existing records.

=== Emphasis on RESTful and Stateless Design ===

Unchanged. All endpoints remain resource-based with JWT authentication, compatible with the React frontend and stateless horizontal scaling.

== Test Coverage ==

=== Current Test Suite ===

The initial implementation is covered by 77 passing examples across model and request specs:

{| class="wikitable"
! File !! Key Scenarios Tested
|-
| <code>spec/models/task_ordering/base_task_spec.rb</code> || Default <code>complete?</code> behavior, <code>map_id</code> delegation, interface contract
|-
| <code>spec/models/task_ordering/review_task_spec.rb</code> || Completion based on <code>is_submitted</code>, incomplete when not submitted
|-
| <code>spec/models/task_ordering/quiz_task_spec.rb</code> || Quiz-specific completion detection and eligibility
|-
| <code>spec/models/task_ordering/task_factory_spec.rb</code> || Correct class returned for each map type, error on unknown type
|-
| <code>spec/models/task_ordering/task_queue_spec.rb</code> || Queue ordering, <code>map_in_queue?</code>, <code>prior_tasks_complete_for?</code>, <code>next_incomplete_task</code>
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task — response codes 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST, GET, PATCH /responses — response codes 201, 200, 401, 403, 404
|}

To run the current suite:

<pre>
bundle exec rspec \
spec/requests/api/v1/student_tasks_controller_spec.rb \
spec/requests/api/v1/responses_controller_spec.rb \
spec/models/task_ordering/base_task_spec.rb \
spec/models/task_ordering/review_task_spec.rb \
spec/models/task_ordering/quiz_task_spec.rb \
spec/models/task_ordering/task_factory_spec.rb \
spec/models/task_ordering/task_queue_spec.rb
</pre>

Expected result: '''77 examples, 0 failures'''

=== Planned Test Suite After Refactor ===

The five <code>spec/models/task_ordering/*</code> files will be deleted alongside the source files they test. They will be replaced by the following:

{| class="wikitable"
! File !! What It Will Cover
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> (extended) || Queue order — quiz before review when both exist; quiz-only when no review maps; review-only when duty disallows quiz; empty queue; <code>next_task</code> returns first incomplete task, then review after quiz submitted, then completion message; <code>start_task</code> blocks when prior task incomplete, rejects map not in queue, rejects map owned by another user, returns 404 for nonexistent map
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> (extended) || POST blocked when prior task incomplete; POST allowed when prerequisites complete; PATCH blocked/allowed under same conditions; ownership checks preserved
|-
| <code>spec/controllers/student_tasks_controller_task_items_spec.rb</code> (new) || <code>QuizTaskItem</code>: reuses existing quiz map for reviewer/reviewee; creates quiz map when questionnaire exists and none is present; returns nil map when questionnaire absent and no existing map; <code>ensure_response!</code> creates record with <code>round: 1</code> and <code>is_submitted: false</code>. <code>ReviewTaskItem</code>: returns the given review map; <code>completed?</code> is true only when a submitted response exists. Shared: <code>to_h</code> always includes the stable payload keys
|}

The following payload keys must remain present and unchanged across all student task endpoints:

* <code>task_type</code>
* <code>assignment_id</code>
* <code>response_map_id</code>
* <code>response_map_type</code>
* <code>reviewee_id</code>
* <code>team_participant_id</code>

Response code contracts that must not regress:

{| class="wikitable"
! Endpoint Group !! Status Codes
|-
| Student Tasks (list, view, queue, next_task, start_task) || 200, 401, 403, 404, 500
|-
| Responses (POST, GET, PATCH) || 201, 200, 401, 403, 404
|}

== Migration Plan ==

The refactor will proceed in four phases to avoid breaking the working implementation at any intermediate step.

=== Phase 1 — Add Inner Task Classes ===

Implement <code>BaseTaskItem</code>, <code>QuizTaskItem</code>, and <code>ReviewTaskItem</code> as inner classes inside <code>StudentTasksController</code>. The existing <code>TaskOrdering</code> module remains untouched. No controller behavior changes in this phase — the new classes exist but are not yet wired in.

=== Phase 2 — Move Orchestration Logic into the Controller ===

Add the private controller methods (<code>resolve_context_for_assignment</code>, <code>resolve_context_for_participant</code>, <code>build_tasks</code>, <code>ensure_response_objects!</code>, <code>find_task_for_map</code>, <code>prior_tasks_complete?</code>) to <code>StudentTasksController</code>. Refactor the <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions to call these methods instead of <code>TaskQueue</code>. Update <code>ResponsesController#enforce_task_order!</code> to use the same logic. Run the full test suite to confirm no regressions before proceeding.

=== Phase 3 — Remove the Legacy Layer ===

Delete:
* <code>app/models/task_ordering/base_task.rb</code>
* <code>app/models/task_ordering/review_task.rb</code>
* <code>app/models/task_ordering/quiz_task.rb</code>
* <code>app/models/task_ordering/task_factory.rb</code>
* <code>app/models/task_ordering/task_queue.rb</code>
* <code>spec/models/task_ordering/base_task_spec.rb</code>
* <code>spec/models/task_ordering/review_task_spec.rb</code>
* <code>spec/models/task_ordering/quiz_task_spec.rb</code>
* <code>spec/models/task_ordering/task_factory_spec.rb</code>
* <code>spec/models/task_ordering/task_queue_spec.rb</code>

=== Phase 4 — Update Tests and Documentation ===

Write the new request specs and the <code>student_tasks_controller_task_items_spec.rb</code> unit spec as described in the [[#Planned Test Suite After Refactor|Planned Test Suite]] section. Update <code>docs/POSTMAN_STUDENT_TASKS.md</code> if any wording references <code>TaskOrdering</code>. Update this wiki page to move the "Planned Refactor" content into the past tense once the work is complete.

=== Definition of Done ===

* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.
* Sequencing and gating logic lives in shared <code>StudentTask</code> class methods.
* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>.
* Legacy <code>app/models/task_ordering</code> source files have been removed.

== Demo Video ==

'''Demo Video for Old Implementation:''' https://youtu.be/Zg-fQmIUCSc
'''Demo Video for Refactor:''' https://youtu.be/fhK0roDhT7k

The demo walks through the current (pre-refactor) implementation:
* The <code>TaskOrdering</code> engine enforcing sequential task completion for quiz tasks
* Live API calls to the student tasks endpoints showing queue state and next task resolution
* Response creation flow including JWT authentication, map ownership verification, and task queue enforcement
* Full RSpec test suite run showing all 77 passing examples

== Future Work ==

* Extend <code>build_tasks</code> to support deadline-aware ordering — tasks past their due date could be automatically skipped or flagged
* Add per-question completion tracking for quiz responses, rather than treating a response as binary submitted/not-submitted
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Add new inner task classes to <code>StudentTasksController</code> to support additional response map types as new workflow stages are added to Expertiza
* Add admin endpoints to inspect or manually override a participant's queue state for debugging and support purposes

== References ==

* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* [https://guides.rubyonrails.org Ruby on Rails Guides]
* [https://rspec.info RSpec Documentation]
* [https://github.com/rswag/rswag Rswag GitHub Repository]
* [https://github.com/jwt/ruby-jwt JWT Ruby Gem]

== Team ==

'''Members:'''
* Akhil Kumar
* Dev Patel
* Arnav Mejari

'''Mentor:'''
* Vihar Manojkumar Shah

----
''Last updated: April 2026 | CSC 517, Spring 2026, NCSU''

CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes

2026-04-29T01:57:25Z

Amejari:

== Expertiza Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source peer review platform built on '''Ruby on Rails''' and maintained at '''North Carolina State University'''. It is used across multiple courses at NCSU and other universities to facilitate structured peer feedback, team-based assignments, and multi-round review workflows.

In Expertiza, instructors define assignments that walk students through a sequence of tasks — submitting work, reviewing peers, taking quizzes, and providing feedback. The system tracks participants, teams, response maps, and responses across all of these activities.

The ongoing '''reimplementation effort''' modernizes the Expertiza codebase into a clean Rails JSON API backend and a React SPA frontend, with a focus on proper separation of concerns, RESTful conventions, and comprehensive test coverage. Each semester, CSC 517 students contribute targeted reimplementations of specific subsystems as part of their graduate coursework in object-oriented design.

== Project Description ==

This project — '''E2601: Reimplement Student Quizzes''' — focused on the backend infrastructure that governs how students interact with quiz tasks within an assignment workflow. Quizzes in Expertiza are not standalone — they are one task type within a larger ordered sequence that may also include submission, peer review, and feedback stages.

For quizzes to work correctly in this context, three backend systems were built:

* '''A task ordering engine''' — a dedicated <code>TaskOrdering</code> module that knows the correct sequence of tasks for a participant and determines whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' — a <code>StudentTasksController</code> that surfaces the current state of a student's task queue, including which tasks are complete, which is next, and how to start a quiz task
* '''A response management API''' — a <code>ResponsesController</code> that handles the creation and updating of quiz responses with proper authentication, ownership checks, and queue-order enforcement

Without all three of these systems working correctly together, a student could take a quiz before completing required prerequisite tasks, or be blocked from taking a quiz they were legitimately eligible for.

=== Why We Are Refactoring ===

After completing the initial implementation, feedback was received that the <code>TaskOrdering</code> module introduced unnecessary complexity. The module spans five separate files and a dedicated namespace — <code>BaseTask</code>, <code>ReviewTask</code>, <code>QuizTask</code>, <code>TaskFactory</code>, and <code>TaskQueue</code> — yet its logic is only ever called from two controllers. This level of abstraction is harder to trace and maintain than the problem warrants.

The planned refactor will '''remove the <code>TaskOrdering</code> namespace entirely''' and move all sequencing logic directly into <code>StudentTasksController</code> as private methods, supported by two polymorphic inner classes. Every existing API endpoint, response payload shape, and status code will remain unchanged. The refactor is purely an internal structural simplification.

The sections below describe '''what we built first''' and, within each section, '''how it will change''' after the refactor.

== What We Built ==

=== Task Ordering Engine (Current Implementation) ===

We built a self-contained <code>TaskOrdering</code> module under <code>app/models/task_ordering/</code> that encapsulates all logic for determining task eligibility and sequence. This module is intentionally decoupled from controllers — it knows nothing about HTTP requests or responses, only about assignments, participants, and response maps.

The module consists of five classes:

{| class="wikitable"
! Class !! Role
|-
| <code>BaseTask</code> || Abstract base defining the shared interface: <code>complete?</code> and <code>map_id</code>
|-
| <code>ReviewTask</code> || Concrete task for <code>ReviewResponseMap</code> — complete when <code>is_submitted</code> is true
|-
| <code>QuizTask</code> || Concrete task for quiz response maps — the central task type for this project
|-
| <code>TaskFactory</code> || Factory that instantiates the correct task class given a response map
|-
| <code>TaskQueue</code> || Orchestrator that builds and queries the ordered task list for a participant
|}

The <code>TaskQueue</code> is the primary interface that controllers use. Given an assignment and a <code>TeamsParticipant</code>, it answers three questions:

* Is this map part of the participant's task queue? (<code>map_in_queue?</code>)
* Have all tasks before this one been completed? (<code>prior_tasks_complete_for?</code>)
* What is the next task the student should work on? (<code>next_incomplete_task</code>)

==== What Changed ====

The <code>TaskOrdering</code> namespace was removed from the application code. Its orchestration responsibilities now live on <code>StudentTask</code> as shared class methods used by both <code>StudentTasksController</code> and <code>ResponsesController</code>.

<code>BaseTask</code> was replaced by <code>StudentTask::BaseTaskItem</code>. <code>QuizTask</code> and <code>ReviewTask</code> were replaced by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>, implemented as model classes that inherit from <code>StudentTask::BaseTaskItem</code>.

<code>TaskFactory</code> and <code>TaskQueue</code> were eliminated. Their former responsibilities are now handled by <code>StudentTask.build_tasks</code>, <code>StudentTask.find_task_for_map</code>, <code>StudentTask.prior_tasks_complete?</code>, and <code>StudentTask.ensure_response_objects!</code>.

The inner classes will share the following interface via <code>BaseTaskItem</code>:

{| class="wikitable"
! Method !! Purpose
|-
| <code>response_map</code> || Returns the associated response map (creates one for <code>QuizTaskItem</code> if needed)
|-
| <code>ensure_response_map!</code> || Guarantees a response map record exists
|-
| <code>ensure_response!</code> || Creates or finds the <code>Response</code> record (<code>round: 1</code>, <code>is_submitted: false</code> by default)
|-
| <code>completed?</code> || Returns true when a submitted response exists for this map
|-
| <code>to_h</code> || Serializes the task to the same stable JSON payload shape as today
|}

<code>QuizTaskItem</code> will implement <code>response_map</code> as follows: first return a cached map if already loaded; otherwise look for an existing <code>QuizResponseMap</code> by reviewer and reviewee; if none exists and a quiz questionnaire is present, create one with <code>save!(validate: false)</code>; if no questionnaire exists either, return <code>nil</code>. <code>ReviewTaskItem</code> simply returns the <code>ReviewResponseMap</code> it was initialized with.

=== Student Tasks API (Current Implementation) ===

We implemented <code>StudentTasksController</code> with five endpoints that give students full visibility into their task workload:

{| class="wikitable"
! Endpoint !! Method !! What It Returns
|-
| <code>/student_tasks/list</code> || GET || All tasks for the current user across their assignments
|-
| <code>/student_tasks/view</code> || GET || Detailed information for a specific participant task
|-
| <code>/student_tasks/queue</code> || GET || The full ordered task queue for a given assignment
|-
| <code>/student_tasks/next_task</code> || GET || The next incomplete task the student should work on
|-
| <code>/student_tasks/start_task</code> || POST || Attempts to start a task — blocked if prerequisites are incomplete
|}

Currently, every endpoint that involves task ordering resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records and then constructs a <code>TaskQueue</code> instance to answer eligibility questions.

==== What Will Change ====

The <code>list</code>, <code>view</code>, and <code>show</code> actions will remain as-is. The <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions will be refactored to call private controller methods instead of <code>TaskQueue</code>.

'''<code>queue</code> after refactor:'''
# Call <code>resolve_context_for_assignment(params[:assignment_id])</code> to obtain participant, team membership, assignment, and duty. Return 404 if the participant cannot be found.
# Call <code>build_tasks(context)</code> to construct the ordered task list.
# Call <code>ensure_response_objects!(tasks)</code> to guarantee response maps and response records exist for every task.
# Render <code>tasks.map(&:to_h)</code> as JSON.

'''<code>next_task</code> after refactor:'''
# Resolve context and build tasks as above.
# Find the first task where <code>completed?</code> returns false.
# Render that task's <code>to_h</code> payload, or render <code>{ message: "All tasks completed" }</code> if all tasks are done.

'''<code>start_task</code> after refactor:'''
# Find the <code>ResponseMap</code> by <code>params[:response_map_id]</code>. Return 404 if not found.
# Verify <code>map.reviewer.user_id == current_user.id</code>. Return 403 if not.
# Call <code>resolve_context_for_participant(map.reviewer)</code> to build the context.
# Call <code>build_tasks(context)</code> and locate the task for this map via <code>find_task_for_map(tasks, map.id)</code>. Return 404 if the map is not in the participant's queue.
# Call <code>prior_tasks_complete?(tasks, current_task)</code>. Return 403 with "Complete previous task first" if any earlier task is still incomplete.
# Call <code>current_task.ensure_response!</code> and render the task payload.

The key private methods introduced are:

{| class="wikitable"
! Method !! Role
|-
| <code>StudentTask.resolve_context_for_assignment(user, assignment_id)</code> || Finds the participant for the current user and assignment, then resolves the team participant and duty
|-
| <code>StudentTask.resolve_context_for_participant(participant)</code> || Builds the same task context starting from a known participant
|-
| <code>StudentTask.build_tasks(context)</code> || Builds the ordered quiz/review task list
|-
| <code>StudentTask.ensure_response_objects!(tasks)</code> || Ensures response maps and response records exist
|-
| <code>StudentTask.find_task_for_map(tasks, map_id)</code> || Finds the task associated with a response map
|-
| <code>StudentTask.prior_tasks_complete?(tasks, current_task)</code> || Checks whether all earlier tasks are submitted
|}

Task ordering rules in <code>build_tasks</code> will be: if review maps exist, append a <code>QuizTaskItem</code> first (when duty allows and a quiz questionnaire or existing quiz map is present) then a <code>ReviewTaskItem</code> (when duty allows); if no review maps exist, append a quiz-only <code>QuizTaskItem</code> when duty allows and a questionnaire exists. Duty permissions are resolved as: <code>duty_allows_quiz?</code> is true for participant, reader, and mentor roles; <code>duty_allows_review?</code> is true for participant, reader, reviewer, and mentor roles.

=== Response Management API (Current Implementation) ===

We implemented <code>ResponsesController</code> with three endpoints that handle quiz and review response lifecycle:

{| class="wikitable"
! Endpoint !! Method !! What It Does
|-
| <code>/responses</code> || POST || Creates a new response for a quiz or review map
|-
| <code>/responses/:id</code> || GET || Retrieves a specific response
|-
| <code>/responses/:id</code> || PATCH || Updates an existing response
|}

Response creation currently enforces two layers of protection before any data is written:

# '''Ownership check''' — the requesting user must be the reviewer assigned to the response map
# '''Queue order check''' — <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

==== What Changed ====

The <code>GET</code> endpoint is unaffected. The <code>POST</code> and <code>PATCH</code> endpoints now both call <code>enforce_task_order!</code>, which reuses the shared <code>StudentTask</code> task-building and prerequisite-checking methods.
== Technical Deep Dive ==

=== How Task Ordering Works (Current) ===

When a student attempts to start a quiz task or create a response today, the following sequence occurs:

<pre>
StudentTasksController or ResponsesController
|
| TaskQueue.new(assignment, teams_participant)
v
TaskQueue
→ fetches all ResponseMaps for this participant
→ calls TaskFactory.build(map) for each
→ builds ordered array of BaseTask subclass instances
|
| queue.prior_tasks_complete_for?(map_id)
v
→ iterates tasks in order
→ for each task before the target, calls task.complete?
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

=== How Task Sequencing Will Work After the Refactor ===

The same logical flow will execute, but entirely inside the controller with no external module:

<pre>
StudentTasksController or ResponsesController
|
| resolve_context_for_assignment(assignment_id)
v
→ finds AssignmentParticipant by current_user + assignment_id
→ finds TeamsParticipant by participant_id
→ resolves duty (team_participant.duty_id fallback to participant.duty_id)
|
| build_tasks(context)
v
→ queries ReviewResponseMaps for this participant
→ loads quiz questionnaire via assignment.quiz_questionnaire_for_review_flow
→ checks for existing QuizResponseMaps
→ instantiates QuizTaskItem / ReviewTaskItem in correct order
|
| prior_tasks_complete?(tasks, current_task)
v
→ iterates tasks before the target
→ calls task.completed? on each
→ returns false if any prior task is incomplete
|
v
Controller either proceeds or renders 403/428
</pre>

The outcome for every request — which status codes are returned, which tasks are blocked, what JSON is rendered — is identical to today. Only the internal path through the code changes.

=== How Authentication and Authorization Are Layered ===

This layer is unchanged by the refactor. All requests pass through two concerns registered in <code>ApplicationController</code> before reaching any controller logic:

<pre>
Incoming Request
|
v
JwtToken concern → authenticate_request!
→ reads Authorization: Bearer <token> header
→ decodes token using RSA public key
→ sets @current_user via User.find(auth_token[:id])
→ halts with 401 if token missing, expired, or invalid
|
v
Authorization concern → authorize
→ calls all_actions_allowed?
→ checks super-admin privileges OR action_allowed?
→ halts with 403 if not permitted
|
v
Controller before_actions (e.g. find_and_authorize_map_for_create)
→ map-level ownership checks using current_user
|
v
Controller action
</pre>

The critical constraint is that <code>find_and_authorize_map_for_create</code> must remain a standard <code>before_action</code> — not a <code>prepend_before_action</code> — so that <code>current_user</code> is always populated by the time ownership checks run.

=== Round-Aware Response Handling ===

This behavior is unchanged by the refactor. When a response is created, the controller scopes its lookup by both <code>map_id</code> and <code>round</code>:

<pre>
Response.where(map_id: @map.id, round: round)
.order(:created_at)
.last || Response.new(map_id: @map.id, round: round)
</pre>

If a response already exists for this map and round, it is updated in place. If none exists, a new one is initialized. This supports quiz retakes and multi-round review scenarios.

== Design Decisions ==

=== Original Design: Separation of Task Logic into a Dedicated Module ===

The initial implementation encapsulated all task sequencing and eligibility logic within the <code>TaskOrdering</code> module, entirely decoupled from controllers. The reasoning was that controllers should only handle HTTP concerns, while task logic should be independently testable as a pure domain model.

The <code>TaskFactory</code> was introduced so that the correct task class could be instantiated from any response map type without conditional logic in controllers. The <code>TaskQueue</code> served as the single orchestration point so that the same ordering rules were guaranteed to apply whether a student was viewing their queue, starting a task, or submitting a response.

=== Why the Design Is Being Simplified ===

In practice, the <code>TaskOrdering</code> module is only ever called from <code>StudentTasksController</code> and <code>ResponsesController</code>. There are no background jobs, rake tasks, or alternative interfaces that reuse it. The five-file namespace therefore adds indirection without providing the reuse benefits that would justify it.

The refactor recognizes that '''polymorphism belongs where it helps''' — quiz and review tasks genuinely behave differently, so inner classes are still the right tool. But '''orchestration does not need its own namespace''' — a set of private controller methods is simpler to read, easier to test through the request layer, and just as correct.

=== Refactored Design: Controller-Owned Orchestration with Inner Classes ===

After the refactor, the design will follow these principles:

* '''Single orchestration owner''' — all task sequencing decisions flow through one set of private methods in <code>StudentTasksController</code>. <code>ResponsesController</code> will reuse the same logic via a shared concern or equivalent private methods.
* '''Polymorphism without over-engineering''' — <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> are inner classes that share a <code>BaseTaskItem</code> interface. The difference in behavior is encapsulated; the orchestration logic treats both identically.
* '''No extra namespace''' — everything lives in <code>app/controllers/student_tasks_controller.rb</code>. A developer reading the <code>queue</code> action can follow the entire flow without opening any other file.
* '''High cohesion''' — task lifecycle behavior (response map creation, response initialization, completion detection, serialization) is grouped with the task objects themselves.
* '''Low coupling''' — the controller works against the shared <code>BaseTaskItem</code> interface, so adding a new task type requires only a new inner class with no changes to orchestration methods.

=== Layered Authorization and Validation ===

This decision is unchanged. Validation is enforced at three distinct layers: JWT authentication globally in <code>ApplicationController</code>, role-level authorization via the <code>authorize</code> concern, and map-level ownership checks as controller <code>before_action</code> callbacks. Task-order enforcement is the final layer, applied inside the action itself. This defense-in-depth approach remains intact after the refactor.

=== Round-Aware Response Handling ===

Unchanged. Responses continue to be scoped by <code>map_id</code> and <code>round</code>, with update-in-place semantics for existing records.

=== Emphasis on RESTful and Stateless Design ===

Unchanged. All endpoints remain resource-based with JWT authentication, compatible with the React frontend and stateless horizontal scaling.

== Test Coverage ==

=== Current Test Suite ===

The initial implementation is covered by 77 passing examples across model and request specs:

{| class="wikitable"
! File !! Key Scenarios Tested
|-
| <code>spec/models/task_ordering/base_task_spec.rb</code> || Default <code>complete?</code> behavior, <code>map_id</code> delegation, interface contract
|-
| <code>spec/models/task_ordering/review_task_spec.rb</code> || Completion based on <code>is_submitted</code>, incomplete when not submitted
|-
| <code>spec/models/task_ordering/quiz_task_spec.rb</code> || Quiz-specific completion detection and eligibility
|-
| <code>spec/models/task_ordering/task_factory_spec.rb</code> || Correct class returned for each map type, error on unknown type
|-
| <code>spec/models/task_ordering/task_queue_spec.rb</code> || Queue ordering, <code>map_in_queue?</code>, <code>prior_tasks_complete_for?</code>, <code>next_incomplete_task</code>
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task — response codes 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST, GET, PATCH /responses — response codes 201, 200, 401, 403, 404
|}

To run the current suite:

<pre>
bundle exec rspec \
spec/requests/api/v1/student_tasks_controller_spec.rb \
spec/requests/api/v1/responses_controller_spec.rb \
spec/models/task_ordering/base_task_spec.rb \
spec/models/task_ordering/review_task_spec.rb \
spec/models/task_ordering/quiz_task_spec.rb \
spec/models/task_ordering/task_factory_spec.rb \
spec/models/task_ordering/task_queue_spec.rb
</pre>

Expected result: '''77 examples, 0 failures'''

=== Planned Test Suite After Refactor ===

The five <code>spec/models/task_ordering/*</code> files will be deleted alongside the source files they test. They will be replaced by the following:

{| class="wikitable"
! File !! What It Will Cover
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> (extended) || Queue order — quiz before review when both exist; quiz-only when no review maps; review-only when duty disallows quiz; empty queue; <code>next_task</code> returns first incomplete task, then review after quiz submitted, then completion message; <code>start_task</code> blocks when prior task incomplete, rejects map not in queue, rejects map owned by another user, returns 404 for nonexistent map
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> (extended) || POST blocked when prior task incomplete; POST allowed when prerequisites complete; PATCH blocked/allowed under same conditions; ownership checks preserved
|-
| <code>spec/controllers/student_tasks_controller_task_items_spec.rb</code> (new) || <code>QuizTaskItem</code>: reuses existing quiz map for reviewer/reviewee; creates quiz map when questionnaire exists and none is present; returns nil map when questionnaire absent and no existing map; <code>ensure_response!</code> creates record with <code>round: 1</code> and <code>is_submitted: false</code>. <code>ReviewTaskItem</code>: returns the given review map; <code>completed?</code> is true only when a submitted response exists. Shared: <code>to_h</code> always includes the stable payload keys
|}

The following payload keys must remain present and unchanged across all student task endpoints:

* <code>task_type</code>
* <code>assignment_id</code>
* <code>response_map_id</code>
* <code>response_map_type</code>
* <code>reviewee_id</code>
* <code>team_participant_id</code>

Response code contracts that must not regress:

{| class="wikitable"
! Endpoint Group !! Status Codes
|-
| Student Tasks (list, view, queue, next_task, start_task) || 200, 401, 403, 404, 500
|-
| Responses (POST, GET, PATCH) || 201, 200, 401, 403, 404
|}

== Migration Plan ==

The refactor will proceed in four phases to avoid breaking the working implementation at any intermediate step.

=== Phase 1 — Add Inner Task Classes ===

Implement <code>BaseTaskItem</code>, <code>QuizTaskItem</code>, and <code>ReviewTaskItem</code> as inner classes inside <code>StudentTasksController</code>. The existing <code>TaskOrdering</code> module remains untouched. No controller behavior changes in this phase — the new classes exist but are not yet wired in.

=== Phase 2 — Move Orchestration Logic into the Controller ===

Add the private controller methods (<code>resolve_context_for_assignment</code>, <code>resolve_context_for_participant</code>, <code>build_tasks</code>, <code>ensure_response_objects!</code>, <code>find_task_for_map</code>, <code>prior_tasks_complete?</code>) to <code>StudentTasksController</code>. Refactor the <code>queue</code>, <code>next_task</code>, and <code>start_task</code> actions to call these methods instead of <code>TaskQueue</code>. Update <code>ResponsesController#enforce_task_order!</code> to use the same logic. Run the full test suite to confirm no regressions before proceeding.

=== Phase 3 — Remove the Legacy Layer ===

Delete:
* <code>app/models/task_ordering/base_task.rb</code>
* <code>app/models/task_ordering/review_task.rb</code>
* <code>app/models/task_ordering/quiz_task.rb</code>
* <code>app/models/task_ordering/task_factory.rb</code>
* <code>app/models/task_ordering/task_queue.rb</code>
* <code>spec/models/task_ordering/base_task_spec.rb</code>
* <code>spec/models/task_ordering/review_task_spec.rb</code>
* <code>spec/models/task_ordering/quiz_task_spec.rb</code>
* <code>spec/models/task_ordering/task_factory_spec.rb</code>
* <code>spec/models/task_ordering/task_queue_spec.rb</code>

=== Phase 4 — Update Tests and Documentation ===

Write the new request specs and the <code>student_tasks_controller_task_items_spec.rb</code> unit spec as described in the [[#Planned Test Suite After Refactor|Planned Test Suite]] section. Update <code>docs/POSTMAN_STUDENT_TASKS.md</code> if any wording references <code>TaskOrdering</code>. Update this wiki page to move the "Planned Refactor" content into the past tense once the work is complete.

=== Definition of Done ===

* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.
* Sequencing and gating logic lives in shared <code>StudentTask</code> class methods.
* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code>.
* Legacy <code>app/models/task_ordering</code> source files have been removed.

== Demo Video ==

'''Demo Video:''' https://youtu.be/Zg-fQmIUCSc

The demo walks through the current (pre-refactor) implementation:
* The <code>TaskOrdering</code> engine enforcing sequential task completion for quiz tasks
* Live API calls to the student tasks endpoints showing queue state and next task resolution
* Response creation flow including JWT authentication, map ownership verification, and task queue enforcement
* Full RSpec test suite run showing all 77 passing examples

== Future Work ==

* Extend <code>build_tasks</code> to support deadline-aware ordering — tasks past their due date could be automatically skipped or flagged
* Add per-question completion tracking for quiz responses, rather than treating a response as binary submitted/not-submitted
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Add new inner task classes to <code>StudentTasksController</code> to support additional response map types as new workflow stages are added to Expertiza
* Add admin endpoints to inspect or manually override a participant's queue state for debugging and support purposes

== References ==

* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* [https://guides.rubyonrails.org Ruby on Rails Guides]
* [https://rspec.info RSpec Documentation]
* [https://github.com/rswag/rswag Rswag GitHub Repository]
* [https://github.com/jwt/ruby-jwt JWT Ruby Gem]

== Team ==

'''Members:'''
* Akhil Kumar
* Dev Patel
* Arnav Mejari

'''Mentor:'''
* Vihar Manojkumar Shah

----
''Last updated: April 2026 | CSC 517, Spring 2026, NCSU''