Expertiza_Wiki - User contributions [en]

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

2026-04-13T21:42:29Z

Avkumar2:

== 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 Will Change ====

The five <code>TaskOrdering</code> files will be deleted. Their responsibilities will be redistributed as follows:

* <code>BaseTask</code>, <code>ReviewTask</code>, and <code>QuizTask</code> will be replaced by <code>BaseTaskItem</code>, <code>ReviewTaskItem</code>, and <code>QuizTaskItem</code> — defined as '''inner classes inside <code>StudentTasksController</code>''', with no separate files or namespace.
* <code>TaskFactory</code> will be eliminated entirely. Instead of a factory object, <code>build_tasks</code> — a private controller method — will directly instantiate <code>QuizTaskItem</code> or <code>ReviewTaskItem</code> based on what response maps and questionnaires exist for the participant.
* <code>TaskQueue</code> will be eliminated entirely. Its three query methods (<code>map_in_queue?</code>, <code>prior_tasks_complete_for?</code>, <code>next_incomplete_task</code>) will be replaced by equivalent private controller methods: <code>find_task_for_map</code>, <code>prior_tasks_complete?</code>, and a direct <code>tasks.find</code> call in the <code>next_task</code> action.

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>resolve_context_for_assignment(assignment_id)</code> || Finds <code>AssignmentParticipant</code> by current user and assignment, finds <code>TeamsParticipant</code>, resolves duty via <code>team_participant.duty_id</code> with fallback to <code>participant.duty_id</code>
|-
| <code>resolve_context_for_participant(participant)</code> || Same context resolution starting from a known participant rather than an assignment id
|-
| <code>build_tasks(context)</code> || Queries <code>ReviewResponseMap</code>, quiz questionnaire, and existing <code>QuizResponseMap</code> records; instantiates <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> in the correct order based on duty permissions
|-
| <code>ensure_response_objects!(tasks)</code> || Calls <code>ensure_response_map!</code> and <code>ensure_response!</code> on every task
|-
| <code>find_task_for_map(tasks, map_id)</code> || Returns the task whose <code>response_map.id</code> matches the given map id
|-
| <code>prior_tasks_complete?(tasks, target_task)</code> || Returns false if any task appearing before the target in the list has <code>completed? == false</code>
|}

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 Will Change ====

The <code>GET</code> and <code>PATCH</code> endpoints are unaffected. For <code>POST /responses</code>, the <code>enforce_task_order!</code> method currently calls <code>TaskOrdering::TaskQueue</code> directly. After the refactor, it will instead reuse the same <code>build_tasks</code> and <code>prior_tasks_complete?</code> private methods that <code>StudentTasksController</code> uses — either by extracting them into a shared concern or by duplicating the minimal logic in <code>ResponsesController</code>. Either way, the status codes (403 when order is violated, 201 on success) and the ownership check behavior will remain exactly the same.

== 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 private controller methods with no extra namespace.
* Quiz/review differences are encapsulated by <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> inner classes.
* All legacy <code>task_ordering</code> source and spec files are deleted.
* All specs pass with no API contract regression.

== 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 Merjeri

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

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

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

2026-04-13T21:34:39Z

Avkumar2:

== 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 or significantly repaired:

* '''A task ordering engine''' that knows the correct sequence of tasks for a participant and can determine whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' 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''' 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.

Following feedback received after the initial implementation, a '''simplification refactor''' is planned. The goal is to remove the separate <code>TaskOrdering</code> module and fold sequencing logic directly into <code>StudentTasksController</code>, reducing the number of files and abstraction layers while preserving all existing behavior. This refactor is described in the [[#Planned Refactor|Planned Refactor]] section below.

== What We Built ==

=== Task Ordering Engine ===

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 can answer 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>)

=== Student Tasks API ===

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
|}

Every endpoint requires a valid JWT token and resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records before delegating to a <code>TaskQueue</code> instance for eligibility decisions.

=== Response Management API ===

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 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''' — the <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

== Technical Deep Dive ==

=== How Task Ordering Works ===

When a student attempts to start a quiz task or create a response, 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 Authentication and Authorization Are Layered ===

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 insight here is that <code>find_and_authorize_map_for_create</code> must be 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. This was a central bug we fixed (see [[#Bugs We Fixed|Bugs We Fixed]]).

=== Round-Aware Response Handling ===

Expertiza supports multi-round assignment workflows. 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>

This means that if a response already exists for this map and round, it is updated in place rather than duplicated. If no response exists yet, a new one is initialized. This supports quiz retakes and multi-round review scenarios cleanly.

== Design Decisions ==

The reimplementation of Student Quizzes emphasized modularity, separation of concerns, and extensibility to ensure the system can evolve alongside future Expertiza features.

=== Decoupling Task Logic from Controllers ===

A key architectural decision was to encapsulate all task sequencing and eligibility logic within the <code>TaskOrdering</code> module, rather than embedding it directly in controllers. Controllers are responsible only for handling HTTP requests and responses, while <code>TaskOrdering</code> operates purely on domain objects such as assignments, participants, and response maps.

This separation improves testability, as task logic can be validated independently of the API layer, and ensures that future interfaces (e.g., background jobs or alternative frontends) can reuse the same core logic without duplication.

=== Use of the Factory Pattern ===

The introduction of <code>TaskFactory</code> allows the system to dynamically instantiate the correct task type based on the underlying response map. This avoids conditional logic scattered throughout the codebase and centralizes object creation in a single location.

By adhering to the factory pattern, the system becomes easier to extend — new task types can be added with minimal modification to existing code, requiring only the addition of a new task class and a corresponding mapping in the factory.

=== Centralized Task Orchestration via TaskQueue ===

The <code>TaskQueue</code> class serves as the single source of truth for task ordering and progression. Instead of allowing each controller to independently determine task eligibility, all such decisions are delegated to <code>TaskQueue</code>.

This design ensures consistency across the system: whether a student is viewing their tasks, starting a quiz, or submitting a response, the same ordering rules are enforced. It also reduces duplication and prevents subtle inconsistencies that could arise if multiple components attempted to implement ordering logic independently.

=== Layered Authorization and Validation ===

Another important design decision was to enforce validation at multiple layers of the request lifecycle. Authentication and high-level authorization are handled globally through concerns in <code>ApplicationController</code>, while resource-specific checks (such as map ownership) are implemented as controller <code>before_action</code> callbacks.

Finally, task-order enforcement is delegated to <code>TaskQueue</code>, ensuring that even if a request passes authentication and ownership checks, it cannot violate assignment workflow constraints. This layered approach provides defense in depth and reduces the likelihood of invalid state transitions.

=== Round-Aware Response Handling ===

To support Expertiza's multi-round workflow model, responses are scoped by both <code>map_id</code> and <code>round</code>. Instead of creating duplicate responses for the same round, the system updates the most recent response if it exists, or initializes a new one otherwise.

This design avoids redundant data while enabling clean support for quiz retakes and iterative peer review cycles.

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

All APIs were designed following RESTful principles, with clear resource-based endpoints and appropriate use of HTTP methods. Authentication is handled using JWT tokens, allowing the backend to remain stateless and scalable.

This approach ensures compatibility with modern frontend frameworks such as React and simplifies horizontal scaling by eliminating the need for server-side session storage.

== Test Coverage ==

=== Model 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>
|}

=== Request Specs ===

{| class="wikitable"
! File !! Endpoints !! Response Codes Tested
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task || 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST /responses, GET /responses/:id, PATCH /responses/:id || 201, 200, 401, 403, 404
|}

=== Running the Tests ===

<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'''

== Demo Video ==

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

The demo walks through:
* The task ordering system 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

== Planned Refactor ==

Following feedback on the initial implementation, the <code>TaskOrdering</code> module will be simplified. Rather than maintaining a separate namespace with five model-layer classes, all sequencing and eligibility logic will be moved directly into <code>StudentTasksController</code>, supported by two polymorphic inner classes. The public API contract and all existing behavior will remain unchanged.

=== Motivation ===

The <code>TaskOrdering</code> module introduced five separate files (<code>BaseTask</code>, <code>ReviewTask</code>, <code>QuizTask</code>, <code>TaskFactory</code>, <code>TaskQueue</code>) to solve a problem that does not require a dedicated namespace. Task sequencing is only ever invoked from two controllers — <code>StudentTasksController</code> and <code>ResponsesController</code> — and the added abstraction layers make the flow harder to trace without providing meaningful reuse benefits. The refactor aims to make the code simpler to read and maintain while preserving all correctness guarantees.

