Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-30T22:45:45Z

Atmai:

= E2619: Student Quizzes — Design Document =

== Introduction ==

[https://expertiza.ncsu.edu/ Expertiza] is an educational web application collaboratively
developed and maintained by students and faculty at NCSU. As an open-source project built
on the Ruby on Rails platform, its code is accessible on GitHub. The platform enables
students to provide peer reviews and refine their work based on feedback.

This design document describes the implementation of the '''E2619 Student Quizzes'''
project, covering both the frontend (React/TypeScript) and backend (Ruby on Rails API).
The project builds on the E2607 questionnaire rendering code and extends it with
quiz-specific capabilities: directing students to quizzes/reviews, scoring quiz responses,
specifying correct answers, and handling fill-in-the-blank questions.

== Project Overview ==

Quizzes in Expertiza are designed to ensure that reviewers comprehend the material they
are evaluating. When an assignment includes quizzes (<code>require_quiz = true</code>),
submitting teams create quizzes based on their submissions. Reviewers must complete the
quizzes before reviewing to demonstrate their understanding. If a reviewer performs
poorly, their review can be discounted to maintain quality.

== Previous Implementation ==

The prior codebase provided the data models, CRUD controllers, and UI components needed for assignments, questionnaires, and peer reviews. However, the quiz workflow was incomplete in several key ways:

* <code>Response#aggregate_questionnaire_score</code> computed scores as <code>answer * weight</code> using only the numeric answer column, with no correctness check against a stored correct answer. There was no way to distinguish a quiz response from a regular review response.
* The <code>Item</code> model had no <code>correct_answer</code> column; there was nowhere to persist the expected answer for a quiz item.
* The <code>StudentTask</code> model did not carry quiz gateway fields (<code>require_quiz</code>, <code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>), so the frontend had no structured way to know whether a student must take a quiz before reviewing.
* The <code>Team</code> model had no <code>quiz_questionnaire_id</code>. Quiz questionnaire ownership was expected to flow through the assignment's questionnaire list, which required instructor configuration and did not support per-team quizzes.
* The <code>ResponseMapsController</code> had no index action that filtered out quiz maps, so the frontend could not safely list a student's review assignments without also receiving spurious self-referential quiz entries.
* No <code>QuizResponseMapsController</code> existed; there was no endpoint to create a <code>QuizResponseMap</code> before a student started a quiz.
* The questionnaire editor rendered no "Correct answer" field for any item type when the questionnaire type was set to "Quiz".
* The student task page had no "Take Quiz" button or any flow to route a student from a quiz gate to the quiz form and back to their review.

== Project Goals ==

Based on the gaps above, this project aimed to:

# Add a <code>correct_answer</code> string column to quiz items so submitting teams can specify expected answers at quiz-creation time.
# Extend <code>Response#aggregate_questionnaire_score</code> to detect quiz responses by the <code>reviewer_id == reviewee_id</code> invariant and score text/choice items from the <code>comments</code> column using case-insensitive equality.
# Extend <code>StudentTask</code> with four quiz gateway fields so the frontend can render the correct button (Take Quiz / Start Review) without extra API calls.
# Add a <code>quiz_questionnaire_id</code> column to <code>Team</code> so each submitting team directly owns its quiz questionnaire, enabling per-team quizzes on the same assignment.
# Implement <code>POST /quiz_response_maps</code> so the frontend can create (or reuse) a <code>QuizResponseMap</code> before navigating a student to the quiz form.
# Update <code>ResponseMapsController#index</code> to exclude quiz maps and include per-row quiz state.
# Add a "Correct answer" row in the questionnaire editor for every quiz item type.
# Implement an instructor "Create Quiz" button on the reviewer-assignment page that opens the questionnaire editor pre-linked to the team.
# Implement a "Take Quiz" button in the student task list that calls <code>POST /quiz_response_maps</code> and navigates to the existing review form in quiz mode.
# Add <code>GET /questions/quiz_types</code> so the frontend can fetch the allowed quiz item types dynamically.

== Design ==

=== Architecture Overview ===

<pre>
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React/TS) │
│ │
│ AssignedReviews ──→ [Take Quiz] ──→ TeammateReview │
│ │ (quiz mode) │ │
│ │ └──→ [redirect] │
│ └──→ [Start/Open Review] ──→ TeammateReview │
│ (review mode) │
│ QuestionnaireEditor ──→ correct_answer fields per type │
└──────────────────────────┬──────────────────────────────────┘
│ REST API
┌──────────────────────────┴──────────────────────────────────┐
│ Backend (Rails API) │
│ │
│ QuizResponseMapsController (POST /quiz_response_maps) │
│ ResponsesController (create / update / submit) │
│ ResponseMapsController (index — filters quiz maps) │
│ Response model (aggregate_questionnaire_score) │
│ StudentTask model (quiz gateway fields) │
└─────────────────────────────────────────────────────────────┘
</pre>

=== UML Design ===

<pre>
┌───────────────────────────────────────┐
│ Assignment │
├───────────────────────────────────────┤
│ +boolean require_quiz │
│ +int num_quiz_questions │
│ +has_many questionnaires (via AQ) │
└────────────────────┬──────────────────┘
│ has_many (via AQ)
▼
┌───────────────────────────────────────┐ ┌─────────────────────────────┐
│ Questionnaire │ │ Team [UPDATED] │
├───────────────────────────────────────┤ ├─────────────────────────────┤
│ +String name │ │ +int quiz_questionnaire_id │◄─── NEW
│ +String questionnaire_type │◄────│ +belongs_to │
│ ("Quiz" for quiz questionnaires) │ │ quiz_questionnaire │
│ +int min_question_score │ └─────────────────────────────┘
│ +int max_question_score │
│ +int instructor_id │
└────────────────────┬──────────────────┘
│ has_many
▼
┌───────────────────────────────────────┐
│ Item [UPDATED] │
├───────────────────────────────────────┤
│ +String txt │
│ +String question_type │
│ +int weight │
│ +String correct_answer ◄│─── NEW
│ +QUIZ_ITEM_TYPES : Array ◄│─── NEW
│ +is_quiz_item?() : boolean ◄│─── NEW
└────────────────────┬──────────────────┘
│ has_many answers
▼
┌───────────────────────────────────────┐
│ Answer │
├───────────────────────────────────────┤
│ +int item_id │
│ +int response_id │
│ +int answer │
│ +String comments (quiz answer here) │
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ Response [UPDATED] │
├───────────────────────────────────────┤
│ +int map_id │
│ +boolean is_submitted │
│ +int round │
│ +aggregate_questionnaire_score() ◄│─── quiz-aware: checks
│ │ reviewer_id == reviewee_id
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ QuizResponseMap [UPDATED] │
├───────────────────────────────────────┤
│ +int reviewer_id │
│ +int reviewee_id │
│ (reviewer_id == reviewee_id ◄│─── self-referential invariant
│ identifies quiz maps) │ distinguishes quiz from review
│ +int reviewed_object_id ◄│─── quiz questionnaire id
│ +mappings_for_reviewer() │
└───────────────────────────────────────┘
</pre>

== Screenshots ==

=== Take Quiz Button (Assigned Reviews) ===
[[File:take_quiz_button.png| 500px]]

=== Questionnaire Editor – Correct Answer Fields ===
[[File:correct_answer_fields.png| 500px]]

=== Quiz Submission and Score Display ===
[[File:quiz_score_display.png| 500px]]

== Changes Implemented ==

=== 1) Database Schema Additions ===

Two new columns support the quiz feature. The <code>correct_answer</code> string column on <code>items</code> stores the expected answer for each quiz question. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items. The <code>quiz_questionnaire_id</code> integer column on <code>teams</code> lets each submitting team directly own its quiz questionnaire — a key change that makes per-team quizzes possible and replaces a previous approach that required manual wiring at the assignment level.

Two migrations were added to support the quiz features:

<syntaxhighlight lang="ruby">
# db/migrate/20260423000001_add_correct_answer_to_items.rb
class AddCorrectAnswerToItems < ActiveRecord::Migration[8.0]
def change
add_column :items, :correct_answer, :string
end
end

# db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb
class AddQuizQuestionnaireIdToTeams < ActiveRecord::Migration[8.0]
def change
add_column :teams, :quiz_questionnaire_id, :integer, null: true, default: nil
add_index :teams, :quiz_questionnaire_id
end
end
</syntaxhighlight>

The <code>correct_answer</code> column stores the expected answer for each quiz item. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items.

The <code>quiz_questionnaire_id</code> column on <code>teams</code> allows each submitting team to directly own its quiz questionnaire. This replaces a previous approach that required the instructor to manually wire a questionnaire to the assignment, and is the key change that makes per-team quizzes possible.

=== 2) Quiz-Aware Scoring in Response Model ===

Quiz responses are identified by the invariant <code>reviewer_id == reviewee_id</code> on the associated <code>ResponseMap</code> — no STI <code>type</code> column is needed. For text and choice quiz items the student's answer is stored in the <code>comments</code> column (not the numeric <code>answer</code> column), so scoring uses case-insensitive string equality. Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions. The final score is returned in the <code>PATCH /responses/:id/submit</code> response body as <code>total_score</code> and displayed to the student before the redirect.

The core scoring logic in <code>Response#aggregate_questionnaire_score</code> was extended to handle quiz responses:

<syntaxhighlight lang="ruby">
def aggregate_questionnaire_score
sum = 0
is_quiz = map.reviewer_id == map.reviewee_id
comment_scored_types = %w[
TextField MultipleChoiceRadio MultipleChoiceCheckbox
Text\ field Multiple\ choice Multiple\ choice\ checkbox
].freeze

scores.each do |s|
if is_quiz && comment_scored_types.include?(s.item.question_type)
correct = s.item.correct_answer.to_s.strip.downcase
student_answer = s.comments.to_s.strip.downcase
sum += (student_answer == correct && correct.present? ? 1 : 0) * (s.item.weight || 1)
else
sum += s.answer * (s.item.weight || 1) unless s.answer.nil?
end
end
sum
end
</syntaxhighlight>

Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions.

=== 3) StudentTask Quiz Gateway Fields ===

Four fields were added to <code>StudentTask</code> so the frontend can make gatekeeping decisions without additional API calls: <code>require_quiz</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>, and <code>quiz_taken</code> (true only when a submitted <code>Response</code> exists against the student's <code>QuizResponseMap</code>). The frontend <code>AssignedReviews</code> component uses these fields to gate each review row — if <code>require_quiz && has_quiz_questionnaire && !quiz_taken</code>, a yellow "Take Quiz" button is shown instead of the review button.

Four fields were added to <code>StudentTask</code>:

<syntaxhighlight lang="ruby">
attr_accessor :assignment, :assignment_id, :current_stage, :participant,
:stage_deadline, :topic, :permission_granted,
:require_quiz, :quiz_taken, :has_quiz_questionnaire, :quiz_questionnaire_id
</syntaxhighlight>

The <code>from_participant</code> factory method was updated to compute these fields:

<syntaxhighlight lang="ruby">
def self.from_participant(participant)
asgn = participant.assignment
return nil unless asgn

review_maps = ReviewResponseMap.where(reviewer_id: participant.id)
quiz_q_id = review_maps.filter_map { |m| Team.find_by(id: m.reviewee_id)&.quiz_questionnaire_id }.first
quiz_taken = QuizResponseMap.where(reviewer_id: participant.id, reviewed_object_id: quiz_q_id)
.joins(:responses)
.where(responses: { is_submitted: true })
.exists? if quiz_q_id

new(
assignment: asgn.name,
assignment_id: asgn.id,
require_quiz: asgn.require_quiz || false,
has_quiz_questionnaire: quiz_q_id.present?,
quiz_questionnaire_id: quiz_q_id,
quiz_taken: quiz_taken || false,
# ... other fields
)
end
</syntaxhighlight>

=== 4) QuizResponseMapsController ===

A <code>QuizResponseMap</code> is self-referential: <code>reviewer_id == reviewee_id</code>, both pointing to the reviewer's own <code>AssignmentParticipant</code> record. This invariant is what distinguishes quiz maps from peer-review maps throughout the system. The endpoint is idempotent — if a map already exists for this student/questionnaire pair it is returned as-is rather than creating a duplicate, making it safe for the frontend to call on every "Take Quiz" click.

A new controller handles quiz map creation:

<syntaxhighlight lang="ruby">
# POST /quiz_response_maps
def create
# ... validate params, find assignment, resolve quiz questionnaire from team ...
map = QuizResponseMap.find_by(
reviewed_object_id: quiz_questionnaire.id,
reviewer_id: reviewer_participant.id,
reviewee_id: reviewer_participant.id
) || QuizResponseMap.new(...)

render json: {
quiz_map_id: map.id,
quiz_questionnaire_id: quiz_questionnaire.id,
reviewer_participant_id: reviewer_participant.id
}, status: :created
end
</syntaxhighlight>

=== 5) ResponseMapsController — Quiz Map Filtering ===

The <code>index</code> action must return only peer-review maps; quiz maps must not appear in the reviewer table. The primary guard <code>next if map.reviewer_id == map.reviewee_id</code> is reliable regardless of accidental id coincidences between questionnaire ids and assignment ids. A secondary <code>next unless assignment</code> check acts as belt-and-suspenders. Each returned row is augmented with <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> so the frontend can render the "Take Quiz" button without a second API call.

<code>ResponseMapsController#index</code> was updated to exclude quiz maps and include per-row quiz state for the frontend:

<syntaxhighlight lang="ruby">
result = maps.filter_map do |map|
# E2619: skip quiz maps (reviewer_id == reviewee_id)
next if map.reviewer_id == map.reviewee_id
# belt-and-suspenders: reviewed_object_id must reference an assignment
assignment = Assignment.find_by(id: map.reviewed_object_id)
next unless assignment

team = Team.find_by(id: map.reviewee_id)
quiz_questionnaire_id = team&.quiz_questionnaire_id
quiz_taken = quiz_questionnaire_id.present? &&
QuizResponseMap.where(reviewer_id: map.reviewer_id, reviewed_object_id: quiz_questionnaire_id)
.joins("INNER JOIN responses ON responses.map_id = response_maps.id")
.where(responses: { is_submitted: true }).exists?

{ id: map.id, quiz_questionnaire_id:, quiz_taken:, ... }
end
</syntaxhighlight>

=== 6) Instructor "Create Quiz" Button (AssignReviewer) ===

When clicked, the button navigates to the questionnaire editor with URL parameters (<code>type=Quiz</code>, <code>team_id</code>, <code>return_to</code>) that cause the editor to link the created questionnaire back to the team automatically via <code>PATCH /teams/:team_id/quiz_questionnaire</code>. After saving, the editor redirects back to the reviewer page.

'''Note:''' This is a temporary solution. In the full Expertiza workflow, quiz creation is initiated by a submitting team member from their own task page — not by an instructor from the reviewer-assignment page. The button was placed here because the student-facing entry point was not yet implemented in this codebase and should be removed or relocated once the proper student team submission flow is in place.

An <code>onCreateQuiz</code> handler was added to the <code>AssignReviewer</code> page:

<syntaxhighlight lang="typescript">
const onCreateQuiz = useCallback((teamId: number) => {
navigate(
`/questionnaires/new?type=Quiz` +
`&team_id=${teamId}` +
`&return_to=${encodeURIComponent(location.pathname + location.search)}`
);
}, [navigate, location]);
</syntaxhighlight>

After the questionnaire is saved, <code>QuestionnaireEditor</code> reads <code>team_id</code> and <code>return_to</code> from the URL, calls <code>PATCH /teams/:team_id/quiz_questionnaire</code>, and redirects back to the reviewer page.

=== 7) Student "Take Quiz" Button (AssignedReviews) ===

The per-row quiz state (<code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>) is returned directly in the <code>GET /response_maps</code> response so no extra API call is needed to decide which button to show. When the student clicks "Take Quiz", the frontend first calls <code>POST /quiz_response_maps</code> (idempotent) to obtain or reuse a quiz map id, then navigates to the existing <code>TeammateReview</code> page with a <code>redirect_after</code> parameter encoding the peer-review URL. After the quiz is submitted the page auto-redirects to the actual review.

