Expertiza_Wiki - User contributions [en]

Score Calculation

2026-07-07T00:36:24Z

Admin: /* Layer 2: ResponseMap (Round Weights) */

= Score Calculation =

Peer review grades in Expertiza are computed in three models.

== Layer 1: Response (Item Weights) ==

<code>Response#aggregate_questionnaire_score</code> sums <code>answer * item.weight</code> for all answered, scored items in a single submitted review. Section-header items, text-area items, etc., are excluded (they carry no weight).

<code>Response#maximum_score</code> computes the maximum possible score for the same set of answered items: <code>sum(item.weight) * questionnaire.max_question_score</code>.

== Layer 2: ResponseMap (Round Weights) ==

<code>ResponseMap#review_grade</code> normalizes each round's score (<code>aggregate_questionnaire_score / maximum_score</code>) and computes a weighted average across rounds using <code>AssignmentQuestionnaire#questionnaire_weight</code>.

Only the latest submitted response per round is used. Rounds with no submitted response are excluded from both the numerator and denominator.

== Layer 3: AssignmentTeam (Reviewer Reputation) ==

<code>AssignmentTeam#aggregate_reviewer_score</code> averages <code>ResponseMap#review_grade</code> across all reviewers of the team, weighted by each reviewer's reputation score (currently defaulting to 1.0 — placeholder for future Uchswas integration).

The same computation is used by <code>AssignmentParticipant#aggregate_teammate_review_grade</code> for teammate reviews.

== Validation ==

<code>AssignmentQuestionnaire</code> validates that <code>questionnaire_weight</code> is 0 when the linked rubric contains no scored items (only <code>SectionHeader</code> items), since a non-zero weight on an unscored rubric would produce meaningless grades.

Score Calculation

2026-07-07T00:35:22Z

Admin: /* Layer 1: Response (Item Weights) */

= Score Calculation =

Peer review grades in Expertiza are computed in three models.

== Layer 1: Response (Item Weights) ==

<code>Response#aggregate_questionnaire_score</code> sums <code>answer * item.weight</code> for all answered, scored items in a single submitted review. Section-header items, text-area items, etc., are excluded (they carry no weight).

<code>Response#maximum_score</code> computes the maximum possible score for the same set of answered items: <code>sum(item.weight) * questionnaire.max_question_score</code>.

== Layer 2: ResponseMap (Round Weights) ==

<code>ResponseMap#review_grade</code> normalises each round's score (<code>aggregate_questionnaire_score / maximum_score</code>) and computes a weighted average across rounds using <code>AssignmentQuestionnaire#questionnaire_weight</code>.

Only the latest submitted response per round is used. Rounds with no submitted response are excluded from both the numerator and denominator.

== Layer 3: AssignmentTeam (Reviewer Reputation) ==

<code>AssignmentTeam#aggregate_reviewer_score</code> averages <code>ResponseMap#review_grade</code> across all reviewers of the team, weighted by each reviewer's reputation score (currently defaulting to 1.0 — placeholder for future Uchswas integration).

The same computation is used by <code>AssignmentParticipant#aggregate_teammate_review_grade</code> for teammate reviews.

== Validation ==

<code>AssignmentQuestionnaire</code> validates that <code>questionnaire_weight</code> is 0 when the linked rubric contains no scored items (only <code>SectionHeader</code> items), since a non-zero weight on an unscored rubric would produce meaningless grades.

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:27:59Z