=== Proposed Design ===

The replacement design uses controller-owned private methods for orchestration, and two inner classes for polymorphic task-type behavior:

{| class="wikitable"
! Inner Class !! Role
|-
| <code>QuizTaskItem</code> || Handles quiz-specific completion detection, response map lookup/creation, and serialization
|-
| <code>ReviewTaskItem</code> || Handles review map completion based on <code>is_submitted</code>
|}

Both classes will share a common interface via a parent <code>BaseTaskItem</code>, with the following methods:

{| class="wikitable"
! Method !! Purpose
|-
| <code>response_map</code> || Returns the associated response map (creates one for quiz tasks 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 a stable JSON payload shape
|}

The private controller methods that will orchestrate the task flow are:

{| class="wikitable"
! Method !! Role
|-
| <code>build_tasks(context)</code> || Builds the ordered task list (quiz before review) for a participant
|-
| <code>ensure_response_objects!(tasks)</code> || Ensures response maps and responses exist for all tasks
|-
| <code>prior_tasks_complete?(tasks, target)</code> || Returns false if any task before the target is incomplete
|-
| <code>find_task_for_map(tasks, map_id)</code> || Looks up a task by its response map id
|-
| <code>resolve_context_for_assignment(assignment_id)</code> || Resolves participant, team membership, assignment, and duty from a given assignment id
|}

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

The request flow through <code>StudentTasksController</code> and <code>ResponsesController</code> will change from delegating to <code>TaskQueue</code> to calling private methods directly:

<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
→ loads ReviewResponseMaps for this participant
→ loads quiz questionnaire and existing QuizResponseMaps
→ instantiates QuizTaskItem / ReviewTaskItem in 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>

Task ordering rules will remain identical:
* If review maps exist: quiz task is added first (when duty allows and quiz is available or an existing quiz map is present), then review task (when duty allows).
* If no review maps exist: a quiz-only task is added when duty allows and a quiz questionnaire exists.

=== 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>QuizTaskItem</code> and <code>ReviewTaskItem</code> as inner classes inside <code>StudentTasksController</code>. The existing <code>TaskOrdering</code> module will remain untouched at this stage.

'''Phase 2 — Move orchestration logic into controller'''

Port queue construction and gating logic into private controller methods (<code>build_tasks</code>, <code>prior_tasks_complete?</code>, etc.). Update <code>StudentTasksController</code> and <code>ResponsesController</code> to use the new inner classes and private methods instead of <code>TaskQueue</code>. The JSON payload shape will not change.

'''Phase 3 — Remove the legacy layer'''

Delete the following files once all controllers and specs have been updated:
* <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>

'''Phase 4 — Update tests and documentation'''

Replace <code>spec/models/task_ordering/*</code> with:
* Request/integration specs for <code>queue</code>, <code>next_task</code>, and <code>start_task</code> covering all ordering scenarios
* Focused controller unit specs covering <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> behavior

Update <code>docs/POSTMAN_STUDENT_TASKS.md</code> if any wording references <code>TaskOrdering</code>.

=== Planned Test Coverage After Refactor ===

{| class="wikitable"
! File !! Key Scenarios to Cover
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || Queue order (quiz before review), quiz-only, review-only, empty queue, <code>start_task</code> blocking out-of-order attempts, unauthorized map access
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || Response create/update blocked when prior task incomplete, allowed when prerequisites complete, authorization checks preserved
|-
| <code>spec/controllers/student_tasks_controller_task_items_spec.rb</code> || <code>QuizTaskItem</code>: reuses existing map, creates map when questionnaire present, returns nil when absent; <code>ReviewTaskItem</code>: returns given map, completion based on submitted response; shared <code>to_h</code> payload contract
|}

The following payload keys must remain stable across all student task endpoints after the refactor:

* <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>

=== Definition of Done ===

* <code>StudentTasksController</code> and <code>ResponsesController</code> no longer reference <code>TaskOrdering</code>.
* Sequencing and gating logic lives in private controller methods with no extra namespace.
* Quiz/review differences are encapsulated by polymorphic <code>QuizTaskItem</code> and <code>ReviewTaskItem</code> inner classes.
* All legacy <code>task_ordering</code> files are deleted.
* All specs pass with no API contract regression.

== Future Work ==

* Extend task-building logic 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 fully submitted or not
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Add new inner task classes to support additional response map types as new assignment 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 Merjeri

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

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

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

2026-04-13T16:37:07Z

Avkumar2:

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

2026-03-31T02:27:25Z

Avkumar2:

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

2026-03-31T02:25:33Z

Avkumar2:

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

2026-03-31T02:24:24Z

Avkumar2:

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

2026-03-31T02:18:59Z

Avkumar2:

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

2026-03-31T02:14:09Z

Avkumar2:

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

2026-03-31T01:36:36Z

Avkumar2:

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

2026-03-31T01:29:13Z

Avkumar2:

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

2026-03-31T01:28:05Z

Avkumar2:

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

2026-03-31T01:26:51Z

Avkumar2:

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

2026-03-31T01:24:21Z

Avkumar2:

= CSC/ECE 517 Spring 2026 - E2601. Reimplement Student Quizzes =

== 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 needed to be built or significantly repaired:

* '''A task ordering engine''' that knows the correct sequence of tasks for a participant and can determine whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' 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''' 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.

== What We Built ==

=== Task Ordering Engine ===

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 can answer 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>)

=== Student Tasks API ===

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
|}

Every endpoint requires a valid JWT token and resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records before delegating to a <code>TaskQueue</code> instance for eligibility decisions.

=== Response Management API ===

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 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''' — the <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

== Technical Deep Dive ==

=== How Task Ordering Works ===

When a student attempts to start a quiz task or create a response, 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 Authentication and Authorization Are Layered ===

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 insight here is that <code>find_and_authorize_map_for_create</code> must be 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. This was a central bug we fixed (see [[#Bugs We Fixed|Bugs We Fixed]]).

=== Round-Aware Response Handling ===

Expertiza supports multi-round assignment workflows. 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>

This means that if a response already exists for this map and round, it is updated in place rather than duplicated. If no response exists yet, a new one is initialized. This supports quiz retakes and multi-round review scenarios cleanly.

== Bugs We Fixed ==

During implementation and testing we encountered and resolved several non-trivial bugs. We document them here in detail because they reveal important architectural lessons about how Rails before-action ordering and RSpec let scoping interact.

=== Bug 1: <code>prepend_before_action</code> Running Before Authentication ===

'''Symptom:''' Every POST to <code>/responses</code> returned 500 with <code>NoMethodError: undefined method 'id' for nil</code>, even with a valid token.

'''Root cause:''' <code>find_and_authorize_map_for_create</code> was declared with <code>prepend_before_action</code>, which inserts it at the front of the callback chain — before <code>authenticate_request!</code> had a chance to set <code>current_user</code>. The method then called <code>current_user.id</code> on a nil object.

'''Fix:''' Changed the declaration to a standard <code>before_action</code>:

<pre>
# Before (broken)
prepend_before_action :find_and_authorize_map_for_create, only: %i[create]

# After (fixed)
before_action :find_and_authorize_map_for_create, only: %i[create]
</pre>

This ensures the callback chain runs in the correct order: authenticate → authorize → find and check map ownership.

=== Bug 2: Stale RSA Key File Causing Silent 401 Failures ===

'''Symptom:''' Tests with valid tokens were returning 401 even after the before-action ordering was fixed. The error message was <code>Not Authorized</code> with no further detail.

'''Root cause:''' <code>JsonWebToken</code> loads RSA keys at class initialization time. If <code>rsa_keys.yml</code> exists on disk, those keys are used. If the file was written by a previous process with different keys, tokens encoded during the test run (using newly generated in-memory keys) would fail RSA signature verification during decoding.

'''Fix:''' Deleted the stale <code>rsa_keys.yml</code> and added it to <code>.gitignore</code>:

<pre>
rm rsa_keys.yml
echo "rsa_keys.yml" >> .gitignore
</pre>

=== Bug 3: RSpec <code>let!</code> Scoping Causing Token/User Mismatch ===

'''Symptom:''' Tests continued to return 401 even after the RSA key fix. <code>User.find(auth_token[:id])</code> was finding the correct ID but authentication was still failing intermittently.

'''Root cause:''' The responses spec declared the user with <code>let!</code> (eager) while <code>let(:token)</code> was lazy. Because <code>let!</code> runs eagerly in its own evaluation context, the user object memoized inside the <code>let!</code> block could differ from the one referenced when <code>let(:token)</code> was later evaluated. This caused the encoded token to contain a user ID that did not match what was in the database for that example.

'''Fix:''' Changed <code>let!(:student)</code> to <code>let(:student)</code> and relied on the dependent <code>let!(:reviewer_participant)</code> — which references <code>student.id</code> — to force eager creation through the dependency chain:

<pre>
# Before (broken)
let!(:student) { User.create!(...) }

# After (fixed)
let(:student) { User.create!(...) } # lazy
let!(:reviewer_participant) do
AssignmentParticipant.create!(user_id: student.id, ...) # forces student creation
end
</pre>

This mirrors the exact pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

=== Bug 4: Error Message Mismatch in 401 Test ===

'''Symptom:''' The 401 unauthorized test was failing with <code>expected "Not Authorized" but got "Unauthorized"</code>.

'''Root cause:''' The controller's nil-user guard rendered <code>"Unauthorized"</code> while the <code>JwtToken</code> concern (which handles missing/invalid tokens) renders <code>"Not Authorized"</code>. The test expected the latter.

'''Fix:''' Removed the redundant nil-user guard from <code>find_and_authorize_map_for_create</code> entirely. Since <code>authenticate_request!</code> now always runs first, <code>current_user</code> will never be nil by the time the map ownership check runs — unauthenticated requests are rejected at the <code>JwtToken</code> layer with the correct <code>"Not Authorized"</code> message.

== Test Coverage ==

=== Model 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>
|}

=== Request Specs ===

{| class="wikitable"
! File !! Endpoints !! Response Codes Tested
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task || 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST /responses, GET /responses/:id, PATCH /responses/:id || 201, 200, 401, 403, 404
|}

=== Running the Tests ===

<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'''

== Demo Video ==

'''Demo Video:''' [Link to be added]

The demo will walk through:
* The task ordering system 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>TaskQueue</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 fully submitted or not
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Expand <code>TaskFactory</code> to support additional response map types as new assignment 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 Merjeri

'''Mentor:''' Dr. Ed Gehringer

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

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

2026-03-31T01:22:27Z

Avkumar2:

= CSC/ECE 517 Spring 2026 - E2601. Reimplement Student Quizzes =

== Table of Contents ==
# [[#Important Links|Important Links]]
# [[#Expertiza Background|Expertiza Background]]
# [[#Project Description|Project Description]]
# [[#What We Built|What We Built]]
# [[#Technical Deep Dive|Technical Deep Dive]]
# [[#Bugs We Fixed|Bugs We Fixed]]
# [[#Test Coverage|Test Coverage]]
# [[#Demo Video|Demo Video]]
# [[#Future Work|Future Work]]
# [[#References|References]]
# [[#Team|Team]]

== Important Links ==

* '''Git PR (back-end):''' [https://github.com/expertiza/reimplementation-back-end/pull/XXX Back-end Pull Request]
* '''Demo Video:''' [[#Demo Video|See Demo Video Section]]

== 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 needed to be built or significantly repaired:

* '''A task ordering engine''' that knows the correct sequence of tasks for a participant and can determine whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' 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''' 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.

== What We Built ==

=== Task Ordering Engine ===

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 can answer 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>)

=== Student Tasks API ===

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
|}

Every endpoint requires a valid JWT token and resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records before delegating to a <code>TaskQueue</code> instance for eligibility decisions.

=== Response Management API ===

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 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''' — the <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

== Technical Deep Dive ==

=== How Task Ordering Works ===

When a student attempts to start a quiz task or create a response, 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 Authentication and Authorization Are Layered ===

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 insight here is that <code>find_and_authorize_map_for_create</code> must be 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. This was a central bug we fixed (see [[#Bugs We Fixed|Bugs We Fixed]]).

=== Round-Aware Response Handling ===

Expertiza supports multi-round assignment workflows. 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>

This means that if a response already exists for this map and round, it is updated in place rather than duplicated. If no response exists yet, a new one is initialized. This supports quiz retakes and multi-round review scenarios cleanly.

== Bugs We Fixed ==

During implementation and testing we encountered and resolved several non-trivial bugs. We document them here in detail because they reveal important architectural lessons about how Rails before-action ordering and RSpec let scoping interact.

=== Bug 1: <code>prepend_before_action</code> Running Before Authentication ===

'''Symptom:''' Every POST to <code>/responses</code> returned 500 with <code>NoMethodError: undefined method 'id' for nil</code>, even with a valid token.

'''Root cause:''' <code>find_and_authorize_map_for_create</code> was declared with <code>prepend_before_action</code>, which inserts it at the front of the callback chain — before <code>authenticate_request!</code> had a chance to set <code>current_user</code>. The method then called <code>current_user.id</code> on a nil object.

'''Fix:''' Changed the declaration to a standard <code>before_action</code>:

<pre>
# Before (broken)
prepend_before_action :find_and_authorize_map_for_create, only: %i[create]

# After (fixed)
before_action :find_and_authorize_map_for_create, only: %i[create]
</pre>

This ensures the callback chain runs in the correct order: authenticate → authorize → find and check map ownership.

=== Bug 2: Stale RSA Key File Causing Silent 401 Failures ===

'''Symptom:''' Tests with valid tokens were returning 401 even after the before-action ordering was fixed. The error message was <code>Not Authorized</code> with no further detail.

'''Root cause:''' <code>JsonWebToken</code> loads RSA keys at class initialization time. If <code>rsa_keys.yml</code> exists on disk, those keys are used. If the file was written by a previous process with different keys, tokens encoded during the test run (using newly generated in-memory keys) would fail RSA signature verification during decoding.

'''Fix:''' Deleted the stale <code>rsa_keys.yml</code> and added it to <code>.gitignore</code>:

<pre>
rm rsa_keys.yml
echo "rsa_keys.yml" >> .gitignore
</pre>

=== Bug 3: RSpec <code>let!</code> Scoping Causing Token/User Mismatch ===

'''Symptom:''' Tests continued to return 401 even after the RSA key fix. <code>User.find(auth_token[:id])</code> was finding the correct ID but authentication was still failing intermittently.

'''Root cause:''' The responses spec declared the user with <code>let!</code> (eager) while <code>let(:token)</code> was lazy. Because <code>let!</code> runs eagerly in its own evaluation context, the user object memoized inside the <code>let!</code> block could differ from the one referenced when <code>let(:token)</code> was later evaluated. This caused the encoded token to contain a user ID that did not match what was in the database for that example.

'''Fix:''' Changed <code>let!(:student)</code> to <code>let(:student)</code> and relied on the dependent <code>let!(:reviewer_participant)</code> — which references <code>student.id</code> — to force eager creation through the dependency chain:

<pre>
# Before (broken)
let!(:student) { User.create!(...) }

# After (fixed)
let(:student) { User.create!(...) } # lazy
let!(:reviewer_participant) do
AssignmentParticipant.create!(user_id: student.id, ...) # forces student creation
end
</pre>

This mirrors the exact pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

=== Bug 4: Error Message Mismatch in 401 Test ===

'''Symptom:''' The 401 unauthorized test was failing with <code>expected "Not Authorized" but got "Unauthorized"</code>.

'''Root cause:''' The controller's nil-user guard rendered <code>"Unauthorized"</code> while the <code>JwtToken</code> concern (which handles missing/invalid tokens) renders <code>"Not Authorized"</code>. The test expected the latter.

'''Fix:''' Removed the redundant nil-user guard from <code>find_and_authorize_map_for_create</code> entirely. Since <code>authenticate_request!</code> now always runs first, <code>current_user</code> will never be nil by the time the map ownership check runs — unauthenticated requests are rejected at the <code>JwtToken</code> layer with the correct <code>"Not Authorized"</code> message.

== Test Coverage ==

=== Model 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>
|}

=== Request Specs ===

{| class="wikitable"
! File !! Endpoints !! Response Codes Tested
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task || 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST /responses, GET /responses/:id, PATCH /responses/:id || 201, 200, 401, 403, 404
|}

=== Running the Tests ===

<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'''

== Demo Video ==

'''Demo Video:''' [Link to be added]

The demo will walk through:
* The task ordering system 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>TaskQueue</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 fully submitted or not
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Expand <code>TaskFactory</code> to support additional response map types as new assignment 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]
* North Carolina State University, CSC 517 Course Materials
* Metz, S. (2018). ''Practical Object-Oriented Design: An Agile Primer Using Ruby'' (2nd ed.). Addison-Wesley.
* Fowler, M. (2018). ''Refactoring: Improving the Design of Existing Code'' (2nd ed.). Addison-Wesley.

== Team ==

'''Members:'''
* Akhil Kumar

'''Mentor:''' Dr. Ed Gehringer

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

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

2026-03-31T01:21:46Z

Avkumar2:

= E2601: Reimplementation of the Student Quiz System =

'''E2601: Reimplementation of the Student Quiz System''' is a graduate-level project conducted as part of the CSC/ECE 517 course at [[North Carolina State University]] in Spring 2026. The project focuses on modernizing the quiz subsystem within the [[Expertiza]] peer review platform, ensuring correct sequencing of tasks in multi-step assignment workflows.

== Background ==

[[Expertiza]] is an open-source platform developed at North Carolina State University that facilitates structured peer reviews, team-based assignments, and multi-stage workflows including submissions, reviews, quizzes, and feedback.<ref>https://github.com/expertiza/expertiza
</ref> In Expertiza, each assignment is organized as a workflow, where students must complete tasks in a prescribed order. Accurate task sequencing is essential to maintain the integrity of these workflows, particularly for quiz tasks, which may depend on prior completion of submission or review stages.

The platform is being reimplemented to separate the backend (Rails API) and frontend (React SPA), emphasizing modularity, test coverage, and adherence to RESTful principles.<ref>https://guides.rubyonrails.org
</ref>

== Objectives ==

The project addressed three primary challenges:

Implementing reliable task sequencing logic for student workflows.
Developing a student-facing API for task visibility and management.
Ensuring secure creation and updating of quiz responses with authentication and prerequisite checks.

== System Architecture ==

The reimplementation separates responsibilities into three layers: task ordering, student task API, and response management API.

=== Task Ordering Layer ===

The '''TaskOrdering''' module encapsulates all logic related to task sequencing and eligibility. It is independent of controllers and HTTP requests.

Key components include:

'''BaseTask''': Abstract interface for all task types.
'''ReviewTask''': Represents review tasks; completion depends on submission status.
'''QuizTask''': Represents quiz tasks and determines completion state.
'''TaskFactory''': Maps response maps to task objects.
'''TaskQueue''': Orchestrates ordered tasks and provides eligibility queries.

The module determines whether a task belongs to a student, verifies completion of prior tasks, and identifies the next actionable task.

=== Student Task API ===

The student task API exposes task information via five endpoints:

<code>/student_tasks/list</code> – Lists all tasks for a student.
<code>/student_tasks/view</code> – Provides detailed task information.
<code>/student_tasks/queue</code> – Returns the ordered task queue for an assignment.
<code>/student_tasks/next_task</code> – Retrieves the next incomplete task.
<code>/student_tasks/start_task</code> – Initiates a task if prerequisites are complete.

All endpoints require JWT authentication and resolve the participant context before delegating to TaskQueue.

=== Response Management API ===

The response management API ensures secure creation and modification of quiz and review responses.

<code>POST /responses</code> – Creates a new response.
<code>GET /responses/:id</code> – Retrieves an existing response.
<code>PATCH /responses/:id</code> – Updates an existing response.

Security measures include ownership verification and task order enforcement to prevent unauthorized or out-of-sequence submissions.

=== Task Enforcement and Workflow ===

When a student attempts to start or submit a quiz:

A TaskQueue instance is initialized.
Response maps are converted into task objects.
Tasks are ordered sequentially.
Completion of prior tasks is verified.
Requests failing prerequisite checks are rejected.

This enforces strict task order without embedding logic directly into controllers.

=== Authentication and Authorization ===

All requests follow a layered processing pipeline:

JWT authentication decodes tokens and sets <code>current_user</code>.
Authorization verifies permitted actions.
Controller-level validation confirms resource ownership.
Business logic execution handles task and response operations.

=== Multi-Round Support ===

The system supports multi-round assignments by scoping responses to both <code>map_id</code> and <code>round</code>. Existing responses are reused when appropriate, while new responses are created only when necessary, supporting quiz retakes and multi-round reviews.

== Implementation Challenges ==

Several issues were encountered and resolved during development:

'''Callback Execution Order''': Using <code>prepend_before_action</code> caused authorization to run before authentication. Replaced with <code>before_action</code> to correct the callback sequence.
'''RSA Key Inconsistencies''': Stale RSA keys caused JWT validation failures. Resolved by removing outdated key files and excluding them from version control.
'''Test Initialization Conflicts''': Mixed eager and lazy initialization in RSpec caused intermittent failures. Standardized lazy evaluation with dependency chaining.
'''Consistency of Error Messages''': Different layers returned conflicting 401 messages. Resolved by relying on the authentication layer to handle all unauthorized requests uniformly.

== Testing ==

Model and request tests were implemented to validate:

Task completion logic
Queue ordering
Factory behavior
API endpoint correctness
Authentication and authorization checks

All tests executed successfully, resulting in 77 passing examples.

== Future Work ==

Potential improvements include:

Deadline-aware task sequencing
Partial progress tracking for quizzes
Frontend progress indicators for task completion
Support for additional task types
Administrative tools for queue inspection and overrides

== Team ==

Akhil Kumar
Dev Patel
Arnav Merjari

Mentor: Dr. Ed Gehringer

== References ==

<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/jwt/ruby-jwt JWT Ruby Gem]

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

2026-03-31T01:18:43Z

Avkumar2:

= CSC/ECE 517 Spring 2026 - E2601. Reimplement Student Quizzes =

== Important Links ==

* '''Git PR (back-end):''' [https://github.com/expertiza/reimplementation-back-end/pull/XXX Back-end Pull Request]
* '''Demo Video:''' [[#Demo Video|See Demo Video Section]]

== 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 needed to be built or significantly repaired:

* '''A task ordering engine''' that knows the correct sequence of tasks for a participant and can determine whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' 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''' 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.

== What We Built ==

=== Task Ordering Engine ===

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 can answer 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>)

=== Student Tasks API ===

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
|}

Every endpoint requires a valid JWT token and resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records before delegating to a <code>TaskQueue</code> instance for eligibility decisions.

=== Response Management API ===

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 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''' — the <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

== Technical Deep Dive ==

=== How Task Ordering Works ===

When a student attempts to start a quiz task or create a response, 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 Authentication and Authorization Are Layered ===

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 insight here is that <code>find_and_authorize_map_for_create</code> must be 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. This was a central bug we fixed (see [[#Bugs We Fixed|Bugs We Fixed]]).

=== Round-Aware Response Handling ===

Expertiza supports multi-round assignment workflows. 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>

This means that if a response already exists for this map and round, it is updated in place rather than duplicated. If no response exists yet, a new one is initialized. This supports quiz retakes and multi-round review scenarios cleanly.

== Bugs We Fixed ==

During implementation and testing we encountered and resolved several non-trivial bugs. We document them here in detail because they reveal important architectural lessons about how Rails before-action ordering and RSpec let scoping interact.

=== Bug 1: <code>prepend_before_action</code> Running Before Authentication ===

'''Symptom:''' Every POST to <code>/responses</code> returned 500 with <code>NoMethodError: undefined method 'id' for nil</code>, even with a valid token.

'''Root cause:''' <code>find_and_authorize_map_for_create</code> was declared with <code>prepend_before_action</code>, which inserts it at the front of the callback chain — before <code>authenticate_request!</code> had a chance to set <code>current_user</code>. The method then called <code>current_user.id</code> on a nil object.

'''Fix:''' Changed the declaration to a standard <code>before_action</code>:

<pre>
# Before (broken)
prepend_before_action :find_and_authorize_map_for_create, only: %i[create]

# After (fixed)
before_action :find_and_authorize_map_for_create, only: %i[create]
</pre>

This ensures the callback chain runs in the correct order: authenticate → authorize → find and check map ownership.

=== Bug 2: Stale RSA Key File Causing Silent 401 Failures ===

'''Symptom:''' Tests with valid tokens were returning 401 even after the before-action ordering was fixed. The error message was <code>Not Authorized</code> with no further detail.

'''Root cause:''' <code>JsonWebToken</code> loads RSA keys at class initialization time. If <code>rsa_keys.yml</code> exists on disk, those keys are used. If the file was written by a previous process with different keys, tokens encoded during the test run (using newly generated in-memory keys) would fail RSA signature verification during decoding.

'''Fix:''' Deleted the stale <code>rsa_keys.yml</code> and added it to <code>.gitignore</code>:

<pre>
rm rsa_keys.yml
echo "rsa_keys.yml" >> .gitignore
</pre>

=== Bug 3: RSpec <code>let!</code> Scoping Causing Token/User Mismatch ===

'''Symptom:''' Tests continued to return 401 even after the RSA key fix. <code>User.find(auth_token[:id])</code> was finding the correct ID but authentication was still failing intermittently.

'''Root cause:''' The responses spec declared the user with <code>let!</code> (eager) while <code>let(:token)</code> was lazy. Because <code>let!</code> runs eagerly in its own evaluation context, the user object memoized inside the <code>let!</code> block could differ from the one referenced when <code>let(:token)</code> was later evaluated. This caused the encoded token to contain a user ID that did not match what was in the database for that example.

'''Fix:''' Changed <code>let!(:student)</code> to <code>let(:student)</code> and relied on the dependent <code>let!(:reviewer_participant)</code> — which references <code>student.id</code> — to force eager creation through the dependency chain:

<pre>
# Before (broken)
let!(:student) { User.create!(...) }

# After (fixed)
let(:student) { User.create!(...) } # lazy
let!(:reviewer_participant) do
AssignmentParticipant.create!(user_id: student.id, ...) # forces student creation
end
</pre>

This mirrors the exact pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

=== Bug 4: Error Message Mismatch in 401 Test ===

'''Symptom:''' The 401 unauthorized test was failing with <code>expected "Not Authorized" but got "Unauthorized"</code>.

'''Root cause:''' The controller's nil-user guard rendered <code>"Unauthorized"</code> while the <code>JwtToken</code> concern (which handles missing/invalid tokens) renders <code>"Not Authorized"</code>. The test expected the latter.

'''Fix:''' Removed the redundant nil-user guard from <code>find_and_authorize_map_for_create</code> entirely. Since <code>authenticate_request!</code> now always runs first, <code>current_user</code> will never be nil by the time the map ownership check runs — unauthenticated requests are rejected at the <code>JwtToken</code> layer with the correct <code>"Not Authorized"</code> message.

== Test Coverage ==

=== Model 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>
|}

=== Request Specs ===

{| class="wikitable"
! File !! Endpoints !! Response Codes Tested
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task || 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST /responses, GET /responses/:id, PATCH /responses/:id || 201, 200, 401, 403, 404
|}

=== Running the Tests ===

<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'''

== Demo Video ==

'''Demo Video:''' [Link to be added]

The demo will walk through:
* The task ordering system 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>TaskQueue</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 fully submitted or not
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Expand <code>TaskFactory</code> to support additional response map types as new assignment 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 Merjari

'''Mentor:''' Dr. Ed Gehringer

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

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

2026-03-31T01:17:46Z

Avkumar2:

= CSC/ECE 517 Spring 2026 - E2601. Reimplement Student Quizzes =

== Table of Contents ==
# [[#Important Links|Important Links]]
# [[#Expertiza Background|Expertiza Background]]
# [[#Project Description|Project Description]]
# [[#What We Built|What We Built]]
# [[#Technical Deep Dive|Technical Deep Dive]]
# [[#Bugs We Fixed|Bugs We Fixed]]
# [[#Test Coverage|Test Coverage]]
# [[#Demo Video|Demo Video]]
# [[#Future Work|Future Work]]
# [[#References|References]]
# [[#Team|Team]]

== Important Links ==

* '''Git PR (back-end):''' [https://github.com/expertiza/reimplementation-back-end/pull/XXX Back-end Pull Request]
* '''Demo Video:''' [[#Demo Video|See Demo Video Section]]

== 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 needed to be built or significantly repaired:

* '''A task ordering engine''' that knows the correct sequence of tasks for a participant and can determine whether a student is eligible to take a quiz at any given moment
* '''A student-facing task API''' 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''' 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.

== What We Built ==

=== Task Ordering Engine ===

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 can answer 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>)

=== Student Tasks API ===

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
|}

Every endpoint requires a valid JWT token and resolves the student's <code>AssignmentParticipant</code> and <code>TeamsParticipant</code> records before delegating to a <code>TaskQueue</code> instance for eligibility decisions.

=== Response Management API ===

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 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''' — the <code>TaskQueue</code> must confirm that all prerequisite tasks are complete before this response can be created

== Technical Deep Dive ==

=== How Task Ordering Works ===

When a student attempts to start a quiz task or create a response, 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 Authentication and Authorization Are Layered ===

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 insight here is that <code>find_and_authorize_map_for_create</code> must be 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. This was a central bug we fixed (see [[#Bugs We Fixed|Bugs We Fixed]]).

=== Round-Aware Response Handling ===

Expertiza supports multi-round assignment workflows. 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>

This means that if a response already exists for this map and round, it is updated in place rather than duplicated. If no response exists yet, a new one is initialized. This supports quiz retakes and multi-round review scenarios cleanly.

== Bugs We Fixed ==

During implementation and testing we encountered and resolved several non-trivial bugs. We document them here in detail because they reveal important architectural lessons about how Rails before-action ordering and RSpec let scoping interact.

=== Bug 1: <code>prepend_before_action</code> Running Before Authentication ===

'''Symptom:''' Every POST to <code>/responses</code> returned 500 with <code>NoMethodError: undefined method 'id' for nil</code>, even with a valid token.

'''Root cause:''' <code>find_and_authorize_map_for_create</code> was declared with <code>prepend_before_action</code>, which inserts it at the front of the callback chain — before <code>authenticate_request!</code> had a chance to set <code>current_user</code>. The method then called <code>current_user.id</code> on a nil object.

'''Fix:''' Changed the declaration to a standard <code>before_action</code>:

<pre>
# Before (broken)
prepend_before_action :find_and_authorize_map_for_create, only: %i[create]

# After (fixed)
before_action :find_and_authorize_map_for_create, only: %i[create]
</pre>

This ensures the callback chain runs in the correct order: authenticate → authorize → find and check map ownership.

=== Bug 2: Stale RSA Key File Causing Silent 401 Failures ===

'''Symptom:''' Tests with valid tokens were returning 401 even after the before-action ordering was fixed. The error message was <code>Not Authorized</code> with no further detail.

'''Root cause:''' <code>JsonWebToken</code> loads RSA keys at class initialization time. If <code>rsa_keys.yml</code> exists on disk, those keys are used. If the file was written by a previous process with different keys, tokens encoded during the test run (using newly generated in-memory keys) would fail RSA signature verification during decoding.

'''Fix:''' Deleted the stale <code>rsa_keys.yml</code> and added it to <code>.gitignore</code>:

<pre>
rm rsa_keys.yml
echo "rsa_keys.yml" >> .gitignore
</pre>

=== Bug 3: RSpec <code>let!</code> Scoping Causing Token/User Mismatch ===

'''Symptom:''' Tests continued to return 401 even after the RSA key fix. <code>User.find(auth_token[:id])</code> was finding the correct ID but authentication was still failing intermittently.

'''Root cause:''' The responses spec declared the user with <code>let!</code> (eager) while <code>let(:token)</code> was lazy. Because <code>let!</code> runs eagerly in its own evaluation context, the user object memoized inside the <code>let!</code> block could differ from the one referenced when <code>let(:token)</code> was later evaluated. This caused the encoded token to contain a user ID that did not match what was in the database for that example.

'''Fix:''' Changed <code>let!(:student)</code> to <code>let(:student)</code> and relied on the dependent <code>let!(:reviewer_participant)</code> — which references <code>student.id</code> — to force eager creation through the dependency chain:

<pre>
# Before (broken)
let!(:student) { User.create!(...) }

# After (fixed)
let(:student) { User.create!(...) } # lazy
let!(:reviewer_participant) do
AssignmentParticipant.create!(user_id: student.id, ...) # forces student creation
end
</pre>

This mirrors the exact pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

=== Bug 4: Error Message Mismatch in 401 Test ===

'''Symptom:''' The 401 unauthorized test was failing with <code>expected "Not Authorized" but got "Unauthorized"</code>.

'''Root cause:''' The controller's nil-user guard rendered <code>"Unauthorized"</code> while the <code>JwtToken</code> concern (which handles missing/invalid tokens) renders <code>"Not Authorized"</code>. The test expected the latter.

'''Fix:''' Removed the redundant nil-user guard from <code>find_and_authorize_map_for_create</code> entirely. Since <code>authenticate_request!</code> now always runs first, <code>current_user</code> will never be nil by the time the map ownership check runs — unauthenticated requests are rejected at the <code>JwtToken</code> layer with the correct <code>"Not Authorized"</code> message.

== Test Coverage ==

=== Model 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>
|}

=== Request Specs ===

{| class="wikitable"
! File !! Endpoints !! Response Codes Tested
|-
| <code>spec/requests/api/v1/student_tasks_controller_spec.rb</code> || list, view, queue, next_task, start_task || 200, 401, 404, 500
|-
| <code>spec/requests/api/v1/responses_controller_spec.rb</code> || POST /responses, GET /responses/:id, PATCH /responses/:id || 201, 200, 401, 403, 404
|}

=== Running the Tests ===

<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'''

== Demo Video ==

'''Demo Video:''' [Link to be added]

The demo will walk through:
* The task ordering system 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>TaskQueue</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 fully submitted or not
* Expose a participant-level quiz completion percentage endpoint for frontend progress indicators
* Expand <code>TaskFactory</code> to support additional response map types as new assignment 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 Merjari

'''Mentor:''' Dr. Ed Gehringer

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

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

2026-03-31T01:07:13Z

Avkumar2:

== Table of Contents ==
# [[#Background|Background]]
# [[#Project Overview|Project Overview]]
# [[#Implementation|Implementation]]
# [[#Testing|Testing]]
# [[#Demo Video|Demo Video]]
# [[#References|References]]

== Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source, peer-review-based learning management system developed and maintained at '''North Carolina State University'''. It is used in courses across NCSU and other institutions to facilitate collaborative learning through structured peer review, team assignments, and iterative feedback cycles.

The platform allows instructors to create assignments with multi-round review workflows, where students submit work, review their peers' submissions, and receive feedback. Expertiza is built on '''Ruby on Rails''' and has an active community of student contributors who extend and improve its functionality each semester as part of graduate coursework in CSC 517.

The system manages complex entities including assignments, participants, response maps, and responses — all coordinated through a carefully structured authorization and task-ordering pipeline.

== Project Overview ==

This project is a reimplementation of key backend components of Expertiza as part of '''Program 3''' in CSC 517. The goal was to redesign and improve three interconnected areas of the system:

* '''Task Ordering''' — enforcing that participants complete tasks in a defined sequence before proceeding to subsequent ones
* '''Student Task Management''' — providing students with a clear view of their current tasks, queue position, and next actionable item
* '''Response Creation & Authorization''' — ensuring that only authorized participants can create or modify responses tied to their assigned review maps

The reimplementation emphasizes clean object-oriented design, proper separation of concerns, RESTful API conventions, and comprehensive test coverage using RSpec and Rswag.

== Implementation ==

=== Task Ordering ===

A dedicated task ordering module was introduced under <code>app/models/task_ordering/</code> to encapsulate the logic for determining which tasks a participant is eligible to complete. Key classes include:

{| class="wikitable"
! Class !! Responsibility
|-
| <code>BaseTask</code> || Defines the shared interface for all task types, including completion status and map membership checks
|-
| <code>ReviewTask</code> || Extends <code>BaseTask</code> to handle review-specific logic tied to <code>ReviewResponseMap</code>
|-
| <code>QuizTask</code> || Extends <code>BaseTask</code> to handle quiz participation tasks
|-
| <code>TaskFactory</code> || Implements the factory pattern to instantiate the correct task type based on the response map class
|-
| <code>TaskQueue</code> || Orchestrates the ordered sequence of tasks for a given participant and assignment, exposing <code>map_in_queue?</code> and <code>prior_tasks_complete_for?</code>
|}

This design replaces ad-hoc task eligibility checks that were previously scattered across controllers, centralizing the logic in a maintainable and testable module.

=== Student Tasks Controller ===

The <code>StudentTasksController</code> was implemented to give students visibility into their assignment workload. It exposes the following endpoints:

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>GET</code> || <code>/student_tasks/list</code> || Returns all tasks for the current user
|-
| <code>GET</code> || <code>/student_tasks/view</code> || Returns details for a specific participant task
|-
| <code>GET</code> || <code>/student_tasks/queue</code> || Returns the ordered task queue for an assignment
|-
| <code>GET</code> || <code>/student_tasks/next_task</code> || Returns the next incomplete task
|-
| <code>POST</code> || <code>/student_tasks/start_task</code> || Marks a task as started if queue order allows
|}

Authorization is handled via JWT token authentication inherited from <code>ApplicationController</code>, with <code>action_allowed?</code> overridden to enforce participant-level access control.

=== Responses Controller ===

The <code>ResponsesController</code> manages the creation and updating of peer review responses. Key design decisions include:

* '''Authorization via <code>before_action</code>''' — <code>find_and_authorize_map_for_create</code> runs after <code>authenticate_request!</code> to ensure <code>current_user</code> is available before map ownership is verified
* '''Task order enforcement''' — the <code>enforce_task_order!</code> helper delegates to <code>TaskQueue</code> to confirm the participant is eligible to respond before allowing creation or update
* '''Round-aware response handling''' — responses are scoped by <code>map_id</code> and <code>round</code>, supporting multi-round review workflows

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>POST</code> || <code>/responses</code> || Create a new response for a review map
|-
| <code>GET</code> || <code>/responses/:id</code> || Retrieve a specific response
|-
| <code>PATCH</code> || <code>/responses/:id</code> || Update an existing response
|}

=== Authorization & JWT Authentication ===

Authentication is handled via RSA-signed JWT tokens using the <code>JsonWebToken</code> class. The <code>JwtToken</code> concern decodes the token from the <code>Authorization</code> header on every request and sets <code>current_user</code>. The <code>Authorization</code> concern then runs <code>action_allowed?</code> to determine whether the authenticated user is permitted to perform the requested action.

A key architectural fix during this implementation was ensuring that <code>find_and_authorize_map_for_create</code> uses a standard <code>before_action</code> rather than <code>prepend_before_action</code>, so that <code>authenticate_request!</code> always runs first and <code>current_user</code> is reliably available before ownership checks occur.

== Testing ==

All components were tested using '''RSpec''' for unit and integration testing and '''Rswag''' for API-level request specs that simultaneously generate OpenAPI documentation.

=== Model Specs ===

Located under <code>spec/models/task_ordering/</code>:

{| class="wikitable"
! Spec File !! Coverage
|-
| <code>base_task_spec.rb</code> || Tests shared task interface and completion logic
|-
| <code>review_task_spec.rb</code> || Tests review-specific map membership and completion status
|-
| <code>quiz_task_spec.rb</code> || Tests quiz task eligibility and completion detection
|-
| <code>task_factory_spec.rb</code> || Tests correct task instantiation by response map type
|-
| <code>task_queue_spec.rb</code> || Tests queue ordering, <code>map_in_queue?</code>, and <code>prior_tasks_complete_for?</code>
|}

=== Request Specs ===

Located under <code>spec/requests/api/v1/</code>:

{| class="wikitable"
! Spec File !! Scenarios Covered
|-
| <code>student_tasks_controller_spec.rb</code> || 200 success, 401 unauthorized, 404 not found across all five endpoints
|-
| <code>responses_controller_spec.rb</code> || 201 created, 401 unauthorized, 403 forbidden, 404 not found for POST; 200, 401, 403 for GET and PATCH
|}

=== Notable Testing Challenges & Fixes ===

During development, several non-trivial testing issues were encountered and resolved:

; <code>prepend_before_action</code> ordering bug
: <code>find_and_authorize_map_for_create</code> was running before <code>authenticate_request!</code>, causing <code>current_user</code> to always be <code>nil</code> and returning 401 even for valid tokens. Fixed by switching to a standard <code>before_action</code>.

; Stale <code>rsa_keys.yml</code>
: A pre-existing RSA key file caused JWT decode failures in tests because the keys used to encode tokens at spec time differed from those loaded at class initialization. Resolved by deleting the stale file and adding it to <code>.gitignore</code>.

; <code>let!</code> vs <code>let</code> scoping in RSpec
: Eager <code>let!</code> declarations for user records caused token encoding to reference a different object instance than the one persisted in the database, leading to <code>User.find</code> failures during authentication. Fixed by using lazy <code>let</code> with a <code>let!</code> dependent that forces creation through the dependency chain, mirroring the pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

== Demo Video ==

{{Video placeholder}}

'''Demo Video:''' [Link to be added]

The demo will cover:
* A walkthrough of the task ordering system and how it enforces sequential task completion
* Live API calls demonstrating the student tasks endpoints
* Response creation and authorization flow including JWT authentication
* RSpec and Rswag test suite execution showing all passing examples

== References ==

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

----
''Last updated: March 2026 | Contributors: Akhil Kumar et al. | CSC 517, Spring 2026, NCSU''

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

2026-03-31T01:06:54Z

Avkumar2:

= Expertiza: Response & Task Ordering System =

'''Course:''' CSC 517 — Object-Oriented Design and Development 
'''Institution:''' North Carolina State University 
'''Semester:''' Spring 2026 

== Table of Contents ==
# [[#Background|Background]]
# [[#Project Overview|Project Overview]]
# [[#Implementation|Implementation]]
# [[#Testing|Testing]]
# [[#Demo Video|Demo Video]]
# [[#References|References]]

== Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source, peer-review-based learning management system developed and maintained at '''North Carolina State University'''. It is used in courses across NCSU and other institutions to facilitate collaborative learning through structured peer review, team assignments, and iterative feedback cycles.

The platform allows instructors to create assignments with multi-round review workflows, where students submit work, review their peers' submissions, and receive feedback. Expertiza is built on '''Ruby on Rails''' and has an active community of student contributors who extend and improve its functionality each semester as part of graduate coursework in CSC 517.

The system manages complex entities including assignments, participants, response maps, and responses — all coordinated through a carefully structured authorization and task-ordering pipeline.

== Project Overview ==

This project is a reimplementation of key backend components of Expertiza as part of '''Program 3''' in CSC 517. The goal was to redesign and improve three interconnected areas of the system:

* '''Task Ordering''' — enforcing that participants complete tasks in a defined sequence before proceeding to subsequent ones
* '''Student Task Management''' — providing students with a clear view of their current tasks, queue position, and next actionable item
* '''Response Creation & Authorization''' — ensuring that only authorized participants can create or modify responses tied to their assigned review maps

The reimplementation emphasizes clean object-oriented design, proper separation of concerns, RESTful API conventions, and comprehensive test coverage using RSpec and Rswag.

== Implementation ==

=== Task Ordering ===

A dedicated task ordering module was introduced under <code>app/models/task_ordering/</code> to encapsulate the logic for determining which tasks a participant is eligible to complete. Key classes include:

{| class="wikitable"
! Class !! Responsibility
|-
| <code>BaseTask</code> || Defines the shared interface for all task types, including completion status and map membership checks
|-
| <code>ReviewTask</code> || Extends <code>BaseTask</code> to handle review-specific logic tied to <code>ReviewResponseMap</code>
|-
| <code>QuizTask</code> || Extends <code>BaseTask</code> to handle quiz participation tasks
|-
| <code>TaskFactory</code> || Implements the factory pattern to instantiate the correct task type based on the response map class
|-
| <code>TaskQueue</code> || Orchestrates the ordered sequence of tasks for a given participant and assignment, exposing <code>map_in_queue?</code> and <code>prior_tasks_complete_for?</code>
|}

This design replaces ad-hoc task eligibility checks that were previously scattered across controllers, centralizing the logic in a maintainable and testable module.

=== Student Tasks Controller ===

The <code>StudentTasksController</code> was implemented to give students visibility into their assignment workload. It exposes the following endpoints:

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>GET</code> || <code>/student_tasks/list</code> || Returns all tasks for the current user
|-
| <code>GET</code> || <code>/student_tasks/view</code> || Returns details for a specific participant task
|-
| <code>GET</code> || <code>/student_tasks/queue</code> || Returns the ordered task queue for an assignment
|-
| <code>GET</code> || <code>/student_tasks/next_task</code> || Returns the next incomplete task
|-
| <code>POST</code> || <code>/student_tasks/start_task</code> || Marks a task as started if queue order allows
|}

Authorization is handled via JWT token authentication inherited from <code>ApplicationController</code>, with <code>action_allowed?</code> overridden to enforce participant-level access control.

=== Responses Controller ===

The <code>ResponsesController</code> manages the creation and updating of peer review responses. Key design decisions include:

* '''Authorization via <code>before_action</code>''' — <code>find_and_authorize_map_for_create</code> runs after <code>authenticate_request!</code> to ensure <code>current_user</code> is available before map ownership is verified
* '''Task order enforcement''' — the <code>enforce_task_order!</code> helper delegates to <code>TaskQueue</code> to confirm the participant is eligible to respond before allowing creation or update
* '''Round-aware response handling''' — responses are scoped by <code>map_id</code> and <code>round</code>, supporting multi-round review workflows

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>POST</code> || <code>/responses</code> || Create a new response for a review map
|-
| <code>GET</code> || <code>/responses/:id</code> || Retrieve a specific response
|-
| <code>PATCH</code> || <code>/responses/:id</code> || Update an existing response
|}

=== Authorization & JWT Authentication ===

Authentication is handled via RSA-signed JWT tokens using the <code>JsonWebToken</code> class. The <code>JwtToken</code> concern decodes the token from the <code>Authorization</code> header on every request and sets <code>current_user</code>. The <code>Authorization</code> concern then runs <code>action_allowed?</code> to determine whether the authenticated user is permitted to perform the requested action.

A key architectural fix during this implementation was ensuring that <code>find_and_authorize_map_for_create</code> uses a standard <code>before_action</code> rather than <code>prepend_before_action</code>, so that <code>authenticate_request!</code> always runs first and <code>current_user</code> is reliably available before ownership checks occur.

== Testing ==

All components were tested using '''RSpec''' for unit and integration testing and '''Rswag''' for API-level request specs that simultaneously generate OpenAPI documentation.

=== Model Specs ===

Located under <code>spec/models/task_ordering/</code>:

{| class="wikitable"
! Spec File !! Coverage
|-
| <code>base_task_spec.rb</code> || Tests shared task interface and completion logic
|-
| <code>review_task_spec.rb</code> || Tests review-specific map membership and completion status
|-
| <code>quiz_task_spec.rb</code> || Tests quiz task eligibility and completion detection
|-
| <code>task_factory_spec.rb</code> || Tests correct task instantiation by response map type
|-
| <code>task_queue_spec.rb</code> || Tests queue ordering, <code>map_in_queue?</code>, and <code>prior_tasks_complete_for?</code>
|}

=== Request Specs ===

Located under <code>spec/requests/api/v1/</code>:

{| class="wikitable"
! Spec File !! Scenarios Covered
|-
| <code>student_tasks_controller_spec.rb</code> || 200 success, 401 unauthorized, 404 not found across all five endpoints
|-
| <code>responses_controller_spec.rb</code> || 201 created, 401 unauthorized, 403 forbidden, 404 not found for POST; 200, 401, 403 for GET and PATCH
|}

=== Notable Testing Challenges & Fixes ===

During development, several non-trivial testing issues were encountered and resolved:

; <code>prepend_before_action</code> ordering bug
: <code>find_and_authorize_map_for_create</code> was running before <code>authenticate_request!</code>, causing <code>current_user</code> to always be <code>nil</code> and returning 401 even for valid tokens. Fixed by switching to a standard <code>before_action</code>.

; Stale <code>rsa_keys.yml</code>
: A pre-existing RSA key file caused JWT decode failures in tests because the keys used to encode tokens at spec time differed from those loaded at class initialization. Resolved by deleting the stale file and adding it to <code>.gitignore</code>.

; <code>let!</code> vs <code>let</code> scoping in RSpec
: Eager <code>let!</code> declarations for user records caused token encoding to reference a different object instance than the one persisted in the database, leading to <code>User.find</code> failures during authentication. Fixed by using lazy <code>let</code> with a <code>let!</code> dependent that forces creation through the dependency chain, mirroring the pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

== Demo Video ==

{{Video placeholder}}

'''Demo Video:''' [Link to be added]

The demo will cover:
* A walkthrough of the task ordering system and how it enforces sequential task completion
* Live API calls demonstrating the student tasks endpoints
* Response creation and authorization flow including JWT authentication
* RSpec and Rswag test suite execution showing all passing examples

== References ==

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

----
''Last updated: March 2026 | Contributors: Akhil Kumar et al. | CSC 517, Spring 2026, NCSU''

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

2026-03-31T01:06:35Z

Avkumar2: Created page with "= Expertiza: Response & Task Ordering System = '''Course:''' CSC 517 — Object-Oriented Design and Development '''Institution:''' North Carolina State University '''Semester:''' Spring 2026 == Table of Contents == # Background # Project Overview # Implementation # Testing # Demo Video # References == Background == [https://github.com/expertiza/expert..."

= Expertiza: Response & Task Ordering System =

'''Course:''' CSC 517 — Object-Oriented Design and Development 
'''Institution:''' North Carolina State University 
'''Semester:''' Spring 2026 

== Table of Contents ==
# [[#Background|Background]]
# [[#Project Overview|Project Overview]]
# [[#Implementation|Implementation]]
# [[#Testing|Testing]]
# [[#Demo Video|Demo Video]]
# [[#References|References]]

== Background ==

[https://github.com/expertiza/expertiza Expertiza] is an open-source, peer-review-based learning management system developed and maintained at '''North Carolina State University'''. It is used in courses across NCSU and other institutions to facilitate collaborative learning through structured peer review, team assignments, and iterative feedback cycles.

The platform allows instructors to create assignments with multi-round review workflows, where students submit work, review their peers' submissions, and receive feedback. Expertiza is built on '''Ruby on Rails''' and has an active community of student contributors who extend and improve its functionality each semester as part of graduate coursework in CSC 517.

The system manages complex entities including assignments, participants, response maps, and responses — all coordinated through a carefully structured authorization and task-ordering pipeline.

== Project Overview ==

This project is a reimplementation of key backend components of Expertiza as part of '''Program 3''' in CSC 517. The goal was to redesign and improve three interconnected areas of the system:

* '''Task Ordering''' — enforcing that participants complete tasks in a defined sequence before proceeding to subsequent ones
* '''Student Task Management''' — providing students with a clear view of their current tasks, queue position, and next actionable item
* '''Response Creation & Authorization''' — ensuring that only authorized participants can create or modify responses tied to their assigned review maps

The reimplementation emphasizes clean object-oriented design, proper separation of concerns, RESTful API conventions, and comprehensive test coverage using RSpec and Rswag.

== Implementation ==

=== Task Ordering ===

A dedicated task ordering module was introduced under <code>app/models/task_ordering/</code> to encapsulate the logic for determining which tasks a participant is eligible to complete. Key classes include:

{| class="wikitable"
! Class !! Responsibility
|-
| <code>BaseTask</code> || Defines the shared interface for all task types, including completion status and map membership checks
|-
| <code>ReviewTask</code> || Extends <code>BaseTask</code> to handle review-specific logic tied to <code>ReviewResponseMap</code>
|-
| <code>QuizTask</code> || Extends <code>BaseTask</code> to handle quiz participation tasks
|-
| <code>TaskFactory</code> || Implements the factory pattern to instantiate the correct task type based on the response map class
|-
| <code>TaskQueue</code> || Orchestrates the ordered sequence of tasks for a given participant and assignment, exposing <code>map_in_queue?</code> and <code>prior_tasks_complete_for?</code>
|}

This design replaces ad-hoc task eligibility checks that were previously scattered across controllers, centralizing the logic in a maintainable and testable module.

=== Student Tasks Controller ===

The <code>StudentTasksController</code> was implemented to give students visibility into their assignment workload. It exposes the following endpoints:

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>GET</code> || <code>/student_tasks/list</code> || Returns all tasks for the current user
|-
| <code>GET</code> || <code>/student_tasks/view</code> || Returns details for a specific participant task
|-
| <code>GET</code> || <code>/student_tasks/queue</code> || Returns the ordered task queue for an assignment
|-
| <code>GET</code> || <code>/student_tasks/next_task</code> || Returns the next incomplete task
|-
| <code>POST</code> || <code>/student_tasks/start_task</code> || Marks a task as started if queue order allows
|}

Authorization is handled via JWT token authentication inherited from <code>ApplicationController</code>, with <code>action_allowed?</code> overridden to enforce participant-level access control.

=== Responses Controller ===

The <code>ResponsesController</code> manages the creation and updating of peer review responses. Key design decisions include:

* '''Authorization via <code>before_action</code>''' — <code>find_and_authorize_map_for_create</code> runs after <code>authenticate_request!</code> to ensure <code>current_user</code> is available before map ownership is verified
* '''Task order enforcement''' — the <code>enforce_task_order!</code> helper delegates to <code>TaskQueue</code> to confirm the participant is eligible to respond before allowing creation or update
* '''Round-aware response handling''' — responses are scoped by <code>map_id</code> and <code>round</code>, supporting multi-round review workflows

{| class="wikitable"
! Method !! Path !! Description
|-
| <code>POST</code> || <code>/responses</code> || Create a new response for a review map
|-
| <code>GET</code> || <code>/responses/:id</code> || Retrieve a specific response
|-
| <code>PATCH</code> || <code>/responses/:id</code> || Update an existing response
|}

=== Authorization & JWT Authentication ===

Authentication is handled via RSA-signed JWT tokens using the <code>JsonWebToken</code> class. The <code>JwtToken</code> concern decodes the token from the <code>Authorization</code> header on every request and sets <code>current_user</code>. The <code>Authorization</code> concern then runs <code>action_allowed?</code> to determine whether the authenticated user is permitted to perform the requested action.

A key architectural fix during this implementation was ensuring that <code>find_and_authorize_map_for_create</code> uses a standard <code>before_action</code> rather than <code>prepend_before_action</code>, so that <code>authenticate_request!</code> always runs first and <code>current_user</code> is reliably available before ownership checks occur.

== Testing ==

All components were tested using '''RSpec''' for unit and integration testing and '''Rswag''' for API-level request specs that simultaneously generate OpenAPI documentation.

=== Model Specs ===

Located under <code>spec/models/task_ordering/</code>:

{| class="wikitable"
! Spec File !! Coverage
|-
| <code>base_task_spec.rb</code> || Tests shared task interface and completion logic
|-
| <code>review_task_spec.rb</code> || Tests review-specific map membership and completion status
|-
| <code>quiz_task_spec.rb</code> || Tests quiz task eligibility and completion detection
|-
| <code>task_factory_spec.rb</code> || Tests correct task instantiation by response map type
|-
| <code>task_queue_spec.rb</code> || Tests queue ordering, <code>map_in_queue?</code>, and <code>prior_tasks_complete_for?</code>
|}

=== Request Specs ===

Located under <code>spec/requests/api/v1/</code>:

{| class="wikitable"
! Spec File !! Scenarios Covered
|-
| <code>student_tasks_controller_spec.rb</code> || 200 success, 401 unauthorized, 404 not found across all five endpoints
|-
| <code>responses_controller_spec.rb</code> || 201 created, 401 unauthorized, 403 forbidden, 404 not found for POST; 200, 401, 403 for GET and PATCH
|}

=== Notable Testing Challenges & Fixes ===

During development, several non-trivial testing issues were encountered and resolved:

; <code>prepend_before_action</code> ordering bug
: <code>find_and_authorize_map_for_create</code> was running before <code>authenticate_request!</code>, causing <code>current_user</code> to always be <code>nil</code> and returning 401 even for valid tokens. Fixed by switching to a standard <code>before_action</code>.

; Stale <code>rsa_keys.yml</code>
: A pre-existing RSA key file caused JWT decode failures in tests because the keys used to encode tokens at spec time differed from those loaded at class initialization. Resolved by deleting the stale file and adding it to <code>.gitignore</code>.

; <code>let!</code> vs <code>let</code> scoping in RSpec
: Eager <code>let!</code> declarations for user records caused token encoding to reference a different object instance than the one persisted in the database, leading to <code>User.find</code> failures during authentication. Fixed by using lazy <code>let</code> with a <code>let!</code> dependent that forces creation through the dependency chain, mirroring the pattern used in the passing <code>student_tasks_controller_spec.rb</code>.

== Demo Video ==

{{Video placeholder}}

'''Demo Video:''' [Link to be added]

The demo will cover:
* A walkthrough of the task ordering system and how it enforces sequential task completion
* Live API calls demonstrating the student tasks endpoints
* Response creation and authorization flow including JWT authentication
* RSpec and Rswag test suite execution showing all passing examples

== References ==

* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* [https://guides.rubyonrails.org Ruby on Rails Documentation]
* [https://rspec.info RSpec Documentation]
* [https://github.com/rswag/rswag Rswag GitHub Repository]
* [https://github.com/jwt/ruby-jwt JWT Ruby Gem]
* North Carolina State University, CSC 517 Course Page
* Fowler, M. (2018). ''Refactoring: Improving the Design of Existing Code'' (2nd ed.). Addison-Wesley.
* Metz, S. (2018). ''Practical Object-Oriented Design: An Agile Primer Using Ruby'' (2nd ed.). Addison-Wesley.

----
''Last updated: March 2026 | Contributors: Akhil Kumar et al. | CSC 517, Spring 2026, NCSU''

CSC/ECE 517 Spring 2026

2026-03-31T01:01:03Z

Avkumar2:

* [[CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes]]
* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2606. Finishing Import and Export helper module]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]

CSC/ECE 517 Spring 2026

2026-03-31T01:00:46Z

Avkumar2:

* [CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes]]
* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2606. Finishing Import and Export helper module]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]