The <code>AssignedReviews</code> component now reads per-row quiz state from the response maps API response. When <code>require_quiz && hasQuizQuestionnaire && !quizCompleted</code>, a yellow "Take Quiz" button is shown:

<syntaxhighlight lang="typescript">
const handleTakeQuiz = async (review: AssignedReviewRow, reviewUrl: string) => {
const res = await axiosClient.post('/quiz_response_maps', {
assignment_id: review.assignmentId,
reviewer_user_id: currentUser.id,
reviewee_team_id: review.revieweeTeamId,
});
const { quiz_map_id, quiz_questionnaire_id } = res.data;
navigate(
`/student_teams/teammate_review?` +
`map_id=${quiz_map_id}` +
`&questionnaire_id=${quiz_questionnaire_id}` +
`&questionnaire_type=Quiz` +
`&redirect_after=${encodeURIComponent(reviewUrl)}`
);
};
</syntaxhighlight>

=== 8) Quiz Mode in TeammateReview ===

Reusing the existing <code>TeammateReview</code> page for quiz-taking avoids duplicating the form rendering logic. Quiz mode is activated by <code>questionnaire_type=Quiz</code> in the URL, which causes the page to fetch quiz questionnaire items, disable the "Save Draft" button (quizzes are single-submission), display the score after submission, and show a "Proceed to Review" button that navigates to the <code>redirect_after</code> URL.

The existing <code>TeammateReview</code> page was extended with a quiz mode:

<syntaxhighlight lang="typescript">
if (isQuizMode) {
setQuizScore(submitRes.data?.total_score ?? null);
}
</syntaxhighlight>

=== 9) Correct Answer Fields in Questionnaire Editor ===

When the questionnaire type is "Quiz", each item in <code>QuestionnaireItemsFieldArray</code> needs a "Correct answer" input whose control type depends on the question type. A dropdown makes sense for choice questions (the options are already defined), a bounded number input for Scale, a checkbox for Checkbox, and a free-text input for TextField (scored case-insensitively). The <code>correct_answer</code> value is persisted through <code>QuestionnairesController</code> and serialised via <code>Item#as_json</code> only for quiz items.

<code>QuestionnaireItemsFieldArray</code> renders a "Correct answer" row for each quiz item. The input type varies by question type:

{| class="wikitable"
! Question type !! Correct answer input
|-
| Text field || Free-text <code><input type="text"></code>; scored case-insensitively at submission
|-
| Multiple choice / Multiple choice checkbox || <code><select></code> pre-populated from the item's alternatives
|-
| Scale || <code><input type="number"></code> bounded by the item's weight range
|-
| Checkbox || <code><input type="checkbox"></code> (correct = checked)
|}

=== 10) GET /questions/quiz_types Endpoint ===

Hard-coding the list of allowed quiz item types in the frontend would create a maintenance hazard every time a new type is added to the backend. The <code>GET /questions/quiz_types</code> endpoint lets the frontend fetch the authoritative list at runtime. The same constant is used in the <code>create</code> action to validate incoming item types, returning 422 if an unsupported type is submitted for a quiz questionnaire.

A new endpoint returns the allowed item types for quiz questionnaires so the frontend does not hard-code the list:

<syntaxhighlight lang="ruby">
QUIZ_ITEM_TYPES = %w[TextField MultipleChoiceRadio MultipleChoiceCheckbox Scale Checkbox].freeze

# GET /questions/quiz_types
def quiz_types
render json: QUIZ_ITEM_TYPES, status: :ok
end
</syntaxhighlight>

The <code>create</code> action on <code>QuestionsController</code> also validates that quiz questionnaires only accept items of these types, returning 422 with an error message otherwise.

== Test Plan ==

Tests were added for all new and modified backend components. The full suite passes with 0 failures.

=== Pre-Test Setup ===

All request specs use the shared <code>create_roles_hierarchy</code> helper and JWT-based auth:

<syntaxhighlight lang="ruby">
before(:all) { @roles = create_roles_hierarchy }
let(:token) { JsonWebToken.encode({ id: instructor.id }) }
let(:Authorization) { "Bearer #{token}" }
</syntaxhighlight>

=== Model: Response — Quiz Scoring ===

11 new examples in <code>spec/models/response_spec.rb</code> validate the quiz scoring path, covering both spaced and CamelCase question type names, correct/incorrect answers, blank answers, multi-item accumulation, and maximum score calculation.

<syntaxhighlight lang="ruby">
describe '#aggregate_questionnaire_score (quiz)' do
it 'scores a correct "Text field" answer' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'paris') # case-insensitive
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(2)
end

it 'scores an incorrect "Text field" answer as 0' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'London')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end

it 'gives 0 when the comments column is blank' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: '')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end
end
</syntaxhighlight>

=== Model: StudentTask — Quiz Gateway Fields ===

7 examples in <code>spec/models/student_task_spec.rb</code> verify the quiz gateway fields are populated by <code>from_participant</code> and serialised by <code>as_json</code>.

=== Request: QuizResponseMaps ===

6 examples in <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| Happy path — creates map and returns IDs || 201
|-
| Idempotent — reuses existing map on repeat call || 201
|-
| Missing <code>assignment_id</code> || 400
|-
| Missing <code>reviewer_user_id</code> || 400
|-
| Assignment not found (id = 999999999) || 404
|-
| Team has no quiz questionnaire || 422
|}

=== Request: ResponseMaps ===

7 examples in <code>spec/requests/api/v1/response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| GET — returns peer-review maps, excludes quiz maps || 200
|-
| GET — each entry includes <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> || 200
|-
| GET — returns empty array when reviewer has no maps || 200
|-
| GET — missing <code>reviewer_user_id</code> || 400
|-
| POST — creates ReviewResponseMap and returns IDs || 201
|-
| POST — idempotent, returns same map on repeat call || 201
|-
| POST — missing required param || 400
|}

=== Request: Questions — Quiz Types ===

3 new examples in <code>spec/requests/api/v1/questions_spec.rb</code>:

<syntaxhighlight lang="ruby">
describe 'GET /questions/quiz_types' do
it 'returns 200 with the allowed quiz item type strings' do
get '/questions/quiz_types', headers: { 'Authorization' => auth_header }
types = JSON.parse(response.body)
expect(types).to include('TextField', 'MultipleChoiceRadio', 'MultipleChoiceCheckbox')
end
end
</syntaxhighlight>

=== Test Coverage Summary ===

{| class="wikitable"
! Spec file !! Examples before !! Examples after
|-
| <code>spec/models/student_task_spec.rb</code> || 3 (failing) || 7 ✅
|-
| <code>spec/models/response_spec.rb</code> || 11 || 22 ✅
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || 19 || 22 ✅
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || 0 || 6 ✅
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || 0 || 7 ✅
|-
| '''Total new examples''' || || '''27'''
|}

== Files Modified ==

=== Backend (Ruby on Rails) ===

{| class="wikitable"
! File !! Change
|-
| <code>app/models/response.rb</code> || Added quiz-aware scoring to <code>aggregate_questionnaire_score</code> and <code>maximum_score</code>
|-
| <code>app/models/student_task.rb</code> || Added four quiz gateway fields; updated <code>from_participant</code> and <code>as_json</code>
|-
| <code>app/models/Item.rb</code> || Added <code>QUIZ_ITEM_TYPES</code>, <code>is_quiz_item?</code>, <code>correct_answer_only_for_quiz</code> validation, and conditional <code>as_json</code>
|-
| <code>app/models/team.rb</code> || Added <code>quiz_questionnaire_id</code> attribute and <code>quiz_questionnaire</code> association
|-
| <code>app/models/quiz_response_map.rb</code> || Minor documentation updates
|-
| <code>app/controllers/questions_controller.rb</code> || Added <code>GET /questions/quiz_types</code>; added quiz item type validation in <code>create</code>
|-
| <code>app/controllers/quiz_response_maps_controller.rb</code> || New controller: <code>POST /quiz_response_maps</code>
|-
| <code>app/controllers/response_maps_controller.rb</code> || Updated <code>index</code> to filter quiz maps and return per-row quiz state; added <code>create</code> and <code>destroy</code>
|-
| <code>app/controllers/teams_controller.rb</code> || Added <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>app/controllers/questionnaires_controller.rb</code> || Exposed <code>correct_answer</code> in strong parameters
|-
| <code>config/routes.rb</code> || Added routes for quiz_response_maps, quiz_types, and quiz_questionnaire on teams
|-
| <code>db/migrate/20260423000001_add_correct_answer_to_items.rb</code> || New migration: adds <code>correct_answer</code> string column to <code>items</code>
|-
| <code>db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb</code> || New migration: adds <code>quiz_questionnaire_id</code> integer column + index to <code>teams</code>
|-
| <code>spec/models/student_task_spec.rb</code> || Fixed existing test failures; added quiz gateway field assertions
|-
| <code>spec/models/response_spec.rb</code> || Added 11 new quiz scoring tests
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || Added tests for <code>quiz_types</code> endpoint and quiz item creation/rejection
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || New spec: 6 tests covering happy path, idempotency, and error cases
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || New spec: 7 tests covering quiz-map exclusion, quiz state fields, and POST CRUD
|}

=== Frontend (React/TypeScript) ===

{| class="wikitable"
! File !! Change
|-
| <code>src/pages/StudentTasks/AssignedReviews.tsx</code> || Added "Take Quiz" button; per-row quiz state; <code>handleTakeQuiz</code> calling <code>POST /quiz_response_maps</code>
|-
| <code>src/pages/Assignments/AssignReviewer.tsx</code> || Added "Create Quiz" button that navigates to the questionnaire editor pre-linked to the team
|-
| <code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> || Added correct-answer row for each quiz item type
|-
| <code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> || Added team-quiz creation flow: links new questionnaire to team via <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>src/pages/Student Teams/TeammateReview.tsx</code> || Added quiz mode (<code>isQuizMode</code>), quiz score display, and <code>redirect_after</code> param support
|-
| <code>src/pages/Assignments/AssignmentEditor.tsx</code> || Ensured <code>require_quiz</code> checkbox is wired to the form state
|-
| <code>src/pages/Assignments/AssignmentUtil.ts</code> || Added <code>require_quiz</code> to <code>IAssignmentFormValues</code>
|-
| <code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> || Added <code>correct_answer</code> to <code>IItem</code>; updated <code>transformQuestionnaireRequest</code>
|-
| <code>src/components/Form/FormSelect.tsx</code> || Documentation only (JSDoc)
|}

=== Github Pull Request ===

* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/181
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/349
=== Video ===

https://youtu.be/BWh_6bavtbE

=== Mentor ===

Ed Gehringer (efg@ncsu.edu)

=== Team Member ===

* An Mai (atmai@ncsu.edu)
* Mekhi Parker (mrparke4@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-28T14:55:26Z

Atmai:

= E2619: Student Quizzes — Design Document =

== Introduction ==

[https://expertiza.ncsu.edu/ Expertiza] is an educational web application collaboratively
developed and maintained by students and faculty at NCSU. As an open-source project built
on the Ruby on Rails platform, its code is accessible on GitHub. The platform enables
students to provide peer reviews and refine their work based on feedback.

This design document describes the implementation of the '''E2619 Student Quizzes'''
project, covering both the frontend (React/TypeScript) and backend (Ruby on Rails API).
The project builds on the E2607 questionnaire rendering code and extends it with
quiz-specific capabilities: directing students to quizzes/reviews, scoring quiz responses,
specifying correct answers, and handling fill-in-the-blank questions.

== Project Overview ==

Quizzes in Expertiza are designed to ensure that reviewers comprehend the material they
are evaluating. When an assignment includes quizzes (<code>require_quiz = true</code>),
submitting teams create quizzes based on their submissions. Reviewers must complete the
quizzes before reviewing to demonstrate their understanding. If a reviewer performs
poorly, their review can be discounted to maintain quality.

== Previous Implementation ==

The prior codebase provided the data models, CRUD controllers, and UI components needed for assignments, questionnaires, and peer reviews. However, the quiz workflow was incomplete in several key ways:

* <code>Response#aggregate_questionnaire_score</code> computed scores as <code>answer * weight</code> using only the numeric answer column, with no correctness check against a stored correct answer. There was no way to distinguish a quiz response from a regular review response.
* The <code>Item</code> model had no <code>correct_answer</code> column; there was nowhere to persist the expected answer for a quiz item.
* The <code>StudentTask</code> model did not carry quiz gateway fields (<code>require_quiz</code>, <code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>), so the frontend had no structured way to know whether a student must take a quiz before reviewing.
* The <code>Team</code> model had no <code>quiz_questionnaire_id</code>. Quiz questionnaire ownership was expected to flow through the assignment's questionnaire list, which required instructor configuration and did not support per-team quizzes.
* The <code>ResponseMapsController</code> had no index action that filtered out quiz maps, so the frontend could not safely list a student's review assignments without also receiving spurious self-referential quiz entries.
* No <code>QuizResponseMapsController</code> existed; there was no endpoint to create a <code>QuizResponseMap</code> before a student started a quiz.
* The questionnaire editor rendered no "Correct answer" field for any item type when the questionnaire type was set to "Quiz".
* The student task page had no "Take Quiz" button or any flow to route a student from a quiz gate to the quiz form and back to their review.

== Project Goals ==

Based on the gaps above, this project aimed to:

# Add a <code>correct_answer</code> string column to quiz items so submitting teams can specify expected answers at quiz-creation time.
# Extend <code>Response#aggregate_questionnaire_score</code> to detect quiz responses by the <code>reviewer_id == reviewee_id</code> invariant and score text/choice items from the <code>comments</code> column using case-insensitive equality.
# Extend <code>StudentTask</code> with four quiz gateway fields so the frontend can render the correct button (Take Quiz / Start Review) without extra API calls.
# Add a <code>quiz_questionnaire_id</code> column to <code>Team</code> so each submitting team directly owns its quiz questionnaire, enabling per-team quizzes on the same assignment.
# Implement <code>POST /quiz_response_maps</code> so the frontend can create (or reuse) a <code>QuizResponseMap</code> before navigating a student to the quiz form.
# Update <code>ResponseMapsController#index</code> to exclude quiz maps and include per-row quiz state.
# Add a "Correct answer" row in the questionnaire editor for every quiz item type.
# Implement an instructor "Create Quiz" button on the reviewer-assignment page that opens the questionnaire editor pre-linked to the team.
# Implement a "Take Quiz" button in the student task list that calls <code>POST /quiz_response_maps</code> and navigates to the existing review form in quiz mode.
# Add <code>GET /questions/quiz_types</code> so the frontend can fetch the allowed quiz item types dynamically.

== Design ==

=== Architecture Overview ===

<pre>
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React/TS) │
│ │
│ AssignedReviews ──→ [Take Quiz] ──→ TeammateReview │
│ │ (quiz mode) │ │
│ │ └──→ [redirect] │
│ └──→ [Start/Open Review] ──→ TeammateReview │
│ (review mode) │
│ QuestionnaireEditor ──→ correct_answer fields per type │
└──────────────────────────┬──────────────────────────────────┘
│ REST API
┌──────────────────────────┴──────────────────────────────────┐
│ Backend (Rails API) │
│ │
│ QuizResponseMapsController (POST /quiz_response_maps) │
│ ResponsesController (create / update / submit) │
│ ResponseMapsController (index — filters quiz maps) │
│ Response model (aggregate_questionnaire_score) │
│ StudentTask model (quiz gateway fields) │
└─────────────────────────────────────────────────────────────┘
</pre>

=== UML Design ===

<pre>
┌───────────────────────────────────────┐
│ Assignment │
├───────────────────────────────────────┤
│ +boolean require_quiz │
│ +int num_quiz_questions │
│ +has_many questionnaires (via AQ) │
└────────────────────┬──────────────────┘
│ has_many (via AQ)
▼
┌───────────────────────────────────────┐ ┌─────────────────────────────┐
│ Questionnaire │ │ Team [UPDATED] │
├───────────────────────────────────────┤ ├─────────────────────────────┤
│ +String name │ │ +int quiz_questionnaire_id │◄─── NEW
│ +String questionnaire_type │◄────│ +belongs_to │
│ ("Quiz" for quiz questionnaires) │ │ quiz_questionnaire │
│ +int min_question_score │ └─────────────────────────────┘
│ +int max_question_score │
│ +int instructor_id │
└────────────────────┬──────────────────┘
│ has_many
▼
┌───────────────────────────────────────┐
│ Item [UPDATED] │
├───────────────────────────────────────┤
│ +String txt │
│ +String question_type │
│ +int weight │
│ +String correct_answer ◄│─── NEW
│ +QUIZ_ITEM_TYPES : Array ◄│─── NEW
│ +is_quiz_item?() : boolean ◄│─── NEW
└────────────────────┬──────────────────┘
│ has_many answers
▼
┌───────────────────────────────────────┐
│ Answer │
├───────────────────────────────────────┤
│ +int item_id │
│ +int response_id │
│ +int answer │
│ +String comments (quiz answer here) │
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ Response [UPDATED] │
├───────────────────────────────────────┤
│ +int map_id │
│ +boolean is_submitted │
│ +int round │
│ +aggregate_questionnaire_score() ◄│─── quiz-aware: checks
│ │ reviewer_id == reviewee_id
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ QuizResponseMap [UPDATED] │
├───────────────────────────────────────┤
│ +int reviewer_id │
│ +int reviewee_id │
│ (reviewer_id == reviewee_id ◄│─── self-referential invariant
│ identifies quiz maps) │ distinguishes quiz from review
│ +int reviewed_object_id ◄│─── quiz questionnaire id
│ +mappings_for_reviewer() │
└───────────────────────────────────────┘
</pre>

=== Screenshots ===
[[File:e2619_take_quiz_button.png|Take Quiz button in AssignedReviews]]
[[File:e2619_correct_answer_fields.png|Correct answer fields in Questionnaire Editor]]
[[File:e2619_quiz_score.png|Quiz score display after submission]]

== Changes Implemented ==

=== 1) Database Schema Additions ===