Admin: /* Reviewer reputation-weighted grading */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
<br clear="all" />
Clicking on "Feedback" will show all of the feedback along with the scores.
[[File:student_view_assignment_feedback_page.png|800px|thumb|left|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===

Grades are calculated in <code>Response.rb</code> (score for a particular review by a specific reviewer), <code>ResponseMap.rb</code> (composite score for reviews in all rounds by the same reviewer) and <code>AssignmentTeam.rb</code> (combined score for all reviews by all reviewers).

'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Running ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder weight for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:26:19Z

Admin: /* Setup & Run */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
<br clear="all" />
Clicking on "Feedback" will show all of the feedback along with the scores.
[[File:student_view_assignment_feedback_page.png|800px|thumb|left|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===

Grades are calculated in <code>Response.rb</code> (score for a particular review by a specific reviewer), <code>ResponseMap.rb</code> (composite score for reviews in all rounds by the same reviewer) and <code>AssignmentTeam.rb</code> (combined score for all reviews by all reviewers).

'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Running ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:23:00Z

Admin: /* As an instructor, I want calculated review grades to reflect each rubric's configured weight */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
<br clear="all" />
Clicking on "Feedback" will show all of the feedback along with the scores.
[[File:student_view_assignment_feedback_page.png|800px|thumb|left|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===

Grades are calculated in <code>Response.rb</code> (score for a particular review by a specific reviewer), <code>ResponseMap.rb</code> (composite score for reviews in all rounds by the same reviewer) and <code>AssignmentTeam.rb</code> (combined score for all reviews by all reviewers).

'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:22:03Z

Admin: /* As an instructor, I want calculated review grades to reflect each rubric's configured weight */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
<br clear="all" />
Clicking on "Feedback" will show all of the feedback along with the scores.
[[File:student_view_assignment_feedback_page.png|800px|thumb|left|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===

Grades are calculated in <code>Response.rb</code> (score for a particular review by a specific reviewer), <code>ResponseMap.rb</code> (composite score for reviews in all rounds by the same reviewer) and <code>AssignmentTeam.rb</code> (combined score for all reviews by all reviewers).
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:17:45Z

Admin: /* As a student, I want my team's score heatgrid to load fast and stay readable while scrolling */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]

Clicking on "Feedback" will show all of the feedback along with the scores.
[[File:student_view_assignment_feedback_page.png|800px|thumb|right|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:14:42Z

Admin: /* As a student, I want my team's score heatgrid to load fast and stay readable while scrolling */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

The heatgrid shows all of the reviews that have been written of the team's submission (or, the student's submission, if this is not a team assignment). The user can hover over any cell with a score that is underlined, meaning that the reviewer has made a comment to go along with the score. Hovering over a cell will show the comments it contains.

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|800px|thumb|right|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:11:57Z

Admin: /* As a student, I want to view a single assignment's deadlines and details */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

A student can perform several tasks for each assignment, depending upon the role they play (e.g., whether they are a submitter, a reviewer, or both.

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|800px|thumb|right|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:10:40Z

Admin: /* As a student, I want to see all my assignments in one place */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

This is the home view for a student. It shows all of the student's assignments, arranged by the course they pertain to.

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|800px|thumb|right|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-07T00:08:41Z

Admin: /* Introduction */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
''This page documents the reimplementation of the Student Task view. It supersedes the earlier [[E2602]] team's version. All searches for E2602 will hit here.''
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky Question column during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===

[[File:student_view_assignments_page.png|800px|thumb|center|Student View Assignments Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===

[[File:student_view_assignment_detail_page.png|800px|thumb|center|Student View Assignment Detail Page]]

'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===

[[File:student_view_assignment_grades_page.png|800px|thumb|left|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|800px|thumb|right|Student View Assignment View Feedbacks]]
<br clear="all" />
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who is not permitted to submit or review will not see those task links ===

'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice section-header marker objects into the response before it is returned to the frontend

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> - item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Inserts <code>{ type: "header", txt: "..." }</code> marker objects into the scores array at positions derived from each <code>SectionHeader</code> item's sequence order, so the frontend renders section heading rows between score rows without those rows affecting item numbering.

=== Review Grade Calculation ===
For details on how peer review grades are computed, see [[Score Calculation]].

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:54:39Z

Admin: /* Review Grade Calculation */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice headers into the displayed review (which is a Response instance).

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of weights of all the scored items in the rubric

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:48:58Z

Admin: /* Score Aggregation Flow */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice headers into the displayed review (which is a Response instance).

=== Aggregation of Scores Assigned by a Reviewer ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:45:44Z

Admin: /* Request / Response Flow */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice headers into the displayed review (which is a Response instance).

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:38:53Z

Admin: /* Request / Response Flow */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:38:08Z

Admin: /* Request / Response Flow */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.timeline_events</code> merges the assignment's due dates with timestamps of reviews done of the logged-in user's work into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:28:57Z

Admin: /* Student Task Overview */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
A StudentTask is a task that a student performs in the course of doing an assignment, e.g., forming a team, choosing a topic, submitting work, or reviewing work. No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:26:24Z

Admin: /* Student Task Overview */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. A <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:24:49Z

Admin: /* As an instructor, I want review grades to reflect each rubric's configured weight */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want calculated review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:23:18Z

Admin: /* As a student who isn't permitted to submit or review, I should not see those task links */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== A student who isn't permitted to submit or review will not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:22:28Z

Admin: /* As a student, I want my team's score heatgrid to load fast and stay readable while scrolling */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item) remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== As a student who isn't permitted to submit or review, I should not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:22:10Z

Admin: /* As a student, I want my team's score heatgrid to load fast and stay readable while scrolling */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* The first two columns (item number "<code>#</code>" and Item remain fixed during horizontal scroll, along with section headers
* Hovering over a score with a comment shows the corresponding reviewer's feedback as a tooltip

=== As a student who isn't permitted to submit or review, I should not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view

2026-07-02T23:10:17Z

Admin: /* User Stories */

= CSC/ECE 517 Spring 2026 - E2602. Reimplement Student Task View =

== About Expertiza ==
Expertiza is a robust, open-source web platform designed to empower educational environments that emphasize project-based learning. It streamlines collaborative activities including peer reviews, surveys, and team assignments — giving instructors tools to manage assignments and track performance, and giving students a single place to submit work, review peers, and track feedback.

== Introduction ==
This iteration of E2602 hardens and extends the Student Task View: consolidating the student dashboard and detail pages into single-call REST endpoints, eliminating N+1 queries in the peer-review score heatgrid, and fixing several display/permission bugs surfaced by manual QA against real assignment data.

=== Tech Stack ===
* '''Backend:''' Ruby on Rails (API-only)
* '''Frontend:''' React + TypeScript
* '''Database:''' MySQL
* '''Backend Testing:''' RSpec
* '''Frontend Testing:''' Jest, React Testing Library

=== Key Improvements ===
* Eliminated N+1 queries in the score heatgrid (<code>get_team_scores</code>, <code>get_my_scores_data</code>, <code>accumulate_round_scores</code>, <code>get_answer</code>) via <code>.includes(responses: { scores: :item })</code> and in-memory filtering instead of re-querying preloaded associations
* Converted <code>ReviewTable</code>'s stylesheet to CSS Modules, fixing a Bootstrap class collision and scoping color classes (<code>c1</code>–<code>c5</code>) correctly
* Redesigned the score/feedback heatgrid with sticky <code>#</code>/Question columns and a sticky, full-width SectionHeader row that stays fixed during horizontal scroll
* Added hover tooltips on score cells showing the reviewer's written feedback
* Rewrote <code>StudentTasks</code> from a (mis-implemented) topic sign-up sheet into a proper course-grouped assignment dashboard
* Added participant-level <code>can_submit</code> / <code>can_review</code> permission checks, hiding "Your work" / "Others' work" task links accordingly
* Refactored review grade calculation: <code>ResponseMap#review_grade</code> now weights each round by its <code>questionnaire_weight</code>; <code>ResponseMap.compute_average_reviewer_score</code> centralizes the weighted-average logic previously duplicated across <code>AssignmentTeam</code> and <code>AssignmentParticipant</code>

== Problem Statement ==
The previous Student Task View had several concrete defects:
* The score heatgrid fired one SQL query per response/score across all reviewers and rounds, producing hundreds of queries for a single page load
* SectionHeader rubric rows (non-scorable dividers) were incorrectly counted in the <code>#</code> column numbering and lost their fixed position during horizontal scroll
* <code>StudentTasks.tsx</code> was previously implemented as a topic sign-up sheet, not a task dashboard, and required a full rewrite
* The page did not respect participant-level <code>can_submit</code>/<code>can_review</code> flags — all task links were always shown regardless of permission
* Review grade calculation treated every reviewer and every round equally, ignoring each rubric's configured <code>questionnaire_weight</code>

== User Stories ==

=== As a student, I want to see all my assignments in one place ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/list</code> returns all tasks for the logged-in student in one call
* Tasks are grouped by course on the dashboard
* Each task shows current stage and days remaining, if applicable

=== As a student, I want to view a single assignment's deadlines and details ===
'''Acceptance Criteria:'''
* <code>GET /student_tasks/show/:id</code> returns the task plus a unified <code>due_dates</code> timeline
* The timeline visually distinguishes completed, current, and pending stages
* <code>GET /student_tasks/team</code> returns teammates grouped by course

=== As a student, I want my team's score heatgrid to load fast and stay readable while scrolling ===
'''Acceptance Criteria:'''
* The heatgrid loads from a single <code>GET /grades/:id/view_our_scores</code> call
* SectionHeaders are excluded from the <code>#</code> column numbering
* SectionHeader rows and the <code>#</code>/Question columns stay fixed during horizontal scroll
* Hovering a score with a comment shows the reviewer's feedback as a tooltip

=== As a student who isn't permitted to submit or review, I should not see those task links ===
'''Acceptance Criteria:'''
* "Your work" is hidden when <code>can_submit</code> is <code>false</code>
* "Others' work" is hidden when <code>can_review</code> is <code>false</code>

=== As an instructor, I want review grades to reflect each rubric's configured weight ===
'''Acceptance Criteria:'''
* <code>ResponseMap#review_grade</code> weights each round's normalized score by that round's <code>questionnaire_weight</code>
* <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code> both compute their averages through the same shared <code>ResponseMap.compute_average_reviewer_score</code>

== Design ==

=== Student Task Overview ===
No dedicated <code>StudentTask</code> database table exists. <code>StudentTask</code> is a plain Ruby object composed from <code>AssignmentParticipant</code> and its associated <code>Assignment</code>, <code>Course</code>, <code>DueDate</code>, <code>SignedUpTeam</code>/<code>ProjectTopic</code>, and permission fields (<code>can_submit</code>, <code>can_review</code>, <code>permission_granted</code>).

==== Request / Response Flow ====
* Student navigates to <code>/student_tasks</code> → frontend calls <code>GET /student_tasks/list</code>
* <code>StudentTask.tasks(user)</code> preloads <code>assignment: :course</code> and <code>:user</code> associations, then maps each <code>AssignmentParticipant</code> through <code>StudentTask.create_from_participant</code>
* Selecting an assignment navigates to the detail route → frontend calls <code>GET /student_tasks/show/:id</code>
* <code>StudentTask.get_events_for_assignment</code> merges due dates with submitted review/feedback activity into one sorted timeline
* For the score heatgrid: frontend calls <code>GET /grades/:id/view_our_scores</code> → <code>GradesController#get_team_scores</code> eager-loads <code>responses: { scores: :item }</code> and calls <code>insert_section_headers</code> to splice header sentinels into the response

=== Score Aggregation Flow ===
* <code>Response#aggregate_questionnaire_score</code> — item-weighted score for one submitted response
* <code>ResponseMap#review_grade</code> — normalizes a map's score per round and weights it by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score(maps)</code> — weighted average across multiple maps, the single implementation shared by <code>AssignmentTeam#aggregate_reviewer_score</code> and <code>AssignmentParticipant#aggregate_teammate_review_grade</code>

== Backend Implementation ==

=== StudentTasksController ===
* <code>list</code> — all <code>StudentTask</code> objects for the logged-in user
* <code>show</code> — single task by participant ID with the unified timeline
* <code>team</code> — teammates grouped by course name (<code>StudentTask.all_teammates</code>)

=== GradesController — N+1 elimination ===
<code>get_team_scores</code> and <code>get_my_scores_data</code> eager-load <code>responses: { scores: :item }</code> on the <code>ReviewResponseMap</code>/<code>TeammateReviewResponseMap</code> queries. <code>accumulate_round_scores</code> filters SectionHeader scores via Ruby <code>.reject</code> instead of <code>.joins</code>/<code>.where</code> — calling <code>.where</code> on an already-preloaded association silently bypasses the cache and re-queries the database. <code>get_answer</code> now accepts the parent <code>response</code> directly instead of re-fetching it via <code>score.response</code>.

=== insert_section_headers ===
Splices <code>{ type: "header", txt: "..." }</code> sentinel hashes into a round's scores array at positions matching each <code>SectionHeader</code> item in the questionnaire's sequence, so the frontend can render heading rows between score rows without those rows affecting numbering.

=== Review Grade Calculation ===
* <code>ResponseMap#review_grade</code> — latest submitted response per round, normalized (<code>score/max</code>), weighted by that round's <code>questionnaire_weight</code>
* <code>ResponseMap.compute_average_reviewer_score</code> / <code>ResponseMap.reviewer_reputation_for</code> — shared weighted-average logic; reviewer reputation currently defaults to <code>1.0</code> (placeholder for a future review-quality grader integration)
* <code>Questionnaire#total_item_weight</code> — pre-calculates the sum of scored item weights, excluding <code>SectionHeader</code> items

=== Comprehensive Testing ===
* Model specs for <code>StudentTask.all_teammates</code>, <code>create_from_participant</code>, <code>get_events_for_assignment</code>
* Request specs for <code>student_tasks/list</code>, <code>student_tasks/show/:id</code>, <code>student_tasks/team</code>, and <code>grades/:id/view_our_scores</code>
* Routing specs verifying the above routes resolve correctly

== Frontend Implementation ==
[[File:student_view_assignments_page.png|600px|thumb|right|Student View Assignments Page]]
[[File:student_view_assignment_detail_page.png|600px|thumb|right|Student View Assignment Detail Page]]
[[File:student_view_assignment_grades_page.png|600px|thumb|right|Student View Assignment View Team Grades]]
[[File:student_view_assignment_feedback_page.png|600px|thumb|right|Student View Assignment View Feedbacks]]
=== New/Updated Files ===
{| class="wikitable"
! File !! Purpose
|-
| <code>StudentTasks.tsx</code> || Course-grouped assignment dashboard (rewritten from a topic sign-up sheet)
|-
| <code>StudentTasksList.tsx</code> || Sidebar — not-started tasks, revisions, teammates by course
|-
| <code>StudentTaskDetail.tsx</code> || Per-assignment detail page — timeline, task links, conditional <code>can_submit</code>/<code>can_review</code> rendering
|-
| <code>ViewTeamGrades.module.scss</code> || CSS Modules conversion; scoped <code>c1</code>–<code>c5</code> color classes, sticky-column and tooltip styles
|-
| <code>ReviewTable.tsx</code> || Single-call heatgrid; Scores/Feedback toggle; sticky SectionHeader rows
|-
| <code>ReviewTableRow.tsx</code> || Sticky <code>#</code>/Question columns; reduced row height; hover tooltip via <code>data-question</code>
|-
| <code>FeedbackTable.tsx</code> || Feedback-mode table mirroring <code>ReviewTable</code>'s sticky-column layout
|-
| <code>heatgridUtils.ts</code> || <code>RoundRow</code>/<code>isHeader()</code> types; fixed <code>#</code> numbering to skip SectionHeader sentinels
|}

=== StudentTasks (List View) ===
* Single <code>GET /student_tasks/list</code> call, grouped by course
* Fixed: "Assignments" heading was rendering as body text because its class was referenced as a plain string instead of the CSS Modules export (<code>styles['assignments-title']</code>)

=== StudentTaskDetail (Detail View) ===
* Visual timeline with progress line and stage nodes (completed/current/pending)
* Task links list — "Your work" and "Others' work" conditionally rendered based on <code>can_submit</code>/<code>can_review</code>
* "Send Email To Reviewers" button repositioned to align with the task list rather than floating disconnected at the page top

=== ViewTeamGrades (Heatgrid) ===
* Consolidated ~6 sequential API calls into one <code>GET /grades/:id/view_our_scores</code>
* SectionHeader rows split into a sticky label cell + scrolling spacer cell so they stay fixed during horizontal scroll
* Score cells show reviewer feedback as a hover tooltip
* Round headings simplified from "Review (Round: 1 of 2)" to "Round 1"

== Design Principles ==

=== Single Responsibility ===
Score aggregation is layered: <code>Response</code> owns item-level scoring, <code>ResponseMap</code> owns per-map/per-round weighting, <code>ResponseMap.compute_average_reviewer_score</code> owns cross-map averaging — each level only knows about the one below it.

=== Don't Repeat Yourself ===
The weighted-average logic that was duplicated between <code>AssignmentTeam#aggregate_review_grade</code> and <code>ReviewAggregator#compute_average_review_score</code> was consolidated into a single <code>ResponseMap.compute_average_reviewer_score</code>, and the now-dead <code>ReviewAggregator</code> concern was deleted.

=== Performance by Design ===
Eager loading (<code>.includes</code>) and in-memory filtering (<code>.reject</code>) were chosen deliberately over additional database round-trips after profiling showed the heatgrid endpoint firing hundreds of queries under the old implementation.

== Test Plan ==

=== Backend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTask.all_teammates</code> groups teammates by course || Returns <code>{course_name => [fullnames]}</code>
|-
| 2 || <code>all_teammates</code> excludes calibrated assignments || Calibrated-assignment teammates excluded
|-
| 3 || <code>all_teammates</code> excludes the user themself || Solo team returns empty hash
|-
| 4 || <code>GET /student_tasks/list</code> returns all tasks for user || 200 OK with task array
|-
| 5 || <code>GET /student_tasks/show/:id</code> returns due_dates timeline || 200 OK with <code>due_dates</code> array
|-
| 6 || <code>GET /student_tasks/team</code> groups teammates by course || 200 OK with grouped hash
|-
| 7 || Heatgrid <code>#</code> column excludes SectionHeaders from numbering || Sequential numbering skips header rows
|-
| 8 || <code>accumulate_round_scores</code> filters SectionHeaders without re-querying || No additional SQL fired against preloaded association
|-
| 9 || <code>AssignmentQuestionnaire</code> weight validation || <code>questionnaire_weight</code> must be 0 when rubric has no scored questions
|-
| 10 || <code>ResponseMap.compute_average_reviewer_score</code> || Weighted average matches Σ(grade × weight) / Σ(weight)
|}

=== Frontend Tests ===
{| class="wikitable"
! # !! Test !! Expected Result
|-
| 1 || <code>StudentTasks</code> renders "Assignments" heading with correct styling || Heading uses module class, renders bold and large
|-
| 2 || <code>StudentTaskDetail</code> hides "Your work" when <code>can_submit</code> is false || List item not rendered
|-
| 3 || <code>StudentTaskDetail</code> hides "Others' work" when <code>can_review</code> is false || List item not rendered
|-
| 4 || <code>heatgridUtils</code> itemNumber skips SectionHeader rows || Numbering matches scored items only
|-
| 5 || <code>ReviewTable</code> SectionHeader row stays fixed during horizontal scroll || Header cell <code>position: sticky</code>
|-
| 6 || <code>ReviewTableRow</code> shows tooltip only when a comment exists || No tooltip box when <code>data-question</code> is undefined
|-
| 7 || Heatgrid column borders render as <code>#ddd</code> || No black borders after <code>tbl_heat</code> class applied
|}

== Relevant Links ==

=== Repos ===
* https://github.com/expertiza/reimplementation-back-end
* https://github.com/expertiza/reimplementation-front-end

=== Pull Requests ===
* Backend: https://github.com/expertiza/reimplementation-back-end/pull/352
* Frontend: https://github.com/expertiza/reimplementation-front-end/pull/182

=== Demo Video ===
* (add link once recorded)

== Developer Guidance ==

=== Backend ===
==== Setup & Run (via Docker) ====
<pre>
docker compose up
</pre>

==== Within the container ====
<pre>
bundle exec rspec spec/models/student_task_spec.rb
bundle exec rspec spec/requests/api/v1/student_tasks_controller_spec.rb
bundle exec rspec spec/requests/api/v1/grades_controller_spec.rb
</pre>

=== Frontend ===
==== Setup & Run ====
<pre>
npm install
npm start
</pre>

==== Running Frontend Tests ====
<pre>
npm test -- StudentTaskDetail # run a single suite
npm test # run full suite
</pre>

== Future Scope ==

=== Reviewer reputation-weighted grading ===
Integrate an external review-quality grader (e.g. an LLM-based reviewer grader) so <code>ResponseMap.reviewer_reputation_for</code> reflects actual review quality instead of the current <code>1.0</code> placeholder for every reviewer.

=== Email-the-authors integration ===
Wire "Send Email To Reviewers" to a real backend endpoint instead of the current placeholder route.

=== Dedicated StudentTask abstraction ===
<code>StudentTask</code> remains a composed, non-persisted object. A future dedicated table could centralize derived state and simplify queries if the feature's scope grows further.

== Mentor ==
[mailto:kgudipe@ncsu.edu Koushik Gudipelly]

== Members ==
[mailto:rsgopara@ncsu.edu Ravi Goparaju]
[mailto:xmi@ncsu.edu Xiangjun Mi]

== Completed by ==
[mailto:blalu@ncsu.edu Bestin Lalu]

CSC/ECE 517 Spring 2026 - E2609. Review calibration

2026-04-17T00:49:54Z

Admin: /* Problem statements */

== Project overview ==

Expertiza supports course assignments with peer review. The reimplementation exposes a '''Rails JSON API''' and a '''React''' single-page application.

||| This should describe the motivation for calibration. It's a way to make sure that the reviewer knows what they're doing. The instructor evaluates a "calibration submission" before the students do, and then the system compares how close the student's review is to the instructor's review. If it's close, the student can be deemed competent. ||| This project implements a '''calibration assignment''' in the reimplementation: instructors use the '''Calibration''' tab to register '''calibration participants''' by username, use '''Begin''' to open the same rubric UI students see, and '''enter the calibration review''' as an instructor <code>Response</code> on a <code>for_calibration</code> <code>ResponseMap</code>. A '''comparison report''' summarizes how each student’s calibration review compares to the '''instructor’s review''' of the same submission, per rubric item. As in the course description, students review work that '''course staff''' have already reviewed; the system stores reviews and rubric scores for training and reporting.

== Problem statements ==

# '''Data model.''' Normal peer review and calibration must be distinguishable. The implementation adds <code>for_calibration</code> on <code>response_maps</code> ||| response maps are the way that Expertiza knows who's reviewing whom.||| so the system can select the right maps for listing, saving the instructor calibration review at the <code>instructor_response</code> endpoint, and report logic.
# '''Instructor workflow.''' Teaching staff add calibration participants by username, open the review via '''Begin''', and save drafts or submit the instructor calibration review. Submit must lock that review so comparison reports stay stable.
# '''Reporting.''' For each calibration submission the instructor needs a view that compares many student calibration responses to one instructor response on the same rubric, with per-item summaries suitable for charts.
# '''Authorization''' Only instructor or teaching-assistant roles for the assignment may use the calibration instructor APIs.
# '''Controller boundaries''' Instructor calibration maps, instructor-review persistence, '''and''' the comparison-report '''<code>GET</code>''' are '''<code>ReviewMappingsController</code>''' responsibilities. One '''new student review controller''' covers '''student'''-scoped HTTP: review listing, calibration links, and comparison affordances. Submitted content uses the '''<code>SubmittedContentController</code>''' stack.
# '''Student workflow ''' Students see their work as reviewers through a '''student review''' API: list the '''<code>ResponseMap</code>s / reviews''' relevant to them. Where <code>for_calibration</code> applies, provide a '''link to the calibration comparison''' for instructor versus class scores and enough '''score/feedback''' context that the student can see '''how they compare''' to the instructor on that calibration submission. Teaching-staff map management remains on '''<code>ReviewMappingsController</code>'''; the student API lists maps and comparison links and reuses the same report JSON where appropriate.

== Design goals ==

* '''Clarity''' — A reader can follow the instructor path from configuration through '''Begin''' and the instructor calibration review to the comparison report, '''and''' the student path from their review list to calibration comparison where applicable.
* '''Separation''' — '''<code>ReviewMappingsController</code>''' owns every teaching-staff calibration endpoint: the map list <code>GET</code>, add participant, '''Begin''', instructor response, map delete, and the comparison-report '''<code>GET</code>'''. A '''dedicated student review controller''' for student-facing HTTP lists student reviews / maps and exposes calibration comparison entry points, delegating instructor tab behavior and report aggregation to '''<code>ReviewMappingsController</code>'''.
* '''DRY''' — One rubric <code>Response</code>/<code>Answer</code> persistence path using a '''shared rubric writer''' for instructor calibration and other reviews where applicable. One submitted-content path via '''<code>SubmittedContentController</code>''' for list rows and report payloads.
* '''Minimal footprint''' — Ship what the course feature needs: an instructor path to enter calibration reviews and a student path to compare their calibration work to the instructor’s. Prefer small methods, clear names, focused PRs, and plain comments on the calibration surface.
* '''Testability''' — Prefer factories and request specs for repeatable scenarios.
* '''Documentation''' — Controllers are described in prose with routes in the appendix; screenshots pair UI with the backing API.

== Database design ==

Column: <code>response_maps.for_calibration</code>

* Type: boolean, default <code>false</code>, <code>NOT NULL</code>.
* When <code>true</code>, the row is part of the calibration workflow for that assignment: either the instructor-to-calibration-participant map or a student calibrator map that shares the same <code>reviewee_id</code> as other calibration maps for that participant.
* When <code>false</code>, the row behaves as a normal peer-review map.

== Solution approach ==

=== Phase 1 — Calibration participants and response maps ===

Instructors register calibration participants on the assignment and obtain a <code>ResponseMap</code> that backs the instructor <code>Response</code> for that calibration submission. '''<code>ReviewMappingsController</code>''', extended for calibration, validates assignment and teaching-staff role, ensures the target user is an <code>AssignmentParticipant</code> when required, sets <code>for_calibration</code> on the map, and returns list rows with display name, submitted artifact summary using the same helpers as '''<code>SubmittedContentController</code>''', and review status. Adding a participant by username is idempotent.

=== Phase 2 — Reporting and comparison ===

The comparison-report '''<code>GET</code>''' returns the JSON consumed by the Calibration report React page and is implemented on '''<code>ReviewMappingsController</code>'''. It returns one payload for the stacked chart and rubric detail views. The server resolves the instructor calibration map, identifies the reviewee as the calibration participant, loads rubric <code>Item</code>s, loads instructor and student <code>Response</code> / <code>Answer</code> data for the same reviewed work. Per map, aggregation uses '''submitted''' student responses, taking the latest row by <code>updated_at</code> among submitted responses, then runs <code>CalibrationPerItemSummary</code> for per-item buckets.

=== Phase 3 — Instructor calibration review UI ===

The instructor uses the same rubric experience as students: draft and submit, then the submitted rubric is locked for further edits. That matches the course description of a normal-looking rubric review after '''Begin''' and establishes a stable instructor review for downstream comparison reports.

=== High-level architecture ===

All '''teaching-staff''' calibration JSON — the calibration map '''list''', mutating map and review actions including add participant, '''Begin''', instructor response, and delete, '''and''' the comparison-report '''<code>GET</code>''' — goes through '''<code>ReviewMappingsController</code>'''. Student-facing review HTTP lives in '''one new student review controller''' whose Ruby class and path names follow <code>config/routes.rb</code>.

* '''Review mappings — JSON, teaching staff.''' Extended '''<code>ReviewMappingsController</code>''' serves the Calibration tab: list calibration maps, add a participant and the corresponding <code>for_calibration</code> map, '''Begin''' metadata, save or submit the instructor calibration review, optional map delete, '''and''' the comparison-report '''<code>GET</code>'''. Implement the report action as a thin entry point that delegates to POROs or private methods for assembly. <code>Response</code> / <code>Answer</code> persistence for saves uses the same shared rubric writer as elsewhere where possible.

* '''Report — JSON, teaching staff.''' The report '''<code>GET</code>''' is a '''<code>ReviewMappingsController</code>''' action; declare it as a member or collection route in <code>config/routes.rb</code> next to the action implementation. It returns JSON: rubric items, instructor and student <code>Response</code> data for the reviewee, <code>per_item_summary</code>, reviewee hyperlinks/files via '''<code>SubmittedContentController</code>'''.

* '''Student reviews — JSON.''' The '''student review controller''' lists '''<code>ResponseMap</code>s / reviews''' for the student; for '''<code>for_calibration</code>''' rows it exposes a '''link''' to the teaching-staff comparison report JSON and UI to compare '''student vs instructor''' scores and feedback. Thin layer over existing review models; instructor map listing and report aggregation stay in '''<code>ReviewMappingsController</code>'''.

* '''React SPA.''' Assignment editor → Calibration tab → '''Begin''' → instructor rubric page → report page '''<code>GET</code>'''.

* '''Server-side helpers.''' <code>CalibrationPerItemSummary</code> builds per-item chart buckets. Submitted hyperlinks/files always go through '''<code>SubmittedContentController</code>'''; details are under '''Implementation''' and '''Backend'''.

== UML diagram ==

[[File:E2609-calibration-domain-class-uml.png|720px|center]]

Instructors and students are <code>AssignmentParticipant</code>s. The instructor’s calibration map is a <code>ResponseMap</code> with <code>for_calibration</code> true whose reviewer is the instructor participant and whose reviewee is the calibration participant. Student calibration maps share the same <code>reviewee_id</code>, the calibration author, but use other <code>reviewer_id</code> values. <code>Response</code> and <code>Answer</code> store scores. List and report use '''<code>SubmittedContentController</code>''' for hyperlinks/files; <code>CalibrationPerItemSummary</code> supports report aggregation.

== Flow: Review calibration ==

'''Figure 1a — Calibration setup, overview.''' Student lane: review list and submit via the student review stack. Staff lane: Calibration tab and rubric send teaching-staff calibration traffic to '''<code>ReviewMappingsController</code>'''. The two lanes can happen in any order; details and routes are in '''Implementation''' and the '''Appendix'''.

[[File:E2609-calibration-pipelines-flow.png|820px|center]]

'''Figure 1b — Calibration report, overview.''' Teaching staff open the report in React; the page issues one <code>GET</code> to '''<code>ReviewMappingsController</code>''' and receives either <code>403</code> or <code>200</code> report JSON. Assembly of rubric, scores, <code>CalibrationPerItemSummary</code>, and the <code>SubmittedContentController</code> stack is specified in code and in '''Implementation''' and '''Backend'''; the diagram highlights the browser–Rails exchange.

[[File:E2609-calibration-flow-report.png|720px|center]]

Figure 1b: maps for one calibration run share a <code>reviewee_id</code>; <code>per_item_summary</code> aggregates '''submitted''' student <code>Response</code> rows per map using the latest <code>updated_at</code> among submitted rows.

== Implementation ==

{| class="wikitable"
|-
! Area
! Implementation
! Verify
|-
| Teaching-staff HTTP
| Implement list, create, begin, instructor response save, map delete, '''and''' comparison-report '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''', optionally split into a Rails concern mixed into that controller, scoped with <code>for_calibration</code> and teaching-staff authorization. Add '''one new student review controller''': list student '''<code>ResponseMap</code>s / reviews'''; for <code>for_calibration</code> items, '''link''' to the comparison report and expose '''student vs instructor''' score/feedback comparison. Keep the student controller thin: delegate to existing review models and reuse the same report JSON payload shape where appropriate.
| Request specs for all <code>review_mappings</code> calibration actions; request specs for student review list, calibration link, and comparison paths; coverage lives on '''<code>ReviewMappingsController</code>''' for teaching-staff calibration HTTP.
|-
| Report <code>GET</code>
| Report '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''': thin entry + PORO/private steps; stable JSON for the React report page. Uses <code>CalibrationPerItemSummary</code> and the '''<code>SubmittedContentController</code>''' stack for reviewee hyperlinks/files.
| Request spec for report '''<code>GET</code>''' documents required JSON keys and error cases.
|-
| Instructor review write
| Instructor calibration draft/submit on '''<code>ReviewMappingsController</code>'''. Delegate <code>Response</code>/<code>Answer</code> persistence to a '''shared rubric writer'''; action handles guards, validation, and JSON only.
| Request specs: draft, submit, 422, invalid <code>answers</code> payload.
|-
| Submitted content
| Build list and report <code>{ hyperlinks, files }</code> through '''<code>SubmittedContentController</code>''' or the same service object that controller already delegates to.
| Specs assert list and report payloads match submitted-content for the same participant.
|-
| Team + participant bootstrap
| Implement solo-team and related bootstrap logic in a '''team/participant service''' called from map '''create''', with '''<code>Assignment</code>''' updates limited to what map create and listing need. Keep <code>AssignmentTeam</code> hyperlink behavior correct for those paths.
| Service/unit tests + create path; hyperlink regressions if any.
|-
| Scope hygiene
| Scope edits to calibration controllers, services, routes, and React surfaces named in this document, plus the smallest shared-model touches that map create and listing require.
| Code review checklist; small, focused diffs.
|-
| Report UI
| <code>CalibrationReview</code> and related report components match the mockup while consuming the report JSON shape from '''<code>ReviewMappingsController</code>'''.
| Vitest; refresh '''Figure 2''' left pane when the shipped UI changes.
|-
| E2E · repo · docs
| Browser E2E over <code>review_mappings</code> calibration routes and report tab. Record generated-asset rules for this repo in the PR checklist or team wiki so commits stay consistent.
| CI or <code>test:e2e</code>; PR checklist.
|}

== Backend — controller behavior ==

Teaching-staff APIs use auth, '''<code>authorize</code>''', and staff checks consistent with the assignment. '''<code>ReviewMappingsController</code>''', extended for calibration, hosts all teaching-staff calibration endpoints: it lists calibration maps where the current user is the instructor reviewer and <code>for_calibration</code> is true; each row includes map/reviewee fields, '''<code>participant_name</code>''', '''<code>review_status</code>''' from the latest '''<code>Response</code>''', and '''<code>submitted_content</code>''' built with the '''same service/helpers as <code>SubmittedContentController</code>'''. '''Create''' resolves username to '''<code>AssignmentParticipant</code>''', runs team bootstrap via a '''dedicated service''', '''<code>find_or_create_by!</code>''' the instructor→reviewee map with <code>for_calibration</code> true, returns '''<code>201</code>'''. '''Begin''' returns '''<code>map_id</code>''', optional '''<code>response_id</code>''', '''<code>redirect_to</code>'''. '''Instructor response save''' validates input, enforces the submitted-state rules, delegates persistence to a '''shared writer''', returns '''<code>200</code>''' JSON. '''Destroy''' returns '''<code>204</code>''' after ownership checks. '''Comparison-report <code>GET</code>''' for the instructor’s calibration map id on the same controller returns rubric items, '''<code>instructor_response</code>''', submitted student '''<code>Response</code>s''', '''<code>CalibrationPerItemSummary.build</code>''', reviewee hyperlinks/files via the '''<code>SubmittedContentController</code> stack''', '''<code>200</code>''' JSON, or '''<code>404</code>''' / '''<code>422</code>''' when assignment, map, or rubric preconditions fail.

'''Student review controller — new, thin layer''' — Lists '''<code>ResponseMap</code>s / reviews''' for the logged-in student as reviewer; for '''<code>for_calibration</code>''' maps, provides a '''link''' to the calibration comparison using the instructor-facing report '''<code>GET</code>''' or a student-safe JSON projection, plus fields and UI so the student can see '''how their scores and feedback compare''' to the instructor’s. Delegates to existing review / <code>ResponseMap</code> models; instructor Calibration tab CRUD, rubric save, and server-side report aggregation live in '''<code>ReviewMappingsController</code>'''.

== Appendix — API routes ==

{| class="wikitable"
|-
! Method
! Path pattern
! Purpose
|-
| <code>GET</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration list.''' List calibration <code>ResponseMap</code> rows for teaching staff; exact path under <code>review_mappings</code> is defined in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration create.''' Add calibration participant; request includes <code>username</code>. Exact path in <code>config/routes.rb</code>.
|-
| <code>DELETE</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id</code>
| '''Calibration map delete.''' Remove one calibration map by id; exact path in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id/…</code>
| '''Begin.''' Return navigation JSON for instructor calibration rubric SPA; exact member path in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id/…</code>
| '''Instructor response.''' Save draft or submit instructor calibration review; exact member path in <code>config/routes.rb</code>.
|-
| <code>GET</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration report.''' Return comparison report JSON for the instructor calibration map id; exact path in <code>config/routes.rb</code>.
|-
| <code>GET</code> / <code>POST</code>
| <code>/assignments/:assignment_id/…</code>
| '''Student review controller.''' Student review list, calibration report links, and comparison to instructor; verbs and paths declared in <code>config/routes.rb</code>.
|}

== Frontend — data expectations and user flow ==

'''Calibration tab table:''' Each row shows map id, display name, submitted links and files summary, and status: '''Not started''', '''Draft''', or '''Submitted'''. Data comes from the teaching-staff calibration '''list''' <code>GET</code> on '''<code>ReviewMappingsController</code>''' under <code>review_mappings</code> routes, with submitted fields from the same pipeline as '''<code>SubmittedContentController</code>'''.

'''Report page:''' Rubric items in order, instructor scores and comments per item, each student’s scores, and per-item buckets from the report JSON.

'''User flow:'''

# Open Assignment editor, then Calibration tab.
# Enter username; system ensures participant and <code>for_calibration</code> map.
# <code>GET</code> calibration list on <code>review_mappings</code>; table refreshes.
# Begin; <code>POST</code> begin; SPA opens the instructor calibration review page.
# Save draft or submit; <code>POST</code> instructor response on '''<code>ReviewMappingsController</code>'''.
# Open report; <code>GET</code> comparison JSON from '''<code>ReviewMappingsController</code>'''; charts and rubric detail render.

'''Student review list: ''' The student review controller lists the student’s reviews / '''<code>ResponseMap</code>s'''. Calibration rows show a '''link''' to open the comparison for instructor versus class scores and, where the UI implements it, the student’s position relative to the instructor.

=== Assignment editor — Calibration tab ===

[[File:E2609-calibration-assignment-tab.png|480px|center]]

<div style="text-align:center; margin-top:0.2em;">'''Figure 1.''' Reference UI — assignment editor Calibration tab: add participants, open report or '''Begin''' the instructor calibration review, and see submitted items. Each row is filled from the calibration '''list''' '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''' under <code>review_mappings</code>, with <code>participant_name</code>, submitted content from the '''<code>SubmittedContentController</code>''' pipeline, and <code>review_status</code>. Adding the same username again is idempotent.</div>

=== Calibration report: comparison UI ===

{| style="width:100%; max-width:980px; margin:0.8em auto; border-collapse:separate; border-spacing:10px;"
|-
| style="vertical-align:top; text-align:center; width:50%;" | '''Reference UI — Class comparison, stacked chart tab'''
| style="vertical-align:top; text-align:center; width:50%;" | '''Mockup chart layout; same report <code>GET</code> JSON from <code>ReviewMappingsController</code>'''
|-
| style="vertical-align:top; text-align:center;" | [[File:E2609-calibration-report-stacked.png|440px]]
| style="vertical-align:top; text-align:center;" | [[File:E2609-calibration-stacked-chart-improved-mockup.png|440px]]
|}

<div style="text-align:center; margin-top:0.35em;">'''Figure 2.''' Side by side: reference stacked-chart tab versus the intended layout. The mockup adds per-criterion axis labels, framing, legend, and full criterion text in tooltips in <code>CalibrationReview</code>. Same report JSON from '''<code>ReviewMappingsController</code>'''.</div>

[[File:E2609-calibration-report-rubric-detail.png|480px|center]]

<div style="text-align:center; margin-top:0.2em;">'''Figure 3.''' Reference UI — rubric detail: instructor review versus class summary and reviewer selections, using the comparison-report '''<code>GET</code>''' JSON from '''<code>ReviewMappingsController</code>'''.</div>

== Testing and Verification ==

=== Test Plan ===

==== Automated Testing — RSpec ====

* '''Request specs''' for '''<code>ReviewMappingsController</code>''' calibration: list, create participant/map, begin, instructor response for draft, submit, and error paths, destroy, and comparison-report '''<code>GET</code>'''. Co-locate spec files under <code>spec/requests/</code> with the route names in <code>config/routes.rb</code>.
* '''Request specs''' for the '''student review controller''': list reviews/maps; '''<code>for_calibration</code>''' rows include correct report link or comparison payload; responses match the logged-in student reviewer.
* Service specs for aggregation logic, for example <code>spec/services/calibration_per_item_summary_spec.rb</code> next to <code>CalibrationPerItemSummary</code>.
* '''Factories / fixtures''' for <code>for_calibration</code> maps, participants, and submitted responses as needed for the above.

==== Frontend Testing — Vitest ====

* <code>src/pages/Assignments/__tests__/CalibrationReview.test.tsx</code>
* <code>src/pages/Assignments/__tests__/CalibrationInstructorReview.test.tsx</code>
* <code>src/pages/Assignments/__tests__/calibrationReportNormalize.test.ts</code>
* <code>src/pages/Assignments/__tests__/calibrationSummary.test.ts</code>
* <code>src/pages/Assignments/__tests__/calibrationReportDemo.test.ts</code>

==== End-to-end — E2E ====

# Teaching staff: assignment editor → Calibration tab → calibration map list <code>GET</code> on <code>review_mappings</code> → table or empty state renders cleanly in the browser.
# Teaching staff: comparison report <code>GET</code> on '''<code>ReviewMappingsController</code>''' → “Class comparison (stacked)” and “Rubric detail” render; chart region populated when <code>per_item_summary</code> is non-empty.
# Teaching staff: '''Begin''', including opening the calibration review by direct URL if supported → draft save → submit → UI matches post-submit lock rules.
# Student: open student review list → calibration row shows '''link''' to comparison for instructor versus class view → student can see '''how their review compares''' to the instructor’s when that panel is implemented.

==== Manual UI Testing ====

# Login as instructor/TA.
# Open assignment editor → Calibration tab.
# Add a calibration participant by username.
# Click '''View report''' and verify stacked and rubric detail tabs.
# Enter/edit instructor review: save draft, submit, and confirm the form locks.
# Login as student calibrator: open student review list; for a calibration map, follow the report/comparison link and confirm scores or feedback align with expectations versus the instructor view.

== Future Scope ==

* Add an overall calibration score and trend visualization per participant.
* Provide additional endpoints for:
** calibration summary per map,
** detailed agreement breakdown per item across all rounds.
* Improve diagnostics, such as highlighting criteria with the largest score spread across reviewers.

== References ==

* [https://wiki.expertiza.ncsu.edu/index.php?title=Main_Page Expertiza wiki main page]
* Front-end pull request: [https://github.com/expertiza/reimplementation-front-end/pull/164 expertiza/reimplementation-front-end#164]
* Back-end pull request: [https://github.com/expertiza/reimplementation-back-end/pull/323 expertiza/reimplementation-back-end#323]

== Team ==

* Mentor: Dr. Ed Gehringer
* Team members: Xiangjun Mi, Rujuta Palimkar, Emma Hassler

CSC/ECE 517 Spring 2026 - E2609. Review calibration

2026-04-17T00:46:53Z

Admin: /* Project overview */

== Project overview ==

Expertiza supports course assignments with peer review. The reimplementation exposes a '''Rails JSON API''' and a '''React''' single-page application.

||| This should describe the motivation for calibration. It's a way to make sure that the reviewer knows what they're doing. The instructor evaluates a "calibration submission" before the students do, and then the system compares how close the student's review is to the instructor's review. If it's close, the student can be deemed competent. ||| This project implements a '''calibration assignment''' in the reimplementation: instructors use the '''Calibration''' tab to register '''calibration participants''' by username, use '''Begin''' to open the same rubric UI students see, and '''enter the calibration review''' as an instructor <code>Response</code> on a <code>for_calibration</code> <code>ResponseMap</code>. A '''comparison report''' summarizes how each student’s calibration review compares to the '''instructor’s review''' of the same submission, per rubric item. As in the course description, students review work that '''course staff''' have already reviewed; the system stores reviews and rubric scores for training and reporting.

== Problem statements ==

# '''Data model.''' Normal peer review and calibration must be distinguishable. The implementation adds <code>for_calibration</code> on <code>response_maps</code> so the system can select the right maps for listing, saving the instructor calibration review at the <code>instructor_response</code> endpoint, and report logic.
# '''Instructor workflow.''' Teaching staff add calibration participants by username, open the review via '''Begin''', and save drafts or submit the instructor calibration review. Submit must lock that review so comparison reports stay stable.
# '''Reporting.''' For each calibration submission the instructor needs a view that compares many student calibration responses to one instructor response on the same rubric, with per-item summaries suitable for charts.
# '''Authorization''' Only instructor or teaching-assistant roles for the assignment may use the calibration instructor APIs.
# '''Controller boundaries''' Instructor calibration maps, instructor-review persistence, '''and''' the comparison-report '''<code>GET</code>''' are '''<code>ReviewMappingsController</code>''' responsibilities. One '''new student review controller''' covers '''student'''-scoped HTTP: review listing, calibration links, and comparison affordances. Submitted content uses the '''<code>SubmittedContentController</code>''' stack.
# '''Student workflow ''' Students see their work as reviewers through a '''student review''' API: list the '''<code>ResponseMap</code>s / reviews''' relevant to them. Where <code>for_calibration</code> applies, provide a '''link to the calibration comparison''' for instructor versus class scores and enough '''score/feedback''' context that the student can see '''how they compare''' to the instructor on that calibration submission. Teaching-staff map management remains on '''<code>ReviewMappingsController</code>'''; the student API lists maps and comparison links and reuses the same report JSON where appropriate.

== Design goals ==

* '''Clarity''' — A reader can follow the instructor path from configuration through '''Begin''' and the instructor calibration review to the comparison report, '''and''' the student path from their review list to calibration comparison where applicable.
* '''Separation''' — '''<code>ReviewMappingsController</code>''' owns every teaching-staff calibration endpoint: the map list <code>GET</code>, add participant, '''Begin''', instructor response, map delete, and the comparison-report '''<code>GET</code>'''. A '''dedicated student review controller''' for student-facing HTTP lists student reviews / maps and exposes calibration comparison entry points, delegating instructor tab behavior and report aggregation to '''<code>ReviewMappingsController</code>'''.
* '''DRY''' — One rubric <code>Response</code>/<code>Answer</code> persistence path using a '''shared rubric writer''' for instructor calibration and other reviews where applicable. One submitted-content path via '''<code>SubmittedContentController</code>''' for list rows and report payloads.
* '''Minimal footprint''' — Ship what the course feature needs: an instructor path to enter calibration reviews and a student path to compare their calibration work to the instructor’s. Prefer small methods, clear names, focused PRs, and plain comments on the calibration surface.
* '''Testability''' — Prefer factories and request specs for repeatable scenarios.
* '''Documentation''' — Controllers are described in prose with routes in the appendix; screenshots pair UI with the backing API.

== Database design ==

Column: <code>response_maps.for_calibration</code>

* Type: boolean, default <code>false</code>, <code>NOT NULL</code>.
* When <code>true</code>, the row is part of the calibration workflow for that assignment: either the instructor-to-calibration-participant map or a student calibrator map that shares the same <code>reviewee_id</code> as other calibration maps for that participant.
* When <code>false</code>, the row behaves as a normal peer-review map.

== Solution approach ==

=== Phase 1 — Calibration participants and response maps ===

Instructors register calibration participants on the assignment and obtain a <code>ResponseMap</code> that backs the instructor <code>Response</code> for that calibration submission. '''<code>ReviewMappingsController</code>''', extended for calibration, validates assignment and teaching-staff role, ensures the target user is an <code>AssignmentParticipant</code> when required, sets <code>for_calibration</code> on the map, and returns list rows with display name, submitted artifact summary using the same helpers as '''<code>SubmittedContentController</code>''', and review status. Adding a participant by username is idempotent.

=== Phase 2 — Reporting and comparison ===

The comparison-report '''<code>GET</code>''' returns the JSON consumed by the Calibration report React page and is implemented on '''<code>ReviewMappingsController</code>'''. It returns one payload for the stacked chart and rubric detail views. The server resolves the instructor calibration map, identifies the reviewee as the calibration participant, loads rubric <code>Item</code>s, loads instructor and student <code>Response</code> / <code>Answer</code> data for the same reviewed work. Per map, aggregation uses '''submitted''' student responses, taking the latest row by <code>updated_at</code> among submitted responses, then runs <code>CalibrationPerItemSummary</code> for per-item buckets.

=== Phase 3 — Instructor calibration review UI ===

The instructor uses the same rubric experience as students: draft and submit, then the submitted rubric is locked for further edits. That matches the course description of a normal-looking rubric review after '''Begin''' and establishes a stable instructor review for downstream comparison reports.

=== High-level architecture ===

All '''teaching-staff''' calibration JSON — the calibration map '''list''', mutating map and review actions including add participant, '''Begin''', instructor response, and delete, '''and''' the comparison-report '''<code>GET</code>''' — goes through '''<code>ReviewMappingsController</code>'''. Student-facing review HTTP lives in '''one new student review controller''' whose Ruby class and path names follow <code>config/routes.rb</code>.

* '''Review mappings — JSON, teaching staff.''' Extended '''<code>ReviewMappingsController</code>''' serves the Calibration tab: list calibration maps, add a participant and the corresponding <code>for_calibration</code> map, '''Begin''' metadata, save or submit the instructor calibration review, optional map delete, '''and''' the comparison-report '''<code>GET</code>'''. Implement the report action as a thin entry point that delegates to POROs or private methods for assembly. <code>Response</code> / <code>Answer</code> persistence for saves uses the same shared rubric writer as elsewhere where possible.

* '''Report — JSON, teaching staff.''' The report '''<code>GET</code>''' is a '''<code>ReviewMappingsController</code>''' action; declare it as a member or collection route in <code>config/routes.rb</code> next to the action implementation. It returns JSON: rubric items, instructor and student <code>Response</code> data for the reviewee, <code>per_item_summary</code>, reviewee hyperlinks/files via '''<code>SubmittedContentController</code>'''.

* '''Student reviews — JSON.''' The '''student review controller''' lists '''<code>ResponseMap</code>s / reviews''' for the student; for '''<code>for_calibration</code>''' rows it exposes a '''link''' to the teaching-staff comparison report JSON and UI to compare '''student vs instructor''' scores and feedback. Thin layer over existing review models; instructor map listing and report aggregation stay in '''<code>ReviewMappingsController</code>'''.

* '''React SPA.''' Assignment editor → Calibration tab → '''Begin''' → instructor rubric page → report page '''<code>GET</code>'''.

* '''Server-side helpers.''' <code>CalibrationPerItemSummary</code> builds per-item chart buckets. Submitted hyperlinks/files always go through '''<code>SubmittedContentController</code>'''; details are under '''Implementation''' and '''Backend'''.

== UML diagram ==

[[File:E2609-calibration-domain-class-uml.png|720px|center]]

Instructors and students are <code>AssignmentParticipant</code>s. The instructor’s calibration map is a <code>ResponseMap</code> with <code>for_calibration</code> true whose reviewer is the instructor participant and whose reviewee is the calibration participant. Student calibration maps share the same <code>reviewee_id</code>, the calibration author, but use other <code>reviewer_id</code> values. <code>Response</code> and <code>Answer</code> store scores. List and report use '''<code>SubmittedContentController</code>''' for hyperlinks/files; <code>CalibrationPerItemSummary</code> supports report aggregation.

== Flow: Review calibration ==

'''Figure 1a — Calibration setup, overview.''' Student lane: review list and submit via the student review stack. Staff lane: Calibration tab and rubric send teaching-staff calibration traffic to '''<code>ReviewMappingsController</code>'''. The two lanes can happen in any order; details and routes are in '''Implementation''' and the '''Appendix'''.

[[File:E2609-calibration-pipelines-flow.png|820px|center]]

'''Figure 1b — Calibration report, overview.''' Teaching staff open the report in React; the page issues one <code>GET</code> to '''<code>ReviewMappingsController</code>''' and receives either <code>403</code> or <code>200</code> report JSON. Assembly of rubric, scores, <code>CalibrationPerItemSummary</code>, and the <code>SubmittedContentController</code> stack is specified in code and in '''Implementation''' and '''Backend'''; the diagram highlights the browser–Rails exchange.

[[File:E2609-calibration-flow-report.png|720px|center]]

Figure 1b: maps for one calibration run share a <code>reviewee_id</code>; <code>per_item_summary</code> aggregates '''submitted''' student <code>Response</code> rows per map using the latest <code>updated_at</code> among submitted rows.

== Implementation ==

{| class="wikitable"
|-
! Area
! Implementation
! Verify
|-
| Teaching-staff HTTP
| Implement list, create, begin, instructor response save, map delete, '''and''' comparison-report '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''', optionally split into a Rails concern mixed into that controller, scoped with <code>for_calibration</code> and teaching-staff authorization. Add '''one new student review controller''': list student '''<code>ResponseMap</code>s / reviews'''; for <code>for_calibration</code> items, '''link''' to the comparison report and expose '''student vs instructor''' score/feedback comparison. Keep the student controller thin: delegate to existing review models and reuse the same report JSON payload shape where appropriate.
| Request specs for all <code>review_mappings</code> calibration actions; request specs for student review list, calibration link, and comparison paths; coverage lives on '''<code>ReviewMappingsController</code>''' for teaching-staff calibration HTTP.
|-
| Report <code>GET</code>
| Report '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''': thin entry + PORO/private steps; stable JSON for the React report page. Uses <code>CalibrationPerItemSummary</code> and the '''<code>SubmittedContentController</code>''' stack for reviewee hyperlinks/files.
| Request spec for report '''<code>GET</code>''' documents required JSON keys and error cases.
|-
| Instructor review write
| Instructor calibration draft/submit on '''<code>ReviewMappingsController</code>'''. Delegate <code>Response</code>/<code>Answer</code> persistence to a '''shared rubric writer'''; action handles guards, validation, and JSON only.
| Request specs: draft, submit, 422, invalid <code>answers</code> payload.
|-
| Submitted content
| Build list and report <code>{ hyperlinks, files }</code> through '''<code>SubmittedContentController</code>''' or the same service object that controller already delegates to.
| Specs assert list and report payloads match submitted-content for the same participant.
|-
| Team + participant bootstrap
| Implement solo-team and related bootstrap logic in a '''team/participant service''' called from map '''create''', with '''<code>Assignment</code>''' updates limited to what map create and listing need. Keep <code>AssignmentTeam</code> hyperlink behavior correct for those paths.
| Service/unit tests + create path; hyperlink regressions if any.
|-
| Scope hygiene
| Scope edits to calibration controllers, services, routes, and React surfaces named in this document, plus the smallest shared-model touches that map create and listing require.
| Code review checklist; small, focused diffs.
|-
| Report UI
| <code>CalibrationReview</code> and related report components match the mockup while consuming the report JSON shape from '''<code>ReviewMappingsController</code>'''.
| Vitest; refresh '''Figure 2''' left pane when the shipped UI changes.
|-
| E2E · repo · docs
| Browser E2E over <code>review_mappings</code> calibration routes and report tab. Record generated-asset rules for this repo in the PR checklist or team wiki so commits stay consistent.
| CI or <code>test:e2e</code>; PR checklist.
|}

== Backend — controller behavior ==

Teaching-staff APIs use auth, '''<code>authorize</code>''', and staff checks consistent with the assignment. '''<code>ReviewMappingsController</code>''', extended for calibration, hosts all teaching-staff calibration endpoints: it lists calibration maps where the current user is the instructor reviewer and <code>for_calibration</code> is true; each row includes map/reviewee fields, '''<code>participant_name</code>''', '''<code>review_status</code>''' from the latest '''<code>Response</code>''', and '''<code>submitted_content</code>''' built with the '''same service/helpers as <code>SubmittedContentController</code>'''. '''Create''' resolves username to '''<code>AssignmentParticipant</code>''', runs team bootstrap via a '''dedicated service''', '''<code>find_or_create_by!</code>''' the instructor→reviewee map with <code>for_calibration</code> true, returns '''<code>201</code>'''. '''Begin''' returns '''<code>map_id</code>''', optional '''<code>response_id</code>''', '''<code>redirect_to</code>'''. '''Instructor response save''' validates input, enforces the submitted-state rules, delegates persistence to a '''shared writer''', returns '''<code>200</code>''' JSON. '''Destroy''' returns '''<code>204</code>''' after ownership checks. '''Comparison-report <code>GET</code>''' for the instructor’s calibration map id on the same controller returns rubric items, '''<code>instructor_response</code>''', submitted student '''<code>Response</code>s''', '''<code>CalibrationPerItemSummary.build</code>''', reviewee hyperlinks/files via the '''<code>SubmittedContentController</code> stack''', '''<code>200</code>''' JSON, or '''<code>404</code>''' / '''<code>422</code>''' when assignment, map, or rubric preconditions fail.

'''Student review controller — new, thin layer''' — Lists '''<code>ResponseMap</code>s / reviews''' for the logged-in student as reviewer; for '''<code>for_calibration</code>''' maps, provides a '''link''' to the calibration comparison using the instructor-facing report '''<code>GET</code>''' or a student-safe JSON projection, plus fields and UI so the student can see '''how their scores and feedback compare''' to the instructor’s. Delegates to existing review / <code>ResponseMap</code> models; instructor Calibration tab CRUD, rubric save, and server-side report aggregation live in '''<code>ReviewMappingsController</code>'''.

== Appendix — API routes ==

{| class="wikitable"
|-
! Method
! Path pattern
! Purpose
|-
| <code>GET</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration list.''' List calibration <code>ResponseMap</code> rows for teaching staff; exact path under <code>review_mappings</code> is defined in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration create.''' Add calibration participant; request includes <code>username</code>. Exact path in <code>config/routes.rb</code>.
|-
| <code>DELETE</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id</code>
| '''Calibration map delete.''' Remove one calibration map by id; exact path in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id/…</code>
| '''Begin.''' Return navigation JSON for instructor calibration rubric SPA; exact member path in <code>config/routes.rb</code>.
|-
| <code>POST</code>
| <code>/assignments/:assignment_id/review_mappings/…/:id/…</code>
| '''Instructor response.''' Save draft or submit instructor calibration review; exact member path in <code>config/routes.rb</code>.
|-
| <code>GET</code>
| <code>/assignments/:assignment_id/review_mappings/…</code>
| '''Calibration report.''' Return comparison report JSON for the instructor calibration map id; exact path in <code>config/routes.rb</code>.
|-
| <code>GET</code> / <code>POST</code>
| <code>/assignments/:assignment_id/…</code>
| '''Student review controller.''' Student review list, calibration report links, and comparison to instructor; verbs and paths declared in <code>config/routes.rb</code>.
|}

== Frontend — data expectations and user flow ==

'''Calibration tab table:''' Each row shows map id, display name, submitted links and files summary, and status: '''Not started''', '''Draft''', or '''Submitted'''. Data comes from the teaching-staff calibration '''list''' <code>GET</code> on '''<code>ReviewMappingsController</code>''' under <code>review_mappings</code> routes, with submitted fields from the same pipeline as '''<code>SubmittedContentController</code>'''.

'''Report page:''' Rubric items in order, instructor scores and comments per item, each student’s scores, and per-item buckets from the report JSON.

'''User flow:'''

# Open Assignment editor, then Calibration tab.
# Enter username; system ensures participant and <code>for_calibration</code> map.
# <code>GET</code> calibration list on <code>review_mappings</code>; table refreshes.
# Begin; <code>POST</code> begin; SPA opens the instructor calibration review page.
# Save draft or submit; <code>POST</code> instructor response on '''<code>ReviewMappingsController</code>'''.
# Open report; <code>GET</code> comparison JSON from '''<code>ReviewMappingsController</code>'''; charts and rubric detail render.

'''Student review list: ''' The student review controller lists the student’s reviews / '''<code>ResponseMap</code>s'''. Calibration rows show a '''link''' to open the comparison for instructor versus class scores and, where the UI implements it, the student’s position relative to the instructor.

=== Assignment editor — Calibration tab ===

[[File:E2609-calibration-assignment-tab.png|480px|center]]

<div style="text-align:center; margin-top:0.2em;">'''Figure 1.''' Reference UI — assignment editor Calibration tab: add participants, open report or '''Begin''' the instructor calibration review, and see submitted items. Each row is filled from the calibration '''list''' '''<code>GET</code>''' on '''<code>ReviewMappingsController</code>''' under <code>review_mappings</code>, with <code>participant_name</code>, submitted content from the '''<code>SubmittedContentController</code>''' pipeline, and <code>review_status</code>. Adding the same username again is idempotent.</div>

=== Calibration report: comparison UI ===

{| style="width:100%; max-width:980px; margin:0.8em auto; border-collapse:separate; border-spacing:10px;"
|-
| style="vertical-align:top; text-align:center; width:50%;" | '''Reference UI — Class comparison, stacked chart tab'''
| style="vertical-align:top; text-align:center; width:50%;" | '''Mockup chart layout; same report <code>GET</code> JSON from <code>ReviewMappingsController</code>'''
|-
| style="vertical-align:top; text-align:center;" | [[File:E2609-calibration-report-stacked.png|440px]]
| style="vertical-align:top; text-align:center;" | [[File:E2609-calibration-stacked-chart-improved-mockup.png|440px]]
|}

<div style="text-align:center; margin-top:0.35em;">'''Figure 2.''' Side by side: reference stacked-chart tab versus the intended layout. The mockup adds per-criterion axis labels, framing, legend, and full criterion text in tooltips in <code>CalibrationReview</code>. Same report JSON from '''<code>ReviewMappingsController</code>'''.</div>

[[File:E2609-calibration-report-rubric-detail.png|480px|center]]

<div style="text-align:center; margin-top:0.2em;">'''Figure 3.''' Reference UI — rubric detail: instructor review versus class summary and reviewer selections, using the comparison-report '''<code>GET</code>''' JSON from '''<code>ReviewMappingsController</code>'''.</div>

== Testing and Verification ==

=== Test Plan ===

==== Automated Testing — RSpec ====

* '''Request specs''' for '''<code>ReviewMappingsController</code>''' calibration: list, create participant/map, begin, instructor response for draft, submit, and error paths, destroy, and comparison-report '''<code>GET</code>'''. Co-locate spec files under <code>spec/requests/</code> with the route names in <code>config/routes.rb</code>.
* '''Request specs''' for the '''student review controller''': list reviews/maps; '''<code>for_calibration</code>''' rows include correct report link or comparison payload; responses match the logged-in student reviewer.
* Service specs for aggregation logic, for example <code>spec/services/calibration_per_item_summary_spec.rb</code> next to <code>CalibrationPerItemSummary</code>.
* '''Factories / fixtures''' for <code>for_calibration</code> maps, participants, and submitted responses as needed for the above.

==== Frontend Testing — Vitest ====

* <code>src/pages/Assignments/__tests__/CalibrationReview.test.tsx</code>
* <code>src/pages/Assignments/__tests__/CalibrationInstructorReview.test.tsx</code>
* <code>src/pages/Assignments/__tests__/calibrationReportNormalize.test.ts</code>
* <code>src/pages/Assignments/__tests__/calibrationSummary.test.ts</code>
* <code>src/pages/Assignments/__tests__/calibrationReportDemo.test.ts</code>

==== End-to-end — E2E ====

# Teaching staff: assignment editor → Calibration tab → calibration map list <code>GET</code> on <code>review_mappings</code> → table or empty state renders cleanly in the browser.
# Teaching staff: comparison report <code>GET</code> on '''<code>ReviewMappingsController</code>''' → “Class comparison (stacked)” and “Rubric detail” render; chart region populated when <code>per_item_summary</code> is non-empty.
# Teaching staff: '''Begin''', including opening the calibration review by direct URL if supported → draft save → submit → UI matches post-submit lock rules.
# Student: open student review list → calibration row shows '''link''' to comparison for instructor versus class view → student can see '''how their review compares''' to the instructor’s when that panel is implemented.

==== Manual UI Testing ====

# Login as instructor/TA.
# Open assignment editor → Calibration tab.
# Add a calibration participant by username.
# Click '''View report''' and verify stacked and rubric detail tabs.
# Enter/edit instructor review: save draft, submit, and confirm the form locks.
# Login as student calibrator: open student review list; for a calibration map, follow the report/comparison link and confirm scores or feedback align with expectations versus the instructor view.

== Future Scope ==

* Add an overall calibration score and trend visualization per participant.
* Provide additional endpoints for:
** calibration summary per map,
** detailed agreement breakdown per item across all rounds.
* Improve diagnostics, such as highlighting criteria with the largest score spread across reviewers.

== References ==

* [https://wiki.expertiza.ncsu.edu/index.php?title=Main_Page Expertiza wiki main page]
* Front-end pull request: [https://github.com/expertiza/reimplementation-front-end/pull/164 expertiza/reimplementation-front-end#164]
* Back-end pull request: [https://github.com/expertiza/reimplementation-back-end/pull/323 expertiza/reimplementation-back-end#323]

== Team ==

* Mentor: Dr. Ed Gehringer
* Team members: Xiangjun Mi, Rujuta Palimkar, Emma Hassler

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-14T21:45:09Z

Admin: /* Purpose */

== Purpose ==
Expertiza currently authenticates users with its own login page, implemented by the Expertiza application. Expertiza has been used at many campuses, however, and each has their own SSO (single signon) protocol that students and staff use to log into other applications. It is more secure for applications to use the standard approach at sites where they are in use, and it also frees Expertiza from managing passwords, and thus removes the risk of compromise. By integrating [https://openid.net/developers/how-connect-works/ OIDC] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== Requirements ==
=== Authentication Flow ===
Users select a provider from a dropdown on the login page that redirects them to the school's OIDC provider, authenticates them, and redirects back to the application with a valid session. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown. On provider selection, the frontend posts to the backend, which returns an authorization URL. After the user completes the OIDC flow, the IdP redirects back to the frontend callback, which posts the authorization code and state to the backend to complete login.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Linking ===
Match the authenticated user's email from the ID token to an existing local account. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, an error is returned.

=== Configuration ===
OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>). Client credentials (client ID, client secret) are stored in environment variables and injected via ERB. Providers that support OIDC discovery have their endpoints and JWKS keys fetched automatically. The system supports multiple OIDC provider configurations simultaneously. The configuration is validated at boot via an initializer, surfacing missing values immediately on deploy rather than at login time.

=== State Management ===
OIDC state, nonce, and PKCE code verifier are stored server-side in an <code>auth_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and deleted after use. This table is named generically to support future federated auth protocols such as SAML. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted.

=== Error Handling ===
Gracefully handle failures such as no local account matching the authenticated email, expired or invalid state parameters, token exchange errors, ID token verification errors, and user-denied consent at the IdP.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE.

=== Testing ===
Backend and frontend are tested independently. Backend request specs use WebMock to stub the identity provider's discovery, token, and JWKS endpoints, allowing the full controller logic (state management, token exchange, ID token verification, user matching) to be tested without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC Provider-2026-04-06-223511.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):''' On page load, the <code>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. If the request fails or returns empty, the component renders nothing and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema ===

The <code>auth_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.

{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}

No foreign keys or associations to other tables. This table is intentionally generic to support future federated auth protocols such as SAML.

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs and Additions (Prototype and subject to change) ==

=== Backend (Rails) ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Controller with providers, client_select, and callback actions
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/auth_request.rb app/models/auth_request.rb] — ActiveRecord model for state/nonce/PKCE storage
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_auth_requests.rb db/migrate/*_create_auth_requests.rb] — Migration for auth_requests table

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/auth_request_spec.rb spec/models/auth_request_spec.rb] — State uniqueness, expiry scope, cleanup of stale rows
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked
* '''TODO''' Returns empty array when no providers configured

'''POST /auth/client-select'''
* '''TODO''' Returns authorization URL with expected query parameters (client_id, redirect_uri, scope, state, nonce, code_challenge)
* '''TODO''' Creates an auth_requests row
* '''TODO''' Returns 404 for unknown provider

'''POST /auth/callback — Happy Path'''
* '''TODO''' Exchanges valid code and state for a session JWT with same payload structure as password login
* '''TODO''' Deletes the auth_requests row after successful use

'''POST /auth/callback — CSRF Protection (State Validation)'''
* '''TODO''' Rejects unknown state (422)
* '''TODO''' Rejects expired state older than 5 minutes (422)
* '''TODO''' Rejects already-consumed state / replay (422)

'''POST /auth/callback — Replay Protection (Nonce Validation)'''
* '''TODO''' Rejects ID token with mismatched nonce

'''POST /auth/callback — Token Verification'''
* '''TODO''' Rejects ID token with invalid signature
* '''TODO''' Rejects ID token with mismatched issuer
* '''TODO''' Rejects ID token with mismatched audience (client_id)

'''POST /auth/callback — User Matching'''
* '''TODO''' Returns 404 when no local user matches the email
* '''TODO''' Matches correct user when multiple users exist

'''POST /auth/callback — PKCE'''
* '''TODO''' Sends code_verifier to the token endpoint during code exchange

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* '''TODO''' Renders dropdown with providers when GET /auth/providers returns a non-empty list
* '''TODO''' Renders nothing when GET /auth/providers returns an empty array
* '''TODO''' Renders nothing when GET /auth/providers fails
* '''TODO''' Calls POST /auth/client-select with selected provider id on dropdown change
* '''TODO''' Redirects browser to returned authorization URL on successful client-select
* '''TODO''' Does not redirect when client-select fails
* '''TODO''' Existing login form remains visible and functional alongside the dropdown

'''OidcCallback Component'''
* '''TODO''' Posts code and state to POST /auth/callback on mount
* '''TODO''' Stores session JWT and dispatches auth state on success
* '''TODO''' Redirects to dashboard on successful login
* '''TODO''' Displays error alert and redirects to login on backend failure (e.g. no matching account)
* '''TODO''' Displays error and redirects to login when IdP returns an error parameter (e.g. user denied consent) without calling the backend
* '''TODO''' Redirects to login when code or state query parameters are missing
* '''TODO''' Shows "Completing login..." message while request is in flight

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
GET /auth/callback → React OidcCallback component

== Development Stories (Planning) ==

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML at boot, exposing methods to list providers and look up a provider by id.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>, <code>scopes</code>.
* Raise a clear boot-time error if required values are missing via <code>config/initializers/oidc.rb</code>.
* Add unit tests for config loading, validation, and missing key detection.

=== Story 2: Backend — Auth Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, and PKCE values, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>auth_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, and <code>created_at</code>.
* Create the <code>AuthRequest</code> model with a uniqueness validation on state, an <code>expired</code> scope, and a <code>cleanup_expired</code> class method.
* Add a rake task or scheduled job to periodically clean up expired rows.
* Add unit tests for creation, lookup, expiry, and deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format and a case with multiple providers.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept a <code>provider</code> param and look up the provider config.
* Generate cryptographically random state, nonce, and PKCE code verifier/challenge.
* Insert a row into <code>auth_requests</code>.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Add request specs covering the happy path, unknown provider, and that the auth_requests row is created.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept <code>code</code> and <code>state</code> params.
* Look up and delete the matching <code>auth_requests</code> row. Reject if not found or expired.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, client_id, and nonce.
* Extract the email claim and match to an existing local user.
* On match: issue a session JWT using the same payload structure as <code>AuthenticationController#login</code> and return it with the user profile.
* On no match: return a 404 error indicating no local account was found.
* Handle <code>ActiveRecord::RecordNotFound</code> (invalid/expired state) and <code>InvalidToken</code> (verification failure) exceptions.
* Add request specs covering the happy path, expired state, invalid state, and no matching user.

=== Story 6: Frontend — Provider Dropdown on Login Page ===
'''As a''' user, '''I want''' to see a provider dropdown on the login page, '''so that''' I can authenticate with my school credentials.

'''Acceptance Criteria:'''
* Create an <code>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* If the request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the redirect and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC backend, '''so that''' I have confidence the endpoints and models work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Mock the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover error scenarios: expired state, invalid state, unknown provider, no matching user, invalid ID token.
* Add model specs for <code>AuthRequest</code> covering creation, uniqueness, expiry scope, and cleanup.
* Add unit tests for <code>OidcConfig</code> covering loading, validation, and missing key detection.
* Verify the existing <code>AuthenticationController#login</code> is unaffected.

=== Story 10: Frontend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Add component tests for <code>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed response, triggers <code>POST /auth/client-select</code> on selection.
* Add component tests for <code>OidcCallback</code>: posts code and state to backend on mount, redirects to dashboard on success, displays error and redirects to login on failure, handles IdP error parameter without calling the backend.
* Mock axios calls to avoid external requests in tests.
* Verify the existing login page renders and functions correctly with and without the <code>OidcLogin</code> component.

=== Additional Refactoring Stories ===

==== Story 11: Backend — Unified Session Response ====
'''As a''' developer, '''I want''' the session object returned to the frontend clearly defined and reusable by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic from <code>AuthenticationController#login</code> and <code>OidcLoginController#callback</code> into a shared method on the <code>User</code> model (e.g. <code>user.generate_jwt</code>).
* Define a consistent response structure (e.g. <code>{ token, user: { id, name, full_name, role, institution_id } }</code>) and use it in both controllers.
* Update the existing password login endpoint to use the shared method without changing its external response shape.
* Add or update request specs for both login endpoints to assert the response structure matches.

==== Story 12: Frontend — Externalize Hardcoded Configuration ====
'''As a''' developer, '''I want''' all hardcoded values moved to isolated configuration files, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the frontend API base URL to an environment variable or shared config file (e.g. <code>.env</code> with <code>REACT_APP_API_URL</code>) and replace all hardcoded references.
* Ensure all existing tests continue to pass after the extraction.

==== Story 13: Backend — Swagger Documentation for Provider Endpoints ====
'''As a''' developer, '''I want''' the OIDC provider endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (including success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

==== Story 14: Backend — Cleanup Expired Auth Requests ====
'''As a''' developer, '''I want''' expired auth request rows cleaned up automatically, '''so that''' the table does not grow unbounded from abandoned login attempts.

'''Acceptance Criteria:'''
* Add a recurring ActiveJob solid_queue <code>auth_requests:cleanup</code> that calls <code>AuthRequest.cleanup_expired</code>.
* The task deletes all rows with <code>created_at</code> older than 5 minutes.
* Schedule the task to run periodically (e.g. 24 hours).
* Add a test verifying that only expired rows are deleted.

== Demo ==

todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-14T21:38:55Z

Admin: /* Purpose */

== Purpose ==
By integrating OIDC login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== Requirements ==
=== Authentication Flow ===
Users select a provider from a dropdown on the login page that redirects them to the school's OIDC provider, authenticates them, and redirects back to the application with a valid session. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown. On provider selection, the frontend posts to the backend, which returns an authorization URL. After the user completes the OIDC flow, the IdP redirects back to the frontend callback, which posts the authorization code and state to the backend to complete login.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Linking ===
Match the authenticated user's email from the ID token to an existing local account. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, an error is returned.

=== Configuration ===
OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>). Client credentials (client ID, client secret) are stored in environment variables and injected via ERB. Providers that support OIDC discovery have their endpoints and JWKS keys fetched automatically. The system supports multiple OIDC provider configurations simultaneously. The configuration is validated at boot via an initializer, surfacing missing values immediately on deploy rather than at login time.

=== State Management ===
OIDC state, nonce, and PKCE code verifier are stored server-side in an <code>auth_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and deleted after use. This table is named generically to support future federated auth protocols such as SAML. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted.

=== Error Handling ===
Gracefully handle failures such as no local account matching the authenticated email, expired or invalid state parameters, token exchange errors, ID token verification errors, and user-denied consent at the IdP.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE.

=== Testing ===
Backend and frontend are tested independently. Backend request specs use WebMock to stub the identity provider's discovery, token, and JWKS endpoints, allowing the full controller logic (state management, token exchange, ID token verification, user matching) to be tested without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC Provider-2026-04-06-223511.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):''' On page load, the <code>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. If the request fails or returns empty, the component renders nothing and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema ===

The <code>auth_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.

{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}

No foreign keys or associations to other tables. This table is intentionally generic to support future federated auth protocols such as SAML.

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs and Additions (Prototype and subject to change) ==

=== Backend (Rails) ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Controller with providers, client_select, and callback actions
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/auth_request.rb app/models/auth_request.rb] — ActiveRecord model for state/nonce/PKCE storage
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_auth_requests.rb db/migrate/*_create_auth_requests.rb] — Migration for auth_requests table

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/auth_request_spec.rb spec/models/auth_request_spec.rb] — State uniqueness, expiry scope, cleanup of stale rows
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked
* '''TODO''' Returns empty array when no providers configured

'''POST /auth/client-select'''
* '''TODO''' Returns authorization URL with expected query parameters (client_id, redirect_uri, scope, state, nonce, code_challenge)
* '''TODO''' Creates an auth_requests row
* '''TODO''' Returns 404 for unknown provider

'''POST /auth/callback — Happy Path'''
* '''TODO''' Exchanges valid code and state for a session JWT with same payload structure as password login
* '''TODO''' Deletes the auth_requests row after successful use

'''POST /auth/callback — CSRF Protection (State Validation)'''
* '''TODO''' Rejects unknown state (422)
* '''TODO''' Rejects expired state older than 5 minutes (422)
* '''TODO''' Rejects already-consumed state / replay (422)

'''POST /auth/callback — Replay Protection (Nonce Validation)'''
* '''TODO''' Rejects ID token with mismatched nonce

'''POST /auth/callback — Token Verification'''
* '''TODO''' Rejects ID token with invalid signature
* '''TODO''' Rejects ID token with mismatched issuer
* '''TODO''' Rejects ID token with mismatched audience (client_id)

'''POST /auth/callback — User Matching'''
* '''TODO''' Returns 404 when no local user matches the email
* '''TODO''' Matches correct user when multiple users exist

'''POST /auth/callback — PKCE'''
* '''TODO''' Sends code_verifier to the token endpoint during code exchange

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* '''TODO''' Renders dropdown with providers when GET /auth/providers returns a non-empty list
* '''TODO''' Renders nothing when GET /auth/providers returns an empty array
* '''TODO''' Renders nothing when GET /auth/providers fails
* '''TODO''' Calls POST /auth/client-select with selected provider id on dropdown change
* '''TODO''' Redirects browser to returned authorization URL on successful client-select
* '''TODO''' Does not redirect when client-select fails
* '''TODO''' Existing login form remains visible and functional alongside the dropdown

'''OidcCallback Component'''
* '''TODO''' Posts code and state to POST /auth/callback on mount
* '''TODO''' Stores session JWT and dispatches auth state on success
* '''TODO''' Redirects to dashboard on successful login
* '''TODO''' Displays error alert and redirects to login on backend failure (e.g. no matching account)
* '''TODO''' Displays error and redirects to login when IdP returns an error parameter (e.g. user denied consent) without calling the backend
* '''TODO''' Redirects to login when code or state query parameters are missing
* '''TODO''' Shows "Completing login..." message while request is in flight

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
GET /auth/callback → React OidcCallback component

== Development Stories (Planning) ==

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML at boot, exposing methods to list providers and look up a provider by id.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>, <code>scopes</code>.
* Raise a clear boot-time error if required values are missing via <code>config/initializers/oidc.rb</code>.
* Add unit tests for config loading, validation, and missing key detection.

=== Story 2: Backend — Auth Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, and PKCE values, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>auth_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, and <code>created_at</code>.
* Create the <code>AuthRequest</code> model with a uniqueness validation on state, an <code>expired</code> scope, and a <code>cleanup_expired</code> class method.
* Add a rake task or scheduled job to periodically clean up expired rows.
* Add unit tests for creation, lookup, expiry, and deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format and a case with multiple providers.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept a <code>provider</code> param and look up the provider config.
* Generate cryptographically random state, nonce, and PKCE code verifier/challenge.
* Insert a row into <code>auth_requests</code>.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Add request specs covering the happy path, unknown provider, and that the auth_requests row is created.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept <code>code</code> and <code>state</code> params.
* Look up and delete the matching <code>auth_requests</code> row. Reject if not found or expired.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, client_id, and nonce.
* Extract the email claim and match to an existing local user.
* On match: issue a session JWT using the same payload structure as <code>AuthenticationController#login</code> and return it with the user profile.
* On no match: return a 404 error indicating no local account was found.
* Handle <code>ActiveRecord::RecordNotFound</code> (invalid/expired state) and <code>InvalidToken</code> (verification failure) exceptions.
* Add request specs covering the happy path, expired state, invalid state, and no matching user.

=== Story 6: Frontend — Provider Dropdown on Login Page ===
'''As a''' user, '''I want''' to see a provider dropdown on the login page, '''so that''' I can authenticate with my school credentials.

'''Acceptance Criteria:'''
* Create an <code>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* If the request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the redirect and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC backend, '''so that''' I have confidence the endpoints and models work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Mock the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover error scenarios: expired state, invalid state, unknown provider, no matching user, invalid ID token.
* Add model specs for <code>AuthRequest</code> covering creation, uniqueness, expiry scope, and cleanup.
* Add unit tests for <code>OidcConfig</code> covering loading, validation, and missing key detection.
* Verify the existing <code>AuthenticationController#login</code> is unaffected.

=== Story 10: Frontend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Add component tests for <code>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed response, triggers <code>POST /auth/client-select</code> on selection.
* Add component tests for <code>OidcCallback</code>: posts code and state to backend on mount, redirects to dashboard on success, displays error and redirects to login on failure, handles IdP error parameter without calling the backend.
* Mock axios calls to avoid external requests in tests.
* Verify the existing login page renders and functions correctly with and without the <code>OidcLogin</code> component.

=== Additional Refactoring Stories ===

==== Story 11: Backend — Unified Session Response ====
'''As a''' developer, '''I want''' the session object returned to the frontend clearly defined and reusable by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic from <code>AuthenticationController#login</code> and <code>OidcLoginController#callback</code> into a shared method on the <code>User</code> model (e.g. <code>user.generate_jwt</code>).
* Define a consistent response structure (e.g. <code>{ token, user: { id, name, full_name, role, institution_id } }</code>) and use it in both controllers.
* Update the existing password login endpoint to use the shared method without changing its external response shape.
* Add or update request specs for both login endpoints to assert the response structure matches.

==== Story 12: Frontend — Externalize Hardcoded Configuration ====
'''As a''' developer, '''I want''' all hardcoded values moved to isolated configuration files, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the frontend API base URL to an environment variable or shared config file (e.g. <code>.env</code> with <code>REACT_APP_API_URL</code>) and replace all hardcoded references.
* Ensure all existing tests continue to pass after the extraction.

==== Story 13: Backend — Swagger Documentation for Provider Endpoints ====
'''As a''' developer, '''I want''' the OIDC provider endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (including success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

==== Story 14: Backend — Cleanup Expired Auth Requests ====
'''As a''' developer, '''I want''' expired auth request rows cleaned up automatically, '''so that''' the table does not grow unbounded from abandoned login attempts.

'''Acceptance Criteria:'''
* Add a recurring ActiveJob solid_queue <code>auth_requests:cleanup</code> that calls <code>AuthRequest.cleanup_expired</code>.
* The task deletes all rows with <code>created_at</code> older than 5 minutes.
* Schedule the task to run periodically (e.g. 24 hours).
* Add a test verifying that only expired rows are deleted.

== Demo ==

todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-14T21:38:30Z

Admin:

== Purpose ==
By integrating [[https://openid.net/developers/how-connect-works/|OIDC]] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== Requirements ==
=== Authentication Flow ===
Users select a provider from a dropdown on the login page that redirects them to the school's OIDC provider, authenticates them, and redirects back to the application with a valid session. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown. On provider selection, the frontend posts to the backend, which returns an authorization URL. After the user completes the OIDC flow, the IdP redirects back to the frontend callback, which posts the authorization code and state to the backend to complete login.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Linking ===
Match the authenticated user's email from the ID token to an existing local account. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, an error is returned.

=== Configuration ===
OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>). Client credentials (client ID, client secret) are stored in environment variables and injected via ERB. Providers that support OIDC discovery have their endpoints and JWKS keys fetched automatically. The system supports multiple OIDC provider configurations simultaneously. The configuration is validated at boot via an initializer, surfacing missing values immediately on deploy rather than at login time.

=== State Management ===
OIDC state, nonce, and PKCE code verifier are stored server-side in an <code>auth_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and deleted after use. This table is named generically to support future federated auth protocols such as SAML. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted.

=== Error Handling ===
Gracefully handle failures such as no local account matching the authenticated email, expired or invalid state parameters, token exchange errors, ID token verification errors, and user-denied consent at the IdP.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE.

=== Testing ===
Backend and frontend are tested independently. Backend request specs use WebMock to stub the identity provider's discovery, token, and JWKS endpoints, allowing the full controller logic (state management, token exchange, ID token verification, user matching) to be tested without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC Provider-2026-04-06-223511.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):''' On page load, the <code>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. If the request fails or returns empty, the component renders nothing and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema ===

The <code>auth_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.

{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}

No foreign keys or associations to other tables. This table is intentionally generic to support future federated auth protocols such as SAML.

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs and Additions (Prototype and subject to change) ==

=== Backend (Rails) ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Controller with providers, client_select, and callback actions
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/auth_request.rb app/models/auth_request.rb] — ActiveRecord model for state/nonce/PKCE storage
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_auth_requests.rb db/migrate/*_create_auth_requests.rb] — Migration for auth_requests table

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/auth_request_spec.rb spec/models/auth_request_spec.rb] — State uniqueness, expiry scope, cleanup of stale rows
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked
* '''TODO''' Returns empty array when no providers configured

'''POST /auth/client-select'''
* '''TODO''' Returns authorization URL with expected query parameters (client_id, redirect_uri, scope, state, nonce, code_challenge)
* '''TODO''' Creates an auth_requests row
* '''TODO''' Returns 404 for unknown provider

'''POST /auth/callback — Happy Path'''
* '''TODO''' Exchanges valid code and state for a session JWT with same payload structure as password login
* '''TODO''' Deletes the auth_requests row after successful use

'''POST /auth/callback — CSRF Protection (State Validation)'''
* '''TODO''' Rejects unknown state (422)
* '''TODO''' Rejects expired state older than 5 minutes (422)
* '''TODO''' Rejects already-consumed state / replay (422)

'''POST /auth/callback — Replay Protection (Nonce Validation)'''
* '''TODO''' Rejects ID token with mismatched nonce

'''POST /auth/callback — Token Verification'''
* '''TODO''' Rejects ID token with invalid signature
* '''TODO''' Rejects ID token with mismatched issuer
* '''TODO''' Rejects ID token with mismatched audience (client_id)

'''POST /auth/callback — User Matching'''
* '''TODO''' Returns 404 when no local user matches the email
* '''TODO''' Matches correct user when multiple users exist

'''POST /auth/callback — PKCE'''
* '''TODO''' Sends code_verifier to the token endpoint during code exchange

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* '''TODO''' Renders dropdown with providers when GET /auth/providers returns a non-empty list
* '''TODO''' Renders nothing when GET /auth/providers returns an empty array
* '''TODO''' Renders nothing when GET /auth/providers fails
* '''TODO''' Calls POST /auth/client-select with selected provider id on dropdown change
* '''TODO''' Redirects browser to returned authorization URL on successful client-select
* '''TODO''' Does not redirect when client-select fails
* '''TODO''' Existing login form remains visible and functional alongside the dropdown

'''OidcCallback Component'''
* '''TODO''' Posts code and state to POST /auth/callback on mount
* '''TODO''' Stores session JWT and dispatches auth state on success
* '''TODO''' Redirects to dashboard on successful login
* '''TODO''' Displays error alert and redirects to login on backend failure (e.g. no matching account)
* '''TODO''' Displays error and redirects to login when IdP returns an error parameter (e.g. user denied consent) without calling the backend
* '''TODO''' Redirects to login when code or state query parameters are missing
* '''TODO''' Shows "Completing login..." message while request is in flight

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
GET /auth/callback → React OidcCallback component

== Development Stories (Planning) ==

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML at boot, exposing methods to list providers and look up a provider by id.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>, <code>scopes</code>.
* Raise a clear boot-time error if required values are missing via <code>config/initializers/oidc.rb</code>.
* Add unit tests for config loading, validation, and missing key detection.

=== Story 2: Backend — Auth Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, and PKCE values, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>auth_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, and <code>created_at</code>.
* Create the <code>AuthRequest</code> model with a uniqueness validation on state, an <code>expired</code> scope, and a <code>cleanup_expired</code> class method.
* Add a rake task or scheduled job to periodically clean up expired rows.
* Add unit tests for creation, lookup, expiry, and deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format and a case with multiple providers.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept a <code>provider</code> param and look up the provider config.
* Generate cryptographically random state, nonce, and PKCE code verifier/challenge.
* Insert a row into <code>auth_requests</code>.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Add request specs covering the happy path, unknown provider, and that the auth_requests row is created.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept <code>code</code> and <code>state</code> params.
* Look up and delete the matching <code>auth_requests</code> row. Reject if not found or expired.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, client_id, and nonce.
* Extract the email claim and match to an existing local user.
* On match: issue a session JWT using the same payload structure as <code>AuthenticationController#login</code> and return it with the user profile.
* On no match: return a 404 error indicating no local account was found.
* Handle <code>ActiveRecord::RecordNotFound</code> (invalid/expired state) and <code>InvalidToken</code> (verification failure) exceptions.
* Add request specs covering the happy path, expired state, invalid state, and no matching user.

=== Story 6: Frontend — Provider Dropdown on Login Page ===
'''As a''' user, '''I want''' to see a provider dropdown on the login page, '''so that''' I can authenticate with my school credentials.

'''Acceptance Criteria:'''
* Create an <code>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* If the request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the redirect and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC backend, '''so that''' I have confidence the endpoints and models work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Mock the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover error scenarios: expired state, invalid state, unknown provider, no matching user, invalid ID token.
* Add model specs for <code>AuthRequest</code> covering creation, uniqueness, expiry scope, and cleanup.
* Add unit tests for <code>OidcConfig</code> covering loading, validation, and missing key detection.
* Verify the existing <code>AuthenticationController#login</code> is unaffected.

=== Story 10: Frontend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Add component tests for <code>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed response, triggers <code>POST /auth/client-select</code> on selection.
* Add component tests for <code>OidcCallback</code>: posts code and state to backend on mount, redirects to dashboard on success, displays error and redirects to login on failure, handles IdP error parameter without calling the backend.
* Mock axios calls to avoid external requests in tests.
* Verify the existing login page renders and functions correctly with and without the <code>OidcLogin</code> component.

=== Additional Refactoring Stories ===

==== Story 11: Backend — Unified Session Response ====
'''As a''' developer, '''I want''' the session object returned to the frontend clearly defined and reusable by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic from <code>AuthenticationController#login</code> and <code>OidcLoginController#callback</code> into a shared method on the <code>User</code> model (e.g. <code>user.generate_jwt</code>).
* Define a consistent response structure (e.g. <code>{ token, user: { id, name, full_name, role, institution_id } }</code>) and use it in both controllers.
* Update the existing password login endpoint to use the shared method without changing its external response shape.
* Add or update request specs for both login endpoints to assert the response structure matches.

==== Story 12: Frontend — Externalize Hardcoded Configuration ====
'''As a''' developer, '''I want''' all hardcoded values moved to isolated configuration files, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the frontend API base URL to an environment variable or shared config file (e.g. <code>.env</code> with <code>REACT_APP_API_URL</code>) and replace all hardcoded references.
* Ensure all existing tests continue to pass after the extraction.

==== Story 13: Backend — Swagger Documentation for Provider Endpoints ====
'''As a''' developer, '''I want''' the OIDC provider endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (including success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

==== Story 14: Backend — Cleanup Expired Auth Requests ====
'''As a''' developer, '''I want''' expired auth request rows cleaned up automatically, '''so that''' the table does not grow unbounded from abandoned login attempts.

'''Acceptance Criteria:'''
* Add a recurring ActiveJob solid_queue <code>auth_requests:cleanup</code> that calls <code>AuthRequest.cleanup_expired</code>.
* The task deletes all rows with <code>created_at</code> older than 5 minutes.
* Schedule the task to run periodically (e.g. 24 hours).
* Add a test verifying that only expired rows are deleted.

== Demo ==

todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2618. Support OIDC Logins

2026-04-14T21:38:04Z

Admin: /* Purpose */

== Purpose ==
By integrating [[OIDC|https://openid.net/developers/how-connect-works/]] login, users can authenticate using their existing university credentials, providing a familiar and streamlined login experience. Traditional username and password login will continue to be supported alongside OIDC, allowing users to choose their preferred authentication method.

== Requirements ==
=== Authentication Flow ===
Users select a provider from a dropdown on the login page that redirects them to the school's OIDC provider, authenticates them, and redirects back to the application with a valid session. The frontend fetches available providers from the backend via <code>GET /auth/providers</code> and renders them dynamically in a dropdown. On provider selection, the frontend posts to the backend, which returns an authorization URL. After the user completes the OIDC flow, the IdP redirects back to the frontend callback, which posts the authorization code and state to the backend to complete login.

=== Session Management ===
Issue and maintain a local application session (JWT) after successful OIDC authentication, using the same <code>JsonWebToken</code> class and payload structure as the existing password login. Refresh token grant flow will not be considered at this time (since session is managed by the application).

=== Account Linking ===
Match the authenticated user's email from the ID token to an existing local account. No dedicated account linking table or just-in-time account creation will be built at this time. If no matching local account is found, an error is returned.

=== Configuration ===
OIDC provider configurations (display name, scopes, endpoints) are defined in a YAML config file (<code>config/oidc_providers.yml</code>). Client credentials (client ID, client secret) are stored in environment variables and injected via ERB. Providers that support OIDC discovery have their endpoints and JWKS keys fetched automatically. The system supports multiple OIDC provider configurations simultaneously. The configuration is validated at boot via an initializer, surfacing missing values immediately on deploy rather than at login time.

=== State Management ===
OIDC state, nonce, and PKCE code verifier are stored server-side in an <code>auth_requests</code> database table (via ActiveRecord) rather than in session cookies. This avoids cross-origin cookie issues between the separate frontend and backend. Rows are expired after 5 minutes and deleted after use. This table is named generically to support future federated auth protocols such as SAML. Note that many OIDC libraries (including <code>omniauth_openid_connect</code>) use cookies to track state; due to SameSite restrictions on cross-origin requests, this approach leads to instability with a separated frontend and backend and should be avoided.

=== Logout ===
Logout will not be impacted.

=== Error Handling ===
Gracefully handle failures such as no local account matching the authenticated email, expired or invalid state parameters, token exchange errors, ID token verification errors, and user-denied consent at the IdP.

=== Security ===
Use the Authorization Code flow with the <code>openid_connect</code> Ruby gem (by nov). Validate the ID token signature and claims via JWKS keys from the provider's discovery document. Enforce a <code>state</code> parameter to prevent CSRF and a <code>nonce</code> to prevent replay attacks. PKCE (code verifier and code challenge) is always included in the authorization request and token exchange; providers that support it will enforce it, and providers that do not will ignore the extra parameters. The backend is a confidential client and always authenticates with both client secret and PKCE.

=== Testing ===
Backend and frontend are tested independently. Backend request specs use WebMock to stub the identity provider's discovery, token, and JWKS endpoints, allowing the full controller logic (state management, token exchange, ID token verification, user matching) to be tested without external dependencies. Frontend component tests mock axios calls to verify rendering, dropdown behavior, callback handling, and error display. End-to-end testing across both systems with a live identity provider is not planned at this time, as it would require standing up a mock IdP server (e.g. Keycloak or mock-oauth2-server), which is beyond the scope of the existing test infrastructure. The full OIDC login flow will be manually verified against Google's OIDC provider in a local development environment and demonstrated as needed.

== Design ==

[[File:OIDC Provider-2026-04-06-223511.png|1000px]]

=== Backend ===
* '''Boot (Step 0):''' Load provider configurations from <code>config/oidc_providers.yml</code> with secrets injected from environment variables via ERB. Each provider entry defines a display name, scopes, issuer, client credentials, and redirect URI. The <code>OidcConfig</code> class validates that all required keys are present at boot via <code>config/initializers/oidc.rb</code>. For providers with <code>discovery: true</code>, the <code>.well-known/openid-configuration</code> document is fetched using the <code>openid_connect</code> gem to resolve the authorization endpoint, token endpoint, userinfo endpoint, and JWKS keys. Discovery results are not aggressively cached to allow for key rotation; on signature verification failure, keys are re-fetched and verification is retried once.
* '''Provider List (Step 1):''' Expose a <code>GET /auth/providers</code> endpoint that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>. No secrets or endpoint details are included in this response.
* '''Client Select (Step 2):''' Expose a <code>POST /auth/client-select</code> endpoint that accepts a provider id. Generate a cryptographically random state and nonce via <code>SecureRandom.hex(32)</code>, and a PKCE code verifier via <code>SecureRandom.urlsafe_base64(64)</code> with a SHA256 code challenge. Insert a row into the <code>auth_requests</code> table containing the state, nonce, code verifier, provider id, and creation timestamp. Construct the authorization URL using the <code>openid_connect</code> gem's <code>authorization_uri</code> method and return it to the frontend.
* '''Callback (Step 4):''' Expose a <code>POST /auth/callback</code> endpoint (and a temporary <code>GET</code> for direct IdP redirect during backend-only testing) that accepts the authorization code and state. Look up the matching <code>auth_requests</code> row by state, rejecting the request if no row is found or if the row is older than 5 minutes. Delete the row to prevent reuse. Using the <code>openid_connect</code> gem, exchange the authorization code for tokens via <code>access_token!</code> with the stored code verifier. Decode the ID token using <code>OpenIDConnect::ResponseObject::IdToken.decode</code> against the provider's JWKS keys, and verify the issuer, client_id, and nonce via <code>id_token.verify!</code>. Extract the user's email from the ID token claims and look up a matching local user. If a match is found, issue a session JWT using the same <code>JsonWebToken.encode</code> method and payload structure as the existing <code>AuthenticationController#login</code> action. If no match is found, return a 404 error indicating no local account exists for that email.

=== Frontend ===
* '''Login Page (Step 1):''' On page load, the <code>OidcLogin</code> component calls <code>GET /auth/providers</code> and renders a dropdown (<code>Form.Select</code>) for each configured provider below the existing username and password form. If the request fails or returns empty, the component renders nothing and the standard login form remains available and unaffected. No loading state is shown to avoid visual disruption when no providers are configured.
* '''Initiate Login (Step 2):''' When the user selects a provider from the dropdown, <code>POST</code> to <code>/auth/client-select</code> with the selected provider id. On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>. The user then authenticates with the identity provider and is redirected back to the frontend callback route.
* '''Callback (Step 4):''' The <code>OidcCallback</code> page component handles the redirect back from the identity provider at <code>/auth/callback</code>. It extracts the authorization code and state from the query parameters and <code>POST</code>s them to <code>/auth/callback</code>. If the query parameters contain an <code>error</code> parameter instead of a code (e.g. the user denied consent), the error is displayed without calling the backend and the user is redirected to the login page.
* '''Login Complete (Step 5):''' On a successful callback response, store the session JWT via <code>setAuthToken</code>, update the Redux auth state via <code>authenticationActions.setAuthentication</code>, persist the session to localStorage, and redirect the user to the dashboard. This mirrors the existing password login flow exactly. On failure, display an error alert and redirect to the login page.
* The existing username and password login flow remains unchanged and fully functional.

=== Design Patterns ===
The implementation uses the '''Strategy pattern''' for provider configuration. Each OIDC provider is defined declaratively in YAML with its own credentials, scopes, and endpoints, while the controller logic remains provider-agnostic. Adding a new identity provider requires only a new configuration block and environment variables, with no code changes.

=== Schema ===

The <code>auth_requests</code> table stores temporary OIDC login state. Each row represents a single in-progress login attempt and is deleted after use or expiry.

{| class="wikitable"
! Column !! Type !! Constraints !! Purpose
|-
| <code>id</code> || bigint || primary key || Row identifier
|-
| <code>state</code> || string || unique, indexed || CSRF protection; used to look up the request on callback
|-
| <code>nonce</code> || string || not null || Replay attack prevention; verified against the ID token claim
|-
| <code>code_verifier</code> || string || not null || PKCE secret; sent to the token endpoint to prove the same party initiated the flow
|-
| <code>provider</code> || string || not null || Which OIDC provider config to use on callback
|-
| <code>created_at</code> || datetime || not null || Used to expire rows older than 5 minutes
|}

No foreign keys or associations to other tables. This table is intentionally generic to support future federated auth protocols such as SAML.

== Library Choice ==

The <code>openid_connect</code> gem (by nov, [https://github.com/nov/openid_connect github.com/nov/openid_connect]) was chosen over <code>omniauth_openid_connect</code> for the following reasons:

* '''No cookie/session dependency:''' <code>omniauth_openid_connect</code> stores state and nonce in the server-side session via cookies. With a separate frontend and backend on different origins, session cookies are not reliably shared due to SameSite restrictions. Using <code>openid_connect</code> directly allows state management via the database instead.
* '''Explicit control:''' The gem provides building blocks (discovery, client construction, token exchange, ID token verification) without middleware magic. Each step in the OIDC flow is visible in the controller code.
* '''Lightweight:''' No OmniAuth middleware stack or Rack integration required. The gem handles the protocol; the application handles routing and state.
* '''Actively maintained:''' The gem is OpenID Foundation certified and used by 2,700+ projects on GitHub.

The tradeoff is approximately 10 additional lines of code for state management (generating and storing state/nonce/PKCE in the <code>auth_requests</code> table), which is minimal compared to the complexity of debugging cross-origin cookie issues.

== File Diffs and Additions (Prototype and subject to change) ==

=== Backend (Rails) ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/controllers/oidc_login_controller.rb app/controllers/oidc_login_controller.rb] — Controller with providers, client_select, and callback actions
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/oidc_config.rb app/models/oidc_config.rb] — YAML config loader with validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/app/models/auth_request.rb app/models/auth_request.rb] — ActiveRecord model for state/nonce/PKCE storage
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/oidc_providers.yml config/oidc_providers.yml] — Provider configuration (ERB for env var injection)
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/config/initializers/oidc.rb config/initializers/oidc.rb] — Boot-time config validation
[https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/db/migrate/20260407003623_create_auth_requests.rb db/migrate/*_create_auth_requests.rb] — Migration for auth_requests table

=== Backend (RSpec) Tests ===
([https://github.com/johnmweisz/reimplementation-back-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/oidc_config_spec.rb spec/models/oidc_config_spec.rb] — Config loading, validation, missing keys, public_list secrets exclusion, provider lookup
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/models/auth_request_spec.rb spec/models/auth_request_spec.rb] — State uniqueness, expiry scope, cleanup of stale rows
'''TODO''' [https://github.com/johnmweisz/reimplementation-back-end/blob/2618-oidc-login/spec/requests/oidc_login_spec.rb spec/requests/oidc_login_spec.rb] — Endpoint tests covering:

'''GET /auth/providers'''
* Returns provider list with id and name only, no secrets leaked
* '''TODO''' Returns empty array when no providers configured

'''POST /auth/client-select'''
* '''TODO''' Returns authorization URL with expected query parameters (client_id, redirect_uri, scope, state, nonce, code_challenge)
* '''TODO''' Creates an auth_requests row
* '''TODO''' Returns 404 for unknown provider

'''POST /auth/callback — Happy Path'''
* '''TODO''' Exchanges valid code and state for a session JWT with same payload structure as password login
* '''TODO''' Deletes the auth_requests row after successful use

'''POST /auth/callback — CSRF Protection (State Validation)'''
* '''TODO''' Rejects unknown state (422)
* '''TODO''' Rejects expired state older than 5 minutes (422)
* '''TODO''' Rejects already-consumed state / replay (422)

'''POST /auth/callback — Replay Protection (Nonce Validation)'''
* '''TODO''' Rejects ID token with mismatched nonce

'''POST /auth/callback — Token Verification'''
* '''TODO''' Rejects ID token with invalid signature
* '''TODO''' Rejects ID token with mismatched issuer
* '''TODO''' Rejects ID token with mismatched audience (client_id)

'''POST /auth/callback — User Matching'''
* '''TODO''' Returns 404 when no local user matches the email
* '''TODO''' Matches correct user when multiple users exist

'''POST /auth/callback — PKCE'''
* '''TODO''' Sends code_verifier to the token endpoint during code exchange

=== Frontend (React) ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.tsx src/components/OidcLogin/OidcLogin.tsx] — Provider dropdown component
[https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.tsx src/pages/OidcCallback/OidcCallback.tsx] — Callback page handling code exchange

=== Frontend (Vitest) Tests ===
([https://github.com/johnmweisz/reimplementation-front-end/tree/2618-oidc-login branch: 2618-oidc-login])

'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/components/OidcLogin/OidcLogin.test.tsx src/components/OidcLogin/OidcLogin.test.tsx] — Provider dropdown component tests
'''TODO''' [https://github.com/johnmweisz/reimplementation-front-end/blob/2618-oidc-login/src/pages/OidcCallback/OidcCallback.test.tsx src/pages/OidcCallback/OidcCallback.test.tsx] — Callback page tests

'''OidcLogin Component'''
* '''TODO''' Renders dropdown with providers when GET /auth/providers returns a non-empty list
* '''TODO''' Renders nothing when GET /auth/providers returns an empty array
* '''TODO''' Renders nothing when GET /auth/providers fails
* '''TODO''' Calls POST /auth/client-select with selected provider id on dropdown change
* '''TODO''' Redirects browser to returned authorization URL on successful client-select
* '''TODO''' Does not redirect when client-select fails
* '''TODO''' Existing login form remains visible and functional alongside the dropdown

'''OidcCallback Component'''
* '''TODO''' Posts code and state to POST /auth/callback on mount
* '''TODO''' Stores session JWT and dispatches auth state on success
* '''TODO''' Redirects to dashboard on successful login
* '''TODO''' Displays error alert and redirects to login on backend failure (e.g. no matching account)
* '''TODO''' Displays error and redirects to login when IdP returns an error parameter (e.g. user denied consent) without calling the backend
* '''TODO''' Redirects to login when code or state query parameters are missing
* '''TODO''' Shows "Completing login..." message while request is in flight

=== Routes ===
GET /auth/providers → oidc_login#providers
POST /auth/client-select → oidc_login#client_select
POST /auth/callback → oidc_login#callback
GET /auth/callback → React OidcCallback component

== Development Stories (Planning) ==

=== Story 1: Backend — OIDC Provider Configuration ===
'''As a''' developer, '''I want''' provider configurations loaded from a YAML file at boot, '''so that''' new OIDC providers can be added without code changes.

'''Acceptance Criteria:'''
* Create <code>config/oidc_providers.yml</code> with ERB support for injecting secrets from environment variables.
* Create an <code>OidcConfig</code> class that loads and validates the YAML at boot, exposing methods to list providers and look up a provider by id.
* Define the config file path as a constant (<code>CONFIG_FILE</code>) for clarity.
* Validate required keys: <code>display_name</code>, <code>issuer</code>, <code>client_id</code>, <code>client_secret</code>, <code>redirect_uri</code>, <code>scopes</code>.
* Raise a clear boot-time error if required values are missing via <code>config/initializers/oidc.rb</code>.
* Add unit tests for config loading, validation, and missing key detection.

=== Story 2: Backend — Auth Requests Table ===
'''As a''' developer, '''I want''' a database-backed store for OIDC state, nonce, and PKCE values, '''so that''' the backend can validate callbacks without relying on cookies.

'''Acceptance Criteria:'''
* Generate an ActiveRecord migration for <code>auth_requests</code> with columns: <code>state</code> (string, indexed, unique), <code>nonce</code>, <code>code_verifier</code>, <code>provider</code>, and <code>created_at</code>.
* Create the <code>AuthRequest</code> model with a uniqueness validation on state, an <code>expired</code> scope, and a <code>cleanup_expired</code> class method.
* Add a rake task or scheduled job to periodically clean up expired rows.
* Add unit tests for creation, lookup, expiry, and deletion.

=== Story 3: Backend — Provider List Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>GET /auth/providers</code> endpoint, '''so that''' the login page can dynamically render provider options.

'''Acceptance Criteria:'''
* Create a controller action that returns a JSON array of <code>{ id, name }</code> from <code>OidcConfig.public_list</code>.
* No secrets or endpoint URLs are included in the response.
* Add a request spec covering the response format and a case with multiple providers.

=== Story 4: Backend — Client Select Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/client-select</code> endpoint that returns an authorization URL, '''so that''' the frontend can redirect the user to the identity provider.

'''Acceptance Criteria:'''
* Accept a <code>provider</code> param and look up the provider config.
* Generate cryptographically random state, nonce, and PKCE code verifier/challenge.
* Insert a row into <code>auth_requests</code>.
* Construct and return the authorization URL with client_id, redirect_uri, scopes, state, nonce, and code_challenge.
* Return a 404 if the provider is unknown.
* Add request specs covering the happy path, unknown provider, and that the auth_requests row is created.

=== Story 5: Backend — Callback Endpoint ===
'''As a''' frontend developer, '''I want''' a <code>POST /auth/callback</code> endpoint that exchanges the authorization code for tokens and returns a session, '''so that''' the user is logged in after completing the OIDC flow.

'''Acceptance Criteria:'''
* Accept <code>code</code> and <code>state</code> params.
* Look up and delete the matching <code>auth_requests</code> row. Reject if not found or expired.
* Exchange the code for tokens using the <code>openid_connect</code> gem with the stored code_verifier.
* Verify the ID token signature (JWKS), issuer, client_id, and nonce.
* Extract the email claim and match to an existing local user.
* On match: issue a session JWT using the same payload structure as <code>AuthenticationController#login</code> and return it with the user profile.
* On no match: return a 404 error indicating no local account was found.
* Handle <code>ActiveRecord::RecordNotFound</code> (invalid/expired state) and <code>InvalidToken</code> (verification failure) exceptions.
* Add request specs covering the happy path, expired state, invalid state, and no matching user.

=== Story 6: Frontend — Provider Dropdown on Login Page ===
'''As a''' user, '''I want''' to see a provider dropdown on the login page, '''so that''' I can authenticate with my school credentials.

'''Acceptance Criteria:'''
* Create an <code>OidcLogin</code> component that calls <code>GET /auth/providers</code> on mount.
* Render a <code>Form.Select</code> dropdown with a disabled "Sign in with..." default option.
* If the request fails or returns empty, render nothing (no error, no placeholder).
* Existing login form remains unchanged and fully functional.
* Add component tests for rendering with providers and graceful fallback.

=== Story 7: Frontend — Initiate OIDC Flow ===
'''As a''' user, '''I want''' selecting a provider from the dropdown to start the login flow, '''so that''' I am redirected to my school's login page.

'''Acceptance Criteria:'''
* On selection change, <code>POST</code> to <code>/auth/client-select</code> with the provider id.
* On success, redirect the browser to the returned authorization URL via <code>window.location.href</code>.
* On failure, log the error to the console.
* Add component tests for the redirect and error handling.

=== Story 8: Frontend — Callback Route and Login Completion ===
'''As a''' user, '''I want''' to be logged in automatically after authenticating with my school, '''so that''' I don't have to take any additional steps.

'''Acceptance Criteria:'''
* Add a <code>/auth/callback</code> route in the React router pointing to the <code>OidcCallback</code> component.
* Extract <code>code</code> and <code>state</code> from query parameters and <code>POST</code> them to <code>/auth/callback</code>.
* If the query parameters contain an <code>error</code> param (e.g. user denied consent), display the error via the alert slice and redirect to login without calling the backend.
* On success: call <code>setAuthToken</code>, persist session to localStorage, dispatch <code>authenticationActions.setAuthentication</code>, and redirect to the dashboard — mirroring the existing password login flow.
* On failure: display an error message via the alert slice and redirect to the login page.
* Show a "Completing login..." message while the token exchange is in progress.
* Add component tests for success, provider error, and backend error scenarios.

=== Story 9: Backend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC backend, '''so that''' I have confidence the endpoints and models work correctly.

'''Acceptance Criteria:'''
* Add request specs for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Mock the identity provider's discovery, token, and JWKS endpoints to avoid external calls in tests.
* Cover error scenarios: expired state, invalid state, unknown provider, no matching user, invalid ID token.
* Add model specs for <code>AuthRequest</code> covering creation, uniqueness, expiry scope, and cleanup.
* Add unit tests for <code>OidcConfig</code> covering loading, validation, and missing key detection.
* Verify the existing <code>AuthenticationController#login</code> is unaffected.

=== Story 10: Frontend — Tests ===
'''As a''' developer, '''I want''' test coverage for the OIDC frontend components, '''so that''' I have confidence the login flow and callback work correctly.

'''Acceptance Criteria:'''
* Add component tests for <code>OidcLogin</code>: renders dropdown when providers are returned, renders nothing on empty or failed response, triggers <code>POST /auth/client-select</code> on selection.
* Add component tests for <code>OidcCallback</code>: posts code and state to backend on mount, redirects to dashboard on success, displays error and redirects to login on failure, handles IdP error parameter without calling the backend.
* Mock axios calls to avoid external requests in tests.
* Verify the existing login page renders and functions correctly with and without the <code>OidcLogin</code> component.

=== Additional Refactoring Stories ===

==== Story 11: Backend — Unified Session Response ====
'''As a''' developer, '''I want''' the session object returned to the frontend clearly defined and reusable by all login flows, '''so that''' the frontend can rely on a consistent response shape regardless of authentication method.

'''Acceptance Criteria:'''
* Extract the JWT payload construction and token issuance logic from <code>AuthenticationController#login</code> and <code>OidcLoginController#callback</code> into a shared method on the <code>User</code> model (e.g. <code>user.generate_jwt</code>).
* Define a consistent response structure (e.g. <code>{ token, user: { id, name, full_name, role, institution_id } }</code>) and use it in both controllers.
* Update the existing password login endpoint to use the shared method without changing its external response shape.
* Add or update request specs for both login endpoints to assert the response structure matches.

==== Story 12: Frontend — Externalize Hardcoded Configuration ====
'''As a''' developer, '''I want''' all hardcoded values moved to isolated configuration files, '''so that''' environment-specific settings can be changed without code modifications.

'''Acceptance Criteria:'''
* Move the frontend API base URL to an environment variable or shared config file (e.g. <code>.env</code> with <code>REACT_APP_API_URL</code>) and replace all hardcoded references.
* Ensure all existing tests continue to pass after the extraction.

==== Story 13: Backend — Swagger Documentation for Provider Endpoints ====
'''As a''' developer, '''I want''' the OIDC provider endpoints documented in Swagger, '''so that''' frontend developers and future contributors can understand the API contract without reading the source code.

'''Acceptance Criteria:'''
* Add Swagger/OpenAPI annotations for <code>GET /auth/providers</code>, <code>POST /auth/client-select</code>, and <code>POST /auth/callback</code>.
* Document request parameters, response schemas (including success and error shapes), and HTTP status codes for each endpoint.
* Include example request and response payloads.
* Verify the endpoints appear correctly in the generated Swagger UI.

==== Story 14: Backend — Cleanup Expired Auth Requests ====
'''As a''' developer, '''I want''' expired auth request rows cleaned up automatically, '''so that''' the table does not grow unbounded from abandoned login attempts.

'''Acceptance Criteria:'''
* Add a recurring ActiveJob solid_queue <code>auth_requests:cleanup</code> that calls <code>AuthRequest.cleanup_expired</code>.
* The task deletes all rows with <code>created_at</code> older than 5 minutes.
* Schedule the task to run periodically (e.g. 24 hours).
* Add a test verifying that only expired rows are deleted.

== Demo ==

todo add screenshots of oidc login at each step

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-04-09T01:52:26Z

Admin: /* Model Specs */

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasizes membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorization and HTTP response behavior.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behavior || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behavior || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.
== Demo Video==
https://www.youtube.com/watch?v=KZh-Kwhduok
== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-04-09T01:51:48Z

Admin: /* Model Specs */

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasizes membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorization and HTTP response behavior.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behavior || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.
== Demo Video==
https://www.youtube.com/watch?v=KZh-Kwhduok
== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing

2026-04-09T01:49:47Z

Admin: Changed several British spellings (flagged by the spellchecker) to American spellings

== About This Project ==

{| class="wikitable"; margin-left:20px; width:320px;"
|-
! colspan="2" style="background:#cee0f2; text-align:center;" | Project Info
|-
| '''Course''' || CSC/ECE 517 Spring 2026
|-
| '''Project''' || E2610 — Teams Hierarchy Testing
|-
| '''Instructor''' || Ed Gehringer
|-
| '''Mentor''' || Vihar Manojkumar Shah
|-
| '''Collaborators''' || Atharva Waingankar, Krisha Darji, Saladin Al-Bataineh
|-
| '''Platform''' || Expertiza (Ruby on Rails)
|-
| '''Test Framework''' || RSpec
|-
| '''Root Class''' || <code>Team</code> (STI superclass)
|-
| '''Subclasses''' || <code>CourseTeam</code>, <code>AssignmentTeam</code>, <code>MentoredTeam</code>
|-
| '''Membership Join Model''' || <code>TeamsParticipant</code>

|}

The Expertiza platform organises student collaboration through a structured class hierarchy dedicated to managing teams. Teams are the fundamental unit of participation: they allow students to reserve topics, collaborate on coursework, and submit assignments for evaluation.

This project focuses on ensuring the correctness of the Team hierarchy and strengthening automated test coverage. The work emphasizes membership validity (enrolment-based participation), preventing duplicate membership across teams, enforcing capacity limits when configured, ensuring MentoredTeam uses duty-based mentor identification, and validating controller authorization and HTTP response behavior.

== Background ==

=== The Team Hierarchy ===
The hierarchy is composed of exactly four classes:

* <code>Team</code> — STI superclass providing shared associations and common behaviours
* <code>CourseTeam</code> — course-scoped teams that persist across a course
* <code>AssignmentTeam</code> — assignment-scoped teams created for a single assignment
* <code>MentoredTeam</code> — subclass of <code>AssignmentTeam</code> with a designated mentor

Two broad kinds of team exist:

* '''Course teams''' (<code>CourseTeam</code>) persist throughout a course. In some instructional designs (e.g., Team-Based Learning), these teams are reused for multiple assignments.
* '''Assignment teams''' (<code>AssignmentTeam</code>) exist only for a single assignment. When mentors are used, assignment teams are instantiated as <code>MentoredTeam</code>.

=== Class Hierarchy Diagram ===
<pre>
┌─────────────────┐
│ Team │
│ (STI parent) │
└────────┬────────┘
│
┌─────────────────┴──────────────────┐
│ │
┌────────┴────────┐ ┌──────────┴──────────┐
│ CourseTeam │ │ AssignmentTeam │
│ (course-scoped) │ │ (assignment-scoped) │
└─────────────────┘ └──────────┬──────────┘
│
┌──────────┴──────────┐
│ MentoredTeam │
│ (mentor via duty) │
└─────────────────────┘
</pre>

=== Subclass Responsibilities ===
{| class="wikitable" style="width:100%;"
|-
! Class !! Scope !! Key Constraint !! Notes
|-
| <code>Team</code> || — || Shared membership/associations || Parent class for all team types (STI)
|-
| <code>CourseTeam</code> || Course || Member must be a course participant || Can be converted to/from assignment teams
|-
| <code>AssignmentTeam</code> || Assignment || Member must be an assignment participant || Capacity comes from <code>Assignment#max_team_size</code>
|-
| <code>MentoredTeam</code> || Assignment || Mentor identified by participant duty || Uses <code>Duty</code> + participant <code>duty_id</code>
|}

== Duty vs. Role Distinction ==

A critical design point (and a core source of bugs in this area) is the separation between a user's '''role''' and a participant's '''duty'''.

{| class="wikitable" style="width:100%;"
|-
! Concept !! Definition !! Examples
|-
| '''Role''' || System-level permission level assigned to a user account || <code>Instructor</code>, <code>Teaching Assistant</code>, <code>Student</code>
|-
| '''Duty''' || A function assigned to a participant ''within a specific team'' || <code>Submitter</code>, <code>Reviewer</code>, <code>Mentor</code>
|}

In Expertiza, mentors are not privileged system accounts; they are normal users assigned the duty of Mentor on one team. Therefore, mentor logic must use participant duty rather than user role.

== Previous Implementation ==

=== 1) MentoredTeam used role-based assumptions ===
The incorrect approach was to treat “mentor” as a system-level role check. This is incompatible with Expertiza’s domain model, where mentor is a team-level duty assigned to a participant.

'''What we changed:''' MentoredTeam mentor assignment and mentor discovery use <code>Duty</code> and the participant’s <code>duty_id</code>.

=== 2) Capacity enforcement was inconsistent / bypassable ===
Membership could be created through multiple paths (domain method, controllers, join-request acceptance). If enforcement only happened in one place, direct creation of <code>TeamsParticipant</code> could bypass capacity checks.

'''What we changed:''' Capacity is enforced at both:
* the domain method level (<code>Team#add_member</code>)
* the join model level (<code>TeamsParticipant</code> validation backstop)

Join-request acceptance also checks capacity inside a lock for race-safety.

=== 3) TeamsController authorisation was not explicit ===
The authorisation framework existed (global before_action), but <code>TeamsController</code> did not implement an explicit access policy. As a result, student actions could succeed where they should be forbidden.

'''What we changed:''' TeamsController now defines <code>action_allowed?</code>, and request specs verify correct <code>403 Forbidden</code> behaviour.

=== 4) CourseTeam capacity was assumed without schema support ===
The current schema does not provide a <code>max_team_size</code> attribute for courses. Attempting to enforce CourseTeam capacity via <code>course.max_team_size</code> results in runtime errors and breaks previously passing tests.

'''What we changed:''' Capacity enforcement is based on assignment configuration (<code>Assignment#max_team_size</code>). CourseTeams remain uncapped by default unless the schema is extended in the future.

== Implementation Summary ==

=== 1) Enrollment-based membership ===
Membership is grounded in valid participation. A user can only be added if the appropriate participant record exists in the correct parent scope.

<syntaxhighlight lang="ruby">
# app/models/team.rb
participant_type = is_a?(AssignmentTeam) ? AssignmentParticipant : CourseParticipant
participant_type.find_by(user_id: participant_or_user.id, parent_id: parent_id)
</syntaxhighlight>

=== 2) Prevent duplicate membership across teams ===
The join model prevents a participant from appearing on multiple teams:

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validates :participant_id, uniqueness: true
</syntaxhighlight>

A unique index migration reinforces this at the database level.

=== 3) Capacity enforcement (configured via Assignment) ===
Capacity is enforced via the assignment’s <code>max_team_size</code>. When at capacity, attempts to add are rejected with an error.

<syntaxhighlight lang="ruby">
# app/models/team.rb
def full?
max = max_size
return false if max.blank?
participants.count >= max
end
</syntaxhighlight>

<syntaxhighlight lang="ruby">
# app/models/team.rb
return { success: false, error: "Unable to add participant: team is at full capacity." } if full?
</syntaxhighlight>

=== 4) Join-model capacity backstop ===
Even direct join-table creation is blocked when a team is at capacity.

<syntaxhighlight lang="ruby">
# app/models/teams_participant.rb
validate :team_not_full, on: :create

def team_not_full
return unless team
max = team.max_size
return if max.blank?

if team.participants.count >= max
errors.add(:base, "Team is at full capacity (max #{max}).")
end
end
</syntaxhighlight>

=== 5) Race-safe join request acceptance ===
Acceptance checks capacity while holding a lock to prevent two concurrent acceptances from overfilling a team.

<syntaxhighlight lang="ruby">
# app/controllers/join_team_requests_controller.rb (accept)
ActiveRecord::Base.transaction do
team.with_lock do
if team.full?
# reject accept
end
result = team.add_member(participant)
# reject if result failed
end

@join_team_request.update!(reply_status: ACCEPTED)
end
</syntaxhighlight>

=== 6) TeamsController authorisation and HTTP codes ===
TeamsController now declares an explicit policy:

* Teaching staff (TA and above): allowed
* Students: cannot list all teams, cannot manage membership, can only view teams they belong to

Request specs assert that restricted actions return <code>403</code> with an error payload.

== RSpec Test Coverage ==

The test suite is organised into model specs (domain rules) and request specs (API behaviour + HTTP status codes).

=== Model Specs ===
{| class="wikitable" style="width:100%;"
|-
! Area !! Spec File(s) !! What is validated
|-
| Team membership + validations || <code>spec/models/team_spec.rb</code> || Type/parent validation, membership checks, <code>full?</code>, <code>add_member</code>
|-
| Capacity behaviour || <code>spec/models/team_capacity_spec.rb</code> || AssignmentTeam capacity and error rejection
|-
| Association integrity || <code>spec/models/team_association_spec.rb</code> || Parent linkage and membership scoping
|-
| Conversion behaviour || <code>spec/models/team_conversion_spec.rb</code> || CourseTeam ⇄ AssignmentTeam conversions and member copying
|-
| MentoredTeam duty behaviour || <code>spec/models/mentored_team_spec.rb</code> || Mentor duty assignment/removal and mentor lookup by duty
|-
| Join model constraints || <code>spec/models/teams_participant_spec.rb</code> || Uniqueness, presence, and capacity backstop (no bypass)
|}

=== Request Specs ===
{| class="wikitable" style="width:100%;"
|-
! Endpoint Area !! Spec File(s) !! What is validated
|-
| Teams API || <code>spec/requests/api/v1/teams_controller_spec.rb</code> || Index/show/members/add/remove + authorisation status codes
|-
| JoinTeamRequests API || <code>spec/requests/api/v1/join_team_requests_controller_spec.rb</code> || Authorisation, create/accept/decline, capacity rejection and rollback behaviour
|-
| TeamsParticipants API || <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code> || Duty update authorisation, list/add/delete flows
|}

=== Important Example Tests ===

==== Capacity and size limits ====
<syntaxhighlight lang="ruby">
# spec/models/team_capacity_spec.rb
it 'rejects member when team is full' do
2.times { |i| team.add_member(make_participant("full#{i}")) }
extra = make_participant('extra')

result = team.add_member(extra)

expect(result[:success]).to be false
expect(result[:error]).to match(/capacity/i)
end
</syntaxhighlight>

Purpose: verifies domain-level capacity enforcement returns a structured failure and a meaningful error.

<syntaxhighlight lang="ruby">
# spec/models/teams_participant_spec.rb
describe 'capacity validation (team_not_full)' do
it 'raises when creating beyond capacity' do
assignment.update!(max_team_size: 1)
team = AssignmentTeam.create!(name: 'Cap Team2', parent_id: assignment.id)

u1 = make_user('cap2_u1')
p1 = AssignmentParticipant.create!(user: u1, parent_id: assignment.id, handle: u1.name)
TeamsParticipant.create!(team: team, participant: p1, user: u1)

u2 = make_user('cap2_u2')
p2 = AssignmentParticipant.create!(user: u2, parent_id: assignment.id, handle: u2.name)

expect {
TeamsParticipant.create!(team: team, participant: p2, user: u2)
}.to raise_error(ActiveRecord::RecordInvalid)
end
end
</syntaxhighlight>

Purpose: ensures capacity cannot be bypassed by direct join-table creation.

==== Join request acceptance rollback correctness ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/join_team_requests_controller_spec.rb
it 'does not change reply_status or add participant when team is full' do
assignment.update!(max_team_size: 1)

patch "/join_team_requests/#{join_team_request.id}/accept", headers: team_member_headers

expect(response).to have_http_status(:unprocessable_entity)
expect(join_team_request.reload.reply_status).to eq('PENDING')
expect(team1.participants.reload).not_to include(participant2)
end
</syntaxhighlight>

Purpose: verifies the accept endpoint rejects at capacity and does not mutate state.

==== TeamsController authorisation / HTTP status codes ====
<syntaxhighlight lang="ruby">
# spec/requests/api/v1/teams_controller_spec.rb
it 'returns 403 for student on GET /teams' do
student_token = JsonWebToken.encode(id: other_user.id)
student_headers = { Authorization: "Bearer #{student_token}" }

get '/teams', headers: student_headers

expect(response).to have_http_status(:forbidden)
expect(JSON.parse(response.body)).to have_key('error')
end
</syntaxhighlight>

Purpose: ensures a student cannot list teams and receives <code>403</code> with an error payload.

==== MentoredTeam duty-based mentor behaviour ====
<syntaxhighlight lang="ruby">
# spec/models/mentored_team_spec.rb
it 'identifies mentor by duty not by role' do
mentor_duty
participant = make_participant('duty_mentor')
team.add_member(participant)
team.assign_mentor(participant.user)

expect(team.send(:mentor)).to eq(participant.user)
expect(participant.reload.duty).to eq(mentor_duty)
end
</syntaxhighlight>

Purpose: proves mentor identification is duty-based, matching Expertiza’s domain model.
== Demo Video==
https://www.youtube.com/watch?v=KZh-Kwhduok
== Summary ==
This project strengthens the Teams hierarchy by ensuring membership is grounded in enrolment, preventing duplicate membership, enforcing assignment team capacity with both domain-level checks and a join-table backstop, making join-request acceptance race-safe with locking, and implementing explicit TeamsController authorisation rules with request specs that validate correct HTTP response codes. MentoredTeam is tested to rely on participant duty (Mentor) rather than user role.

== References ==
* Expertiza project specification — Teams hierarchy testing (Mentor: Vihar Manojkumar Shah)
* Rails Guides — Active Record Associations
* RSpec Documentation

Assignments questionnaires

2026-04-02T02:02:01Z

Admin:

== Assignments Questionnaire Variable Documentation ==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|The unique record id
|-
!questionnaire_id
|int(11)
|This references a questionnaire that is used in t he assignment
|-
!assignment_id
|int(11)
|This references the assignment in which the questionnaire is used
|-
!notification_limit
|int
|If a new review has a score that is more than this # of percentage points away from the current average review score for this artifact, then the instructor will be emailed.
|-
!questionnaire_weight
|int
|Gives the percentage of the contributor's overall score that is based on this questionnaire.
|-
!used_in_round
|int
|Tells which round (1, 2, ...) of review this questionnaire is used in. If null, I suspect that the questionnaire is used in all rounds.
|-
!dropdown
|tinyint(1)
|I believe that if this is true, instead of using a rubric to evaluate this kind of work (e.g., review of work, teammate review), a simple dropdown with integers from 1 to MAX_SCORE is used instead.
|-
!topic_id
|int
|If this field is non-null, then this rubric is used only to review this particular topic.
|-
!duty_id
|int
|If this is non-null, then this rubric is used only to review a team member who takes on a particular role (such as scrum master, tester, or documentor).
|-
|}

== E/R diagram for Parents Tables ==
Tables referred by the Assignment Badges Table as Foreign Key Relationship.

[[File:assignments_questionnaires_imported.png]]

== E/R diagram for Child Tables ==
No Tables refer the Assignment Badges Table as Foreign Key Relationship.

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Response maps

2026-03-28T00:38:17Z

Admin: /* Response maps variable documentation (Reimplementation) */

Maps a connection between the [[participants]] as reviewers and [[participants]] or [[teams]] as reviewees

==Response maps variable documentation (Reimplementation)==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|The unique record id
|-
!reviewed_object_id
|int(11)
|The object being reviewed in the [[responses|response]]. In the reimplemented system, this will always be an [[assignment]].
|-
!reviewer_id
|int(11)
|The [[participants|participant]] (actually AssignmentParticipant) providing the response
|-
!reviewee_id
|int(11)
|Dependent on which subclass of ResponseMap this object is. For a ReviewResponseMap, the [[teams|team]] (AssignmentTeam) receiving the response. For a TeammateReviewResponseMap, the AssignmentParticipant who is being reviewed.
|-
!type
|varchar(255)
|Used for subclassing the response map. Available subclasses are ReviewResponseMap, MetareviewResponseMap, FeedbackResponseMap, TeammateReviewResponseMap
|-
!created_at
|DATETIME
|Date and Time for when the record was created
|-
!updated_at
|DATETIME
|Date and Time when the last update was made
|-
!for_calibration
|int(11)
|Tells whether the record will be used for calibration or not.
|}

==Response maps variable documentation (2023 version)==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|The unique record id
|-
!reviewed_object_id
|int(11)
|The object being reviewed in the [[responses|response]]. Possible objects include other ResponseMaps or [[assignments]]
|-
!reviewer_id
|int(11)
|The [[participants|participant]] (actually AssignmentParticipant) providing the response
|-
!reviewee_id
|int(11)
|Dependent on which subclass of ResponseMap this object is. For a ReviewResponseMap, the [[teams|team]] (AssignmentTeam) receiving the response. For a TeammateReviewResponseMap, the AssignmentParticipant who is being reviewed.
|-
!type
|varchar(255)
|Used for subclassing the response map. Available subclasses are ReviewResponseMap, MetareviewResponseMap, FeedbackResponseMap, TeammateReviewResponseMap
|-
!created_at
|DATETIME
|Date and Time for when the record was created
|-
!updated_at
|DATETIME
|Date and Time when the last update was made
|-
!calibrate_to
|tinyint(1)
|Tells whether the record will be used for calibration or not.
|}

Back to the [[Documentation_on_Database_Tables|database documentation]]

Teams

2026-03-27T00:23:21Z

Admin: /* Teams Variable Documentation (Reimplementation) */

== Teams Variable Documentation (Reimplementation) ==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|
|-
!name
|varchar(255)
|Name of the team
|-
!parent_id
|int(11)
|ID of assignment or course that this team is participating in
|-
!type
|varchar(255)

|Type of the team, either AssignmentTeam or CourseTeam
|-
!directory_num
|int(11)
|directory number where files submitted by this team are stored
|-
!grade_for_submission
|int(11)
|Stores the grade assigned by the instructor, if any
|-
!comment_for_submission
|text
|Stores feedback from the instructor for the team
|}

== Teams Variable Documentation (2023 version) ==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|
|-
!name
|varchar(255)
|Name of the team
|-
!parent_id
|int(11)
|ID of assignment or course that this team is participating in
|-
!type
|varchar(255)

|Type of the team, either AssignmentTeam or CourseTeam
|-
!comments_for_advertisement
|text
|text for comments
|-
!advertise_for_partner
|tinyint(1)
|Boolean that tells whether the team is advertising for a partner
|-
!submitted_hyperlinks
|text
|List of submitted hyperlinks
|-
!directory_num
|int(11)
|directory number where files submitted by this team are stored
|-
!grade_for_submission
|int(11)
|Stores the grade assigned by the instructor, if any
|-
!comment_for_submission
|text
|Stores feedback from the instructor for the team
|}

== E/R diagram of tables referencing users table ==
The following image shows the tables referencing teams table
[[File:teams_export.png]]

== E/R diagram of tables users table is referencing to ==
The teams table is not referenced by any other tables

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Reviewer Assignment implementation

2026-03-15T20:06:39Z

Admin: /* Least‑Reviewed Submission Strategy */

= Overview =
The review‑assignment subsystem ''in the reimplemented Expertiza'' supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

*A reviewer may not be assigned to their own team.
*A reviewer may not be assigned to a team they have already reviewed.
*Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:06:04Z

Admin: /* Overview */

= Overview =
The review‑assignment subsystem ''in the reimplemented Expertiza'' supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:05:26Z

Admin: /* Overview */

= Overview =
The review‑assignment subsystem
'in the reimplemented Expertiza'
supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:04:10Z

Admin: /* Overview */

= Overview =
The review‑assignment subsystem 'in the reimplemented Expertiza' supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:03:33Z

Admin:

= Overview =
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:03:09Z

Admin: /* Common Eligibility Rules */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

*Their own team
*A team they have already reviewed
*A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:02:49Z

Admin: /* Strategy Classes */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

*each_review_pair — for static strategies

*assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:02:25Z

Admin: /* Instructor Grading of Reviews */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

*Locates the review mapping
*Records the instructor’s grade and comment
*Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:02:03Z

Admin: /* Topic‑Balanced Dynamic Assignment */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:
*Reviewers can restrict themselves to topics they prefer.
*Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

Locates the review mapping

Records the instructor’s grade and comment

Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:01:43Z

Admin: /* Topic‑Balanced Dynamic Assignment */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
*is not their own team,
*has not already been reviewed by them,
*has the fewest reviews among eligible teams.

This ensures:

Reviewers can restrict themselves to topics they prefer.

Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

Locates the review mapping

Records the instructor’s grade and comment

Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:01:16Z

Admin: /* CSV‑Based Assignment */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

*The reviewer is located by email and matched to an AssignmentParticipant.
*The team is located by name within the assignment.
*A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
** is not their own team,
** has not already been reviewed by them,
** has the fewest reviews among eligible teams.

This ensures:

Reviewers can restrict themselves to topics they prefer.

Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

Locates the review mapping

Records the instructor’s grade and comment

Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T20:00:31Z

Admin: /* Round‑Robin Assignment */

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

*Deterministic ordering
*Each team receives exactly one reviewer
*Reviewers are reused as needed
*No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

The reviewer is located by email and matched to an AssignmentParticipant.

The team is located by name within the assignment.

A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
** is not their own team,
** has not already been reviewed by them,
** has the fewest reviews among eligible teams.

This ensures:

Reviewers can restrict themselves to topics they prefer.

Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

Locates the review mapping

Records the instructor’s grade and comment

Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Reviewer Assignment implementation

2026-03-15T19:59:10Z

Admin: Created page with "Review Assignment System Overview The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically. This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMa..."

Review Assignment System Overview
The review‑assignment subsystem supports both '''static''' and '''dynamic''' allocation of reviews within an assignment. The goal is to give instructors flexible control over how reviewers are matched to submissions, while also supporting on‑demand, fairness‑aware assignment for students who request reviews dynamically.

This page documents the behavior implemented in ReviewMappingsController and the strategy classes under ReviewMappingStrategies.

= Static Review Assignment =

Static assignment is initiated by the instructor and produces a complete set of review mappings in a single operation. Three static strategies are supported.

== Round‑Robin Assignment ==
'''Controller action:''' assign_round_robin

This strategy cycles through all reviewers in order and assigns each team to the next reviewer in the cycle. Only participants who are eligible to review (can_review?) are included.

'''Characteristics:'''

Deterministic ordering

Each team receives exactly one reviewer

Reviewers are reused as needed

No workload balancing beyond the simple cycle

== Random Assignment ==
'''Controller action:''' assign_random

This strategy assigns reviewers to teams randomly. The distribution is determined by the logic inside ReviewMappingHandler.

== CSV‑Based Assignment ==
'''Controller action:''' assign_from_csv

This strategy imports reviewer–team pairs from an uploaded CSV file.

'''Expected CSV format:'''
<pre>
reviewer_email,team_name
</pre>

For each row:

The reviewer is located by email and matched to an AssignmentParticipant.

The team is located by name within the assignment.

A mapping is created if both are found.

This allows instructors to pre‑compute assignments externally and import them directly.

= Dynamic Review Assignment =

Dynamic assignment is initiated by a reviewer requesting a new review. Instead of pre‑assigning all reviews, the system allocates reviews on demand, which helps avoid the common problem of students failing to complete their assigned reviews.

Two dynamic strategies are supported.

== Least‑Reviewed Submission Strategy ==
'''Controller action:''' request_review_fewest
'''Strategy:''' LeastReviewedSubmissionStrategy

This strategy assigns the reviewer to the team whose submission has received the fewest completed reviews so far.

'''Eligibility rules:'''

A reviewer may not be assigned to their own team.

A reviewer may not be assigned to a team they have already reviewed.

Among eligible teams, the one with the lowest review count is selected.

This ensures a balanced distribution of reviews across submissions.

== Topic‑Balanced Dynamic Assignment ==
'''Controller action:''' request_review_topic_balance
'''Strategy:''' LeastReviewedTopicStrategy

When an assignment uses topics, reviewers may choose which topics they are willing to review. The system then assigns a team within an eligible topic, subject to fairness constraints.

'''Algorithm:'''

Review counts are aggregated per topic.
Let min_count be the smallest number of reviews received by any topic.
A topic is eligible if its review count is within '''k''' of min_count.
The first eligible topic (deterministically) is selected.
Within that topic, the reviewer is assigned to a team that:
** is not their own team,
** has not already been reviewed by them,
** has the fewest reviews among eligible teams.

This ensures:

Reviewers can restrict themselves to topics they prefer.

Topics remain approximately balanced, with fairness controlled by the threshold k.

= Calibration Review Assignment =

== Calibration Round‑Robin ==
'''Controller action:''' assign_calibration_artifacts

This assigns calibration reviews to all reviewers using a round‑robin strategy. Calibration reviews are typically instructor‑provided artifacts used to train or benchmark reviewers.

= Deleting Review Mappings =

== Delete a Single Mapping ==
'''Controller action:''' destroy

Deletes a specific review mapping by ID.

== Delete All Reviews for a Reviewer ==
'''Controller action:''' delete_all_for_reviewer

Removes all review mappings associated with a given reviewer. Useful when resetting or reassigning work.

= Instructor Grading of Reviews =

'''Controller action:''' grade_review

Instructors may grade individual reviews. This action:

Locates the review mapping

Records the instructor’s grade and comment

Returns a success message

= Strategy Classes =

All strategies inherit from ReviewMappingStrategies::BaseStrategy, which defines two abstract methods:

each_review_pair — for static strategies

assign_one — for dynamic strategies

Each concrete strategy implements one of these depending on its purpose.

== CsvImportStrategy ==
Implements each_review_pair by reading reviewer–team pairs from a CSV file.

== LeastReviewedSubmissionStrategy ==
Implements assign_one by selecting the eligible team with the fewest reviews.

== LeastReviewedTopicStrategy ==
Implements assign_one with topic‑level fairness constraints and a threshold k.

== RoundRobinStrategy ==
Implements each_review_pair by cycling through reviewers and pairing them with teams.

= Common Eligibility Rules =

Across all dynamic strategies, a reviewer is never assigned to:

Their own team

A team they have already reviewed

A team outside the selected topic (for topic‑based assignment)

Users

2026-03-08T19:28:51Z

Admin: /* Users Variable Documentation (Reimplementation) */

== Users Variable Documentation (Reimplementation) ==

{| class="wikitable"
!Name !!Datatype !!Description
|-
!id
|int(11)
|Primary key of the entry in table, auto increments by default
|-
!username
|varchar(255)
|User name of the respective user (formerly name)
|-
!crypted_password
|varchar(40)
|Password of the respective user
|-
!role_id
|int(11)
|Role which this user corresponds to FK into ROLES table. Examples are super_admin, admin, instructor, etc.
|-
!password_salt
|varchar(255)
|
|-
!name
|varchar(255)
|Registered full name of the user, e.g., Lastname, firstname (formerly fullname)
|-
!email
|varchar(255)
|Registered email of the respective user.
|-
!parent_id
|int(11)
|Parent of the respective user; corresponding to the user who created this user. The value of this field is the primary key in the users table for the parent user, e.g., 2 if the parent is the super-admin (username admin).
|-
!private_by_default
|tinyint(1)
|If the user is private by default; essentially Boolean. It seems that this is not used in the system, don't know what it was intended to mean. Could be removed.
|-
!email_on_submission
|tiny_int(1)
|If user is to be e-mailed when something they reviewed is resubmitted.
|-
!is_new_user
|tiny_int(1)
|Determines whether the user has logged in before; if not, upon login the user should be presented with the new-user agreement.
|-
!handle
|varchar(255)
|A handle is an alternate name by which the user would want to be known, e.g., on the wiki, if this assignment involves writing on a wiki. This allows the user to appear anonymous. In the code, this is sometimes known as the "default handle", because users can also create assignment-specific handles.
|-
!time_zone_pref
|varchar(255)
|Timezone that times should be displayed in when the user logs in.
|-
!language_pref
|varchar(255)
|Language that the user wants to use in interacting with Expertiza.
|-
!public_key
|mediumtext
|Public key used for data-encryption by user. This is used and should stay in the table, though whether the use is meaningful is not clear.
|-
!copy_of_emails
|tinyint(1)
|Whether this user wants to receive copies of e-mails sent for all assignments they are participating in. This is only implemented for instructors. Instructors would enable it so they start getting copies of all emails being sent related to their assignments. It is a way that the instructor can be reassured that emails are in fact being sent.
|-
!institution_id
|int(11)
|id of the institution that the user is associated with
|}

== Users Variable Documentation (2023 version) ==

{| class="wikitable"
!Name !!Datatype !!Description
|-
!id
|int(11)
|Primary key of the entry in table, auto increments by default
|-
!name
|varchar(255)
|User name of the respective user
|-
!crypted_password
|varchar(40)
|Password of the respective user
|-
!role_id
|int(11)
|Role which this user corresponds to FK into ROLES table. Examples are super_admin, admin, instructor, etc.
|-
!password_salt
|varchar(255)
|
|-
!fullname
|varchar(255)
|Registered full name of the user, e.g., Lastname, firstname
|-
!email
|varchar(255)
|Registered email of the respective user.
|-
!parent_id
|int(11)
|Parent of the respective user; corresponding to the user who created this user. The value of this field is the primary key in the users table for the parent user, e.g., 2 if the parent is the super-admin (username admin).
|-
!private_by_default
|tinyint(1)
|If the user is private by default; essentially Boolean. It seems that this is not used in the system, don't know what it was intended to mean. Could be removed.
|-
!mru_directory_path
|varchar(128)
|To allow the user to log back in to the same directory that (s)he logged out from before.
|-
!email_on_review
|tiny_int(1)
|Whether the user should be e-mailed when a new review is received for their work.
|-
!email_on_submission
|tiny_int(1)
|If user is to be e-mailed when something they reviewed is resubmitted.
|-
!email_on_review_of_review
|tiny_int(1)
|Whether the user should be e-mailed when one of their reviews is meta-reviewed by another reviewer.
|-
!is_new_user
|tiny_int(1)
|Determines whether the user has logged in before; if not, upon login the user should be presented with the new-user agreement.
|-
!master_permssion_granted
|tiny_int(4)
|If the user has the master user permission is granted. What?! What does master permission mean?! Well, doesn't matter, because this field is set but not read in existing code.
|-
!handle
|varchar(255)
|A handle is an alternate name by which the user would want to be known, e.g., on the wiki, if this assignment involves writing on a wiki. This allows the user to appear anonymous. In the code, this is sometimes known as the "default handle", because users can also create assignment-specific handles.
|-
!digital_certificate
|mediumtext
|Digital certificate generated for the user to protect his password. This is never read and could be removed.
|-
!timezonepref
|varchar(255)
|Timezone that times should be displayed in when the user logs in.
|-
!public_key
|mediumtext
|Public key used for data-encryption by user. This is used and should stay in the table, though whether the use is meaningful is not clear.
|-
!copy_of_emails
|tinyint(1)
|Whether this user wants to receive copies of e-mails sent for all assignments they are participating in. This is only implemented for instructors. Instructors would enable it so they start getting copies of all emails being sent related to their assignments. It is a way that the instructor can be reassured that emails are in fact being sent.
|-
!institution_id
|int(11)
|id of the institution that the user is associated with
|}

== E/R diagram of tables referencing users table ==
The following image shows the tables referencing users table
[[File:Users_export.png]]

== E/R diagram of tables users table is referencing to ==
The users table is not referenced by any other tables

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Questionnaires

2026-03-06T01:06:33Z

Admin: /* Questionnaires documentation (Reimplementation) */

==Questionnaires documentation (Reimplementation)==
{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|This object's unique ID value. One per object.
|-
!name
|varchar(64)
|name of the questionnaire
|-
!instructor_id
|int(11)
|id of instructor who created the questionnaire
|-
!private
|tinyint(1)
|whether questionnaire is visible to other instructors
|-
!min_item_score
|int(11)
|the minimum score that the reviewer can give for a question in this questionnaire
|-
!max_item_score
|int(11)
|the maximum score that the reviewer can give for a question in this questionnaire
|-
!created_at
|datetime
|the date and time at which the questionnaire was created at
|-
!updated_at
|datetime
|the date and time at which the questionnaire was last updated
|-
!default_num_choices
|int(11)
|default number of scoring increments
|-
!type
|varchar(255)
|Subclassing for the questionnaire. Possible types are ReviewQuestionnaire, MetareviewQuestionnaire, AuthorFeedbackQuestionnaire, BookmarkRatingQuestionnaire, QuizQuestionniare, SurveyQuestionnaire, CourseEvaluationQuestionnaire, TeammateReviewQuestionnaire, GlobalSurveyQuestionnaire
|-
!instruction_loc
|TEXT
|
|}

==Questionnaires documentation (2023 version)==
{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|This object's unique ID value. One per object.
|-
!name
|varchar(64)
|name of the questionnaire
|-
!instructor_id
|int(11)
|id of instructor who created the questionnaire
|-
!private
|tinyint(1)
|whether questionnaire is visible to other instructors
|-
!min_question_score
|int(11)
|the minimum score that the reviewer can give for a question in this questionnaire
|-
!max_question_score
|int(11)
|the maximum score that the reviewer can give for a question in this questionnaire
|-
!created_at
|datetime
|the date and time at which the questionnaire was created at
|-
!updated_at
|datetime
|the date and time at which the questionnaire was last updated
|-
!default_num_choices
|int(11)
|default number of scoring increments
|-
!type
|varchar(255)
|Subclassing for the questionnaire. Possible types are ReviewQuestionnaire, MetareviewQuestionnaire, AuthorFeedbackQuestionnaire, QuizQuestionniare, SurveyQuestionnaire, CourseEvaluationQuestionnaire, TeammateReviewQuestionnaire, GlobalSurveyQuestionnaire
|-
!display_type
|varchar(255)
|Character representation of type used in tree display. Possible values are Review, Metareview, AuthorFeedback, Survey, CourseEvaluation, TeammateReview GlobalSurvey
|-
!instruction_loc
|TEXT
|
|}

Back to [http://wikis.lib.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.