Expertiza_Wiki - User contributions [en]

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.

Questionnaires

2026-03-06T01:02:21Z

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, 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.

Answers

2026-02-09T21:16:46Z

Admin: /* Answers Variable Documentation */

The Answers table gives information regarding the answers associated to each of the responses.
== Answers Variable Documentation ==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|Unique ID for each Answers record.
|-
!question_id
|int(11)
|ID of Question.
|-
!answer
|int(11)
|Numeric value of the answer.
|-
!comments
|text
|Comment given to the answer.
|-
!response_id
|int(11)
|ID of the response associated with this Answer.
|}

== E/R diagram for Parents Tables ==
Tables referred by the Answers Table as Foreign Key Relationship.

[[File:answers_imported.png]]

== E/R diagram for Child Tables ==
Tables which refer the Answers Table as Foreign Key Relationship.

[[File:answers_exported.png]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

CSC/ECE 517 Fall 2025 - E2568. Finish tabbed view for Assignments, including Topics and Calibration tabs

2025-12-08T21:42:37Z

Admin: /* Calibration Tab */

== Introduction ==

=== Overview ===
This project is a continuation of [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2025_-_E2558._Tabbed_view_for_creating_and_editing_assignments E2558]. The Edit Assignment front end will get an additional tab for review calibration based on the backend work of [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2025_-_E2564._Review_calibration E2564]. Additionally, the Topics tab created as part of E2558 will be integrated with the topic table created by [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2025_-_E2557._Specialized_rubrics_for_different_topic_types E2557]. A more comprehensive testing suite for the AssignmentEditor tabbed view will also be developed. The images below are samples provided to the team.

=== Motivation ===
Expertiza is an open-source assignment management system with support for teams and peer-reviewing. In the context of Expertiza, calibration refers to sample reviews provided for the purpose of determining if a student is a competent reviewer. If the student's reviews align with the samples, the student is assumed to be competent, assisting in grading and review quality. This new frontend will display these instructor-provided sample reviews in the new Calibration tab where they can be viewed and edited. The topic table is used to create, edit, and delete assignment topics, as well as view which students/groups have signed up for which topic once the assignment is live.

=== Requirements ===

==== Calibration Tab ====
* Tab header should be "Submit reviews for calibration"
* Table should have three columns titled:
** Participant name: displays the name in the format of "user-ID (Name)"
** Action: contains a link to "Begin" that once clicked changes to the links "View" and "Edit"
** Submitted item(s): provides a view of the submitted calibration materials
[[File:E2568_Calibration.png|border|500px|Sample image]]

==== Topics Table Integration ====
* Communicate with the respective team to ensure compatibility
* Work with them to adjust any requirements or details
[[File:E2568 Table integration.png|border|500px|Sample image]]

== Design ==
=== Front-end work ===
* We need to add a new Calibration tab to the existing setup
* These changes will happen in the <code>AssignmentEditor.tsx</code> file along with the rest of the editor tabs.
* Since there's a table to be added, we will use the previously built table component to avoid having to create a custom design. This also helps ensure the design stays consistent with the rest of the site.
* We'll need to store certain states on this tab to trigger the visibility of other buttons. These states will be stored in the <code>AssignmentUtils.tsx</code> file.
* To integrate the table from project E2557, we'll have to make changes to the existing tab layout and add any dependencies the new table has.

=== Back-end work ===
* Need to update the database to support the saving of added calibration parameters

=== Design Principles used ===
# Don't Repeat Yourself: Shared table rendering logic reused via helper components. API utility reused for all fetch calls.
# Single Responsibility Principle: Each tab component handles only its own view and logic.
# Open/Closed Principle: Since the tabs are modular, we can add new tabs without modifying existing ones. This makes it much easier to add or change them without messing with the rest of the structure.

=== Testing Plan ===
* For frontend tests, we will focus on getting the system setup from scratch since the Assignment Editor doesn't have one as of yet.
* This will involve adding tests top check whether appropriate components are visible when they should be, and if the different states stored for each tab stay consistent across the session.
* We'll also focus on checking if the data seen in the tables on the tabs is correct and aligns with what we're fetching from the backend

== Implementation ==
=== Front-end ===
Our front-end implementation can be found in <code>AssignmentEditor.tsx</code>, <code>AssignmentUtil.tsx</code>, and <code>AssignmentEditor.test.tsx</code> within <code>src/pages/Assignments</code>. <code>App.tsx</code> and <code>custom.scss</code> were also updated in <code>src</code> to implement correct routing for assignment creation and add the correct tab styling respectively.
==== Calibration Tab ====
[[File:E2568_Calibration_implementation.png|border|500px]]
<small>
<syntaxhighlight lang="typescript">
<Tab eventKey="calibration" title="Calibration">
<h3>Submit reviews for calibration</h3>
<div>
<div style={{ display: 'ruby', marginTop: '30px' }}>
<Table
showColumnFilter={false}
showGlobalFilter={false}
showPagination={false}
data={[
...calibrationSubmissions.map((calibrationSubmission: any) => ({
id: calibrationSubmission.id,
participant_name: calibrationSubmission.participant_name,
review_status: calibrationSubmission.review_status,
submitted_content: calibrationSubmission.submitted_content,
})),
]}
columns={[
{
accessorKey: "participant_name", header: "Participant name", enableSorting: false, enableColumnFilter: false
},
{
cell: ({ row }) => {
if (row.original.review_status === "not_started") {
return <a href={`/assignments/edit/${assignmentData.id}/calibration/${row.original.id}`}>Begin</a>;
} else {
return <div style={{ display: 'flex', alignItems: 'center', columnGap: '5px' }}>
<a href={`/assignments/edit/${assignmentData.id}/calibration/${row.original.id}`}>View</a>
|
<a href={`/assignments/edit/${assignmentData.id}/calibration/${row.original.id}`}>Edit</a>
</div>;
}
},
accessorKey: "action", header: "Action", enableSorting: false, enableColumnFilter: false
},
{
cell: ({ row }) => <>
<div>Hyperlinks:</div>
{
row.original.submitted_content.hyperlinks.map((item: any, index: number) => {
return <a key={index} href={item}>{item}</a>;
})
}
<div style={{ marginTop: '10px' }}>Files:</div>
{
row.original.submitted_content.files.map((item: any, index: number) => {
return <a key={index} href={item}>{item}</a>;
})
}
</>,
accessorKey: "submitted_content", header: "Submitted items(s)", enableSorting: false, enableColumnFilter: false
},
]}
/>
</div>
</div>
</Tab>
</syntaxhighlight>
</small>

=== Back-end ===
The back-end additions are in <code>db/migrate</code> and are called <code>add_frontend_fields_to_assignments.rb</code>, <code>add_remaining_fields_to_assignments.rb</code>, and <code>add_apply_late_policy_to_assignments.rb</code>. The full file names include date codes that are not included here for clarity.

The fields taken from the completed form to be inserted into the database are
<small>
<syntaxhighlight lang="typescript">
export interface AssignmentData {
id?: number;
name: string;
directory_path: string;
spec_location: string;
private: boolean;
show_template_review: boolean;
require_quiz: boolean;
has_badge: boolean;
staggered_deadline: boolean;
is_calibrated: boolean;

// Teams / mentors / topics
has_teams?: boolean;
max_team_size?: number;
show_teammate_review?: boolean;
is_pair_programming?: boolean;
has_mentors?: boolean;
has_topics?: boolean;

// Review strategy / limits
review_topic_threshold?: number;
maximum_number_of_reviews_per_submission?: number;
review_strategy?: string;
review_rubric_varies_by_round?: boolean;
review_rubric_varies_by_topic?: boolean;
review_rubric_varies_by_role?: boolean;
has_max_review_limit?: boolean;
set_allowed_number_of_reviews_per_reviewer?: number;
set_required_number_of_reviews_per_reviewer?: number;
is_review_anonymous?: boolean;
is_review_done_by_teams?: boolean;
allow_self_reviews?: boolean;
reviews_visible_to_other_reviewers?: boolean;
number_of_review_rounds?: number;

// Dates / penalties
days_between_submissions?: number;
late_policy_id?: number;
is_penalty_calculated?: boolean;
calculate_penalty?: boolean;
apply_late_policy?: boolean;

// Deadline toggles
use_signup_deadline?: boolean;
use_drop_topic_deadline?: boolean;
use_team_formation_deadline?: boolean;

// Rubric weights / notification limits
weights?: number[];
notification_limits?: number[];
use_date_updater?: boolean[];

// Per-deadline permissions
submission_allowed?: boolean[];
review_allowed?: boolean[];
teammate_allowed?: boolean[];
metareview_allowed?: boolean[];
reminder?: number[];

// Misc flags from the form
allow_tag_prompts?: boolean;
course_id?: number;
has_quizzes?: boolean;
calibration_for_training?: boolean;
available_to_students?: boolean;
allow_topic_suggestion_from_students?: boolean;
enable_bidding_for_topics?: boolean;
enable_bidding_for_reviews?: boolean;
enable_authors_to_review_other_topics?: boolean;
allow_reviewer_to_choose_topic_to_review?: boolean;
allow_participants_to_create_bookmarks?: boolean;
auto_assign_mentors?: boolean;
staggered_deadline_assignment?: boolean;

// These are used only in tables / dynamic fields
questionnaire?: any;
date_time?: any[];
}
</syntaxhighlight>
</small>

== Testing ==
Another goal for this project as a continuation was to expand our test suite for the tabbed view from E2558. The test file for <code>AssignmentEditor.tsx</code> is currently in the same <code>src/pages/Assignments</code> directory and is named <code>AssignmentEditor.test.tsx</code>. It uses Jest and React testing libraries and mocks to ensure the AssignmentEditor renders properly and that it displays all of the proper tabs and form fields. The tests also cover tab switching and UI updates when certain checkboxes are selected.

=== Sample Test Code ===
==== Render Framework ====
<small>
<syntaxhighlight lang="typescript">
const renderComponent = (mode: 'create' | 'update' = 'create') => {
const store = createMockStore();
return render(
<Provider store={store}>
<BrowserRouter>
<AssignmentEditor mode={mode} />
</BrowserRouter>
</Provider>
);
};
</syntaxhighlight>
</small>

==== Specific Render Test Example ====
<small>
<syntaxhighlight lang="typescript">
it('renders Review strategy tab with select', () => {
renderComponent();
const reviewStrategyTab = screen.getByText('Review strategy');
fireEvent.click(reviewStrategyTab);
expect(screen.getByTestId('select-review_strategy')).toBeInTheDocument();
});
</syntaxhighlight>
</small>

==== Mock Example ====
<small>
<syntaxhighlight lang="typescript">
jest.mock('components/Form/FormSelect', () => ({
__esModule: true,
default: ({ name, options }: any) => (
<select data-testid={`select-${name}`}>
{options?.map((opt: any) => (
<option key={opt.value} value={opt.value}>
{opt.label}
</option>
))}
</select>
),
}));
</syntaxhighlight>
</small>

== Team Members ==
* Keyur Gondhalekar
* Nishad Tardalkar
* Evan Shea
* Mentor: Koushik Gudipelly

== Additional Resources ==
* [https://www.youtube.com/watch?v=SPI0XYOWGZc Video demo (Youtube)]

=== Current Project Repos and Pull Requests ===
* [https://github.com/KeyurGondhalekar/reimplementation-front-end Front-end reimplementation]
* [https://github.com/expertiza/reimplementation-front-end/pull/129/ Front-end pull request]
* [https://github.com/KeyurGondhalekar/reimplementation-back-end Back-end reimplementation]
* [https://github.com/KeyurGondhalekar/reimplementation-back-end/ Back-end pull request]

=== Prior Project (E2558) ===
* [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2025_-_E2558._Tabbed_view_for_creating_and_editing_assignments E2558 Wiki Page]
* [https://github.com/expertiza/reimplementation-front-end Current front-end implementation repo]
* [https://github.com/expertiza/reimplementation-back-end Current back-end implementation repo]

CSC/ECE 517 Fall 2025 - E2566. Finish DueDates

2025-12-06T01:32:38Z

Admin: /* Proposed Solution */

== Introduction ==

=== Background ===

This project aims to complete the implementation of the DueDate system in Expertiza. The current implementation consists mostly of class methods and lacks proper definition of different deadline types and permission checking functionality. This redesign will create a more robust, readable, and maintainable due date system.

=== Existing Components ===
* <code>DueDate</code> model with polymorphic parent association (Assignment/SignUpTopic)
* <code>AssignmentDueDate</code> and <code>TopicDueDate</code> subclasses
* Basic CRUD operations (within <code>Assignment</code> and <code>AssignmentForm</code>) and sorting functionality (<code>deadline_sort</code>)
* Database schema with <code>deadline_type_id</code> field

=== Current Behavior ===

====Admin's View====
[[File:Duedates.png|800px]]

When editing an assignment, due dates can be modified under the Due Dates tab. Each row contains the following columns: <code>Date & Time</code>, <code>Use Date Updater</code>, <code>Submission Allowed</code>, <code>Review Allowed</code>, <code>Teammate Review Allowed</code>, <code>Meta-Review Allowed</code>, and <code>Reminder</code>.

[[File:Assignments-CurrentStage.png|800px]]

In the Assignments tab, the current stage and stage deadline of each assignment is displayed.

[[File:Due-date-topic-instructor.png|800px]]

[[File:Due-date-topic-instructor-2.png|800px]]

In the Topics subtab, due dates for each topic are displayed.

====Student's View====
[[File:Student-assignments.png|800px]]

Students can view due date information under <code>Current State</code> and <code>Stage Deadline</code>. The actions available to students are determined by the current DueDate status.

[[File:Student-duedate-not-over.png|800px]]

During the submission period, students can access the <code>Submit a hyperlink</code> and <code>Submit a file</code> sections.

[[File:Student-duedate-over.png|800px]]

Once the due date has passed, students cannot submit either a hyperlink or a file.

=== Motivation ===

Currently, there are some glaring issues with how due_dates was created in the first place, including redundancy and lack of modularity.

'''Modeling & Structural Issues'''
# No dedicated <code>DeadlineType</code> model to define different kinds of deadlines. The existing <code>DeadlineType</code> class only serves as an association for <code>AssignmentDueDate</code> and <code>TopicDueDate</code> models, and is never referenced in the current <code>DueDate</code> implementation.
# Duplicate <code>team_formation</code> entries in <code>deadline_types</code> table, which may lead to potential bugs.
# Incomplete deadline type definitions — <code>teammate_review</code>, <code>quiz</code> need to be added.
# No clear separation of concerns — data persistence, business logic, and permission logic are mixed in a single model.

'''Permission & Behavior Issues'''
# Overuse of class methods making the code difficult to maintain.
# Missing permission checking logic for user actions that combines both role-based and time-based constraints.

=== Tasks Identified ===

'''Modeling & Structural'''
# Refactor the <code>DueDate</code> model to separate persistence, business logic, and permission logic into distinct layers.
# Implement reusable mixins (<code>DueDatePermissions</code>, <code>DueDateActions</code>) to handle permission evaluation and deadline-related operations.
# Introduce instance-level methods (e.g., <code>next_due_date</code>, <code>copy</code>) to replace class-level utilities and improve testability.

'''Permission & Behavior'''
# Integrate role-based and time-based permission checks within <code>DueDate</code> and <code>Participant</code> to ensure consistent access control.
# Redesign the <code>DeadlineType</code> model to act as the single source of truth for all deadline categories, replacing hard-coded IDs and redundant entries.
# Add missing deadline types (<code>teammate_review</code>, <code>quiz</code>) and remove duplicate <code>team_formation</code> entries for data integrity.

== Proposed Solution ==

The proposed solution restructures the due date system by separating concerns across dedicated models and mixin modules. Deadline definitions (<code>DeadlineType</code>, <code>DeadlineRight</code>), core deadline data (<code>DueDate</code>), and behavioral logic (<code>DueDateActions</code>, <code>DueDatePermissions</code>) are isolated so each component has a single clear responsibility. This modular design improves readability, reduces coupling, and makes deadline-related behavior easier to extend and maintain.

=== Architecture Overview ===

[[File:Duedate-diagram.png|800px]]

This diagram visualizes the redesigned architecture with five distinct layers:

* '''Layer 1 (Blue)''': Parent models (Assignment, SignUpTopic) that own due dates
* '''Layer 2 (Orange)''': DueDateActions module providing action-level queries
* '''Layer 3 (Red)''': DueDate model managing core deadline data
* '''Layer 4 (Orange)''': DueDatePermissions module evaluating permissions
* '''Layer 5 (Green)''': Reference data models (DeadlineType, DeadlineRight, Participant)

The flow works as follows: Parent models include DueDateActions, which queries DueDate objects. Each DueDate includes DueDatePermissions to evaluate whether actions are allowed based on DeadlineRight states and Participant role flags.

=== DeadlineType Model ===

==== Current Problems ====

Although the current codebase includes a <code>DeadlineType</code> model, it only serves as a passive lookup table. In practice, most parts of the system still rely on hard-coded numeric IDs or manual lookups:

<syntaxhighlight lang="ruby">
# Example of current usage
deadline_type_id = DeadlineType.find_by(name: 'review').id
if due_date.deadline_type_id == deadline_type_id
# Perform review-related logic
end
</syntaxhighlight>

This leads to several structural issues:
* Inconsistent references (some use IDs, others strings)
* Tight coupling between <code>DueDate</code> and <code>deadline_type_id</code>
* Lack of semantic helper methods (e.g., <code>review?</code>, <code>submission?</code>)
* Data duplication and integrity risks (two <code>team_formation</code> rows)

==== Database Schema ====

{| class="wikitable"
|+ <code>deadline_types</code> Table Structure
|-
! Column !! Type !! Description
|-
| id || BIGINT || Primary key, referenced by <code>due_dates.deadline_type_id</code>
|-
| name || VARCHAR(255) || Unique symbolic name (e.g., <code>submission</code>, <code>review</code>)
|-
| description || TEXT || Human-readable explanation of the deadline category
|-
| created_at || TIMESTAMP || Creation timestamp
|-
| updated_at || TIMESTAMP || Last update timestamp
|}

==== Deadline Type Definitions ====

{| class="wikitable"
|+ Canonical Deadline Type Entries
|-
! ID !! Name !! Description
|-
| 1 || submission || Student submission deadlines
|-
| 2 || review || Peer review deadlines
|-
| 3 || teammate_review || Team member evaluation deadlines
|-
| 5 || metareview || Meta-review deadlines (backward compatibility)
|-
| 6 || drop_topic || Topic drop deadlines
|-
| 7 || signup || Topic signup deadlines
|-
| 8 || team_formation || Team formation deadlines (duplicate cleaned)
|-
| 11 || quiz || Quiz completion deadlines
|}

=== DeadlineRight Model ===

==== Purpose ====

The <code>DeadlineRight</code> model represents the permission level for a specific action at a given deadline:

* '''OK''': Action is allowed without penalty
* '''Late''': Action is allowed but marked as late
* '''No''': Action is not permitted

These values are referenced by <code>DueDate</code> through fields such as <code>submission_allowed_id</code>, <code>review_allowed_id</code>, and <code>quiz_allowed_id</code>.

==== Database Schema ====

{| class="wikitable"
|+ <code>deadline_rights</code> Table Structure
|-
! Column !! Type !! Description
|-
| id || BIGINT || Primary key, referenced by <code>due_dates.*_allowed_id</code> fields
|-
| name || VARCHAR(255) || Unique permission name (<code>No</code>, <code>Late</code>, <code>OK</code>)
|-
| created_at || TIMESTAMP || Creation timestamp
|-
| updated_at || TIMESTAMP || Last update timestamp
|}

=== DueDate Model Refactoring ===

==== Current Problems ====

The <code>DueDate</code> model currently mixes persistence logic, deadline calculation, and permission checking, violating the Single Responsibility Principle. Most of its logic is implemented as class methods, which makes testing and extension difficult.

<syntaxhighlight lang="ruby">
# Old design: class method that mixes concerns
def self.copy(old_assignment_id, new_assignment_id)
duedates = where(parent_id: old_assignment_id)
duedates.each do |orig_due_date|
new_due_date = orig_due_date.dup
new_due_date.parent_id = new_assignment_id
new_due_date.save
end
end
</syntaxhighlight>

==== Improved Design ====

The redesigned <code>DueDate</code> model is focused on representing a single deadline entry. Behavior has been extracted into appropriate modules:

{| class="wikitable"
|+ Responsibility Distribution After Refactoring
|-
! Concern !! Where It Lives
|-
| Permission checking || <code>DueDatePermissions</code> module (included in DueDate)
|-
| Deadline-related actions || <code>DueDateActions</code> module (included in parent models)
|-
| Deadline type semantics || <code>DeadlineType</code> model
|-
| Core deadline data || <code>DueDate</code> model
|}

Key improvements:
* '''Instance-based behavior''': Replaced class methods with instance methods
* '''Clear query methods''': Simple predicates like <code>upcoming?</code>, <code>overdue?</code>
* '''Scopes for common queries''': <code>.upcoming</code>, <code>.overdue</code>, <code>.for_round</code>, <code>.for_deadline_type</code>

=== DueDatePermissions Module ===

==== Current Problems ====

Currently, permission checks are split into two disconnected layers:

'''Role-based permissions''' (in participant_helpers.rb):
<syntaxhighlight lang="ruby">
def participant_permissions(authorization)
case authorization
when 'reader' then { can_submit: false, can_review: true, can_take_quiz: true }
# ...
end
end
</syntaxhighlight>

'''Deadline-based checks''' (in Assignment model):
<syntaxhighlight lang="ruby">
def submission_allowed(topic_id = nil)
check_condition('submission_allowed_id', topic_id)
end
</syntaxhighlight>

These two layers never interact, leading to inconsistencies.

==== Proposed Solution ====

The <code>DueDatePermissions</code> module integrates both layers:

{| class="wikitable"
|+ Permission Methods
|-
! Method !! What It Checks
|-
| <code>can_submit?(participant)</code> || Submission deadline is OK/Late AND participant can submit
|-
| <code>can_review?(participant)</code> || Review deadline is OK/Late AND participant can review
|-
| <code>can_take_quiz?(participant)</code> || Quiz deadline is OK/Late AND participant can take quiz
|-
| <code>can_review_teammate?(participant)</code> || Teammate review deadline is OK/Late AND participant can review
|-
| <code>activity_permissible?(activity)</code> || Generic checker for any activity
|-
| <code>permission_status_for(action)</code> || Returns 'OK', 'Late', or 'No' for display
|}

=== DueDateActions Module ===

The <code>DueDateActions</code> module provides a unified interface for models that own due dates (<code>Assignment</code> and <code>SignUpTopic</code>). This centralizes the logic for querying upcoming deadlines and determining whether specific activities are currently allowed.

==== Proposed Solution ====

{| class="wikitable"
|+ Methods in DueDateActions
|-
! Method !! Purpose
|-
| <code>activity_permissible?(activity)</code> || Checks if an activity is permitted at the current time
|-
| <code>submission_permissible?</code> || Convenience wrapper for submission checking
|-
| <code>review_permissible?</code> || Convenience wrapper for review checking
|-
| <code>next_due_date(topic_id)</code> || Returns the next applicable deadline (which may or may not be specific to the ProjectTopic the team has chosen)
|-
| <code>current_stage</code> || Returns human-readable stage name (e.g., "review", "submission")
|-
| <code>has_topic_specific_deadlines?</code> || Determines if assignment uses topic-specific deadlines
|-
| <code>copy_due_dates_to(new_parent)</code> || Utility for cloning due dates to another assignment
|}

==== Deadline Resolution Flow ====

{| class="wikitable"
|+ How next_due_date Works
|-
! Step !! Description
|-
| 1. Topic-specific check || If topic ID provided and assignment uses staggered deadlines, check topic-level deadlines first
|-
| 2. Assignment-level fallback || If no topic deadline exists, use nearest assignment-level deadline
|-
| 3. Permission evaluation || Delegate to DueDatePermissions to determine if action is allowed
|}

== Implementation Summary ==

=== Models Created/Modified ===

* '''DeadlineType''' — Canonical deadline type definitions with semantic helper methods
* '''DeadlineRight''' — Permission state model (OK/Late/No) with comparison methods
* '''DueDate''' — Refactored with instance methods, scopes, and permission checking
* '''TopicDueDate''' — STI subclass for topic-specific deadlines
* '''Assignment''' — Includes DueDateActions mixin
* '''SignUpTopic''' — Includes DueDateActions mixin

=== Modules Created ===

* '''DueDatePermissions''' — Permission checking combining deadline and role constraints
* '''DueDateActions''' — Deadline-related operations for parent models

=== Key Improvements ===

# '''Separation of Concerns''': Permission logic separated into dedicated modules
# '''Instance Methods''': Replaced class methods with testable instance methods
# '''Polymorphic Design''': Single DueDate model serves both Assignment and SignUpTopic
# '''Unified Permissions''': Role-based and time-based checks combined in one interface
# '''Data Integrity''': Removed duplicate deadline types, enforced foreign key constraints

== Testing ==

This test suite provides coverage for both the Assignment model and the DueDate model.
The Assignment tests also exercise all behaviors provided by the DueDateActions mixin, since that module is included directly in the Assignment class.

The tests are designed to verify how deadlines influence allowed activities (submission, review, quiz, etc.), how the system determines the next relevant deadline, and how deadlines are ordered.

=== Coverage Summary ===

==== Assignment (DueDateActions mixin included) ====
The Assignment spec validates:

activity permission logic:
* <code>activity_permissible?</code> – evaluates permissions using the next upcoming deadline
* <code>activity_permissible_for?</code> – finds the most recent past deadline relative to a specific time

deadline-based navigation:
* <code>next_due_date</code>
* <code>deadlines_properly_ordered?</code>

delegation helpers such as:
* <code>submission_permissible?</code>
* <code>review_permissible?</code>

These tests ensure that Assignment correctly interprets the state of its associated due dates.

==== DueDate Model ====
The DueDate spec validates:

required field validations (parent, due_at, deadline_type_id)
round field rules (cannot be zero or negative, sets default when nil)
scopes:
* <code>.upcoming</code>
* <code>.overdue</code>
* <code>.for_round</code>
* <code>.for_deadline_type</code>

instance methods:
* <code>#overdue?</code>, <code>#upcoming?</code>, <code>#set</code>, <code>#copy</code>, <code>#deadline_type_name</code>, <code>#last_deadline?</code>, <code>#<=></code>

class methods:
* <code>.sort_due_dates</code>, <code>.any_future_due_dates?</code>, <code>.copy</code>

callback:
* <code>before_save :set_default_round</code>

=== Rationale for Test Design ===

The test suites for DueDate and Assignment (including DueDateActions) are designed to validate two different layers of behavior:
* DueDate tests verify record-level behavior: validations, scopes, and individual instance methods.
* Assignment tests verify behavior that depends on collections of due dates, such as selecting the next deadline or determining whether an activity is permissible.

All tests use real database records (DeadlineType, DeadlineRight, DueDate) to ensure that associations, validations, and permission checks reflect real application behavior.

=== Test Structure ===

The suite uses nested RSpec contexts:

<syntaxhighlight lang="ruby">
describe 'activity_permissible_for?' do
context 'when past deadline exists' do
it 'returns permission from most recent past deadline'
end

context 'when only future deadlines exist' do
it 'returns false'
end
end </syntaxhighlight>

Contexts clearly describe the situation being tested, while individual examples describe expected behaviors.

== Demo ==

=== Demo Video ===

[https://youtu.be/sTrVRGSaBlE Click to watch on YouTube]

== Future Work ==

* Add deadline notification system using the new permission framework
* Implement deadline templates for common assignment patterns
* Add API endpoints for mobile app integration
* Create admin dashboard for monitoring deadline compliance across courses
* Add automated deadline extension workflows based on configurable rules

CSC/ECE 517 Fall 2025 - E2560. Framework for Import and Export

2025-12-06T00:35:52Z

Admin: /* Approach */

== Important Note ==
The user db schema is being changed soon. It will be removing the field <code>full_name</code> and adding the field <code>username</code>. Since our implementation mirrors fields from the db, the following will need to be changed:

* In <code>app/models/user.rb</code>, change line 5 to match this: <code>mandatory_fields :name, :email, :password, :username</code>

== Introduction ==
The export/import functionality is one of the most valuable tools for instructors when setting up assignments in Expertiza. Instructors often have lists of students, teams, and other data from their learning management systems. The ability to seamlessly export and import this data into Expertiza significantly reduces setup time and effort.

* '''Import Functionality Video''' — https://youtu.be/OYMAJIws0gI
* '''Export Functionality Video''' — https://youtu.be/vhzYiPaoAK8

== Objective ==
The previous version of Expertiza offered multiple export and import features—for example, exporting students, teams, rubrics, topics, and more. These features typically retrieve data from the database and save it in a specified format. However, the same logic is often duplicated across different implementations for various data types.

The goal of this project is to design and implement a generic export/import framework that can handle various types of data based on input parameters. It will create a module that accepts database table names and column names to determine what data should be exported or imported. This module should be flexible and reusable across all export/import features in Expertiza.

== Approach ==

The challenge of this project was making sure our functionality was generic. It needed to be able to run for any class that required it, with the necessary fields and other configuration details. To handle this challenge, we decided to create an overall service that would handle all cases of importing and exporting. To facilitate this, we created a mixin for classes that want to be able to import and export. This mixin provides a place to declare mandatory fields for import/export, and provides functions to facilitate it. The service uses the functions to generically handle any case.

In the case of duplicate data being entered into the system (e.g., two users with the same username), we choose to go with a strategy approach. We created actions for handling duplicates that can be added to each class. Users can't choose between these actions in the frontend, and the chosen action is then performed if a duplicate is found. This initially includes skipping duplicates, changing the offending field, or updating the record. We have left it so that more actions can be created if there are other cases.

== Design Document ==
=== Class Diagram ===
[[File:CSC517Final_5.png|1200px]]

==== How It Fits Together ====

When importing a file (through <code>import_controller.rb</code>), the request passes the file, the class being imported to, the fields in order, a bool telling whether to use the headers in the CSV or not, and a selected duplicate action. The import service (<code>Import.rb</code>) takes these values and passes them to the <code>#try_import_record</code> function included in the <code>importable_exportable_helper.rb</code>. This function goes through each row and calls <code>#import_row</code>. Importing each row takes the values in the current row, looks for any associated <code>ExternalClasses</code> that the values reference, and creates an object based on the values. It then tries to save this object. If the object is a duplicate, it is marked as such and not saved to the database yet. If it is not a duplicate, it then tries to create any External classes as specified in the CSV file. For example, the User class looks up the <code>ExternalClass Role</code>, and the Item class creates the <code>ExternalClass QuestionAdvice</code>. Once all the rows have been created in this way, the duplicate records are passed back out to the service to be dealt with. Each duplicate record has its existing counterpart found in the database, and is then dealt with by the duplicate action that the user selected when importing the file. Once those are dealt with, the result of the import is passed back through the controller to the user as a success.

When exporting a file (through <code>export_controller.rb</code>), the request passes the order of the headers and the class being imported. These are passed to the export service (<code>Export.rb</code>). The export service puts all the headers into a CSV, then picks out the values associated with the base class (ie. the fields of the User class), and puts them into an array. It then goes through each of those classes <code>ExternalClasses</code>, gets the values, and places them in the CSV. After the same has been done to every row, this CSV is passed back to the <code>export_controller.rb</code>, and given to the user successfully.

=== Architecture ===
The system is divided into two main layers:

* '''Backend''' — Handles import/export logic, data validation, and duplicate record management.
* '''Frontend''' — Provides user interfaces for triggering imports and exports, communicating with backend controllers.
----
==== Backend Components ====

===== FieldMapping =====
Represents the relationship between class fields and their corresponding data columns.
* '''''Attributes:'''''
** <code>class: Class</code> — The associated class for data mapping.
** <code>ordered_fields: Array[String]</code> — Field order for import/export operations.

===== DuplicateAction (Mixin) =====
Defines actions to take when duplicate records are detected.
* '''''Attributes'''''
** <code>name: String</code> — Name of the duplicate action.
* '''''Methods:'''''
** <code>on_duplicate_record()</code> — Handles logic when a duplicate record is found.

===== ImportableExportable (Mixin) =====
Provides shared functionality for classes that can be imported or exported.
* '''''Attributes:'''''
** <code>mandatory_fields: Array[String]</code> — Fields required for processing.
** <code>optional_fields: Array[String]</code> — Fields that can optionally be included.
** <code>available_duplicate_actions: Array[DuplicateAction]</code> — List of supported duplicate handling strategies.
* '''''Methods:'''''
** <code>register_detail(class, field: String)</code>
** <code>try_insert_record(DuplicateAction)</code>
** <code>is_duplicate_record()</code>
** <code>get_detail_field(record, detail_class, detail_field: String)</code>
** <code>to_hash()</code>

===== ImportExportManager =====
Acts as the central interface for managing import and export workflows.
* '''''Methods:'''''
** <code>export(class, mapping: FieldMapping, filename: String)</code> — Exports class data based on mapping.
** <code>import(class, mapping: FieldMapping, filename: String, use_header: bool)</code> — Imports data into the specified class.
** <code>default_mapping(class)</code> — Retrieves the default mapping configuration.
** <code>suggest_filename(class, mode: String)</code> — Suggests a filename based on class and mode.

===== ImportController =====
Handles import-related HTTP requests.
* '''''Endpoints:'''''
** <code>index</code> — Returns import configuration data.
** <code>import</code> — Accepts incoming data and triggers import operations.
* '''''Interactions:'''''
** Sends mandatory and optional fields, as well as available duplicate actions, to the frontend.
** Receives chosen ordered fields and duplicate action from the frontend.

===== ExportController =====
Handles export-related HTTP requests.
* '''''Endpoints:'''''
** <code>index</code> — Provides available export configurations.
** <code>export</code> — Generates export files based on selected parameters.
* '''''Interactions:'''''
** Sends mandatory and optional fields to the frontend.
** Receives chosen ordered fields for export.
----
==== Frontend Components ====

===== Import (.tsx) =====
* '''''Methods:'''''
** <code>on_import</code> — Initiates the import process.
* '''''Interactions:'''''
** Receives mandatory/optional field data and duplicate actions.
** Sends selected ordered fields and chosen duplicate handling action back to the backend.

===== Export (.tsx) =====
* '''''Methods:'''''
** <code>on_export</code> — Initiates the export process.
* '''''Interactions:'''''
** Receives mandatory/optional field data from backend.
** Sends selected ordered fields for export.
----
==== Data Flow ====

===== Import Sequence =====
# Frontend requests import configuration.
# Backend responds with mandatory/optional fields and duplicate actions.
# User selects ordered fields and a duplicate action.
# Frontend sends selections to backend for processing via <code>ImportController.import</code>.

===== Export Sequence =====
# Frontend requests export configuration.
# Backend sends available fields.
# User selects ordered fields to include.
# Frontend sends selections to backend via <code>ExportController.export</code>.
----

=== Use Case Diagram ===
[[File:CSC517FinalUseCases_2.png]]

==== Primary Actor ====

'''Instructor / Administrator'''
* Initiates both import and export operations for any class (e.g., Users, Teams, Rubrics).
* Goal is to efficiently transfer data into or out of the system without requiring separate tools for each entity.

==== Use Cases ====

===== Main Use Cases =====

;Import data for any class from a CSV file
# The actor uploads a CSV file.
# The system reads available headers or prompts the actor to select them.
# The actor confirms header order and selects a duplicate-handling option.
# The system validates data and imports records according to the selected duplicate policy.

;Export data for any class to a CSV file
# The actor selects which fields to include.
# The actor orders these fields as desired.
# The system generates a downloadable CSV file containing the chosen data.

===== Included Use Cases =====

;Choose/Auto Read Headers Included in the File
* When importing, the system attempts to automatically detect headers from the uploaded CSV.
* If headers are missing or unclear, the actor manually specifies them.

;Choose the Order of the Headers
* Applies to both import and export operations.
* The actor arranges the order of headers to ensure correct mapping between CSV columns and database fields.

;Choose Headers that will be Included in the File
* Applies primarily to export operations.
* The actor selects specific headers to include in the output CSV file, ensuring only relevant data is exported.

==== Relationships ====

* Both the '''Import''' and '''Export''' use cases include the sub-use cases for choosing headers and their order.
* The actor directly initiates the primary use cases and indirectly interacts with the included ones through system prompts.

==== System Responsibilities ====

* Provide the actor with available class fields and supported duplicate actions.
* Manage CSV validation, field mapping, and record processing.
* Generate clear feedback on import/export results (e.g., success, skipped, or error entries).
----

==== Design Notes ====
The design emphasizes modularity and extensibility because the same flow supports multiple data entities using a unified import/export framework.
* Included use cases ensure flexibility for various file structures and actor preferences.
* Error handling (e.g., missing headers, duplicate data) is encapsulated within the main import process.

== Usage ==

=== Creating CSV for Importing===
----
When creating a CSV that will be imported, there are a few guidelines that should be followed to ensure information is uploaded successfully.

;Guidelines
# CSV should be made with headers that names align with the fields in the program. The names should be in Capital case (ie Name, User id, Txt, etc). These need to align with the program version of the fields (ie. name, user_id, txt) because they will be converted programmatically.
# CSV must include all mandatory fields and necessary external fields. Optional fields may be included as well. To find these, check the import page for the item you are trying to import.
# For Headers that refer to an external class, the class name should be appended to the front of the field. (ex. If a user is trying to reference a Role by its name field, the header should be "Role name", not "name").
# For CSVs that contain Duplicate Headers for External classes (Ex. Items and QuestionAdvice), make sure the external class appears in the CSV grouped together and in sequence.

=== Importing a File ===
----
The Import Modal is a reusable modal used to upload CSV files for different models (Items, Teams, Users, Assignments, etc.).
----
; Opening the Import Modal
:* From the relevant page (e.g., Items index), click the Import button. This opens the Import <ModelName> modal.
:* As soon as the modal opens, the frontend automatically calls:
:*: GET /import/<modelClass> to fetch import metadata for that model. This metadata is what populates the lists at the top of the modal.
; Field Requirements
:* At the top of the modal you’ll see three lists:
:# Mandatory fields – columns that must be present in your import for it to succeed.
:# Optional fields – extra columns you may include if you have that data.
:# External fields – related fields that can be pulled from or linked to other records (e.g., questionnaire_name, question_advice_id, etc.)
:* These lists are read-only and meant to guide how you structure your CSV.
[[File:ImportFrontend.png|600px]]
; Selecting a CSV
:* Under CSV file:
:# Click Choose File and select your .csv file.
:# Decide whether your file’s first row is a header row:
:#* First row contains headers (switch ON)
:#** Use this if your first row has column names like txt, weight, seq.
:#** The backend will match CSV headers to field names automatically.
:#* First row contains headers (switch OFF)
:#** Use this if your file has no header row (just data).
[[File:UploadFile.png|600px]]
; Manual Column Mapping
:* If “First row contains headers” is OFF, the modal:
:** Reads the first one or two lines from your CSV.
:** For each column, shows:
:*** A dropdown to choose which field this column represents.
:*** A “First Row Value” snippet so you can see an example value from that column.
:* You must:
:*# Go through each column.
:*# Use the dropdown to select the corresponding field name (e.g., map column 1 → txt, column 2 → weight, etc.).
:*# Ensure that all mandatory fields appear in at least one column.
:** If mandatory fields are missing from your selection, the modal will block the import and show a status message.
[[File:ColumnMapping.png|600px]]
; Handling Duplicates
:* In the Duplicate handling section:
:** If the backend has configured options, you’ll see one or more radio buttons (e.g., skip, overwrite).
:** Choose how the system should behave if it encounters duplicate records during the import.
:* If no duplicate options are available, you’ll see: “No duplicate options.”
; Running the Import
:* When everything is set:
:*# Click "import"
:*# The frontend sends a POST /import/<modelClass> request with:
:*#* csv_file – the file you selected.
:*#* use_headers – true or false depending on the toggle.
:*#* ordered_fields – only included if header mode is off, listing the fields you selected for each column.
:* While the request is in progress, the modal shows a loading state.
:* When the response returns, the Status line at the bottom will show either:
:** A success message from the backend (e.g., “Import complete” or a custom message)
:** An error message if something went wrong (e.g., missing mandatory fields, invalid format)
:* You can then close the modal with cancel or by using the close icon.
[[File:ImportComplete.png|600px]]

=== Exporting a File ===
----
; Opening the Export Modal
:* Click the Export button on the page for the model you want to export (e.g., Teams).
:* When the modal opens, it automatically makes a request to:
:*: `GET /export/<modelClass>`
:* to fetch the field metadata for the selected model.
; Field Lists Displayed
:* The modal uses the metadata received from the backend to show three types of fields:
:# Mandatory fields – These must always be included in the export and cannot be unchecked.
:# Optional fields – These may be included in the export at the user’s discretion.
:# External fields – Additional related fields made available for export (if applicable).
:* Users can hover over an info icon to view the full field list in a tooltip.
; Choosing Columns to Export
:* The modal provides a checkbox list of all available fields.
:* Users may:
:# Check or uncheck optional fields.
:# View mandatory fields (locked and always selected).
:# Reorder any fields using ↑ and ↓ arrows, which determines the ordering of columns in the exported CSV.
; Column Ordering
:* Fields appear in the export file in the exact order shown in the modal.
:* The user can:
:# Move any non-mandatory field up.
:# Move any non-mandatory field down.
:* Mandatory fields are always included and their order can also be adjusted if they are part of the list returned by the backend.
; Generating the CSV
:* When satisfied with selections:
:** Click export
:* The frontend gathers:
:** The selected fields
:* It then generates a CSV where:
:** The first row contains the field names (in the chosen order)
:** All following rows contain the corresponding values
:** A downloadable `.csv` file is automatically created and saved to the user’s system.
; Status Feedback
:* The modal displays a status message during and after the export operation, for example:
:# “Generating CSV…”
:# “Export complete”
:* If no fields are selected, the modal will prevent exporting and display a warning.
[[File:ExportFile.png|600px]]

=== Making a class Importable/Exportable ===
==== Backend ====
# Add the Import/Export mixin to the top of the class '<code>extend ImportableExportableHelper</code>'
# Specify which fields are mandatory for import/export (in snake_case)
# Specify any external classes that will need to be looked up or created (ie. looking up the Role of a User by id)
# Specify the available duplicate actions. (By default, the offending fields are transformed.)

[[File:UserEx.png]]

''Example of adding helper to the User model''

'''Note''': If you are adding this helper to a class that has sub classes:
Case 1: If you want the sub classes have the same fields, external classes, and duplicate actions as the super class:
* Do the steps listed above in the super class
* Additionally, do only the first step in the sub class.

Case 2: If you want to specify different fields, external classes, or duplicate actions for sub classes:
* Do not do any of the steps for the super class
* Do all steps for each individual sub class

[[File:ItemEx.png]]

[[File:QuizItemEx.png]]

''Example of Case 1: Adding helper to the Item model, then QuizItem model''

==== Frontend ====
# Create the showModal variable
# Create the handleCloseModal method
# Add the ImportModal or ExportModal to your frontend file. In the tag, add the show variable, onHide method, and the string of the class that is being imported/exported. (ie Model Class User => "User")

== Testing ==

=== Fixtures ===
* <code>empty.csv</code>
*: A completely empty CSV file. This file is used to ensure that if no content is included, the import service will fail gracefully.
* <code>empty_with_headers.csv</code>
*: A CSV file that only contains the headers for the User class. This file is used to ensure a file with no records is handled gracefully.
* <code>multiple_users_no_headers.csv</code>
*: A CSV file with no headers for importing records for the User class. It contains multiple User records (John Doe, Jane Doe) to import.
* <code>multiple_users_with_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains multiple User records (John Doe, Jane Doe) to import.
* <code>questionnaire_item_with_headers.csv</code>
*: A CSV file with headers for importing records for the Item class. These Items make up a questionnaire. It contains a single Item that needs to be imported.
* <code>single_user_no_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains a single User (John Doe) who needs to be imported.
* <code>single_user_with_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains a single User (John Doe) who needs to be imported.
* <code>users_duplicate_records.csv</code>
*: A CSV file containing multiple duplicate records that need to be handled.
* <code>single_user_email_invalid.csv</code>
*: A CSV file that contains a user with an invalid email. That is an Internal field that needs to be validated.
* <code>single_user_role_doe_not_exist.csv</code>
*: A CSV file that contains a user with a role that does not exist. That is a field from an External Class that needs to be looked up.

=== Unit Testing ===

----
==== ImportableExportableHelper - Importing ====
----
;Create tests for each of the different importable classes
# Show a class with no headers can be imported (User)
#: This test tries to import the 'single_user_no_headers.csv' file. This file doesn't have headers, so the test passes a list of headers to the import statement. This CSV file calls for the Role Name of the user, which is set to Student. This tests whether the import statement is able to look up a role by its name. It is able to do this because the name is a lookup field for the External Class Role, which is assigned to the User Class.
# Show a class with headers can be imported (User)
#: This test tries to import the 'single_user_with_headers.csv' file. This file has headers, so the test passes nil to the header variable of the import statement. This CSV file calls for the Role ID of the user, which is set to 4 (Teaching Assistant). This tests whether the import statement is able to look up a role by its ID. It can do this even though ID is not the set lookup field, because the lookup function uses the primary key if the lookup field isn't in the file.
# Show a class with multiple records can be imported (User)
#: This test tries to import the 'multiple_users_with_headers.csv' file. This file contains multiple user records that need to be imported (John Doe and Jane Doe). This tests that multiple records successfully get imported with the right information.
# Show a class with external create classes can take duplicate headers (Questionnaire w/ multiple Advice)
#: This test tries to import the 'questionnaire_item_with_headers.csv' file that creates an external class. Not only that, but it can detect if there are multiple instances of this external class and save them individually.

[[File:TestUserNoHeaders.png]]

''Import Export Helper Tests: Test Case 1 Implementation''

[[File:TestQuizItem.png]]

''Import Export Helper Tests: Test Case 4 Implementation''

;Create Tests to test Errors/Edge Cases
# Import a class with external lookup class that doesn't exist
#: Tries to import a csv with an invalid external field. The user's role doesn't exist, so looking up this field should fail and ultimately cause the import to fail.
# Import a class with an invalid field (User with ian nvalid email)
#: Tries to import a csv with an invalid internal field. The user email is validated inside the User class, so make sure that validation raises the correct error.
# Import an empty CSV (With Headers)
#: Tries to import an empty csv with no records inside. This is tested with the <code>use_header</code> option set to true.
# Import an empty CSV (Without Headers)
#: Tries to import an empty csv with nothing inside. This is tested with the <code>use_header</code> option set to false.

[[File:TextLookupBad.png]]

''Import Export Helper Tests: Error Test case 2 and 3 Implementation''

==== ImportExportService - Importing ====
----
;Create tests to make sure the Service works
# Test Get Import: 200 response
#: Test that Import#Index recieves the response, and returns the correct values
# Test Post Import: 200 response
#: Test that Import#Import recieves the response with data, and can return a response.

[[File:TestImportService.png]]

''Import Service Tests: Test case 1 Implementation''

;Create Tests to test Errors/Edge Cases
# Test Post Import: 422 response
# Test Post Import: 500 response

==== ImportExportService - Exporting ====
----
;Create tests for each of the different exportable classes
* Export a class with the default headers
* Export a class with only the mandatory headers
* Export a class with only some optional headers
* Export a class with a different order of headers

;Create tests to test Errors/Edge Cases
* Export a class with chosen headers that are empty

----

=== Frontend Testing ===
----
==== Import Modal ====
----

* Shows loading state when isLoading is true
*: Ensures that when `useAPI` reports `isLoading=true`, the modal hides all content and displays a “Loading…” message.
* Renders field summary and duplicate options from metadata
*: Confirms that metadata returned from the backend (mandatory, optional, external fields, and duplicate handling actions) are rendered correctly in the modal.
* Shows status when importing with no file selected
*: Validates that clicking “import” without choosing a CSV sets an error status message and prevents the import call.
* Shows column mapping and first-row values when header mode is off
*: After uploading a CSV and disabling the “First row contains headers” toggle, verifies that the “Column order” UI appears, column dropdowns are rendered, and the first-row preview text is displayed.
* Calls sendImport when import is valid
*: Uploads a valid CSV containing mandatory fields and clicks “import.” Checks that the `sendRequest` mock is called, proving that the modal sends a correctly prepared API request.
* Calls onHide when cancel is clicked
*: Simulates clicking the “cancel” button and confirms the modal fires the `onHide` callback to close itself.

== Future work ==
* Adding event-based entity registration.
* Extending support for new duplicate resolution policies.
* Integration with the engine demo for visualization and debugging.
* More extensive testing for functionality and edge cases.
* Add a space in the import modal that shows all the values that will be imported.
* Add the helper method across the website wherever the import/export functionality is required.
:* The helper is currently in:
::* QuizItem
::* Item
::* QuestionAdvice
::* Team
::* User

=== Other Notes/Recommendations ===
* For Items, limit the string values that question_type can be using built-in validation rules as well, or else importing will allow just any string.
* For Questionnaires, break_before can't be false because of the validation rules. Maybe try this `validates :break_before, inclusion: { in: [true, false] }`

CSC/ECE 517 Fall 2025 - E2560. Framework for Import and Export

2025-12-06T00:33:44Z

Admin: /* Objective */

== Important Note ==
The user db schema is being changed soon. It will be removing the field <code>full_name</code> and adding the field <code>username</code>. Since our implementation mirrors fields from the db, the following will need to be changed:

* In <code>app/models/user.rb</code>, change line 5 to match this: <code>mandatory_fields :name, :email, :password, :username</code>

== Introduction ==
The export/import functionality is one of the most valuable tools for instructors when setting up assignments in Expertiza. Instructors often have lists of students, teams, and other data from their learning management systems. The ability to seamlessly export and import this data into Expertiza significantly reduces setup time and effort.

* '''Import Functionality Video''' — https://youtu.be/OYMAJIws0gI
* '''Export Functionality Video''' — https://youtu.be/vhzYiPaoAK8

== Objective ==
The previous version of Expertiza offered multiple export and import features—for example, exporting students, teams, rubrics, topics, and more. These features typically retrieve data from the database and save it in a specified format. However, the same logic is often duplicated across different implementations for various data types.

The goal of this project is to design and implement a generic export/import framework that can handle various types of data based on input parameters. It will create a module that accepts database table names and column names to determine what data should be exported or imported. This module should be flexible and reusable across all export/import features in Expertiza.

== Approach ==

The challenge of this project was making sure our functionality was generic. It needed to be able to run for any class that required it, with the necessary fields and other configuration details. To handle this challenge, we decided to create an overall service that would handle all cases of importing and exporting. To facilitate this, we created a mixin for classes that want to be able to import and export. This mixin provides a place to declare mandatory fields for import/export, and provides functions to facilitate it. The service uses the functions to generically handle any case. In the case of duplicate data being entered into the system, we choose to go with a strategy approach. We created actions for handling duplicates that can be added to each class. Users can't choose between these actions in the frontend, and the chosen action is then performed if a duplicate is found. This initially includes skipping duplicates, changing the offending field, or updating the record. We have left it so that more actions can be created if there are other cases.

== Design Document ==
=== Class Diagram ===
[[File:CSC517Final_5.png|1200px]]

==== How It Fits Together ====

When importing a file (through <code>import_controller.rb</code>), the request passes the file, the class being imported to, the fields in order, a bool telling whether to use the headers in the CSV or not, and a selected duplicate action. The import service (<code>Import.rb</code>) takes these values and passes them to the <code>#try_import_record</code> function included in the <code>importable_exportable_helper.rb</code>. This function goes through each row and calls <code>#import_row</code>. Importing each row takes the values in the current row, looks for any associated <code>ExternalClasses</code> that the values reference, and creates an object based on the values. It then tries to save this object. If the object is a duplicate, it is marked as such and not saved to the database yet. If it is not a duplicate, it then tries to create any External classes as specified in the CSV file. For example, the User class looks up the <code>ExternalClass Role</code>, and the Item class creates the <code>ExternalClass QuestionAdvice</code>. Once all the rows have been created in this way, the duplicate records are passed back out to the service to be dealt with. Each duplicate record has its existing counterpart found in the database, and is then dealt with by the duplicate action that the user selected when importing the file. Once those are dealt with, the result of the import is passed back through the controller to the user as a success.

When exporting a file (through <code>export_controller.rb</code>), the request passes the order of the headers and the class being imported. These are passed to the export service (<code>Export.rb</code>). The export service puts all the headers into a CSV, then picks out the values associated with the base class (ie. the fields of the User class), and puts them into an array. It then goes through each of those classes <code>ExternalClasses</code>, gets the values, and places them in the CSV. After the same has been done to every row, this CSV is passed back to the <code>export_controller.rb</code>, and given to the user successfully.

=== Architecture ===
The system is divided into two main layers:

* '''Backend''' — Handles import/export logic, data validation, and duplicate record management.
* '''Frontend''' — Provides user interfaces for triggering imports and exports, communicating with backend controllers.
----
==== Backend Components ====

===== FieldMapping =====
Represents the relationship between class fields and their corresponding data columns.
* '''''Attributes:'''''
** <code>class: Class</code> — The associated class for data mapping.
** <code>ordered_fields: Array[String]</code> — Field order for import/export operations.

===== DuplicateAction (Mixin) =====
Defines actions to take when duplicate records are detected.
* '''''Attributes'''''
** <code>name: String</code> — Name of the duplicate action.
* '''''Methods:'''''
** <code>on_duplicate_record()</code> — Handles logic when a duplicate record is found.

===== ImportableExportable (Mixin) =====
Provides shared functionality for classes that can be imported or exported.
* '''''Attributes:'''''
** <code>mandatory_fields: Array[String]</code> — Fields required for processing.
** <code>optional_fields: Array[String]</code> — Fields that can optionally be included.
** <code>available_duplicate_actions: Array[DuplicateAction]</code> — List of supported duplicate handling strategies.
* '''''Methods:'''''
** <code>register_detail(class, field: String)</code>
** <code>try_insert_record(DuplicateAction)</code>
** <code>is_duplicate_record()</code>
** <code>get_detail_field(record, detail_class, detail_field: String)</code>
** <code>to_hash()</code>

===== ImportExportManager =====
Acts as the central interface for managing import and export workflows.
* '''''Methods:'''''
** <code>export(class, mapping: FieldMapping, filename: String)</code> — Exports class data based on mapping.
** <code>import(class, mapping: FieldMapping, filename: String, use_header: bool)</code> — Imports data into the specified class.
** <code>default_mapping(class)</code> — Retrieves the default mapping configuration.
** <code>suggest_filename(class, mode: String)</code> — Suggests a filename based on class and mode.

===== ImportController =====
Handles import-related HTTP requests.
* '''''Endpoints:'''''
** <code>index</code> — Returns import configuration data.
** <code>import</code> — Accepts incoming data and triggers import operations.
* '''''Interactions:'''''
** Sends mandatory and optional fields, as well as available duplicate actions, to the frontend.
** Receives chosen ordered fields and duplicate action from the frontend.

===== ExportController =====
Handles export-related HTTP requests.
* '''''Endpoints:'''''
** <code>index</code> — Provides available export configurations.
** <code>export</code> — Generates export files based on selected parameters.
* '''''Interactions:'''''
** Sends mandatory and optional fields to the frontend.
** Receives chosen ordered fields for export.
----
==== Frontend Components ====

===== Import (.tsx) =====
* '''''Methods:'''''
** <code>on_import</code> — Initiates the import process.
* '''''Interactions:'''''
** Receives mandatory/optional field data and duplicate actions.
** Sends selected ordered fields and chosen duplicate handling action back to the backend.

===== Export (.tsx) =====
* '''''Methods:'''''
** <code>on_export</code> — Initiates the export process.
* '''''Interactions:'''''
** Receives mandatory/optional field data from backend.
** Sends selected ordered fields for export.
----
==== Data Flow ====

===== Import Sequence =====
# Frontend requests import configuration.
# Backend responds with mandatory/optional fields and duplicate actions.
# User selects ordered fields and a duplicate action.
# Frontend sends selections to backend for processing via <code>ImportController.import</code>.

===== Export Sequence =====
# Frontend requests export configuration.
# Backend sends available fields.
# User selects ordered fields to include.
# Frontend sends selections to backend via <code>ExportController.export</code>.
----

=== Use Case Diagram ===
[[File:CSC517FinalUseCases_2.png]]

==== Primary Actor ====

'''Instructor / Administrator'''
* Initiates both import and export operations for any class (e.g., Users, Teams, Rubrics).
* Goal is to efficiently transfer data into or out of the system without requiring separate tools for each entity.

==== Use Cases ====

===== Main Use Cases =====

;Import data for any class from a CSV file
# The actor uploads a CSV file.
# The system reads available headers or prompts the actor to select them.
# The actor confirms header order and selects a duplicate-handling option.
# The system validates data and imports records according to the selected duplicate policy.

;Export data for any class to a CSV file
# The actor selects which fields to include.
# The actor orders these fields as desired.
# The system generates a downloadable CSV file containing the chosen data.

===== Included Use Cases =====

;Choose/Auto Read Headers Included in the File
* When importing, the system attempts to automatically detect headers from the uploaded CSV.
* If headers are missing or unclear, the actor manually specifies them.

;Choose the Order of the Headers
* Applies to both import and export operations.
* The actor arranges the order of headers to ensure correct mapping between CSV columns and database fields.

;Choose Headers that will be Included in the File
* Applies primarily to export operations.
* The actor selects specific headers to include in the output CSV file, ensuring only relevant data is exported.

==== Relationships ====

* Both the '''Import''' and '''Export''' use cases include the sub-use cases for choosing headers and their order.
* The actor directly initiates the primary use cases and indirectly interacts with the included ones through system prompts.

==== System Responsibilities ====

* Provide the actor with available class fields and supported duplicate actions.
* Manage CSV validation, field mapping, and record processing.
* Generate clear feedback on import/export results (e.g., success, skipped, or error entries).
----

==== Design Notes ====
The design emphasizes modularity and extensibility because the same flow supports multiple data entities using a unified import/export framework.
* Included use cases ensure flexibility for various file structures and actor preferences.
* Error handling (e.g., missing headers, duplicate data) is encapsulated within the main import process.

== Usage ==

=== Creating CSV for Importing===
----
When creating a CSV that will be imported, there are a few guidelines that should be followed to ensure information is uploaded successfully.

;Guidelines
# CSV should be made with headers that names align with the fields in the program. The names should be in Capital case (ie Name, User id, Txt, etc). These need to align with the program version of the fields (ie. name, user_id, txt) because they will be converted programmatically.
# CSV must include all mandatory fields and necessary external fields. Optional fields may be included as well. To find these, check the import page for the item you are trying to import.
# For Headers that refer to an external class, the class name should be appended to the front of the field. (ex. If a user is trying to reference a Role by its name field, the header should be "Role name", not "name").
# For CSVs that contain Duplicate Headers for External classes (Ex. Items and QuestionAdvice), make sure the external class appears in the CSV grouped together and in sequence.

=== Importing a File ===
----
The Import Modal is a reusable modal used to upload CSV files for different models (Items, Teams, Users, Assignments, etc.).
----
; Opening the Import Modal
:* From the relevant page (e.g., Items index), click the Import button. This opens the Import <ModelName> modal.
:* As soon as the modal opens, the frontend automatically calls:
:*: GET /import/<modelClass> to fetch import metadata for that model. This metadata is what populates the lists at the top of the modal.
; Field Requirements
:* At the top of the modal you’ll see three lists:
:# Mandatory fields – columns that must be present in your import for it to succeed.
:# Optional fields – extra columns you may include if you have that data.
:# External fields – related fields that can be pulled from or linked to other records (e.g., questionnaire_name, question_advice_id, etc.)
:* These lists are read-only and meant to guide how you structure your CSV.
[[File:ImportFrontend.png|600px]]
; Selecting a CSV
:* Under CSV file:
:# Click Choose File and select your .csv file.
:# Decide whether your file’s first row is a header row:
:#* First row contains headers (switch ON)
:#** Use this if your first row has column names like txt, weight, seq.
:#** The backend will match CSV headers to field names automatically.
:#* First row contains headers (switch OFF)
:#** Use this if your file has no header row (just data).
[[File:UploadFile.png|600px]]
; Manual Column Mapping
:* If “First row contains headers” is OFF, the modal:
:** Reads the first one or two lines from your CSV.
:** For each column, shows:
:*** A dropdown to choose which field this column represents.
:*** A “First Row Value” snippet so you can see an example value from that column.
:* You must:
:*# Go through each column.
:*# Use the dropdown to select the corresponding field name (e.g., map column 1 → txt, column 2 → weight, etc.).
:*# Ensure that all mandatory fields appear in at least one column.
:** If mandatory fields are missing from your selection, the modal will block the import and show a status message.
[[File:ColumnMapping.png|600px]]
; Handling Duplicates
:* In the Duplicate handling section:
:** If the backend has configured options, you’ll see one or more radio buttons (e.g., skip, overwrite).
:** Choose how the system should behave if it encounters duplicate records during the import.
:* If no duplicate options are available, you’ll see: “No duplicate options.”
; Running the Import
:* When everything is set:
:*# Click "import"
:*# The frontend sends a POST /import/<modelClass> request with:
:*#* csv_file – the file you selected.
:*#* use_headers – true or false depending on the toggle.
:*#* ordered_fields – only included if header mode is off, listing the fields you selected for each column.
:* While the request is in progress, the modal shows a loading state.
:* When the response returns, the Status line at the bottom will show either:
:** A success message from the backend (e.g., “Import complete” or a custom message)
:** An error message if something went wrong (e.g., missing mandatory fields, invalid format)
:* You can then close the modal with cancel or by using the close icon.
[[File:ImportComplete.png|600px]]

=== Exporting a File ===
----
; Opening the Export Modal
:* Click the Export button on the page for the model you want to export (e.g., Teams).
:* When the modal opens, it automatically makes a request to:
:*: `GET /export/<modelClass>`
:* to fetch the field metadata for the selected model.
; Field Lists Displayed
:* The modal uses the metadata received from the backend to show three types of fields:
:# Mandatory fields – These must always be included in the export and cannot be unchecked.
:# Optional fields – These may be included in the export at the user’s discretion.
:# External fields – Additional related fields made available for export (if applicable).
:* Users can hover over an info icon to view the full field list in a tooltip.
; Choosing Columns to Export
:* The modal provides a checkbox list of all available fields.
:* Users may:
:# Check or uncheck optional fields.
:# View mandatory fields (locked and always selected).
:# Reorder any fields using ↑ and ↓ arrows, which determines the ordering of columns in the exported CSV.
; Column Ordering
:* Fields appear in the export file in the exact order shown in the modal.
:* The user can:
:# Move any non-mandatory field up.
:# Move any non-mandatory field down.
:* Mandatory fields are always included and their order can also be adjusted if they are part of the list returned by the backend.
; Generating the CSV
:* When satisfied with selections:
:** Click export
:* The frontend gathers:
:** The selected fields
:* It then generates a CSV where:
:** The first row contains the field names (in the chosen order)
:** All following rows contain the corresponding values
:** A downloadable `.csv` file is automatically created and saved to the user’s system.
; Status Feedback
:* The modal displays a status message during and after the export operation, for example:
:# “Generating CSV…”
:# “Export complete”
:* If no fields are selected, the modal will prevent exporting and display a warning.
[[File:ExportFile.png|600px]]

=== Making a class Importable/Exportable ===
==== Backend ====
# Add the Import/Export mixin to the top of the class '<code>extend ImportableExportableHelper</code>'
# Specify which fields are mandatory for import/export (in snake_case)
# Specify any external classes that will need to be looked up or created (ie. looking up the Role of a User by id)
# Specify the available duplicate actions. (By default, the offending fields are transformed.)

[[File:UserEx.png]]

''Example of adding helper to the User model''

'''Note''': If you are adding this helper to a class that has sub classes:
Case 1: If you want the sub classes have the same fields, external classes, and duplicate actions as the super class:
* Do the steps listed above in the super class
* Additionally, do only the first step in the sub class.

Case 2: If you want to specify different fields, external classes, or duplicate actions for sub classes:
* Do not do any of the steps for the super class
* Do all steps for each individual sub class

[[File:ItemEx.png]]

[[File:QuizItemEx.png]]

''Example of Case 1: Adding helper to the Item model, then QuizItem model''

==== Frontend ====
# Create the showModal variable
# Create the handleCloseModal method
# Add the ImportModal or ExportModal to your frontend file. In the tag, add the show variable, onHide method, and the string of the class that is being imported/exported. (ie Model Class User => "User")

== Testing ==

=== Fixtures ===
* <code>empty.csv</code>
*: A completely empty CSV file. This file is used to ensure that if no content is included, the import service will fail gracefully.
* <code>empty_with_headers.csv</code>
*: A CSV file that only contains the headers for the User class. This file is used to ensure a file with no records is handled gracefully.
* <code>multiple_users_no_headers.csv</code>
*: A CSV file with no headers for importing records for the User class. It contains multiple User records (John Doe, Jane Doe) to import.
* <code>multiple_users_with_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains multiple User records (John Doe, Jane Doe) to import.
* <code>questionnaire_item_with_headers.csv</code>
*: A CSV file with headers for importing records for the Item class. These Items make up a questionnaire. It contains a single Item that needs to be imported.
* <code>single_user_no_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains a single User (John Doe) who needs to be imported.
* <code>single_user_with_headers.csv</code>
*: A CSV file with headers for importing records for the User class. It contains a single User (John Doe) who needs to be imported.
* <code>users_duplicate_records.csv</code>
*: A CSV file containing multiple duplicate records that need to be handled.
* <code>single_user_email_invalid.csv</code>
*: A CSV file that contains a user with an invalid email. That is an Internal field that needs to be validated.
* <code>single_user_role_doe_not_exist.csv</code>
*: A CSV file that contains a user with a role that does not exist. That is a field from an External Class that needs to be looked up.

=== Unit Testing ===

----
==== ImportableExportableHelper - Importing ====
----
;Create tests for each of the different importable classes
# Show a class with no headers can be imported (User)
#: This test tries to import the 'single_user_no_headers.csv' file. This file doesn't have headers, so the test passes a list of headers to the import statement. This CSV file calls for the Role Name of the user, which is set to Student. This tests whether the import statement is able to look up a role by its name. It is able to do this because the name is a lookup field for the External Class Role, which is assigned to the User Class.
# Show a class with headers can be imported (User)
#: This test tries to import the 'single_user_with_headers.csv' file. This file has headers, so the test passes nil to the header variable of the import statement. This CSV file calls for the Role ID of the user, which is set to 4 (Teaching Assistant). This tests whether the import statement is able to look up a role by its ID. It can do this even though ID is not the set lookup field, because the lookup function uses the primary key if the lookup field isn't in the file.
# Show a class with multiple records can be imported (User)
#: This test tries to import the 'multiple_users_with_headers.csv' file. This file contains multiple user records that need to be imported (John Doe and Jane Doe). This tests that multiple records successfully get imported with the right information.
# Show a class with external create classes can take duplicate headers (Questionnaire w/ multiple Advice)
#: This test tries to import the 'questionnaire_item_with_headers.csv' file that creates an external class. Not only that, but it can detect if there are multiple instances of this external class and save them individually.

[[File:TestUserNoHeaders.png]]

''Import Export Helper Tests: Test Case 1 Implementation''

[[File:TestQuizItem.png]]

''Import Export Helper Tests: Test Case 4 Implementation''

;Create Tests to test Errors/Edge Cases
# Import a class with external lookup class that doesn't exist
#: Tries to import a csv with an invalid external field. The user's role doesn't exist, so looking up this field should fail and ultimately cause the import to fail.
# Import a class with an invalid field (User with ian nvalid email)
#: Tries to import a csv with an invalid internal field. The user email is validated inside the User class, so make sure that validation raises the correct error.
# Import an empty CSV (With Headers)
#: Tries to import an empty csv with no records inside. This is tested with the <code>use_header</code> option set to true.
# Import an empty CSV (Without Headers)
#: Tries to import an empty csv with nothing inside. This is tested with the <code>use_header</code> option set to false.

[[File:TextLookupBad.png]]

''Import Export Helper Tests: Error Test case 2 and 3 Implementation''

==== ImportExportService - Importing ====
----
;Create tests to make sure the Service works
# Test Get Import: 200 response
#: Test that Import#Index recieves the response, and returns the correct values
# Test Post Import: 200 response
#: Test that Import#Import recieves the response with data, and can return a response.

[[File:TestImportService.png]]

''Import Service Tests: Test case 1 Implementation''

;Create Tests to test Errors/Edge Cases
# Test Post Import: 422 response
# Test Post Import: 500 response

==== ImportExportService - Exporting ====
----
;Create tests for each of the different exportable classes
* Export a class with the default headers
* Export a class with only the mandatory headers
* Export a class with only some optional headers
* Export a class with a different order of headers

;Create tests to test Errors/Edge Cases
* Export a class with chosen headers that are empty

----

=== Frontend Testing ===
----
==== Import Modal ====
----

* Shows loading state when isLoading is true
*: Ensures that when `useAPI` reports `isLoading=true`, the modal hides all content and displays a “Loading…” message.
* Renders field summary and duplicate options from metadata
*: Confirms that metadata returned from the backend (mandatory, optional, external fields, and duplicate handling actions) are rendered correctly in the modal.
* Shows status when importing with no file selected
*: Validates that clicking “import” without choosing a CSV sets an error status message and prevents the import call.
* Shows column mapping and first-row values when header mode is off
*: After uploading a CSV and disabling the “First row contains headers” toggle, verifies that the “Column order” UI appears, column dropdowns are rendered, and the first-row preview text is displayed.
* Calls sendImport when import is valid
*: Uploads a valid CSV containing mandatory fields and clicks “import.” Checks that the `sendRequest` mock is called, proving that the modal sends a correctly prepared API request.
* Calls onHide when cancel is clicked
*: Simulates clicking the “cancel” button and confirms the modal fires the `onHide` callback to close itself.

== Future work ==
* Adding event-based entity registration.
* Extending support for new duplicate resolution policies.
* Integration with the engine demo for visualization and debugging.
* More extensive testing for functionality and edge cases.
* Add a space in the import modal that shows all the values that will be imported.
* Add the helper method across the website wherever the import/export functionality is required.
:* The helper is currently in:
::* QuizItem
::* Item
::* QuestionAdvice
::* Team
::* User

=== Other Notes/Recommendations ===
* For Items, limit the string values that question_type can be using built-in validation rules as well, or else importing will allow just any string.
* For Questionnaires, break_before can't be false because of the validation rules. Maybe try this `validates :break_before, inclusion: { in: [true, false] }`

Response maps

2025-11-12T19:05:10Z

Admin: /* Response maps variable documentation */

Maps a connection between the [[participants]] as reviewers and [[participants]] or [[teams]] as reviewees

==Response maps variable documentation==

{| 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. *In the new system, this field is named for_calibration.*
|}

Back to the [[Documentation_on_Database_Tables|database documentation]]

Response maps

2025-11-12T19:04:45Z

Admin: /* Response maps variable documentation */

Maps a connection between the [[participants]] as reviewers and [[participants]] or [[teams]] as reviewees

==Response maps variable documentation==

{| 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. _In the new system, this field is named for_calibration_.
|}

Back to the [[Documentation_on_Database_Tables|database documentation]]

CSC/ECE 517 Fall 2025 - E2563. Review tableau

2025-11-12T17:14:07Z

Admin: /* Core Requirements */

This page contains information about E2563.Review calibration, which was a project in CSC517 Fall 2025.

Please see below for a description of the design of the project.

== Background ==
Expertiza is an open-source application based on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams for each one, as well as peer review other teams’ work. The frontend is written in TypeScript, and the backend is written in Ruby. The current codebase can be found here (FRONTEND, BACKEND), as well as in the external info section below. This work is part of an ongoing reimplementation effort of the following old Expertiza repository.

== Problem Statement ==
Instructors need to be able to view the responses made by a student during rounds of peer review in order to accurately assign a grade for that review. To streamline this process, our goal is to design and implement a dedicated page that allows instructors to view all grading reviews submitted by a given student. This page, named the '''review tableau page''', should organize and present the reviews in a clear, structured, and accessible manner. Specifically, the page must display all student grading reviews, grouped by assignment, round, and topic, with each group being rendered as a separate table.

== Requirements ==
=== Core Requirements ===
* A user with the '''Instructor''' role can view the review tableau(s) for a given student from a dedicated page (the ‘tableau page’) of the Expertiza site.
* The tableau page can be accessed by clicking a “Summary” link under the “Reviews Done” column when viewing students in the instructor’s rewiew-grading dashboard.
* The tableau page has the following contents:
** A header, displaying the text “Review by Student, “ followed by the student’s ID.
** Individual tables (‘tableaus’), each corresponding to a round of reviewing from a specific assignment with a specific rubric used during the review.
*** Tableaus are displayed in a single column on the tableau page.
*** Tableaus are sorted first by the '''round in which the review was made''', and then finally by the rubric used for review. This ensures that topics made chronologically close together are displayed sequentially. In the usual case, where the '''same''' rubric is used for all submissions, there will be only a single tableau. If rubric varies by topics, there may be multiple tableaus, reflecting the fact that the rubric may be different for different submissions reviewed by this reviewer.
* An individual tableau has the following contents:
** A label for the course number, semester, and year in which the review was made.
** A label for the assignment for which the review was made.
** A label for the round number for which the review was made.
** The primary table, which contains:
*** A highlighted column, populated with questions asked on the rubric.
*** An arbitrary number of additional columns, each corresponding to a review for that assignment and round that uses the rubric. Each of these is labelled after the team being reviewed and annotated with the date/time the review was submitted.
**** Each row of these columns is populated with the student’s responses for the corresponding review and question.
** Note that a single tableau records the results of all reviews made using the same rubric for a particular round. If a student provided reviews for topics (frontend, backend, full stack) with varying rubrics, then a tableau will be created for each type of rubric filled out.
* Creating a backend API that can retrieve the student’s grading reviews and sort them per each assignment, round, and topic. ''(Functional and local development)''

=== Design Requirements ===
[[File:Sample_of_the_review_tableau_layout.png|500px]]
* Follow the same design guidelines as reimplementation-front-end (https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md).
* Use the same widgets (circles with numbers inside) that are used on the Response views.

== Implementation ==
''To be modified later as implementing''
* Create File for Reviews Done Page
::- Main page that displays a table of students with "summary" links
::- Utility functions for loading student data

* Create File for Review Tableau Page
::- Main page to work on following the requirements above

== Results ==
''To be determined!''

== Test Plan ==
=== Manual Testing ===
# Login to Expertiza with an admin or instructor account
# There should be a “Reviews Done” button on the dashboard. Click on “Reviews Done” button
# A table contains all students who should show up. Click on the “summary” link for one mock student to get to the Review Tableau page
# Confirm table displays correctly with the assignment name, student name, review rounds -> review tables following each rubric

=== Automated Testing ===
* Unit test cases for correct headers, nested tables, and correct layout.

== Team Members ==
Adam Imbert (apimbert)
‎<br />
Bestin Lalu (blalu)
‎<br />
Yumo Shen (jshen23)

CSC/ECE 517 Fall 2025 - E2563. Review tableau

2025-11-12T17:09:59Z

Admin: /* Core Requirements */

This page contains information about E2563.Review calibration, which was a project in CSC517 Fall 2025.

Please see below for a description of the design of the project.

== Background ==
Expertiza is an open-source application based on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams for each one, as well as peer review other teams’ work. The frontend is written in TypeScript, and the backend is written in Ruby. The current codebase can be found here (FRONTEND, BACKEND), as well as in the external info section below. This work is part of an ongoing reimplementation effort of the following old Expertiza repository.

== Problem Statement ==
Instructors need to be able to view the responses made by a student during rounds of peer review in order to accurately assign a grade for that review. To streamline this process, our goal is to design and implement a dedicated page that allows instructors to view all grading reviews submitted by a given student. This page, named the '''review tableau page''', should organize and present the reviews in a clear, structured, and accessible manner. Specifically, the page must display all student grading reviews, grouped by assignment, round, and topic, with each group being rendered as a separate table.

== Requirements ==
=== Core Requirements ===
* A user with the '''Instructor''' role can view the review tableau(s) for a given student from a dedicated page (the ‘tableau page’) of the Expertiza site.
* The tableau page can be accessed by clicking a “Summary” link under the “Reviews Done” column when viewing students in the instructor’s rewiew-grading dashboard.
* The tableau page has the following contents:
** A header, displaying the text “Review by Student, “ followed by the student’s ID.
** Individual tables (‘tableaus’), each corresponding to a round of reviewing from a specific assignment with a specific rubric used during the review.
*** Tableaus are displayed in a single column on the tableau page.
*** Tableaus are sorted first by '''assignment''', then '''round in which the review was made''', then finally by '''topic reviewed for'''. This ensures that topics made chronologically close together are displayed sequentially.
* An individual tableau has the following contents:
** A label for the course number, semester, and year in which the review was made.
** A label for the assignment for which the review was made.
** A label for the round number for which the review was made.
** The primary table, which contains:
*** A highlighted column, populated with questions asked on the rubric.
*** An arbitrary number of additional columns, each corresponding to a review for that assignment and round that uses the rubric. Each of these is labelled after the team being reviewed and annotated with the date/time the review was submitted.
**** Each row of these columns is populated with the student’s responses for the corresponding review and question.
** Note that a single tableau records the results of all reviews made using the same rubric for a particular round. If a student provided reviews for topics (frontend, backend, full stack) with varying rubrics, then a tableau will be created for each type of rubric filled out.
* Creating a backend API that can retrieve the student’s grading reviews and sort them per each assignment, round, and topic. ''(Functional and local development)''

=== Design Requirements ===
[[File:Sample_of_the_review_tableau_layout.png|500px]]
* Follow the same design guidelines as reimplementation-front-end (https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md).
* Use the same widgets (circles with numbers inside) that are used on the Response views.

== Implementation ==
''To be modified later as implementing''
* Create File for Reviews Done Page
::- Main page that displays a table of students with "summary" links
::- Utility functions for loading student data

* Create File for Review Tableau Page
::- Main page to work on following the requirements above

== Results ==
''To be determined!''

== Test Plan ==
=== Manual Testing ===
# Login to Expertiza with an admin or instructor account
# There should be a “Reviews Done” button on the dashboard. Click on “Reviews Done” button
# A table contains all students who should show up. Click on the “summary” link for one mock student to get to the Review Tableau page
# Confirm table displays correctly with the assignment name, student name, review rounds -> review tables following each rubric

=== Automated Testing ===
* Unit test cases for correct headers, nested tables, and correct layout.

== Team Members ==
Adam Imbert (apimbert)
‎<br />
Bestin Lalu (blalu)
‎<br />
Yumo Shen (jshen23)

CSC/ECE 517 Fall 2025 - E2563. Review tableau

2025-11-12T17:08:30Z

Admin: /* Core Requirements */

This page contains information about E2563.Review calibration, which was a project in CSC517 Fall 2025.

Please see below for a description of the design of the project.

== Background ==
Expertiza is an open-source application based on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams for each one, as well as peer review other teams’ work. The frontend is written in TypeScript, and the backend is written in Ruby. The current codebase can be found here (FRONTEND, BACKEND), as well as in the external info section below. This work is part of an ongoing reimplementation effort of the following old Expertiza repository.

== Problem Statement ==
Instructors need to be able to view the responses made by a student during rounds of peer review in order to accurately assign a grade for that review. To streamline this process, our goal is to design and implement a dedicated page that allows instructors to view all grading reviews submitted by a given student. This page, named the '''review tableau page''', should organize and present the reviews in a clear, structured, and accessible manner. Specifically, the page must display all student grading reviews, grouped by assignment, round, and topic, with each group being rendered as a separate table.

== Requirements ==
=== Core Requirements ===
* A user with the '''Instructor''' role can view the review tableau(s) for a given student from a dedicated page (the ‘tableau page’) of the Expertiza site.
* The tableau page can be accessed by clicking a “Summary” link under the “Reviews Done” column when viewing students in the instructor’s rewiew-grading dashboard.
* The tableau page has the following contents:
** A header, displaying the text “Review by Student, “ followed by the student’s ID.
** Individual tables (‘tableaus’), each corresponding to a round of reviewing from a specific assignment, as well as the rubric used during the review.
*** Tableaus are displayed in a single column on the tableau page.
*** Tableaus are sorted first by '''assignment''', then '''round in which the review was made''', then finally by '''topic reviewed for'''. This ensures that topics made chronologically close together are displayed sequentially.
* An individual tableau has the following contents:
** A label for the course number, semester, and year in which the review was made.
** A label for the assignment for which the review was made.
** A label for the round number for which the review was made.
** The primary table, which contains:
*** A highlighted column, populated with questions asked on the rubric.
*** An arbitrary number of additional columns, each corresponding to a review for that assignment and round that uses the rubric. Each of these is labelled after the team being reviewed and annotated with the date/time the review was submitted.
**** Each row of these columns is populated with the student’s responses for the corresponding review and question.
** Note that a single tableau records the results of all reviews made using the same rubric for a particular round. If a student provided reviews for topics (frontend, backend, full stack) with varying rubrics, then a tableau will be created for each type of rubric filled out.
* Creating a backend API that can retrieve the student’s grading reviews and sort them per each assignment, round, and topic. ''(Functional and local development)''

=== Design Requirements ===
[[File:Sample_of_the_review_tableau_layout.png|500px]]
* Follow the same design guidelines as reimplementation-front-end (https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md).
* Use the same widgets (circles with numbers inside) that are used on the Response views.

== Implementation ==
''To be modified later as implementing''
* Create File for Reviews Done Page
::- Main page that displays a table of students with "summary" links
::- Utility functions for loading student data

* Create File for Review Tableau Page
::- Main page to work on following the requirements above

== Results ==
''To be determined!''

== Test Plan ==
=== Manual Testing ===
# Login to Expertiza with an admin or instructor account
# There should be a “Reviews Done” button on the dashboard. Click on “Reviews Done” button
# A table contains all students who should show up. Click on the “summary” link for one mock student to get to the Review Tableau page
# Confirm table displays correctly with the assignment name, student name, review rounds -> review tables following each rubric

=== Automated Testing ===
* Unit test cases for correct headers, nested tables, and correct layout.

== Team Members ==
Adam Imbert (apimbert)
‎<br />
Bestin Lalu (blalu)
‎<br />
Yumo Shen (jshen23)

Assignments

2025-11-12T02:32:46Z

Admin: /* Assignment Variable Documentation */

The Assignments table contains one record for each assignment created by an [[users|instructor]] or [[users|administrator]].

==Assignment Variable Documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|This object's unique ID value. One per object.
|-
!created_at
|datetime
|The date/time stamp when this record was created
|-
!updated_at
|datetime
|The date/time stamp when this record was last modified
|-
!name
|varchar(255)
|The name given to this assignment by the instructor/administrator who created it
|-
!directory_path
|varchar(255)
|If this is an assignment to which files are being submitted, this is the first part of the directory path for the submissions. If this is a wiki assignment, it is the base URL for wiki pages submitted by the creators
|-
!submitter_count
|int(10)
|Number of creators who have submitted so far to this assignment
|-
!course_id
|int(11)
|ID in the [http://wiki.expertiza.ncsu.edu/index.php/Courses_table Courses] table of the course with which this assignment is associated
|-
!instructor_id
|int(11)
|ID of a instructor who created the assignment
|-
!private
|tinyint(1)
|whether assignment is visible to other instructors
|-
!num_reviews
|int(11)
|number of reviews done by a student for this assignment
|-
!num_review_of_reviews
|int(10)
|number of reviews of reviews done by a student for this assignment
|-
!num_review_of_reviewers
|int(11)
|number of reviewers who have reviewed the assignment.
|-
!reviews_visible_to_all
|tinyint(1)
|if false, other reviewers can't see this reviewer's review.
|-
!num_reviewers
|int(10)
|Number of reviewers.
|-
!spec_location
|text
|url of the assignment.
|-
!max_team_size
|int(11)
|Maximum number of participants allowed on the team.
|-
!staggered_deadline
|tinyint(1)
|Indicating whether deadlines are staggered or not *************
|-
!allow_suggestions
|tinyint(1)
|Indicating whether participants in an assignment with topics may suggest additional topics for the instructor to approve.
|-
!days_between_submissions
|int(11)
|Number of Days available between submissions *************
|-
!review_assignment_strategy
|varchar(12)
|
|-
!review_topic_threshold
|int(11)
|***********************************
|-
!copy_flag
|tinyint(1)
|Whether the assignment has a copy or not. *************
|-
!rounds_of_reviews
|int(11)
|Total number of rounds of reviews done for the assignment *************
|-
!microtask
|tinyint(1)
|Indicating whether this is a microtask assignment, i.e., if it has topics that are worth varying amounts of credit, and may be selected by students.
|-
!require_quiz
|tinyint(1)
|Indicating whether the assignment requires a quiz or not. *************
|-
!num_quiz_questions
|int(11)
|Total number of questions present for the quiz. *************
|-
!is_coding_assignment
|tinyint(1)
|Indicating whether whether the given assignment is a coding assignment or not *************
|-
!is_intelligent
|tinyint(1)
|Indicates whether topics are to be bid on, and then the "intelligent assignment" algorithm will assign teams to topics *************
|-
!calculate_penalty
|tinyint(1)
|Indicating whether penalty needs to be calculated for the given assignment. *************
|-
!late_policy_id
|int(11)
|ID in the ******late policy table***** *************. Indicating which late policy is applied here.
|-
!is_penalty_calculated
|tinyint(1)
|Indicating whether the penalty for the assignment is calculated or not. *************
|-
!max_bids
|int(11)
|Total amount of bids given for this assignment. *************
|-
!show_teammate_reviews
|tinyint(1)
|Indicating whether teammate reviews are shown or not. *************
|-
!availability_flag
|tinyint(1)
|Indicating whether the given assignment is available or not. *************
|-
!use_bookmark
|tinyint(1)
|Indicating whether bookmarks are used or not. *************
|-
!can_review_same_topic
|tinyint(1)
|Indicating whether a reviewer can review the same topic again. *************
|-
!can_choose_topic_to_review
|tinyint(1)
|Indicating whether a reviewer can choose a topic to review *************
|-
!is_calibrated
|tinyint(1)
|Indicating whether the assignment is calibrated or not. *************
|-
!is_selfreview_enabled
|tinyint(1)
|Indicating whether an author can review his/her work. *************
|-
!reputation_algorithm
|varchar(12)
|This field gives us the information of the reputation algorithm used for this assignment. *************
|-
!is_anonymous
|tinyint(1)
|Indicating whether whether the reviewer information is anonymous or not. *************
|-
!num_reviews_required
|int(11)
|Total number of reviews required for this assignment. *************
|-
!num_metareviews_required
|int(11)
|Total number of metareviews required for this assignment. *************
|-
!num_metareviews_allowed
|int(11)
|Total number of metareviews allowed for this assignment. *************
|-
!num_reviews_allowed
|int(11)
|Total number of reviews allowed for this assignment. *************
|-
!simicheck
|int(11)
|Similarity Check between assignments. *************
|-
!simicheck_threshold
|int(11)
|Similarity check threshold value for the given assignment. *************
|}

== E/R diagram for Parents Tables ==
Tables referred by the Assignment Table as Foreign Key Relationship.

[[File:assignment_imported.png]]

== E/R diagram for Child Tables ==
Tables which refer the Assignment Table as Foreign Key Relationship.

[[File:assignment_exported.png]]

Back to the [[Documentation_on_Database_Tables|database documentation]]

CSC/ECE 517 Fall 2025 - E2557. Specialized rubrics for different topic types

2025-11-09T18:28:39Z

Admin: /* Motivation */

= CSC/ECE 517 Fall 2025 – E2557. Specialized Rubrics for Different Topic Types =

== Overview ==
In the current Expertiza system, all projects within a course share a single rubric. This means that projects of different types — such as refactoring projects, testing projects, or front-end projects — must be evaluated using the same criteria.

The goal of this project is to enable instructors to assign '''different rubrics to different project topics''', allowing for more accurate and flexible assessment methods.

== Motivation ==
Expertiza supports a variety of project types across CSC/ECE 517 courses. However, because only one rubric can be assigned to an assignment at present, instructors cannot tailor rubrics to the distinct expectations of each project type.

By implementing specialized rubrics per topic, the evaluation process can better reflect the unique goals and deliverables of each project type.

== Functional Requirements ==
Note that several of these functional requirements were shared by the E2552 group, particularly any that rely on frontend implementation.

* By default, each course project uses the rubric specified on the '''Rubrics''' tab.
* On the '''Topics''' tab (in the Assignment Edit page), a '''dropdown''' should appear next to each topic.
** This dropdown allows instructors to choose a rubric specific to that topic.
** If no rubric is selected, the assignment’s default rubric is used.
* The '''signup sheet''' interface should display the rubric chosen for each topic.
* The '''rubric-selection logic''' should not reside within the `signup_sheet_controller`.
** Any non-topic-related logic should instead be handled in another controller or helper.
* A new column, `topic_id`, must be added to the `assignment_questionnaires` table to link a questionnaire to a specific topic.

== Implementation Details ==
To implement the requirements, we have made the following changes to the backend repository:
* Implemented rubric_list, a new GET API endpoint in sign_up_topics_controller.rb, which returns the topics and rubrics associated with a specific assignment. These are serialized into a readable JSON format to facilitate frontend use.
* Inserted "topic_id" as a foreign key assignment_questionnaire.rb, and added a "questionnaire" field to sign_up_topic.rb. These allow topics to be assigned on a per-assignment, per-round basis.
* Implemented rubric_for_review, a function in the sign_up_topic.rb model that returns the appropriate questionnaire for a topic given a specific round number that questionnaire corresponds to.
* Implemented has_specific_rubric?, a function in the sign_up_topic.rb model that returns whether or not the topic has an associated rubric for the given round.
* Introduced topic_rubrics_helper.rb, a helper class designed to carry the assign_rubric_to_topic function. This associates the given assignment, topic, questionnaire, and round number with each other in the database in an unobtrusive way that does not gunk up other classes.
* Created sign_up_topic_spec.rb, a testing class designed to test the aforementioned new functions in the SignUpTopic class.

== Integration of AI ==
Artificially intelligent LLM models (ChatGPT, Claude.ai) were leveraged to streamline development and consult regarding critical design decisions.

Firstly: [https://claude.ai/share/fbd40465-86ae-498c-bb22-1b719784a928 unspecific, project-encompassing] conversations served to give us a high-level understanding of what tasks needed to be completed, and what components might comprise a completed implementation. Having this overview is important for project planning, especially with the shorter time window we gave ourselves to complete implementation. While we did not have access to Issues to populate a GitHub project page, we were able to break the implementation into tasks for our own internal production management.

Secondly: [https://chatgpt.com/c/690227fe-a6c4-832d-a485-e284f1a457f0 troubleshooting] or [https://chatgpt.com/share/6902cda2-364c-8007-b18d-d804023b73d1 class-specific] conversations allowed us to isolate a component of the implementation and (hopefully) keep everything modular, extensible, and maintainable. And, of course, promptly fix any bugs we encountered in setup or execution of our implementation!

== Future Work ==
Due to unfortunate time constraints, both circumstantial and self-imposed, the implementation as it stands is lacking in a number of key categories. Chiefly, our rspec tests are undertested due to issues running the rspec test suite. As such, we recommend careful code review is applied to the resulting PR before it is considered for merging. The PR is set to "DRAFT" to reflect this.

With that being said, here are a few action steps for future teams tackling this problem:
* Finalize the API integration with the front-end dropdown component.
* Implement logic to persist rubric–topic associations.
* Ensure that current automated test coverage for the new functionality is sufficient and correct.
* Conduct usability testing and gather instructor feedback, as always!

== Useful Links ==
* [https://github.com/Prismly/reimplementation-back-end/tree/main Team GitHub Repository]
* [https://github.com/expertiza/reimplementation-back-end/pull/226 Backend Pull Request]
* [https://docs.google.com/presentation/d/1dltJz9vOSq-tDVyGDUtLTfuC5gVlylsdjNs7TPJTQBk/edit?usp=sharing Demo Slide Deck] (requires NCSU Google Account)

== Team Information ==
* Adam Imbert (apimbert)
* Iman Khan (ikhan7)
* Niranjan Rajendran (nrajend4)
* '''Mentor''': Ed Gehringer (efg)

== References ==
* Original codebase feature page: [[CSC/ECE 517 Spring 2020 - E2026. Specialized rubrics for different topic types|Project E2026 Wiki Page]]
* Reimplementation precedent feature page: [[CSC/ECE_517_Spring_2025_-_E2513._Reimplement_sign_up_topic.rb_as_project_topic.rb|Project E2513 Wiki Page]]

----

Teams

2025-10-28T17:44:51Z

Admin:

{| 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.

Teams

2025-10-28T17:44:37Z

Admin:

{| 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 partners
|-
!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.

Participants

2025-10-17T14:28:43Z

Admin:

Users associated with either a [http://wiki.expertiza.ncsu.edu/index.php/Courses_table course] or an [http://wiki.expertiza.ncsu.edu/index.php/Assignments assignment]

==Participants variable documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|INT(10)
|unique identifier for the person participating
|-
!can_submit
|BIT
|bit to identify whether the person can submit or not
|-
!can_review
|BIT
|bit to identify whether the person can review or not
|-
!user_id
|INT(10)
|unique id referring to the user
|-
!parent_id
|INT(10)
|unique id referring to parent assignment or course
|-
!submitted_at
|DATETIME
|Date and Time of the submission made
|-
!permission_granted
|BIT
|this bit tells whether the instructor can use the work that the student has submitted later on.
|-
!penalty_accumulated
|INT UNSIGNED
|
|-
!grade
|FLOAT
|Grade allotted for the submission after evaluation
|-
!type
|VARCHAR(255)
|either CourseParticipant or AssignmentParticipant
|-
!handle
|VARCHAR(255)
|the handle that the user wants to be known by in this assignment
|-
!time_stamp
|DATETIME
|
|-
!digital_signature
|TEXT
|to record what was the evaluation
|-
!duty
|VARCHAR(255)
|the "role" of this person on their team, e.g., tester. Used only when roles are assigned to team members.
|-
!can_take_quiz
|BIT
|this bit signifies whether the participant can take a quiz on the work they are reviewing
|-
|Hamer
|FLOAT
|the reputation of this participant using the Hamer algorithm
|-
|Lauw
|FLOAT
|the reputation of this participant using the Lauw algorithm
|}

== E/R diagram for Parents Tables ==
Tables referred by the Participants Table as Foreign Key Relationship.

[[File:participants_eer.jpg]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Participants

2025-10-17T14:27:49Z

Admin: Undo revision 166733 by Admin (talk)

Users associated with either a [http://wiki.expertiza.ncsu.edu/index.php/Courses_table course] or an [http://wiki.expertiza.ncsu.edu/index.php/Assignments assignment]

==Participants variable documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|INT(10)
|unique identifier for the person participating
|-
!can_submit
|BIT
|bit to identify whether the person can submit or not
|-
!can_review
|BIT
|bit to identify whether the person can review or not
|-
!user_id
|INT(10)
|unique id referring to the user
|-
!parent_id
|INT(10)
|unique id referring to parent assignment or course
|-
!submitted_at
|DATETIME
|Date and Time of the submission made
|-
!permission_granted
|BIT
|this bit tells whether the instructor can use the work that the student has submitted later on.
|-
!penalty_accumulated
|INT UNSIGNED
|
|-
!grade
|FLOAT
|Grade allotted for the submission after evaluation
|-
!type
|VARCHAR(255)
|either CourseParticipant or AssignmentParticipant
|-
!handle
|VARCHAR(255)
|the handle that the user wants to be known by in this assignment
!time_stamp
|DATETIME
|
|-
!digital_signature
|TEXT
|to record what was the evaluation
|-
!duty
|VARCHAR(255)
|the "role" of this person on their team, e.g., tester. Used only when roles are assigned to team members.
|-
!can_take_quiz
|BIT
|this bit signifies whether the participant can take a quiz on the work they are reviewing
|-
|Hamer
|FLOAT
|the reputation of this participant using the Hamer algorithm
|-
|Lauw
|FLOAT
|the reputation of this participant using the Lauw algorithm
|}

== E/R diagram for Parents Tables ==
Tables referred by the Participants Table as Foreign Key Relationship.

[[File:participants_eer.jpg]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Participants

2025-10-17T14:27:20Z

Admin: Undo revision 166734 by Admin (talk)

Users associated with either a [http://wiki.expertiza.ncsu.edu/index.php/Courses_table course] or an [http://wiki.expertiza.ncsu.edu/index.php/Assignments assignment]

==Participants variable documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|INT(10)
|unique identifier for the person participating
|-
!can_submit
|BIT
|bit to identify whether the person can submit or not
|-
!can_review
|BIT
|bit to identify whether the person can review or not
|-
!user_id
|INT(10)
|unique id referring to the user
|-
!parent_id
|INT(10)
|unique id referring to parent assignment or course
|-
!submitted_at
|-
DATETIME
|Date and Time of the submission made
|-
!permission_granted
|BIT
|this bit tells whether the instructor can use the work that the student has submitted later on.
|-
!penalty_accumulated
|INT UNSIGNED
|
|-
!grade
|FLOAT
|Grade allotted for the submission after evaluation
|-
!type
|VARCHAR(255)
|either CourseParticipant or AssignmentParticipant
|-
!handle
|VARCHAR(255)
|the handle that the user wants to be known by in this assignment
!time_stamp
|DATETIME
|
|-
!digital_signature
|TEXT
|to record what was the evaluation
|-
!duty
|VARCHAR(255)
|the "role" of this person on their team, e.g., tester. Used only when roles are assigned to team members.
|-
!can_take_quiz
|BIT
|this bit signifies whether the participant can take a quiz on the work they are reviewing
|-
|Hamer
|FLOAT
|the reputation of this participant using the Hamer algorithm
|-
|Lauw
|FLOAT
|the reputation of this participant using the Lauw algorithm
|}

== E/R diagram for Parents Tables ==
Tables referred by the Participants Table as Foreign Key Relationship.

[[File:participants_eer.jpg]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Participants

2025-10-17T14:26:10Z

Admin: /* Participants variable documentation */

Users associated with either a [http://wiki.expertiza.ncsu.edu/index.php/Courses_table course] or an [http://wiki.expertiza.ncsu.edu/index.php/Assignments assignment]

==Participants variable documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|INT(10)
|unique identifier for the person participating
|-
!can_submit
|BIT
|bit to identify whether the person can submit or not
|-
!can_review
|BIT
|bit to identify whether the person can review or not
|-
!user_id
|INT(10)
|unique id referring to the user
|-
!parent_id
|INT(10)
|unique id referring to parent assignment or course
|-
!submitted_at
DATETIME
|Date and Time of the submission made
|-
!permission_granted
|BIT
|this bit tells whether the instructor can use the work that the student has submitted later on.
|-
!penalty_accumulated
|INT UNSIGNED
|
|-
!grade
|FLOAT
|Grade allotted for the submission after evaluation
|-
!type
|VARCHAR(255)
|either CourseParticipant or AssignmentParticipant
|-
!handle
|VARCHAR(255)
|the handle that the user wants to be known by in this assignment
!time_stamp
|DATETIME
|
|-
!digital_signature
|TEXT
|to record what was the evaluation
|-
!duty
|VARCHAR(255)
|the "role" of this person on their team, e.g., tester. Used only when roles are assigned to team members.
|-
!can_take_quiz
|BIT
|this bit signifies whether the participant can take a quiz on the work they are reviewing
|-
|Hamer
|FLOAT
|the reputation of this participant using the Hamer algorithm
|-
|Lauw
|FLOAT
|the reputation of this participant using the Lauw algorithm
|}

== E/R diagram for Parents Tables ==
Tables referred by the Participants Table as Foreign Key Relationship.

[[File:participants_eer.jpg]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Participants

2025-10-17T14:25:09Z

Admin: /* Participants variable documentation */

Users associated with either a [http://wiki.expertiza.ncsu.edu/index.php/Courses_table course] or an [http://wiki.expertiza.ncsu.edu/index.php/Assignments assignment]

==Participants variable documentation==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|INT(10)
|unique identifier for the person participating
|-
!can_submit
|BIT
|bit to identify whether the person can submit or not
|-
!can_review
|BIT
|bit to identify whether the person can review or not
|-
!user_id
|INT(10)
|unique id referring to the user
|-
!parent_id
|INT(10)
|unique id referring to parent assignment or course
|-
!submitted_at
|-
DATETIME
|Date and Time of the submission made
|-
!permission_granted
|BIT
|this bit tells whether the instructor can use the work that the student has submitted later on.
|-
!penalty_accumulated
|INT UNSIGNED
|
|-
!grade
|FLOAT
|Grade allotted for the submission after evaluation
|-
!type
|VARCHAR(255)
|either CourseParticipant or AssignmentParticipant
|-
!handle
|VARCHAR(255)
|the handle that the user wants to be known by in this assignment
!time_stamp
|DATETIME
|
|-
!digital_signature
|TEXT
|to record what was the evaluation
|-
!duty
|VARCHAR(255)
|the "role" of this person on their team, e.g., tester. Used only when roles are assigned to team members.
|-
!can_take_quiz
|BIT
|this bit signifies whether the participant can take a quiz on the work they are reviewing
|-
|Hamer
|FLOAT
|the reputation of this participant using the Hamer algorithm
|-
|Lauw
|FLOAT
|the reputation of this participant using the Lauw algorithm
|}

== E/R diagram for Parents Tables ==
Tables referred by the Participants Table as Foreign Key Relationship.

[[File:participants_eer.jpg]]

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Answer tags

2025-09-26T15:14:04Z

Admin: /* Answer Tags Variable Documentation */

The Answer Tags table contains tags that have been assigned to rubric comments based on the characteristics those comments have.
== Answer Tags Variable Documentation ==

{| class="wikitable"
!Field Name !!Type !!Description
|-
!id
|int(11)
|Unique ID for each Answer_tag record.
|-
!answer_id
|int(11)
|ID of the Answer comment that is being tagged.
|-
!tag_prompt_deployment_id
|int(11)
|When someone tags a comment, they tag it for a particular characteristic. The deployment_id tells which characteristic
|-
!user_id
|int(11)
|ID of the User who set the tag
|-
!value
|varchar(255)
|Value of the Tag (not set, yes, or no).
|-
!created_at
|datetime
|Date time value when the record was created.
|-
!updated_at
|datetime
|Date time value when the record was updated.
|}

== E/R diagram for Parents Tables ==
Tables referred by the Answer Tags Table as Foreign Key Relationship.

[[File:answer_tags_imported.png]]

== E/R diagram for Child Tables ==
No Tables refer the Answer Tags Table as Foreign Key Relationship.

Back to [http://wiki.expertiza.ncsu.edu/index.php/Documentation_on_Database_Tables Database Tables] Main page.

Design for Automatic Evaluation of Peer Reviews

2025-07-16T18:15:57Z

Admin: /* How it is going to be added to Expertiza */

= Evaluate Using LLMs Integration =

== What we want to do ==

The goal of this project is to integrate LLMs with the peer-assessment process to improve learning. This can be done in various ways, including
* Letting the LLM rate the submission and grade reviewers on how close their review is to the LLM’s (LLM as oracle).
* Using the LLM to read a review and give the reviewer advice on how to improve it (LLM as advisor).
* Using the LLM to rate the reviews and use that metric to weight reviewers’ score in calculating a grade (LLM as reputation system)
* Letting the LLM to do the review and ask reviewers (or authors) if they agree with the LLM and why or why not (LLM as opening salvo)

Students learn best by doing reviews. So, maybe you want the LLM to teach students to review.

We also want to show instructors '''an evaluation of each reviewer’s overall reviewing performance'''.
Rather than looking at individual reviews, instructors will get a '''summary report''' describing how well each reviewer performed overall.
The evaluation includes aspects like quality of comments, score consistency, engagement, and other rubric-related metrics.
This report will be generated using a '''Large Language Model (LLM)''', such as GPT.

Thus, instructors and TAs will be able to '''edit, overwrite, and finalize reviewer evaluation''' based on the LLM-generated suggestions.

== How it is going to be added to Expertiza ==

We can add an "Evaluate using LLM" option to the '''dropdown menu''' alongside Review Report, Author Feedback Report, etc.

When the instructor selects "Evaluate using LLM" and clicks View:
* Review data (responses, reviewer info, reviewee info, scores, comments, etc.) is gathered.
* The data is sent to an '''external API''' (currently stubbed with fake data).
* The returned evaluation is populated into an '''editable table view''' similar to the existing Review Report.

=== Classes ===
* '''LlmEvaluationService''': Located in `app/services/llm_evaluation_service.rb`. Handles outbound API requests and inbound responses.
* '''ReportsController''': New method `llm_evaluation_report` added to generate the LLM evaluation page.

=== Web Service(s) ===
* '''External API call''': Currently stubbed with fake data.
* '''View partial''': `_llm_evaluation_report.html.erb` created to display editable evaluations.

== How much of it is implemented now ==

The following parts are fully working:
* "Evaluate using LLM" dropdown option in the _searchbox.html.erb partial.
* Routing to the correct controller action (`llm_evaluation_report`).
* Service object (`LlmEvaluationService`) created to collect and send review data.
* Stubbed API returning a hardcoded response.
* Editable report table rendered via a new partial called _llm_evaluation_report.html.erb.
* "Overwrite" button added (placeholder functionality). Modify the submit method to overwrite the already existing grades and comments in the reviews_grade table with the LLM generated grades and comments.

Thus, the feature '''end-to-end works with fake data''' for now.

== How to continue development ==

To complete this project:
* Connect to the '''real LLM API''' instead of fake responses.
* Work on the schema for reviews_grade table to incorporate the LLM generated scores and feedback in a new column.
* Implement '''saving''' functionality for the "Overwrite" button which will overwrite the grade_for_reviewer and comment_for_reviewer that already exists with the LLM generated grades and comments.
* Add robust '''error handling''' (for timeout, API errors, etc.).
* Extend support for '''multiple rounds''' and '''varying rubrics'''.
* Add '''RSpec tests''' for the service and controller logic.

== Pull request details ==

The pull request contains the following:

*'''New dropdown entry: Evaluate using LLM'''
A new option titled "Evaluate using LLM" has been added alongside existing report types (such as Review report, Author feedback report) in the reports searchbox partial (`_searchbox.html.erb`). This allows instructors and TAs to select the LLM-based evaluation report from the interface just like any other report type.

*'''New controller action: llm_evaluation_report'''
The `llm_evaluation_report` method has been introduced inside the `ReportsController`. This action is responsible for gathering the necessary assignment and participant data, invoking the service object to fetch LLM-evaluated responses, and rendering the new LLM Evaluation Report view for the instructor or TA.

*'''New service object: LlmEvaluationService'''
A service class `LlmEvaluationService` has been created under `app/services/llm_evaluation_service.rb`. This service collects review and reviewer information from the database, formats it into the expected API request payload, sends a POST request to an external (currently dummy) LLM evaluation API using `HTTParty`, and parses the received response into a structured format that can be easily rendered in the view.

*'''Dummy API interaction using HTTParty'''
For now, the API interaction is stubbed using a static JSON response that simulates an LLM’s feedback. This stubbed interaction ensures the full data flow is functional even without a live backend service. The dummy API response provides evaluation metrics such as reviewer scores, average scores, and LLM-generated comments for the reviews.

*'''New view partial: _llm_evaluation_report.html.erb'''
A new view partial `_llm_evaluation_report.html.erb` has been created to display the LLM evaluation report. The styling and table structure closely follow the traditional Review Report design. It presents reviewer names, the number of reviews completed, teams reviewed, scores (both awarded and average), review volume metrics, and editable input fields for grades and comments.

*'''Editable fields populated with API-returned evaluation data'''
The fields for assigning grades and writing comments are populated directly from the LLM-evaluated API data. These fields remain editable so that instructors and TAs can modify the suggested grades and comments before deciding to overwrite and save them manually if needed.

*'''"Overwrite" button for future saving'''
Each review entry now features an "Overwrite" button that is intended to allow instructors to save changes made to the LLM-suggested evaluations. Currently, this button is connected to a placeholder action, and future development will implement functionality to update and persist these evaluations into the database.

*'''Updated routes and views to integrate the feature cleanly'''
The `routes.rb` file was modified to define a route for the new `llm_evaluation_report` controller action. Additionally, `response_report.html.haml` was updated to render the `_llm_evaluation_report.html.erb` partial when the user selects the "Evaluate using LLM" report type, ensuring a seamless integration into the existing reporting infrastructure.

The pull request provides a '''working prototype''' ready to be connected to a real API.

Design for Automatic Evaluation of Peer Reviews

2025-07-16T18:13:25Z

Admin: /* What we want to do */

= Evaluate Using LLMs Integration =

== What we want to do ==

The goal of this project is to integrate LLMs with the peer-assessment process to improve learning. This can be done in various ways, including
* Letting the LLM rate the submission and grade reviewers on how close their review is to the LLM’s (LLM as oracle).
* Using the LLM to read a review and give the reviewer advice on how to improve it (LLM as advisor).
* Using the LLM to rate the reviews and use that metric to weight reviewers’ score in calculating a grade (LLM as reputation system)
* Letting the LLM to do the review and ask reviewers (or authors) if they agree with the LLM and why or why not (LLM as opening salvo)

Students learn best by doing reviews. So, maybe you want the LLM to teach students to review.

We also want to show instructors '''an evaluation of each reviewer’s overall reviewing performance'''.
Rather than looking at individual reviews, instructors will get a '''summary report''' describing how well each reviewer performed overall.
The evaluation includes aspects like quality of comments, score consistency, engagement, and other rubric-related metrics.
This report will be generated using a '''Large Language Model (LLM)''', such as GPT.

Thus, instructors and TAs will be able to '''edit, overwrite, and finalize reviewer evaluation''' based on the LLM-generated suggestions.

== How it is going to be added to Expertiza ==

The "Evaluate using LLM" option has been added to the '''dropdown menu''' alongside Review Report, Author Feedback Report, etc.

When the instructor selects "Evaluate using LLM" and clicks View:
* Review data (responses, reviewer info, reviewee info, scores, comments, etc.) is gathered.
* The data is sent to an '''external API''' (currently stubbed with fake data).
* The returned evaluation is populated into an '''editable table view''' similar to the existing Review Report.

=== Classes ===
* '''LlmEvaluationService''': Located in `app/services/llm_evaluation_service.rb`. Handles outbound API requests and inbound responses.
* '''ReportsController''': New method `llm_evaluation_report` added to generate the LLM evaluation page.

=== Web Service(s) ===
* '''External API call''': Currently stubbed with fake data.
* '''View partial''': `_llm_evaluation_report.html.erb` created to display editable evaluations.

== How much of it is implemented now ==

The following parts are fully working:
* "Evaluate using LLM" dropdown option in the _searchbox.html.erb partial.
* Routing to the correct controller action (`llm_evaluation_report`).
* Service object (`LlmEvaluationService`) created to collect and send review data.
* Stubbed API returning a hardcoded response.
* Editable report table rendered via a new partial called _llm_evaluation_report.html.erb.
* "Overwrite" button added (placeholder functionality). Modify the submit method to overwrite the already existing grades and comments in the reviews_grade table with the LLM generated grades and comments.

Thus, the feature '''end-to-end works with fake data''' for now.

== How to continue development ==

To complete this project:
* Connect to the '''real LLM API''' instead of fake responses.
* Work on the schema for reviews_grade table to incorporate the LLM generated scores and feedback in a new column.
* Implement '''saving''' functionality for the "Overwrite" button which will overwrite the grade_for_reviewer and comment_for_reviewer that already exists with the LLM generated grades and comments.
* Add robust '''error handling''' (for timeout, API errors, etc.).
* Extend support for '''multiple rounds''' and '''varying rubrics'''.
* Add '''RSpec tests''' for the service and controller logic.

== Pull request details ==

The pull request contains the following:

*'''New dropdown entry: Evaluate using LLM'''
A new option titled "Evaluate using LLM" has been added alongside existing report types (such as Review report, Author feedback report) in the reports searchbox partial (`_searchbox.html.erb`). This allows instructors and TAs to select the LLM-based evaluation report from the interface just like any other report type.

*'''New controller action: llm_evaluation_report'''
The `llm_evaluation_report` method has been introduced inside the `ReportsController`. This action is responsible for gathering the necessary assignment and participant data, invoking the service object to fetch LLM-evaluated responses, and rendering the new LLM Evaluation Report view for the instructor or TA.

*'''New service object: LlmEvaluationService'''
A service class `LlmEvaluationService` has been created under `app/services/llm_evaluation_service.rb`. This service collects review and reviewer information from the database, formats it into the expected API request payload, sends a POST request to an external (currently dummy) LLM evaluation API using `HTTParty`, and parses the received response into a structured format that can be easily rendered in the view.

*'''Dummy API interaction using HTTParty'''
For now, the API interaction is stubbed using a static JSON response that simulates an LLM’s feedback. This stubbed interaction ensures the full data flow is functional even without a live backend service. The dummy API response provides evaluation metrics such as reviewer scores, average scores, and LLM-generated comments for the reviews.

*'''New view partial: _llm_evaluation_report.html.erb'''
A new view partial `_llm_evaluation_report.html.erb` has been created to display the LLM evaluation report. The styling and table structure closely follow the traditional Review Report design. It presents reviewer names, the number of reviews completed, teams reviewed, scores (both awarded and average), review volume metrics, and editable input fields for grades and comments.

*'''Editable fields populated with API-returned evaluation data'''
The fields for assigning grades and writing comments are populated directly from the LLM-evaluated API data. These fields remain editable so that instructors and TAs can modify the suggested grades and comments before deciding to overwrite and save them manually if needed.

*'''"Overwrite" button for future saving'''
Each review entry now features an "Overwrite" button that is intended to allow instructors to save changes made to the LLM-suggested evaluations. Currently, this button is connected to a placeholder action, and future development will implement functionality to update and persist these evaluations into the database.

*'''Updated routes and views to integrate the feature cleanly'''
The `routes.rb` file was modified to define a route for the new `llm_evaluation_report` controller action. Additionally, `response_report.html.haml` was updated to render the `_llm_evaluation_report.html.erb` partial when the user selects the "Evaluate using LLM" report type, ensuring a seamless integration into the existing reporting infrastructure.

The pull request provides a '''working prototype''' ready to be connected to a real API.