Two new columns support the quiz feature. The <code>correct_answer</code> string column on <code>items</code> stores the expected answer for each quiz question. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items. The <code>quiz_questionnaire_id</code> integer column on <code>teams</code> lets each submitting team directly own its quiz questionnaire — a key change that makes per-team quizzes possible and replaces a previous approach that required manual wiring at the assignment level.

Two migrations were added to support the quiz features:

<syntaxhighlight lang="ruby">
# db/migrate/20260423000001_add_correct_answer_to_items.rb
class AddCorrectAnswerToItems < ActiveRecord::Migration[8.0]
def change
add_column :items, :correct_answer, :string
end
end

# db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb
class AddQuizQuestionnaireIdToTeams < ActiveRecord::Migration[8.0]
def change
add_column :teams, :quiz_questionnaire_id, :integer, null: true, default: nil
add_index :teams, :quiz_questionnaire_id
end
end
</syntaxhighlight>

The <code>correct_answer</code> column stores the expected answer for each quiz item. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items.

The <code>quiz_questionnaire_id</code> column on <code>teams</code> allows each submitting team to directly own its quiz questionnaire. This replaces a previous approach that required the instructor to manually wire a questionnaire to the assignment, and is the key change that makes per-team quizzes possible.

=== 2) Quiz-Aware Scoring in Response Model ===

Quiz responses are identified by the invariant <code>reviewer_id == reviewee_id</code> on the associated <code>ResponseMap</code> — no STI <code>type</code> column is needed. For text and choice quiz items the student's answer is stored in the <code>comments</code> column (not the numeric <code>answer</code> column), so scoring uses case-insensitive string equality. Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions. The final score is returned in the <code>PATCH /responses/:id/submit</code> response body as <code>total_score</code> and displayed to the student before the redirect.

The core scoring logic in <code>Response#aggregate_questionnaire_score</code> was extended to handle quiz responses:

<syntaxhighlight lang="ruby">
def aggregate_questionnaire_score
sum = 0
is_quiz = map.reviewer_id == map.reviewee_id
comment_scored_types = %w[
TextField MultipleChoiceRadio MultipleChoiceCheckbox
Text\ field Multiple\ choice Multiple\ choice\ checkbox
].freeze

scores.each do |s|
if is_quiz && comment_scored_types.include?(s.item.question_type)
correct = s.item.correct_answer.to_s.strip.downcase
student_answer = s.comments.to_s.strip.downcase
sum += (student_answer == correct && correct.present? ? 1 : 0) * (s.item.weight || 1)
else
sum += s.answer * (s.item.weight || 1) unless s.answer.nil?
end
end
sum
end
</syntaxhighlight>

Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions.

=== 3) StudentTask Quiz Gateway Fields ===

Four fields were added to <code>StudentTask</code> so the frontend can make gatekeeping decisions without additional API calls: <code>require_quiz</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>, and <code>quiz_taken</code> (true only when a submitted <code>Response</code> exists against the student's <code>QuizResponseMap</code>). The frontend <code>AssignedReviews</code> component uses these fields to gate each review row — if <code>require_quiz && has_quiz_questionnaire && !quiz_taken</code>, a yellow "Take Quiz" button is shown instead of the review button.

Four fields were added to <code>StudentTask</code>:

<syntaxhighlight lang="ruby">
attr_accessor :assignment, :assignment_id, :current_stage, :participant,
:stage_deadline, :topic, :permission_granted,
:require_quiz, :quiz_taken, :has_quiz_questionnaire, :quiz_questionnaire_id
</syntaxhighlight>

The <code>from_participant</code> factory method was updated to compute these fields:

<syntaxhighlight lang="ruby">
def self.from_participant(participant)
asgn = participant.assignment
return nil unless asgn

review_maps = ReviewResponseMap.where(reviewer_id: participant.id)
quiz_q_id = review_maps.filter_map { |m| Team.find_by(id: m.reviewee_id)&.quiz_questionnaire_id }.first
quiz_taken = QuizResponseMap.where(reviewer_id: participant.id, reviewed_object_id: quiz_q_id)
.joins(:responses)
.where(responses: { is_submitted: true })
.exists? if quiz_q_id

new(
assignment: asgn.name,
assignment_id: asgn.id,
require_quiz: asgn.require_quiz || false,
has_quiz_questionnaire: quiz_q_id.present?,
quiz_questionnaire_id: quiz_q_id,
quiz_taken: quiz_taken || false,
# ... other fields
)
end
</syntaxhighlight>

=== 4) QuizResponseMapsController ===

A <code>QuizResponseMap</code> is self-referential: <code>reviewer_id == reviewee_id</code>, both pointing to the reviewer's own <code>AssignmentParticipant</code> record. This invariant is what distinguishes quiz maps from peer-review maps throughout the system. The endpoint is idempotent — if a map already exists for this student/questionnaire pair it is returned as-is rather than creating a duplicate, making it safe for the frontend to call on every "Take Quiz" click.

A new controller handles quiz map creation:

<syntaxhighlight lang="ruby">
# POST /quiz_response_maps
def create
# ... validate params, find assignment, resolve quiz questionnaire from team ...
map = QuizResponseMap.find_by(
reviewed_object_id: quiz_questionnaire.id,
reviewer_id: reviewer_participant.id,
reviewee_id: reviewer_participant.id
) || QuizResponseMap.new(...)

render json: {
quiz_map_id: map.id,
quiz_questionnaire_id: quiz_questionnaire.id,
reviewer_participant_id: reviewer_participant.id
}, status: :created
end
</syntaxhighlight>

=== 5) ResponseMapsController — Quiz Map Filtering ===

The <code>index</code> action must return only peer-review maps; quiz maps must not appear in the reviewer table. The primary guard <code>next if map.reviewer_id == map.reviewee_id</code> is reliable regardless of accidental id coincidences between questionnaire ids and assignment ids. A secondary <code>next unless assignment</code> check acts as belt-and-suspenders. Each returned row is augmented with <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> so the frontend can render the "Take Quiz" button without a second API call.

<code>ResponseMapsController#index</code> was updated to exclude quiz maps and include per-row quiz state for the frontend:

<syntaxhighlight lang="ruby">
result = maps.filter_map do |map|
# E2619: skip quiz maps (reviewer_id == reviewee_id)
next if map.reviewer_id == map.reviewee_id
# belt-and-suspenders: reviewed_object_id must reference an assignment
assignment = Assignment.find_by(id: map.reviewed_object_id)
next unless assignment

team = Team.find_by(id: map.reviewee_id)
quiz_questionnaire_id = team&.quiz_questionnaire_id
quiz_taken = quiz_questionnaire_id.present? &&
QuizResponseMap.where(reviewer_id: map.reviewer_id, reviewed_object_id: quiz_questionnaire_id)
.joins("INNER JOIN responses ON responses.map_id = response_maps.id")
.where(responses: { is_submitted: true }).exists?

{ id: map.id, quiz_questionnaire_id:, quiz_taken:, ... }
end
</syntaxhighlight>

=== 6) Instructor "Create Quiz" Button (AssignReviewer) ===

When clicked, the button navigates to the questionnaire editor with URL parameters (<code>type=Quiz</code>, <code>team_id</code>, <code>return_to</code>) that cause the editor to link the created questionnaire back to the team automatically via <code>PATCH /teams/:team_id/quiz_questionnaire</code>. After saving, the editor redirects back to the reviewer page.

'''Note:''' This is a temporary solution. In the full Expertiza workflow, quiz creation is initiated by a submitting team member from their own task page — not by an instructor from the reviewer-assignment page. The button was placed here because the student-facing entry point was not yet implemented in this codebase and should be removed or relocated once the proper student team submission flow is in place.

An <code>onCreateQuiz</code> handler was added to the <code>AssignReviewer</code> page:

<syntaxhighlight lang="typescript">
const onCreateQuiz = useCallback((teamId: number) => {
navigate(
`/questionnaires/new?type=Quiz` +
`&team_id=${teamId}` +
`&return_to=${encodeURIComponent(location.pathname + location.search)}`
);
}, [navigate, location]);
</syntaxhighlight>

After the questionnaire is saved, <code>QuestionnaireEditor</code> reads <code>team_id</code> and <code>return_to</code> from the URL, calls <code>PATCH /teams/:team_id/quiz_questionnaire</code>, and redirects back to the reviewer page.

=== 7) Student "Take Quiz" Button (AssignedReviews) ===

The per-row quiz state (<code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>) is returned directly in the <code>GET /response_maps</code> response so no extra API call is needed to decide which button to show. When the student clicks "Take Quiz", the frontend first calls <code>POST /quiz_response_maps</code> (idempotent) to obtain or reuse a quiz map id, then navigates to the existing <code>TeammateReview</code> page with a <code>redirect_after</code> parameter encoding the peer-review URL. After the quiz is submitted the page auto-redirects to the actual review.

The <code>AssignedReviews</code> component now reads per-row quiz state from the response maps API response. When <code>require_quiz && hasQuizQuestionnaire && !quizCompleted</code>, a yellow "Take Quiz" button is shown:

<syntaxhighlight lang="typescript">
const handleTakeQuiz = async (review: AssignedReviewRow, reviewUrl: string) => {
const res = await axiosClient.post('/quiz_response_maps', {
assignment_id: review.assignmentId,
reviewer_user_id: currentUser.id,
reviewee_team_id: review.revieweeTeamId,
});
const { quiz_map_id, quiz_questionnaire_id } = res.data;
navigate(
`/student_teams/teammate_review?` +
`map_id=${quiz_map_id}` +
`&questionnaire_id=${quiz_questionnaire_id}` +
`&questionnaire_type=Quiz` +
`&redirect_after=${encodeURIComponent(reviewUrl)}`
);
};
</syntaxhighlight>

=== 8) Quiz Mode in TeammateReview ===

Reusing the existing <code>TeammateReview</code> page for quiz-taking avoids duplicating the form rendering logic. Quiz mode is activated by <code>questionnaire_type=Quiz</code> in the URL, which causes the page to fetch quiz questionnaire items, disable the "Save Draft" button (quizzes are single-submission), display the score after submission, and show a "Proceed to Review" button that navigates to the <code>redirect_after</code> URL.

The existing <code>TeammateReview</code> page was extended with a quiz mode:

<syntaxhighlight lang="typescript">
if (isQuizMode) {
setQuizScore(submitRes.data?.total_score ?? null);
}
</syntaxhighlight>

=== 9) Correct Answer Fields in Questionnaire Editor ===

When the questionnaire type is "Quiz", each item in <code>QuestionnaireItemsFieldArray</code> needs a "Correct answer" input whose control type depends on the question type. A dropdown makes sense for choice questions (the options are already defined), a bounded number input for Scale, a checkbox for Checkbox, and a free-text input for TextField (scored case-insensitively). The <code>correct_answer</code> value is persisted through <code>QuestionnairesController</code> and serialised via <code>Item#as_json</code> only for quiz items.

<code>QuestionnaireItemsFieldArray</code> renders a "Correct answer" row for each quiz item. The input type varies by question type:

{| class="wikitable"
! Question type !! Correct answer input
|-
| Text field || Free-text <code><input type="text"></code>; scored case-insensitively at submission
|-
| Multiple choice / Multiple choice checkbox || <code><select></code> pre-populated from the item's alternatives
|-
| Scale || <code><input type="number"></code> bounded by the item's weight range
|-
| Checkbox || <code><input type="checkbox"></code> (correct = checked)
|}

=== 10) GET /questions/quiz_types Endpoint ===

Hard-coding the list of allowed quiz item types in the frontend would create a maintenance hazard every time a new type is added to the backend. The <code>GET /questions/quiz_types</code> endpoint lets the frontend fetch the authoritative list at runtime. The same constant is used in the <code>create</code> action to validate incoming item types, returning 422 if an unsupported type is submitted for a quiz questionnaire.

A new endpoint returns the allowed item types for quiz questionnaires so the frontend does not hard-code the list:

<syntaxhighlight lang="ruby">
QUIZ_ITEM_TYPES = %w[TextField MultipleChoiceRadio MultipleChoiceCheckbox Scale Checkbox].freeze

# GET /questions/quiz_types
def quiz_types
render json: QUIZ_ITEM_TYPES, status: :ok
end
</syntaxhighlight>

The <code>create</code> action on <code>QuestionsController</code> also validates that quiz questionnaires only accept items of these types, returning 422 with an error message otherwise.

== Test Plan ==

Tests were added for all new and modified backend components. The full suite passes with 0 failures.

=== Pre-Test Setup ===

All request specs use the shared <code>create_roles_hierarchy</code> helper and JWT-based auth:

<syntaxhighlight lang="ruby">
before(:all) { @roles = create_roles_hierarchy }
let(:token) { JsonWebToken.encode({ id: instructor.id }) }
let(:Authorization) { "Bearer #{token}" }
</syntaxhighlight>

=== Model: Response — Quiz Scoring ===

11 new examples in <code>spec/models/response_spec.rb</code> validate the quiz scoring path, covering both spaced and CamelCase question type names, correct/incorrect answers, blank answers, multi-item accumulation, and maximum score calculation.

<syntaxhighlight lang="ruby">
describe '#aggregate_questionnaire_score (quiz)' do
it 'scores a correct "Text field" answer' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'paris') # case-insensitive
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(2)
end

it 'scores an incorrect "Text field" answer as 0' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'London')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end

it 'gives 0 when the comments column is blank' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: '')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end
end
</syntaxhighlight>

=== Model: StudentTask — Quiz Gateway Fields ===

7 examples in <code>spec/models/student_task_spec.rb</code> verify the quiz gateway fields are populated by <code>from_participant</code> and serialised by <code>as_json</code>.

=== Request: QuizResponseMaps ===

6 examples in <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| Happy path — creates map and returns IDs || 201
|-
| Idempotent — reuses existing map on repeat call || 201
|-
| Missing <code>assignment_id</code> || 400
|-
| Missing <code>reviewer_user_id</code> || 400
|-
| Assignment not found (id = 999999999) || 404
|-
| Team has no quiz questionnaire || 422
|}

=== Request: ResponseMaps ===

7 examples in <code>spec/requests/api/v1/response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| GET — returns peer-review maps, excludes quiz maps || 200
|-
| GET — each entry includes <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> || 200
|-
| GET — returns empty array when reviewer has no maps || 200
|-
| GET — missing <code>reviewer_user_id</code> || 400
|-
| POST — creates ReviewResponseMap and returns IDs || 201
|-
| POST — idempotent, returns same map on repeat call || 201
|-
| POST — missing required param || 400
|}

=== Request: Questions — Quiz Types ===

3 new examples in <code>spec/requests/api/v1/questions_spec.rb</code>:

<syntaxhighlight lang="ruby">
describe 'GET /questions/quiz_types' do
it 'returns 200 with the allowed quiz item type strings' do
get '/questions/quiz_types', headers: { 'Authorization' => auth_header }
types = JSON.parse(response.body)
expect(types).to include('TextField', 'MultipleChoiceRadio', 'MultipleChoiceCheckbox')
end
end
</syntaxhighlight>

=== Test Coverage Summary ===

{| class="wikitable"
! Spec file !! Examples before !! Examples after
|-
| <code>spec/models/student_task_spec.rb</code> || 3 (failing) || 7 ✅
|-
| <code>spec/models/response_spec.rb</code> || 11 || 22 ✅
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || 19 || 22 ✅
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || 0 || 6 ✅
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || 0 || 7 ✅
|-
| '''Total new examples''' || || '''27'''
|}

== Files Modified ==

=== Backend (Ruby on Rails) ===

{| class="wikitable"
! File !! Change
|-
| <code>app/models/response.rb</code> || Added quiz-aware scoring to <code>aggregate_questionnaire_score</code> and <code>maximum_score</code>
|-
| <code>app/models/student_task.rb</code> || Added four quiz gateway fields; updated <code>from_participant</code> and <code>as_json</code>
|-
| <code>app/models/Item.rb</code> || Added <code>QUIZ_ITEM_TYPES</code>, <code>is_quiz_item?</code>, <code>correct_answer_only_for_quiz</code> validation, and conditional <code>as_json</code>
|-
| <code>app/models/team.rb</code> || Added <code>quiz_questionnaire_id</code> attribute and <code>quiz_questionnaire</code> association
|-
| <code>app/models/quiz_response_map.rb</code> || Minor documentation updates
|-
| <code>app/controllers/questions_controller.rb</code> || Added <code>GET /questions/quiz_types</code>; added quiz item type validation in <code>create</code>
|-
| <code>app/controllers/quiz_response_maps_controller.rb</code> || New controller: <code>POST /quiz_response_maps</code>
|-
| <code>app/controllers/response_maps_controller.rb</code> || Updated <code>index</code> to filter quiz maps and return per-row quiz state; added <code>create</code> and <code>destroy</code>
|-
| <code>app/controllers/teams_controller.rb</code> || Added <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>app/controllers/questionnaires_controller.rb</code> || Exposed <code>correct_answer</code> in strong parameters
|-
| <code>config/routes.rb</code> || Added routes for quiz_response_maps, quiz_types, and quiz_questionnaire on teams
|-
| <code>db/migrate/20260423000001_add_correct_answer_to_items.rb</code> || New migration: adds <code>correct_answer</code> string column to <code>items</code>
|-
| <code>db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb</code> || New migration: adds <code>quiz_questionnaire_id</code> integer column + index to <code>teams</code>
|-
| <code>spec/models/student_task_spec.rb</code> || Fixed existing test failures; added quiz gateway field assertions
|-
| <code>spec/models/response_spec.rb</code> || Added 11 new quiz scoring tests
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || Added tests for <code>quiz_types</code> endpoint and quiz item creation/rejection
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || New spec: 6 tests covering happy path, idempotency, and error cases
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || New spec: 7 tests covering quiz-map exclusion, quiz state fields, and POST CRUD
|}

=== Frontend (React/TypeScript) ===

{| class="wikitable"
! File !! Change
|-
| <code>src/pages/StudentTasks/AssignedReviews.tsx</code> || Added "Take Quiz" button; per-row quiz state; <code>handleTakeQuiz</code> calling <code>POST /quiz_response_maps</code>
|-
| <code>src/pages/Assignments/AssignReviewer.tsx</code> || Added "Create Quiz" button that navigates to the questionnaire editor pre-linked to the team
|-
| <code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> || Added correct-answer row for each quiz item type
|-
| <code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> || Added team-quiz creation flow: links new questionnaire to team via <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>src/pages/Student Teams/TeammateReview.tsx</code> || Added quiz mode (<code>isQuizMode</code>), quiz score display, and <code>redirect_after</code> param support
|-
| <code>src/pages/Assignments/AssignmentEditor.tsx</code> || Ensured <code>require_quiz</code> checkbox is wired to the form state
|-
| <code>src/pages/Assignments/AssignmentUtil.ts</code> || Added <code>require_quiz</code> to <code>IAssignmentFormValues</code>
|-
| <code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> || Added <code>correct_answer</code> to <code>IItem</code>; updated <code>transformQuestionnaireRequest</code>
|-
| <code>src/components/Form/FormSelect.tsx</code> || Documentation only (JSDoc)
|}

=== Github Pull Request ===

* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/179
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/345
=== Video ===

https://youtu.be/BWh_6bavtbE

=== Mentor ===

Ed Gehringer (efg@ncsu.edu)

=== Team Member ===

* An Mai (atmai@ncsu.edu)
* Mekhi Parker (mrparke4@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-28T14:44:09Z

Atmai:

= E2619: Student Quizzes — Design Document =

== Introduction ==

[https://expertiza.ncsu.edu/ Expertiza] is an educational web application collaboratively
developed and maintained by students and faculty at NCSU. As an open-source project built
on the Ruby on Rails platform, its code is accessible on GitHub. The platform enables
students to provide peer reviews and refine their work based on feedback.

This design document describes the implementation of the '''E2619 Student Quizzes'''
project, covering both the frontend (React/TypeScript) and backend (Ruby on Rails API).
The project builds on the E2607 questionnaire rendering code and extends it with
quiz-specific capabilities: directing students to quizzes/reviews, scoring quiz responses,
specifying correct answers, and handling fill-in-the-blank questions.

== Project Overview ==

Quizzes in Expertiza are designed to ensure that reviewers comprehend the material they
are evaluating. When an assignment includes quizzes (<code>require_quiz = true</code>),
submitting teams create quizzes based on their submissions. Reviewers must complete the
quizzes before reviewing to demonstrate their understanding. If a reviewer performs
poorly, their review can be discounted to maintain quality.

== Previous Implementation ==

The prior codebase provided the data models, CRUD controllers, and UI components needed for assignments, questionnaires, and peer reviews. However, the quiz workflow was incomplete in several key ways:

* <code>Response#aggregate_questionnaire_score</code> computed scores as <code>answer * weight</code> using only the numeric answer column, with no correctness check against a stored correct answer. There was no way to distinguish a quiz response from a regular review response.
* The <code>Item</code> model had no <code>correct_answer</code> column; there was nowhere to persist the expected answer for a quiz item.
* The <code>StudentTask</code> model did not carry quiz gateway fields (<code>require_quiz</code>, <code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>), so the frontend had no structured way to know whether a student must take a quiz before reviewing.
* The <code>Team</code> model had no <code>quiz_questionnaire_id</code>. Quiz questionnaire ownership was expected to flow through the assignment's questionnaire list, which required instructor configuration and did not support per-team quizzes.
* The <code>ResponseMapsController</code> had no index action that filtered out quiz maps, so the frontend could not safely list a student's review assignments without also receiving spurious self-referential quiz entries.
* No <code>QuizResponseMapsController</code> existed; there was no endpoint to create a <code>QuizResponseMap</code> before a student started a quiz.
* The questionnaire editor rendered no "Correct answer" field for any item type when the questionnaire type was set to "Quiz".
* The student task page had no "Take Quiz" button or any flow to route a student from a quiz gate to the quiz form and back to their review.

== Project Goals ==

Based on the gaps above, this project aimed to:

# Add a <code>correct_answer</code> string column to quiz items so submitting teams can specify expected answers at quiz-creation time.
# Extend <code>Response#aggregate_questionnaire_score</code> to detect quiz responses by the <code>reviewer_id == reviewee_id</code> invariant and score text/choice items from the <code>comments</code> column using case-insensitive equality.
# Extend <code>StudentTask</code> with four quiz gateway fields so the frontend can render the correct button (Take Quiz / Start Review) without extra API calls.
# Add a <code>quiz_questionnaire_id</code> column to <code>Team</code> so each submitting team directly owns its quiz questionnaire, enabling per-team quizzes on the same assignment.
# Implement <code>POST /quiz_response_maps</code> so the frontend can create (or reuse) a <code>QuizResponseMap</code> before navigating a student to the quiz form.
# Update <code>ResponseMapsController#index</code> to exclude quiz maps and include per-row quiz state.
# Add a "Correct answer" row in the questionnaire editor for every quiz item type.
# Implement an instructor "Create Quiz" button on the reviewer-assignment page that opens the questionnaire editor pre-linked to the team.
# Implement a "Take Quiz" button in the student task list that calls <code>POST /quiz_response_maps</code> and navigates to the existing review form in quiz mode.
# Add <code>GET /questions/quiz_types</code> so the frontend can fetch the allowed quiz item types dynamically.

== Design ==

=== Architecture Overview ===

<pre>
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React/TS) │
│ │
│ AssignedReviews ──→ [Take Quiz] ──→ TeammateReview │
│ │ (quiz mode) │ │
│ │ └──→ [redirect] │
│ └──→ [Start/Open Review] ──→ TeammateReview │
│ (review mode) │
│ QuestionnaireEditor ──→ correct_answer fields per type │
└──────────────────────────┬──────────────────────────────────┘
│ REST API
┌──────────────────────────┴──────────────────────────────────┐
│ Backend (Rails API) │
│ │
│ QuizResponseMapsController (POST /quiz_response_maps) │
│ ResponsesController (create / update / submit) │
│ ResponseMapsController (index — filters quiz maps) │
│ Response model (aggregate_questionnaire_score) │
│ StudentTask model (quiz gateway fields) │
└─────────────────────────────────────────────────────────────┘
</pre>

=== UML Design ===

<pre>
┌───────────────────────────────────────┐
│ Assignment │
├───────────────────────────────────────┤
│ +boolean require_quiz │
│ +int num_quiz_questions │
│ +has_many questionnaires (via AQ) │
└────────────────────┬──────────────────┘
│ has_many (via AQ)
▼
┌───────────────────────────────────────┐ ┌─────────────────────────────┐
│ Questionnaire │ │ Team [UPDATED] │
├───────────────────────────────────────┤ ├─────────────────────────────┤
│ +String name │ │ +int quiz_questionnaire_id │◄─── NEW
│ +String questionnaire_type │◄────│ +belongs_to │
│ ("Quiz" for quiz questionnaires) │ │ quiz_questionnaire │
│ +int min_question_score │ └─────────────────────────────┘
│ +int max_question_score │
│ +int instructor_id │
└────────────────────┬──────────────────┘
│ has_many
▼
┌───────────────────────────────────────┐
│ Item [UPDATED] │
├───────────────────────────────────────┤
│ +String txt │
│ +String question_type │
│ +int weight │
│ +String correct_answer ◄│─── NEW
│ +QUIZ_ITEM_TYPES : Array ◄│─── NEW
│ +is_quiz_item?() : boolean ◄│─── NEW
└────────────────────┬──────────────────┘
│ has_many answers
▼
┌───────────────────────────────────────┐
│ Answer │
├───────────────────────────────────────┤
│ +int item_id │
│ +int response_id │
│ +int answer │
│ +String comments (quiz answer here) │
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ Response [UPDATED] │
├───────────────────────────────────────┤
│ +int map_id │
│ +boolean is_submitted │
│ +int round │
│ +aggregate_questionnaire_score() ◄│─── quiz-aware: checks
│ │ reviewer_id == reviewee_id
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ QuizResponseMap [UPDATED] │
├───────────────────────────────────────┤
│ +int reviewer_id │
│ +int reviewee_id │
│ (reviewer_id == reviewee_id ◄│─── self-referential invariant
│ identifies quiz maps) │ distinguishes quiz from review
│ +int reviewed_object_id ◄│─── quiz questionnaire id
│ +mappings_for_reviewer() │
└───────────────────────────────────────┘
</pre>

=== Screenshots ===
[[File:e2619_take_quiz_button.png|Take Quiz button in AssignedReviews]]
[[File:e2619_correct_answer_fields.png|Correct answer fields in Questionnaire Editor]]
[[File:e2619_quiz_score.png|Quiz score display after submission]]

== Changes Implemented ==

=== 1) Database Schema Additions ===

Two new columns support the quiz feature. The <code>correct_answer</code> string column on <code>items</code> stores the expected answer for each quiz question. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items. The <code>quiz_questionnaire_id</code> integer column on <code>teams</code> lets each submitting team directly own its quiz questionnaire — a key change that makes per-team quizzes possible and replaces a previous approach that required manual wiring at the assignment level.

Two migrations were added to support the quiz features:

<syntaxhighlight lang="ruby">
# db/migrate/20260423000001_add_correct_answer_to_items.rb
class AddCorrectAnswerToItems < ActiveRecord::Migration[8.0]
def change
add_column :items, :correct_answer, :string
end
end

# db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb
class AddQuizQuestionnaireIdToTeams < ActiveRecord::Migration[8.0]
def change
add_column :teams, :quiz_questionnaire_id, :integer, null: true, default: nil
add_index :teams, :quiz_questionnaire_id
end
end
</syntaxhighlight>

The <code>correct_answer</code> column stores the expected answer for each quiz item. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items.

The <code>quiz_questionnaire_id</code> column on <code>teams</code> allows each submitting team to directly own its quiz questionnaire. This replaces a previous approach that required the instructor to manually wire a questionnaire to the assignment, and is the key change that makes per-team quizzes possible.

=== 2) Quiz-Aware Scoring in Response Model ===

Quiz responses are identified by the invariant <code>reviewer_id == reviewee_id</code> on the associated <code>ResponseMap</code> — no STI <code>type</code> column is needed. For text and choice quiz items the student's answer is stored in the <code>comments</code> column (not the numeric <code>answer</code> column), so scoring uses case-insensitive string equality. Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions. The final score is returned in the <code>PATCH /responses/:id/submit</code> response body as <code>total_score</code> and displayed to the student before the redirect.

The core scoring logic in <code>Response#aggregate_questionnaire_score</code> was extended to handle quiz responses:

<syntaxhighlight lang="ruby">
def aggregate_questionnaire_score
sum = 0
is_quiz = map.reviewer_id == map.reviewee_id
comment_scored_types = %w[
TextField MultipleChoiceRadio MultipleChoiceCheckbox
Text\ field Multiple\ choice Multiple\ choice\ checkbox
].freeze

scores.each do |s|
if is_quiz && comment_scored_types.include?(s.item.question_type)
correct = s.item.correct_answer.to_s.strip.downcase
student_answer = s.comments.to_s.strip.downcase
sum += (student_answer == correct && correct.present? ? 1 : 0) * (s.item.weight || 1)
else
sum += s.answer * (s.item.weight || 1) unless s.answer.nil?
end
end
sum
end
</syntaxhighlight>

Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions.

=== 3) StudentTask Quiz Gateway Fields ===

Four fields were added to <code>StudentTask</code> so the frontend can make gatekeeping decisions without additional API calls: <code>require_quiz</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>, and <code>quiz_taken</code> (true only when a submitted <code>Response</code> exists against the student's <code>QuizResponseMap</code>). The frontend <code>AssignedReviews</code> component uses these fields to gate each review row — if <code>require_quiz && has_quiz_questionnaire && !quiz_taken</code>, a yellow "Take Quiz" button is shown instead of the review button.

Four fields were added to <code>StudentTask</code>:

<syntaxhighlight lang="ruby">
attr_accessor :assignment, :assignment_id, :current_stage, :participant,
:stage_deadline, :topic, :permission_granted,
:require_quiz, :quiz_taken, :has_quiz_questionnaire, :quiz_questionnaire_id
</syntaxhighlight>

The <code>from_participant</code> factory method was updated to compute these fields:

<syntaxhighlight lang="ruby">
def self.from_participant(participant)
asgn = participant.assignment
return nil unless asgn

review_maps = ReviewResponseMap.where(reviewer_id: participant.id)
quiz_q_id = review_maps.filter_map { |m| Team.find_by(id: m.reviewee_id)&.quiz_questionnaire_id }.first
quiz_taken = QuizResponseMap.where(reviewer_id: participant.id, reviewed_object_id: quiz_q_id)
.joins(:responses)
.where(responses: { is_submitted: true })
.exists? if quiz_q_id

new(
assignment: asgn.name,
assignment_id: asgn.id,
require_quiz: asgn.require_quiz || false,
has_quiz_questionnaire: quiz_q_id.present?,
quiz_questionnaire_id: quiz_q_id,
quiz_taken: quiz_taken || false,
# ... other fields
)
end
</syntaxhighlight>

=== 4) QuizResponseMapsController ===

A <code>QuizResponseMap</code> is self-referential: <code>reviewer_id == reviewee_id</code>, both pointing to the reviewer's own <code>AssignmentParticipant</code> record. This invariant is what distinguishes quiz maps from peer-review maps throughout the system. The endpoint is idempotent — if a map already exists for this student/questionnaire pair it is returned as-is rather than creating a duplicate, making it safe for the frontend to call on every "Take Quiz" click.

A new controller handles quiz map creation:

<syntaxhighlight lang="ruby">
# POST /quiz_response_maps
def create
# ... validate params, find assignment, resolve quiz questionnaire from team ...
map = QuizResponseMap.find_by(
reviewed_object_id: quiz_questionnaire.id,
reviewer_id: reviewer_participant.id,
reviewee_id: reviewer_participant.id
) || QuizResponseMap.new(...)

render json: {
quiz_map_id: map.id,
quiz_questionnaire_id: quiz_questionnaire.id,
reviewer_participant_id: reviewer_participant.id
}, status: :created
end
</syntaxhighlight>

=== 5) ResponseMapsController — Quiz Map Filtering ===

The <code>index</code> action must return only peer-review maps; quiz maps must not appear in the reviewer table. The primary guard <code>next if map.reviewer_id == map.reviewee_id</code> is reliable regardless of accidental id coincidences between questionnaire ids and assignment ids. A secondary <code>next unless assignment</code> check acts as belt-and-suspenders. Each returned row is augmented with <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> so the frontend can render the "Take Quiz" button without a second API call.

<code>ResponseMapsController#index</code> was updated to exclude quiz maps and include per-row quiz state for the frontend:

<syntaxhighlight lang="ruby">
result = maps.filter_map do |map|
# E2619: skip quiz maps (reviewer_id == reviewee_id)
next if map.reviewer_id == map.reviewee_id
# belt-and-suspenders: reviewed_object_id must reference an assignment
assignment = Assignment.find_by(id: map.reviewed_object_id)
next unless assignment

team = Team.find_by(id: map.reviewee_id)
quiz_questionnaire_id = team&.quiz_questionnaire_id
quiz_taken = quiz_questionnaire_id.present? &&
QuizResponseMap.where(reviewer_id: map.reviewer_id, reviewed_object_id: quiz_questionnaire_id)
.joins("INNER JOIN responses ON responses.map_id = response_maps.id")
.where(responses: { is_submitted: true }).exists?

{ id: map.id, quiz_questionnaire_id:, quiz_taken:, ... }
end
</syntaxhighlight>

=== 6) Instructor "Create Quiz" Button (AssignReviewer) ===

When clicked, the button navigates to the questionnaire editor with URL parameters (<code>type=Quiz</code>, <code>team_id</code>, <code>return_to</code>) that cause the editor to link the created questionnaire back to the team automatically via <code>PATCH /teams/:team_id/quiz_questionnaire</code>. After saving, the editor redirects back to the reviewer page.

'''Note:''' This is a temporary solution. In the full Expertiza workflow, quiz creation is initiated by a submitting team member from their own task page — not by an instructor from the reviewer-assignment page. The button was placed here because the student-facing entry point was not yet implemented in this codebase and should be removed or relocated once the proper student team submission flow is in place.

An <code>onCreateQuiz</code> handler was added to the <code>AssignReviewer</code> page:

<syntaxhighlight lang="typescript">
const onCreateQuiz = useCallback((teamId: number) => {
navigate(
`/questionnaires/new?type=Quiz` +
`&team_id=${teamId}` +
`&return_to=${encodeURIComponent(location.pathname + location.search)}`
);
}, [navigate, location]);
</syntaxhighlight>

After the questionnaire is saved, <code>QuestionnaireEditor</code> reads <code>team_id</code> and <code>return_to</code> from the URL, calls <code>PATCH /teams/:team_id/quiz_questionnaire</code>, and redirects back to the reviewer page.

=== 7) Student "Take Quiz" Button (AssignedReviews) ===

The per-row quiz state (<code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>) is returned directly in the <code>GET /response_maps</code> response so no extra API call is needed to decide which button to show. When the student clicks "Take Quiz", the frontend first calls <code>POST /quiz_response_maps</code> (idempotent) to obtain or reuse a quiz map id, then navigates to the existing <code>TeammateReview</code> page with a <code>redirect_after</code> parameter encoding the peer-review URL. After the quiz is submitted the page auto-redirects to the actual review.

The <code>AssignedReviews</code> component now reads per-row quiz state from the response maps API response. When <code>require_quiz && hasQuizQuestionnaire && !quizCompleted</code>, a yellow "Take Quiz" button is shown:

<syntaxhighlight lang="typescript">
const handleTakeQuiz = async (review: AssignedReviewRow, reviewUrl: string) => {
const res = await axiosClient.post('/quiz_response_maps', {
assignment_id: review.assignmentId,
reviewer_user_id: currentUser.id,
reviewee_team_id: review.revieweeTeamId,
});
const { quiz_map_id, quiz_questionnaire_id } = res.data;
navigate(
`/student_teams/teammate_review?` +
`map_id=${quiz_map_id}` +
`&questionnaire_id=${quiz_questionnaire_id}` +
`&questionnaire_type=Quiz` +
`&redirect_after=${encodeURIComponent(reviewUrl)}`
);
};
</syntaxhighlight>

=== 8) Quiz Mode in TeammateReview ===

Reusing the existing <code>TeammateReview</code> page for quiz-taking avoids duplicating the form rendering logic. Quiz mode is activated by <code>questionnaire_type=Quiz</code> in the URL, which causes the page to fetch quiz questionnaire items, disable the "Save Draft" button (quizzes are single-submission), display the score after submission, and show a "Proceed to Review" button that navigates to the <code>redirect_after</code> URL.

The existing <code>TeammateReview</code> page was extended with a quiz mode:

<syntaxhighlight lang="typescript">
if (isQuizMode) {
setQuizScore(submitRes.data?.total_score ?? null);
}
</syntaxhighlight>

=== 9) Correct Answer Fields in Questionnaire Editor ===

When the questionnaire type is "Quiz", each item in <code>QuestionnaireItemsFieldArray</code> needs a "Correct answer" input whose control type depends on the question type. A dropdown makes sense for choice questions (the options are already defined), a bounded number input for Scale, a checkbox for Checkbox, and a free-text input for TextField (scored case-insensitively). The <code>correct_answer</code> value is persisted through <code>QuestionnairesController</code> and serialised via <code>Item#as_json</code> only for quiz items.

<code>QuestionnaireItemsFieldArray</code> renders a "Correct answer" row for each quiz item. The input type varies by question type:

{| class="wikitable"
! Question type !! Correct answer input
|-
| Text field || Free-text <code><input type="text"></code>; scored case-insensitively at submission
|-
| Multiple choice / Multiple choice checkbox || <code><select></code> pre-populated from the item's alternatives
|-
| Scale || <code><input type="number"></code> bounded by the item's weight range
|-
| Checkbox || <code><input type="checkbox"></code> (correct = checked)
|}

=== 10) GET /questions/quiz_types Endpoint ===

Hard-coding the list of allowed quiz item types in the frontend would create a maintenance hazard every time a new type is added to the backend. The <code>GET /questions/quiz_types</code> endpoint lets the frontend fetch the authoritative list at runtime. The same constant is used in the <code>create</code> action to validate incoming item types, returning 422 if an unsupported type is submitted for a quiz questionnaire.

A new endpoint returns the allowed item types for quiz questionnaires so the frontend does not hard-code the list:

<syntaxhighlight lang="ruby">
QUIZ_ITEM_TYPES = %w[TextField MultipleChoiceRadio MultipleChoiceCheckbox Scale Checkbox].freeze

# GET /questions/quiz_types
def quiz_types
render json: QUIZ_ITEM_TYPES, status: :ok
end
</syntaxhighlight>

The <code>create</code> action on <code>QuestionsController</code> also validates that quiz questionnaires only accept items of these types, returning 422 with an error message otherwise.

== Test Plan ==

Tests were added for all new and modified backend components. The full suite passes with 0 failures.

=== Pre-Test Setup ===

All request specs use the shared <code>create_roles_hierarchy</code> helper and JWT-based auth:

<syntaxhighlight lang="ruby">
before(:all) { @roles = create_roles_hierarchy }
let(:token) { JsonWebToken.encode({ id: instructor.id }) }
let(:Authorization) { "Bearer #{token}" }
</syntaxhighlight>

=== Model: Response — Quiz Scoring ===

11 new examples in <code>spec/models/response_spec.rb</code> validate the quiz scoring path, covering both spaced and CamelCase question type names, correct/incorrect answers, blank answers, multi-item accumulation, and maximum score calculation.

<syntaxhighlight lang="ruby">
describe '#aggregate_questionnaire_score (quiz)' do
it 'scores a correct "Text field" answer' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'paris') # case-insensitive
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(2)
end

it 'scores an incorrect "Text field" answer as 0' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'London')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end

it 'gives 0 when the comments column is blank' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: '')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end
end
</syntaxhighlight>

=== Model: StudentTask — Quiz Gateway Fields ===

7 examples in <code>spec/models/student_task_spec.rb</code> verify the quiz gateway fields are populated by <code>from_participant</code> and serialised by <code>as_json</code>.

=== Request: QuizResponseMaps ===

6 examples in <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| Happy path — creates map and returns IDs || 201
|-
| Idempotent — reuses existing map on repeat call || 201
|-
| Missing <code>assignment_id</code> || 400
|-
| Missing <code>reviewer_user_id</code> || 400
|-
| Assignment not found (id = 999999999) || 404
|-
| Team has no quiz questionnaire || 422
|}

=== Request: ResponseMaps ===

7 examples in <code>spec/requests/api/v1/response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| GET — returns peer-review maps, excludes quiz maps || 200
|-
| GET — each entry includes <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> || 200
|-
| GET — returns empty array when reviewer has no maps || 200
|-
| GET — missing <code>reviewer_user_id</code> || 400
|-
| POST — creates ReviewResponseMap and returns IDs || 201
|-
| POST — idempotent, returns same map on repeat call || 201
|-
| POST — missing required param || 400
|}

=== Request: Questions — Quiz Types ===

3 new examples in <code>spec/requests/api/v1/questions_spec.rb</code>:

<syntaxhighlight lang="ruby">
describe 'GET /questions/quiz_types' do
it 'returns 200 with the allowed quiz item type strings' do
get '/questions/quiz_types', headers: { 'Authorization' => auth_header }
types = JSON.parse(response.body)
expect(types).to include('TextField', 'MultipleChoiceRadio', 'MultipleChoiceCheckbox')
end
end
</syntaxhighlight>

=== Test Coverage Summary ===

{| class="wikitable"
! Spec file !! Examples before !! Examples after
|-
| <code>spec/models/student_task_spec.rb</code> || 3 (failing) || 7 ✅
|-
| <code>spec/models/response_spec.rb</code> || 11 || 22 ✅
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || 19 || 22 ✅
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || 0 || 6 ✅
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || 0 || 7 ✅
|-
| '''Total new examples''' || || '''27'''
|}

== Files Modified ==

=== Backend (Ruby on Rails) ===

{| class="wikitable"
! File !! Change
|-
| <code>app/models/response.rb</code> || Added quiz-aware scoring to <code>aggregate_questionnaire_score</code> and <code>maximum_score</code>
|-
| <code>app/models/student_task.rb</code> || Added four quiz gateway fields; updated <code>from_participant</code> and <code>as_json</code>
|-
| <code>app/models/Item.rb</code> || Added <code>QUIZ_ITEM_TYPES</code>, <code>is_quiz_item?</code>, <code>correct_answer_only_for_quiz</code> validation, and conditional <code>as_json</code>
|-
| <code>app/models/team.rb</code> || Added <code>quiz_questionnaire_id</code> attribute and <code>quiz_questionnaire</code> association
|-
| <code>app/models/quiz_response_map.rb</code> || Minor documentation updates
|-
| <code>app/controllers/questions_controller.rb</code> || Added <code>GET /questions/quiz_types</code>; added quiz item type validation in <code>create</code>
|-
| <code>app/controllers/quiz_response_maps_controller.rb</code> || New controller: <code>POST /quiz_response_maps</code>
|-
| <code>app/controllers/response_maps_controller.rb</code> || Updated <code>index</code> to filter quiz maps and return per-row quiz state; added <code>create</code> and <code>destroy</code>
|-
| <code>app/controllers/teams_controller.rb</code> || Added <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>app/controllers/questionnaires_controller.rb</code> || Exposed <code>correct_answer</code> in strong parameters
|-
| <code>config/routes.rb</code> || Added routes for quiz_response_maps, quiz_types, and quiz_questionnaire on teams
|-
| <code>db/migrate/20260423000001_add_correct_answer_to_items.rb</code> || New migration: adds <code>correct_answer</code> string column to <code>items</code>
|-
| <code>db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb</code> || New migration: adds <code>quiz_questionnaire_id</code> integer column + index to <code>teams</code>
|-
| <code>spec/models/student_task_spec.rb</code> || Fixed existing test failures; added quiz gateway field assertions
|-
| <code>spec/models/response_spec.rb</code> || Added 11 new quiz scoring tests
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || Added tests for <code>quiz_types</code> endpoint and quiz item creation/rejection
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || New spec: 6 tests covering happy path, idempotency, and error cases
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || New spec: 7 tests covering quiz-map exclusion, quiz state fields, and POST CRUD
|}

=== Frontend (React/TypeScript) ===

{| class="wikitable"
! File !! Change
|-
| <code>src/pages/StudentTasks/AssignedReviews.tsx</code> || Added "Take Quiz" button; per-row quiz state; <code>handleTakeQuiz</code> calling <code>POST /quiz_response_maps</code>
|-
| <code>src/pages/Assignments/AssignReviewer.tsx</code> || Added "Create Quiz" button that navigates to the questionnaire editor pre-linked to the team
|-
| <code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> || Added correct-answer row for each quiz item type
|-
| <code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> || Added team-quiz creation flow: links new questionnaire to team via <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>src/pages/Student Teams/TeammateReview.tsx</code> || Added quiz mode (<code>isQuizMode</code>), quiz score display, and <code>redirect_after</code> param support
|-
| <code>src/pages/Assignments/AssignmentEditor.tsx</code> || Ensured <code>require_quiz</code> checkbox is wired to the form state
|-
| <code>src/pages/Assignments/AssignmentUtil.ts</code> || Added <code>require_quiz</code> to <code>IAssignmentFormValues</code>
|-
| <code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> || Added <code>correct_answer</code> to <code>IItem</code>; updated <code>transformQuestionnaireRequest</code>
|-
| <code>src/components/Form/FormSelect.tsx</code> || Documentation only (JSDoc)
|}

=== Github Pull Request ===

Frontend: https://github.com/expertiza/reimplementation-front-end/pull/179
Backend: https://github.com/expertiza/reimplementation-back-end/pull/345
=== Video ===

https://youtu.be/BWh_6bavtbE

=== Mentor ===

Ed Gehringer (efg@ncsu.edu)

=== Team Member ===

* An Mai (atmai@ncsu.edu)
* Mekhi Parker (mrparke4@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-27T23:13:26Z

Atmai:

= E2619: Student Quizzes — Design Document =

== Introduction ==

[https://expertiza.ncsu.edu/ Expertiza] is an educational web application collaboratively
developed and maintained by students and faculty at NCSU. As an open-source project built
on the Ruby on Rails platform, its code is accessible on GitHub. The platform enables
students to provide peer reviews and refine their work based on feedback.

This design document describes the implementation of the '''E2619 Student Quizzes'''
project, covering both the frontend (React/TypeScript) and backend (Ruby on Rails API).
The project builds on the E2607 questionnaire rendering code and extends it with
quiz-specific capabilities: directing students to quizzes/reviews, scoring quiz responses,
specifying correct answers, and handling fill-in-the-blank questions.

== Project Overview ==

Quizzes in Expertiza are designed to ensure that reviewers comprehend the material they
are evaluating. When an assignment includes quizzes (<code>require_quiz = true</code>),
submitting teams create quizzes based on their submissions. Reviewers must complete the
quizzes before reviewing to demonstrate their understanding. If a reviewer performs
poorly, their review can be discounted to maintain quality.

== Previous Implementation ==

The prior codebase provided the data models, CRUD controllers, and UI components needed for assignments, questionnaires, and peer reviews. However, the quiz workflow was incomplete in several key ways:

* <code>Response#aggregate_questionnaire_score</code> computed scores as <code>answer * weight</code> using only the numeric answer column, with no correctness check against a stored correct answer. There was no way to distinguish a quiz response from a regular review response.
* The <code>Item</code> model had no <code>correct_answer</code> column; there was nowhere to persist the expected answer for a quiz item.
* The <code>StudentTask</code> model did not carry quiz gateway fields (<code>require_quiz</code>, <code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>), so the frontend had no structured way to know whether a student must take a quiz before reviewing.
* The <code>Team</code> model had no <code>quiz_questionnaire_id</code>. Quiz questionnaire ownership was expected to flow through the assignment's questionnaire list, which required instructor configuration and did not support per-team quizzes.
* The <code>ResponseMapsController</code> had no index action that filtered out quiz maps, so the frontend could not safely list a student's review assignments without also receiving spurious self-referential quiz entries.
* No <code>QuizResponseMapsController</code> existed; there was no endpoint to create a <code>QuizResponseMap</code> before a student started a quiz.
* The questionnaire editor rendered no "Correct answer" field for any item type when the questionnaire type was set to "Quiz".
* The student task page had no "Take Quiz" button or any flow to route a student from a quiz gate to the quiz form and back to their review.

== Project Goals ==

Based on the gaps above, this project aimed to:

# Add a <code>correct_answer</code> string column to quiz items so submitting teams can specify expected answers at quiz-creation time.
# Extend <code>Response#aggregate_questionnaire_score</code> to detect quiz responses by the <code>reviewer_id == reviewee_id</code> invariant and score text/choice items from the <code>comments</code> column using case-insensitive equality.
# Extend <code>StudentTask</code> with four quiz gateway fields so the frontend can render the correct button (Take Quiz / Start Review) without extra API calls.
# Add a <code>quiz_questionnaire_id</code> column to <code>Team</code> so each submitting team directly owns its quiz questionnaire, enabling per-team quizzes on the same assignment.
# Implement <code>POST /quiz_response_maps</code> so the frontend can create (or reuse) a <code>QuizResponseMap</code> before navigating a student to the quiz form.
# Update <code>ResponseMapsController#index</code> to exclude quiz maps and include per-row quiz state.
# Add a "Correct answer" row in the questionnaire editor for every quiz item type.
# Implement an instructor "Create Quiz" button on the reviewer-assignment page that opens the questionnaire editor pre-linked to the team.
# Implement a "Take Quiz" button in the student task list that calls <code>POST /quiz_response_maps</code> and navigates to the existing review form in quiz mode.
# Add <code>GET /questions/quiz_types</code> so the frontend can fetch the allowed quiz item types dynamically.

== Design ==

=== Architecture Overview ===

<pre>
┌─────────────────────────────────────────────────────────────┐
│ Frontend (React/TS) │
│ │
│ AssignedReviews ──→ [Take Quiz] ──→ TeammateReview │
│ │ (quiz mode) │ │
│ │ └──→ [redirect] │
│ └──→ [Start/Open Review] ──→ TeammateReview │
│ (review mode) │
│ QuestionnaireEditor ──→ correct_answer fields per type │
└──────────────────────────┬──────────────────────────────────┘
│ REST API
┌──────────────────────────┴──────────────────────────────────┐
│ Backend (Rails API) │
│ │
│ QuizResponseMapsController (POST /quiz_response_maps) │
│ ResponsesController (create / update / submit) │
│ ResponseMapsController (index — filters quiz maps) │
│ Response model (aggregate_questionnaire_score) │
│ StudentTask model (quiz gateway fields) │
└─────────────────────────────────────────────────────────────┘
</pre>

=== UML Design ===

<pre>
┌───────────────────────────────────────┐
│ Assignment │
├───────────────────────────────────────┤
│ +boolean require_quiz │
│ +int num_quiz_questions │
│ +has_many questionnaires (via AQ) │
└────────────────────┬──────────────────┘
│ has_many (via AQ)
▼
┌───────────────────────────────────────┐ ┌─────────────────────────────┐
│ Questionnaire │ │ Team [UPDATED] │
├───────────────────────────────────────┤ ├─────────────────────────────┤
│ +String name │ │ +int quiz_questionnaire_id │◄─── NEW
│ +String questionnaire_type │◄────│ +belongs_to │
│ ("Quiz" for quiz questionnaires) │ │ quiz_questionnaire │
│ +int min_question_score │ └─────────────────────────────┘
│ +int max_question_score │
│ +int instructor_id │
└────────────────────┬──────────────────┘
│ has_many
▼
┌───────────────────────────────────────┐
│ Item [UPDATED] │
├───────────────────────────────────────┤
│ +String txt │
│ +String question_type │
│ +int weight │
│ +String correct_answer ◄│─── NEW
│ +QUIZ_ITEM_TYPES : Array ◄│─── NEW
│ +is_quiz_item?() : boolean ◄│─── NEW
└────────────────────┬──────────────────┘
│ has_many answers
▼
┌───────────────────────────────────────┐
│ Answer │
├───────────────────────────────────────┤
│ +int item_id │
│ +int response_id │
│ +int answer │
│ +String comments (quiz answer here) │
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ Response [UPDATED] │
├───────────────────────────────────────┤
│ +int map_id │
│ +boolean is_submitted │
│ +int round │
│ +aggregate_questionnaire_score() ◄│─── quiz-aware: checks
│ │ reviewer_id == reviewee_id
└────────────────────┬──────────────────┘
│ belongs_to
▼
┌───────────────────────────────────────┐
│ QuizResponseMap [UPDATED] │
├───────────────────────────────────────┤
│ +int reviewer_id │
│ +int reviewee_id │
│ (reviewer_id == reviewee_id ◄│─── self-referential invariant
│ identifies quiz maps) │ distinguishes quiz from review
│ +int reviewed_object_id ◄│─── quiz questionnaire id
│ +mappings_for_reviewer() │
└───────────────────────────────────────┘
</pre>

=== Screenshots ===
[[File:e2619_take_quiz_button.png|Take Quiz button in AssignedReviews]]
[[File:e2619_correct_answer_fields.png|Correct answer fields in Questionnaire Editor]]
[[File:e2619_quiz_score.png|Quiz score display after submission]]

== Changes Implemented ==

=== 1) Database Schema Additions ===

Two new columns support the quiz feature. The <code>correct_answer</code> string column on <code>items</code> stores the expected answer for each quiz question. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items. The <code>quiz_questionnaire_id</code> integer column on <code>teams</code> lets each submitting team directly own its quiz questionnaire — a key change that makes per-team quizzes possible and replaces a previous approach that required manual wiring at the assignment level.

Two migrations were added to support the quiz features:

<syntaxhighlight lang="ruby">
# db/migrate/20260423000001_add_correct_answer_to_items.rb
class AddCorrectAnswerToItems < ActiveRecord::Migration[8.0]
def change
add_column :items, :correct_answer, :string
end
end

# db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb
class AddQuizQuestionnaireIdToTeams < ActiveRecord::Migration[8.0]
def change
add_column :teams, :quiz_questionnaire_id, :integer, null: true, default: nil
add_index :teams, :quiz_questionnaire_id
end
end
</syntaxhighlight>

The <code>correct_answer</code> column stores the expected answer for each quiz item. It is only exposed in API responses when <code>is_quiz_item?</code> is true, preventing accidental leakage on peer-review rubric items.

The <code>quiz_questionnaire_id</code> column on <code>teams</code> allows each submitting team to directly own its quiz questionnaire. This replaces a previous approach that required the instructor to manually wire a questionnaire to the assignment, and is the key change that makes per-team quizzes possible.

=== 2) Quiz-Aware Scoring in Response Model ===

Quiz responses are identified by the invariant <code>reviewer_id == reviewee_id</code> on the associated <code>ResponseMap</code> — no STI <code>type</code> column is needed. For text and choice quiz items the student's answer is stored in the <code>comments</code> column (not the numeric <code>answer</code> column), so scoring uses case-insensitive string equality. Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions. The final score is returned in the <code>PATCH /responses/:id/submit</code> response body as <code>total_score</code> and displayed to the student before the redirect.

The core scoring logic in <code>Response#aggregate_questionnaire_score</code> was extended to handle quiz responses:

<syntaxhighlight lang="ruby">
def aggregate_questionnaire_score
sum = 0
is_quiz = map.reviewer_id == map.reviewee_id
comment_scored_types = %w[
TextField MultipleChoiceRadio MultipleChoiceCheckbox
Text\ field Multiple\ choice Multiple\ choice\ checkbox
].freeze

scores.each do |s|
if is_quiz && comment_scored_types.include?(s.item.question_type)
correct = s.item.correct_answer.to_s.strip.downcase
student_answer = s.comments.to_s.strip.downcase
sum += (student_answer == correct && correct.present? ? 1 : 0) * (s.item.weight || 1)
else
sum += s.answer * (s.item.weight || 1) unless s.answer.nil?
end
end
sum
end
</syntaxhighlight>

Both spaced names (<code>"Text field"</code>, <code>"Multiple choice"</code>) and CamelCase names (<code>"TextField"</code>, <code>"MultipleChoiceRadio"</code>) are handled because the frontend historically used both conventions.

=== 3) StudentTask Quiz Gateway Fields ===

Four fields were added to <code>StudentTask</code> so the frontend can make gatekeeping decisions without additional API calls: <code>require_quiz</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>, and <code>quiz_taken</code> (true only when a submitted <code>Response</code> exists against the student's <code>QuizResponseMap</code>). The frontend <code>AssignedReviews</code> component uses these fields to gate each review row — if <code>require_quiz && has_quiz_questionnaire && !quiz_taken</code>, a yellow "Take Quiz" button is shown instead of the review button.

Four fields were added to <code>StudentTask</code>:

<syntaxhighlight lang="ruby">
attr_accessor :assignment, :assignment_id, :current_stage, :participant,
:stage_deadline, :topic, :permission_granted,
:require_quiz, :quiz_taken, :has_quiz_questionnaire, :quiz_questionnaire_id
</syntaxhighlight>

The <code>from_participant</code> factory method was updated to compute these fields:

<syntaxhighlight lang="ruby">
def self.from_participant(participant)
asgn = participant.assignment
return nil unless asgn

review_maps = ReviewResponseMap.where(reviewer_id: participant.id)
quiz_q_id = review_maps.filter_map { |m| Team.find_by(id: m.reviewee_id)&.quiz_questionnaire_id }.first
quiz_taken = QuizResponseMap.where(reviewer_id: participant.id, reviewed_object_id: quiz_q_id)
.joins(:responses)
.where(responses: { is_submitted: true })
.exists? if quiz_q_id

new(
assignment: asgn.name,
assignment_id: asgn.id,
require_quiz: asgn.require_quiz || false,
has_quiz_questionnaire: quiz_q_id.present?,
quiz_questionnaire_id: quiz_q_id,
quiz_taken: quiz_taken || false,
# ... other fields
)
end
</syntaxhighlight>

=== 4) QuizResponseMapsController ===

A <code>QuizResponseMap</code> is self-referential: <code>reviewer_id == reviewee_id</code>, both pointing to the reviewer's own <code>AssignmentParticipant</code> record. This invariant is what distinguishes quiz maps from peer-review maps throughout the system. The endpoint is idempotent — if a map already exists for this student/questionnaire pair it is returned as-is rather than creating a duplicate, making it safe for the frontend to call on every "Take Quiz" click.

A new controller handles quiz map creation:

<syntaxhighlight lang="ruby">
# POST /quiz_response_maps
def create
# ... validate params, find assignment, resolve quiz questionnaire from team ...
map = QuizResponseMap.find_by(
reviewed_object_id: quiz_questionnaire.id,
reviewer_id: reviewer_participant.id,
reviewee_id: reviewer_participant.id
) || QuizResponseMap.new(...)

render json: {
quiz_map_id: map.id,
quiz_questionnaire_id: quiz_questionnaire.id,
reviewer_participant_id: reviewer_participant.id
}, status: :created
end
</syntaxhighlight>

=== 5) ResponseMapsController — Quiz Map Filtering ===

The <code>index</code> action must return only peer-review maps; quiz maps must not appear in the reviewer table. The primary guard <code>next if map.reviewer_id == map.reviewee_id</code> is reliable regardless of accidental id coincidences between questionnaire ids and assignment ids. A secondary <code>next unless assignment</code> check acts as belt-and-suspenders. Each returned row is augmented with <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> so the frontend can render the "Take Quiz" button without a second API call.

<code>ResponseMapsController#index</code> was updated to exclude quiz maps and include per-row quiz state for the frontend:

<syntaxhighlight lang="ruby">
result = maps.filter_map do |map|
# E2619: skip quiz maps (reviewer_id == reviewee_id)
next if map.reviewer_id == map.reviewee_id
# belt-and-suspenders: reviewed_object_id must reference an assignment
assignment = Assignment.find_by(id: map.reviewed_object_id)
next unless assignment

team = Team.find_by(id: map.reviewee_id)
quiz_questionnaire_id = team&.quiz_questionnaire_id
quiz_taken = quiz_questionnaire_id.present? &&
QuizResponseMap.where(reviewer_id: map.reviewer_id, reviewed_object_id: quiz_questionnaire_id)
.joins("INNER JOIN responses ON responses.map_id = response_maps.id")
.where(responses: { is_submitted: true }).exists?

{ id: map.id, quiz_questionnaire_id:, quiz_taken:, ... }
end
</syntaxhighlight>

=== 6) Instructor "Create Quiz" Button (AssignReviewer) ===

When clicked, the button navigates to the questionnaire editor with URL parameters (<code>type=Quiz</code>, <code>team_id</code>, <code>return_to</code>) that cause the editor to link the created questionnaire back to the team automatically via <code>PATCH /teams/:team_id/quiz_questionnaire</code>. After saving, the editor redirects back to the reviewer page.

'''Note:''' This is a temporary solution. In the full Expertiza workflow, quiz creation is initiated by a submitting team member from their own task page — not by an instructor from the reviewer-assignment page. The button was placed here because the student-facing entry point was not yet implemented in this codebase and should be removed or relocated once the proper student team submission flow is in place.

An <code>onCreateQuiz</code> handler was added to the <code>AssignReviewer</code> page:

<syntaxhighlight lang="typescript">
const onCreateQuiz = useCallback((teamId: number) => {
navigate(
`/questionnaires/new?type=Quiz` +
`&team_id=${teamId}` +
`&return_to=${encodeURIComponent(location.pathname + location.search)}`
);
}, [navigate, location]);
</syntaxhighlight>

After the questionnaire is saved, <code>QuestionnaireEditor</code> reads <code>team_id</code> and <code>return_to</code> from the URL, calls <code>PATCH /teams/:team_id/quiz_questionnaire</code>, and redirects back to the reviewer page.

=== 7) Student "Take Quiz" Button (AssignedReviews) ===

The per-row quiz state (<code>quiz_taken</code>, <code>has_quiz_questionnaire</code>, <code>quiz_questionnaire_id</code>) is returned directly in the <code>GET /response_maps</code> response so no extra API call is needed to decide which button to show. When the student clicks "Take Quiz", the frontend first calls <code>POST /quiz_response_maps</code> (idempotent) to obtain or reuse a quiz map id, then navigates to the existing <code>TeammateReview</code> page with a <code>redirect_after</code> parameter encoding the peer-review URL. After the quiz is submitted the page auto-redirects to the actual review.

The <code>AssignedReviews</code> component now reads per-row quiz state from the response maps API response. When <code>require_quiz && hasQuizQuestionnaire && !quizCompleted</code>, a yellow "Take Quiz" button is shown:

<syntaxhighlight lang="typescript">
const handleTakeQuiz = async (review: AssignedReviewRow, reviewUrl: string) => {
const res = await axiosClient.post('/quiz_response_maps', {
assignment_id: review.assignmentId,
reviewer_user_id: currentUser.id,
reviewee_team_id: review.revieweeTeamId,
});
const { quiz_map_id, quiz_questionnaire_id } = res.data;
navigate(
`/student_teams/teammate_review?` +
`map_id=${quiz_map_id}` +
`&questionnaire_id=${quiz_questionnaire_id}` +
`&questionnaire_type=Quiz` +
`&redirect_after=${encodeURIComponent(reviewUrl)}`
);
};
</syntaxhighlight>

=== 8) Quiz Mode in TeammateReview ===

Reusing the existing <code>TeammateReview</code> page for quiz-taking avoids duplicating the form rendering logic. Quiz mode is activated by <code>questionnaire_type=Quiz</code> in the URL, which causes the page to fetch quiz questionnaire items, disable the "Save Draft" button (quizzes are single-submission), display the score after submission, and show a "Proceed to Review" button that navigates to the <code>redirect_after</code> URL.

The existing <code>TeammateReview</code> page was extended with a quiz mode:

<syntaxhighlight lang="typescript">
if (isQuizMode) {
setQuizScore(submitRes.data?.total_score ?? null);
}
</syntaxhighlight>

=== 9) Correct Answer Fields in Questionnaire Editor ===

When the questionnaire type is "Quiz", each item in <code>QuestionnaireItemsFieldArray</code> needs a "Correct answer" input whose control type depends on the question type. A dropdown makes sense for choice questions (the options are already defined), a bounded number input for Scale, a checkbox for Checkbox, and a free-text input for TextField (scored case-insensitively). The <code>correct_answer</code> value is persisted through <code>QuestionnairesController</code> and serialised via <code>Item#as_json</code> only for quiz items.

<code>QuestionnaireItemsFieldArray</code> renders a "Correct answer" row for each quiz item. The input type varies by question type:

{| class="wikitable"
! Question type !! Correct answer input
|-
| Text field || Free-text <code><input type="text"></code>; scored case-insensitively at submission
|-
| Multiple choice / Multiple choice checkbox || <code><select></code> pre-populated from the item's alternatives
|-
| Scale || <code><input type="number"></code> bounded by the item's weight range
|-
| Checkbox || <code><input type="checkbox"></code> (correct = checked)
|}

=== 10) GET /questions/quiz_types Endpoint ===

Hard-coding the list of allowed quiz item types in the frontend would create a maintenance hazard every time a new type is added to the backend. The <code>GET /questions/quiz_types</code> endpoint lets the frontend fetch the authoritative list at runtime. The same constant is used in the <code>create</code> action to validate incoming item types, returning 422 if an unsupported type is submitted for a quiz questionnaire.

A new endpoint returns the allowed item types for quiz questionnaires so the frontend does not hard-code the list:

<syntaxhighlight lang="ruby">
QUIZ_ITEM_TYPES = %w[TextField MultipleChoiceRadio MultipleChoiceCheckbox Scale Checkbox].freeze

# GET /questions/quiz_types
def quiz_types
render json: QUIZ_ITEM_TYPES, status: :ok
end
</syntaxhighlight>

The <code>create</code> action on <code>QuestionsController</code> also validates that quiz questionnaires only accept items of these types, returning 422 with an error message otherwise.

== Test Plan ==

Tests were added for all new and modified backend components. The full suite passes with 0 failures.

=== Pre-Test Setup ===

All request specs use the shared <code>create_roles_hierarchy</code> helper and JWT-based auth:

<syntaxhighlight lang="ruby">
before(:all) { @roles = create_roles_hierarchy }
let(:token) { JsonWebToken.encode({ id: instructor.id }) }
let(:Authorization) { "Bearer #{token}" }
</syntaxhighlight>

=== Model: Response — Quiz Scoring ===

11 new examples in <code>spec/models/response_spec.rb</code> validate the quiz scoring path, covering both spaced and CamelCase question type names, correct/incorrect answers, blank answers, multi-item accumulation, and maximum score calculation.

<syntaxhighlight lang="ruby">
describe '#aggregate_questionnaire_score (quiz)' do
it 'scores a correct "Text field" answer' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'paris') # case-insensitive
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(2)
end

it 'scores an incorrect "Text field" answer as 0' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: 'London')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end

it 'gives 0 when the comments column is blank' do
item = make_quiz_item(question_type: 'Text field', correct_answer: 'Paris', weight: 2)
answer = make_quiz_answer(item: item, comments: '')
r = quiz_response([answer])
expect(r.aggregate_questionnaire_score).to eq(0)
end
end
</syntaxhighlight>

=== Model: StudentTask — Quiz Gateway Fields ===

7 examples in <code>spec/models/student_task_spec.rb</code> verify the quiz gateway fields are populated by <code>from_participant</code> and serialised by <code>as_json</code>.

=== Request: QuizResponseMaps ===

6 examples in <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| Happy path — creates map and returns IDs || 201
|-
| Idempotent — reuses existing map on repeat call || 201
|-
| Missing <code>assignment_id</code> || 400
|-
| Missing <code>reviewer_user_id</code> || 400
|-
| Assignment not found (id = 999999999) || 404
|-
| Team has no quiz questionnaire || 422
|}

=== Request: ResponseMaps ===

7 examples in <code>spec/requests/api/v1/response_maps_controller_spec.rb</code>:

{| class="wikitable"
! Test !! Expected status
|-
| GET — returns peer-review maps, excludes quiz maps || 200
|-
| GET — each entry includes <code>quiz_taken</code> and <code>quiz_questionnaire_id</code> || 200
|-
| GET — returns empty array when reviewer has no maps || 200
|-
| GET — missing <code>reviewer_user_id</code> || 400
|-
| POST — creates ReviewResponseMap and returns IDs || 201
|-
| POST — idempotent, returns same map on repeat call || 201
|-
| POST — missing required param || 400
|}

=== Request: Questions — Quiz Types ===

3 new examples in <code>spec/requests/api/v1/questions_spec.rb</code>:

<syntaxhighlight lang="ruby">
describe 'GET /questions/quiz_types' do
it 'returns 200 with the allowed quiz item type strings' do
get '/questions/quiz_types', headers: { 'Authorization' => auth_header }
types = JSON.parse(response.body)
expect(types).to include('TextField', 'MultipleChoiceRadio', 'MultipleChoiceCheckbox')
end
end
</syntaxhighlight>

=== Test Coverage Summary ===

{| class="wikitable"
! Spec file !! Examples before !! Examples after
|-
| <code>spec/models/student_task_spec.rb</code> || 3 (failing) || 7 ✅
|-
| <code>spec/models/response_spec.rb</code> || 11 || 22 ✅
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || 19 || 22 ✅
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || 0 || 6 ✅
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || 0 || 7 ✅
|-
| '''Total new examples''' || || '''27'''
|}

== Files Modified ==

=== Backend (Ruby on Rails) ===

{| class="wikitable"
! File !! Change
|-
| <code>app/models/response.rb</code> || Added quiz-aware scoring to <code>aggregate_questionnaire_score</code> and <code>maximum_score</code>
|-
| <code>app/models/student_task.rb</code> || Added four quiz gateway fields; updated <code>from_participant</code> and <code>as_json</code>
|-
| <code>app/models/Item.rb</code> || Added <code>QUIZ_ITEM_TYPES</code>, <code>is_quiz_item?</code>, <code>correct_answer_only_for_quiz</code> validation, and conditional <code>as_json</code>
|-
| <code>app/models/team.rb</code> || Added <code>quiz_questionnaire_id</code> attribute and <code>quiz_questionnaire</code> association
|-
| <code>app/models/quiz_response_map.rb</code> || Minor documentation updates
|-
| <code>app/controllers/questions_controller.rb</code> || Added <code>GET /questions/quiz_types</code>; added quiz item type validation in <code>create</code>
|-
| <code>app/controllers/quiz_response_maps_controller.rb</code> || New controller: <code>POST /quiz_response_maps</code>
|-
| <code>app/controllers/response_maps_controller.rb</code> || Updated <code>index</code> to filter quiz maps and return per-row quiz state; added <code>create</code> and <code>destroy</code>
|-
| <code>app/controllers/teams_controller.rb</code> || Added <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>app/controllers/questionnaires_controller.rb</code> || Exposed <code>correct_answer</code> in strong parameters
|-
| <code>config/routes.rb</code> || Added routes for quiz_response_maps, quiz_types, and quiz_questionnaire on teams
|-
| <code>db/migrate/20260423000001_add_correct_answer_to_items.rb</code> || New migration: adds <code>correct_answer</code> string column to <code>items</code>
|-
| <code>db/migrate/20260424000001_add_quiz_questionnaire_id_to_teams.rb</code> || New migration: adds <code>quiz_questionnaire_id</code> integer column + index to <code>teams</code>
|-
| <code>spec/models/student_task_spec.rb</code> || Fixed existing test failures; added quiz gateway field assertions
|-
| <code>spec/models/response_spec.rb</code> || Added 11 new quiz scoring tests
|-
| <code>spec/requests/api/v1/questions_spec.rb</code> || Added tests for <code>quiz_types</code> endpoint and quiz item creation/rejection
|-
| <code>spec/requests/api/v1/quiz_response_maps_controller_spec.rb</code> || New spec: 6 tests covering happy path, idempotency, and error cases
|-
| <code>spec/requests/api/v1/response_maps_controller_spec.rb</code> || New spec: 7 tests covering quiz-map exclusion, quiz state fields, and POST CRUD
|}

=== Frontend (React/TypeScript) ===

{| class="wikitable"
! File !! Change
|-
| <code>src/pages/StudentTasks/AssignedReviews.tsx</code> || Added "Take Quiz" button; per-row quiz state; <code>handleTakeQuiz</code> calling <code>POST /quiz_response_maps</code>
|-
| <code>src/pages/Assignments/AssignReviewer.tsx</code> || Added "Create Quiz" button that navigates to the questionnaire editor pre-linked to the team
|-
| <code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> || Added correct-answer row for each quiz item type
|-
| <code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> || Added team-quiz creation flow: links new questionnaire to team via <code>PATCH /teams/:id/quiz_questionnaire</code>
|-
| <code>src/pages/Student Teams/TeammateReview.tsx</code> || Added quiz mode (<code>isQuizMode</code>), quiz score display, and <code>redirect_after</code> param support
|-
| <code>src/pages/Assignments/AssignmentEditor.tsx</code> || Ensured <code>require_quiz</code> checkbox is wired to the form state
|-
| <code>src/pages/Assignments/AssignmentUtil.ts</code> || Added <code>require_quiz</code> to <code>IAssignmentFormValues</code>
|-
| <code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> || Added <code>correct_answer</code> to <code>IItem</code>; updated <code>transformQuestionnaireRequest</code>
|-
| <code>src/components/Form/FormSelect.tsx</code> || Documentation only (JSDoc)
|}

=== Github Pull Request ===

https://github.com

=== Video ===

https://youtu.be/BWh_6bavtbE

=== Mentor ===

Ed Gehringer (efg@ncsu.edu)

=== Team Member ===

* An Mai (atmai@ncsu.edu)
* Mekhi Parker (mrparke4@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-24T14:51:28Z

Atmai:

File:2607ss 2.png

2026-04-20T17:36:04Z

Atmai:

File:2607ss1.png

2026-04-20T17:35:30Z

Atmai:

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-12T18:54:57Z

Atmai:

File:E2619uml.png

2026-04-12T18:53:56Z

Atmai:

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-12T18:42:42Z

Atmai:

CSC/ECE 517 Spring 2026 - E2619. Student Quizzes Frontend

2026-04-11T05:41:28Z

Atmai: Created page with "Start"

Start

CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend

2026-03-30T23:13:50Z

Atmai:

= CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend =

== Important Links ==
* Git PR (front-end): https://github.com/expertiza/reimplementation-front-end/pull/163
* GitHub Repository (front-end): https://github.com/EFHassler/ResponsesController_Frontend_CSC517
* Demo Video: https://drive.google.com/file/d/1KaY0lCwc8ppLmhtatW7d38o6kAbKP_TQ/view?usp=sharing

== Expertiza ==
Expertiza is an open-source web application for peer assessment and collaborative learning. It allows instructors to create assignments where students can submit work, review peers, and receive feedback. Expertiza supports team and individual assignments, metareviews, topic sign-ups, staggered deadlines, and detailed rubrics, promoting active learning and continuous improvement.

== Overview ==
The objective of this project is to reimplement the review and response workflow UI for Expertiza. This includes:
* A modern student dashboard for assigned reviews and topic sign-up.
* Dynamic review/teammate review forms supporting all questionnaire item types.
* Instructor tools for assigning reviewers and monitoring review progress.
* Integration with the backend API for seamless data flow.

== Problem ==
The previous review UI was limited in usability and flexibility. Students could not easily track or resume reviews, and instructors lacked intuitive tools for managing reviewer assignments. The interface did not fully support all questionnaire types or provide clear feedback/status indicators.

== Solution Approach ==
* Student dashboard displays all assigned reviews, their status (Not saved, Saved, Submitted), and topic/team info.
* Dynamic review forms render all item types (Criterion, Scale, TextField, TextArea, Dropdown, MultipleChoice, Checkbox, Grid, UploadFile, SectionHeader).
* Drafts can be saved and resumed; submissions are locked for editing.
* Instructor “Assign Reviewer” page allows adding/removing reviewers per team.
* Review Tableau visualizes all reviews for a participant in a matrix format.
* Uses React 18, TypeScript, Redux Toolkit, React-Bootstrap, Formik, and axios for API integration.

== Scope ==
This project focuses on the frontend React application. Backend API endpoints are assumed to be available and compatible. The scope includes:
* StudentTasks dashboard
* TeammateReview form
* ResponseMappings (Assign Reviewer)
* ReviewTableau visualization
* Alert system for user feedback

== Key Components ==
; StudentTasks
: Displays assigned reviews, their status, and topic/team info. Allows navigation to review forms.

; TeammateReview
: Renders dynamic review forms for all questionnaire item types. Supports draft saving, submission, and read-only mode.

; ResponseMappings (Assign Reviewer)
: Instructor tool for assigning/removing reviewers to teams. Uses backend API and localStorage.

; ReviewTableau
: Visualizes all reviews for a participant in a matrix format, showing rubric items, scores, and feedback.

; Alert System
: Provides contextual feedback for user actions (success, error, info), with auto-dismiss and manual close.

; ResponseController (Backend Integration)
: Main backend API controller for managing review responses. Handles creating, updating, submitting, and fetching responses, with proper authorization.

== Screenshots ==
* [[File:Ss1_e2607.png|700px]]
* [[File:Ss2_e2607.png|700px]]

== Demo ==
* Demo Video: https://drive.google.com/file/d/1KaY0lCwc8ppLmhtatW7d38o6kAbKP_TQ/view?usp=sharing

== Setup & Run ==
=== Prerequisites ===
* Docker and Docker Compose
* Node.js (v18+) and npm

=== Backend (Rails API) ===
# In backend directory:
cd E2550-reimplementation-back-end
docker compose build --no-cache
docker compose up
# (First time) In a new terminal:
docker compose exec app bash
bundle install
bundle exec rails db:migrate:reset
bundle exec rails db:seed

=== Frontend (React) ===
# In frontend directory:
cd ResponsesController_Frontend_CSC517
npm install
npm run dev

# Frontend: http://localhost:3000
# Backend API: http://localhost:3002

== Test Plan ==
* Manual testing of all review workflows (dashboard, form, assign reviewer, tableau).
* API error and loading state handling.
* Demo credentials: username: student1@example.com, password: password
* Admin credentials: username: admin, password: password123

== Team ==
'''Members'''
* An Mai (atmai@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)
* Emma Hassler (efhassle@ncsu.edu)
'''Mentor'''
* Vishal Reddy Devireddy (vdevire2@ncsu.edu)

== Future Scope ==
* Add more comprehensive test coverage.
* Enhance accessibility and mobile responsiveness.
* Integrate real-time updates for review assignments.
* Add instructor dashboards for review analytics.

== Navigation ==
* [[#StudentTasks|StudentTasks Component]]
* [[#TeammateReview|TeammateReview Component]]
* [[#ResponseMappings|ResponseMappings Component]]
* [[#ReviewTableau|ReviewTableau Component]]
* [[#Demo|Demo]]
* [[#Future Scope|Future Scope]]

CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend

2026-03-30T19:59:36Z

Atmai:

= CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend =

== Important Links ==
* Git PR (front-end): https://github.com/expertiza/reimplementation-front-end/pull/XX
* GitHub Repository (front-end): https://github.com/your-username/reimplementation-front-end
* Demo Video: https://drive.google.com/your-demo-link

== Expertiza ==
Expertiza is an open-source web application for peer assessment and collaborative learning. It allows instructors to create assignments where students can submit work, review peers, and receive feedback. Expertiza supports team and individual assignments, metareviews, topic sign-ups, staggered deadlines, and detailed rubrics, promoting active learning and continuous improvement.

== Overview ==
The objective of this project is to reimplement the review and response workflow UI for Expertiza. This includes:
* A modern student dashboard for assigned reviews and topic sign-up.
* Dynamic review/teammate review forms supporting all questionnaire item types.
* Instructor tools for assigning reviewers and monitoring review progress.
* Integration with the backend API for seamless data flow.

== Problem ==
The previous review UI was limited in usability and flexibility. Students could not easily track or resume reviews, and instructors lacked intuitive tools for managing reviewer assignments. The interface did not fully support all questionnaire types or provide clear feedback/status indicators.

== Solution Approach ==
* Student dashboard displays all assigned reviews, their status (Not saved, Saved, Submitted), and topic/team info.
* Dynamic review forms render all item types (Criterion, Scale, TextField, TextArea, Dropdown, MultipleChoice, Checkbox, Grid, UploadFile, SectionHeader).
* Drafts can be saved and resumed; submissions are locked for editing.
* Instructor “Assign Reviewer” page allows adding/removing reviewers per team.
* Review Tableau visualizes all reviews for a participant in a matrix format.
* Uses React 18, TypeScript, Redux Toolkit, React-Bootstrap, Formik, and axios for API integration.

== Scope ==
This project focuses on the frontend React application. Backend API endpoints are assumed to be available and compatible. The scope includes:
* StudentTasks dashboard
* TeammateReview form
* ResponseMappings (Assign Reviewer)
* ReviewTableau visualization
* Alert system for user feedback

== Key Components ==
; StudentTasks
: Displays assigned reviews, their status, and topic/team info. Allows navigation to review forms.

; TeammateReview
: Renders dynamic review forms for all questionnaire item types. Supports draft saving, submission, and read-only mode.

; ResponseMappings (Assign Reviewer)
: Instructor tool for assigning/removing reviewers to teams. Uses backend API and localStorage.

; ReviewTableau
: Visualizes all reviews for a participant in a matrix format, showing rubric items, scores, and feedback.

; Alert System
: Provides contextual feedback for user actions (success, error, info), with auto-dismiss and manual close.

; ResponseController (Backend Integration)
: Main backend API controller for managing review responses. Handles creating, updating, submitting, and fetching responses, with proper authorization.

== Screenshots ==
* [[File:Ss1_e2607.png|700px]]
* [[File:Ss2_e2607.png|700px]]

== Demo ==
* Demo Video: https://drive.google.com/your-demo-link

== Setup & Run ==
=== Prerequisites ===
* Docker and Docker Compose
* Node.js (v18+) and npm

=== Backend (Rails API) ===
# In backend directory:
cd E2550-reimplementation-back-end
docker compose build --no-cache
docker compose up
# (First time) In a new terminal:
docker compose exec app bash
bundle install
bundle exec rails db:migrate:reset
bundle exec rails db:seed

=== Frontend (React) ===
# In frontend directory:
cd ResponsesController_Frontend_CSC517
npm install
npm run dev

# Frontend: http://localhost:3000
# Backend API: http://localhost:3002

== Test Plan ==
* Manual testing of all review workflows (dashboard, form, assign reviewer, tableau).
* API error and loading state handling.
* Demo credentials: username: student1@example.com, password: password
* Admin credentials: username: admin, password: password123

== Team ==
'''Members'''
* An Mai (atmai@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)
* Emma Hassler (efhassle@ncsu.edu)
'''Mentor'''
* Vishal Reddy Devireddy (vdevire2@ncsu.edu)

== Future Scope ==
* Add more comprehensive test coverage.
* Enhance accessibility and mobile responsiveness.
* Integrate real-time updates for review assignments.
* Add instructor dashboards for review analytics.

== Navigation ==
* [[#StudentTasks|StudentTasks Component]]
* [[#TeammateReview|TeammateReview Component]]
* [[#ResponseMappings|ResponseMappings Component]]
* [[#ReviewTableau|ReviewTableau Component]]
* [[#Demo|Demo]]
* [[#Future Scope|Future Scope]]

File:Ss2 e2607.png

2026-03-30T19:56:23Z

Atmai:

File:Ss1 e2607.png

2026-03-30T19:55:51Z

Atmai:

CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend

2026-03-30T17:55:04Z

Atmai:

= CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend =

== Important Links ==
* Git PR (front-end): https://github.com/expertiza/reimplementation-front-end/pull/XX
* GitHub Repository (front-end): https://github.com/your-username/reimplementation-front-end
* Demo Video: https://drive.google.com/your-demo-link

== Expertiza ==
Expertiza is an open-source web application for peer assessment and collaborative learning. It allows instructors to create assignments where students can submit work, review peers, and receive feedback. Expertiza supports team and individual assignments, metareviews, topic sign-ups, staggered deadlines, and detailed rubrics, promoting active learning and continuous improvement.

== Overview ==
The objective of this project is to reimplement the review and response workflow UI for Expertiza. This includes:
* A modern student dashboard for assigned reviews and topic sign-up.
* Dynamic review/teammate review forms supporting all questionnaire item types.
* Instructor tools for assigning reviewers and monitoring review progress.
* Integration with the backend API for seamless data flow.

== Problem ==
The previous review UI was limited in usability and flexibility. Students could not easily track or resume reviews, and instructors lacked intuitive tools for managing reviewer assignments. The interface did not fully support all questionnaire types or provide clear feedback/status indicators.

== Solution Approach ==
* Student dashboard displays all assigned reviews, their status (Not saved, Saved, Submitted), and topic/team info.
* Dynamic review forms render all item types (Criterion, Scale, TextField, TextArea, Dropdown, MultipleChoice, Checkbox, Grid, UploadFile, SectionHeader).
* Drafts can be saved and resumed; submissions are locked for editing.
* Instructor “Assign Reviewer” page allows adding/removing reviewers per team.
* Review Tableau visualizes all reviews for a participant in a matrix format.
* Uses React 18, TypeScript, Redux Toolkit, React-Bootstrap, Formik, and axios for API integration.

== Scope ==
This project focuses on the frontend React application. Backend API endpoints are assumed to be available and compatible. The scope includes:
* StudentTasks dashboard
* TeammateReview form
* ResponseMappings (Assign Reviewer)
* ReviewTableau visualization
* Alert system for user feedback

== Key Components ==
; StudentTasks
: Displays assigned reviews, their status, and topic/team info. Allows navigation to review forms.

; TeammateReview
: Renders dynamic review forms for all questionnaire item types. Supports draft saving, submission, and read-only mode.

; ResponseMappings (Assign Reviewer)
: Instructor tool for assigning/removing reviewers to teams. Uses backend API and localStorage.

; ReviewTableau
: Visualizes all reviews for a participant in a matrix format, showing rubric items, scores, and feedback.

; Alert System
: Provides contextual feedback for user actions (success, error, info), with auto-dismiss and manual close.

; ResponseController (Backend Integration)
: Main backend API controller for managing review responses. Handles creating, updating, submitting, and fetching responses, with proper authorization.

== Demo ==
* Demo Video: https://drive.google.com/your-demo-link

== Setup & Run ==
=== Prerequisites ===
* Docker and Docker Compose
* Node.js (v18+) and npm

=== Backend (Rails API) ===
# In backend directory:
cd E2550-reimplementation-back-end
docker compose build --no-cache
docker compose up
# (First time) In a new terminal:
docker compose exec app bash
bundle install
bundle exec rails db:migrate:reset
bundle exec rails db:seed

=== Frontend (React) ===
# In frontend directory:
cd ResponsesController_Frontend_CSC517
npm install
npm run dev

# Frontend: http://localhost:3000
# Backend API: http://localhost:3002

== Test Plan ==
* Manual testing of all review workflows (dashboard, form, assign reviewer, tableau).
* API error and loading state handling.
* Demo credentials: username: student1@example.com, password: password
* Admin credentials: username: admin, password: password123

== Team ==
'''Members'''
* An Mai (atmai@ncsu.edu)
* Tejas Manoj Desai (tdesai@ncsu.edu)
* Emma Hassler (efhassle@ncsu.edu)
'''Mentor'''
* Vishal Reddy Devireddy (vdevire2@ncsu.edu)

== Future Scope ==
* Add more comprehensive test coverage.
* Enhance accessibility and mobile responsiveness.
* Integrate real-time updates for review assignments.
* Add instructor dashboards for review analytics.

== Navigation ==
* [[#StudentTasks|StudentTasks Component]]
* [[#TeammateReview|TeammateReview Component]]
* [[#ResponseMappings|ResponseMappings Component]]
* [[#ReviewTableau|ReviewTableau Component]]
* [[#Demo|Demo]]
* [[#Future Scope|Future Scope]]

CSC/ECE 517 Spring 2026

2026-03-30T17:42:29Z

Atmai:

* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]

CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend

2026-03-30T17:40:36Z

Atmai: Created page with "= CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend = == Introduction == === Background === The ResponseController Frontend provides the user interface for students and instructors to manage peer reviews, teammate reviews, and feedback in the Expertiza platform. It enables students to view assigned review tasks, complete and submit reviews, and instructors to assign reviewers and monitor review progress. === Motivation === * Modernize the review and respons..."

= CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend =

== Introduction ==

=== Background ===
The ResponseController Frontend provides the user interface for students and instructors to manage peer reviews, teammate reviews, and feedback in the Expertiza platform. It enables students to view assigned review tasks, complete and submit reviews, and instructors to assign reviewers and monitor review progress.

=== Motivation ===
* Modernize the review and response UI for clarity and usability.
* Streamline the process of submitting, saving, and resuming reviews.
* Improve assignment and review management for instructors.
* Ensure maintainability and scalability using React, TypeScript, and modular design.

=== Tasks Identified ===
; Student Dashboard (StudentTasks)
: Display assigned reviews and their statuses (Not saved, Saved, Submitted).
: Show topic signup and team information.
: Allow navigation to the review form for each assignment.

; Review/Teammate Review Form (TeammateReview)
: Render dynamic forms for all questionnaire item types (Criterion, Scale, TextField, TextArea, Dropdown, MultipleChoice, Checkbox, Grid, UploadFile, SectionHeader).
: Support saving drafts, resuming, and submitting reviews.
: Display read-only mode for submitted reviews.
: Auto-create ResponseMap if not found.

; Assign Reviewer (Instructor)
: List teams, members, and current reviewer assignments.
: Add or remove reviewers for each team.
: Persist assignments using backend API and localStorage.

; Review Tableau
: Visualize all reviews done by a participant for an assignment.
: Show rubric items, scores, and feedback in a tabular format.

; General Improvements
: Use React-Bootstrap for consistent UI.
: Integrate alert system for feedback (success, error, info).
: Modularize code with hooks, services, and reusable components.

== Demo ==

=== Demo Video ===
''To be added by the team.''

=== Demo Link ===
''To be added by the team.''

== Key Components ==

=== ResponseController ===
The ResponseController is the main backend API controller for managing peer review and teammate review responses. It provides endpoints for:
* Creating a new response (draft) or reusing an existing unsubmitted draft for a given review assignment.
* Fetching an existing response and its associated answers (scores/comments).
* Updating a draft response with new answers.
* Submitting a response, which locks it from further editing.
* Unsubmitting or deleting a response (instructor/admin only).
* Ensuring that only the assigned reviewer or authorized instructor can access or modify each response.

The frontend integrates with these endpoints to support saving drafts, resuming work, and submitting reviews, ensuring a smooth and secure review workflow for both students and instructors.

=== StudentTasks ===
* Fetches assigned reviews from backend and localStorage.
* Renders a table of assignments, teams, review types, statuses, and action buttons.
* Integrates with topic signup and team info.

=== TeammateReview ===
* Fetches questionnaire items and existing responses.
* Renders a dynamic review form based on item types.
* Handles draft saving, submission, and read-only display.
* Integrates with backend for response and response map management.

=== ResponseMappings (Assign Reviewer) ===
* Displays teams, members, and reviewer assignments.
* Allows instructors to add or remove reviewers.
* Uses localStorage for persistence and demo data.

=== ReviewTableau ===
* Fetches and displays all reviews for a participant.
* Shows rubric items, scores, and feedback in a matrix.
* Uses color coding and tooltips for clarity.

=== Alert System ===
* Provides contextual feedback for user actions.
* Alerts auto-dismiss after a timeout or can be closed manually.

== Architecture ==
* '''Frontend''': React 18, TypeScript, Redux Toolkit, React-Bootstrap, Formik, TanStack Table.
* '''Backend''': Ruby on Rails API (see E2550-reimplementation-back-end).
* '''API Integration''': Uses axios for HTTP requests to backend endpoints for responses, response maps, questionnaires, grades, and assignments.

== Setup & Run ==

=== Prerequisites ===
* Docker and Docker Compose installed
* Node.js (v18+) and npm (for frontend development)
* (Optional) Ruby and Rails for direct backend development

=== Backend (Rails API) ===
# Open a terminal in the backend directory:
cd E2550-reimplementation-back-end

# Build and start the backend services:
docker compose build --no-cache
docker compose up

# (First time only) In a new terminal, run setup commands inside the app container:
docker compose exec app bash
bundle install
bundle exec rails db:migrate:reset
bundle exec rails db:seed

# Run backend tests (optional):
bundle exec rspec

=== Frontend (React) ===
# Open a new terminal in the frontend directory:
cd ResponsesController_Frontend_CSC517

# Install dependencies:
npm install

# Start the development server:
npm run dev

# The frontend will be available at http://localhost:3000 (or as shown in the terminal).
# The backend API runs at http://localhost:3002 by default.

=== Notes ===
* Make sure both backend and frontend servers are running for full functionality.
* Update environment variables or API URLs in the frontend if your backend runs on a different port.
* For production deployment, follow additional build and configuration steps as needed.

== Future Work ==
* Add more comprehensive test coverage for all components.
* Enhance accessibility and mobile responsiveness.
* Integrate real-time updates for review assignments.
* Add instructor dashboards for review analytics.

== Navigation ==
* [[#StudentTasks|StudentTasks Component]]
* [[#TeammateReview|TeammateReview Component]]
* [[#ResponseMappings|ResponseMappings Component]]
* [[#ReviewTableau|ReviewTableau Component]]
* [[#Demo|Demo]]
* [[#Future Work|Future Work]]