Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-29T01:58:21Z

Psubram3:

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

====Assignment-Scoped Role Configuration====
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

====Complete Assignment-Duty API Lifecycle====
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

====Assignment Payload Role Context====
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

====Instructor Workflow in Assignment Editor====
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

====Role-Driven Rubric Behavior====
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

====Student Role Validation by Assignment Scope====
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

====Validation and Regression Coverage====
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

====Data Model Mismatch====
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

====Missing Assignment-Duty Lifecycle API====
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

====Disconnected Role Configuration and Rubric Rendering====
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

====Missing Role Data in Assignment Serializer====
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a consumer of role configuration, but it owns its own rubric variation settings. The <code>review_rubric_varies_by_role</code> checkbox lives in the Rubrics tab alongside the existing round- and topic-variation checkboxes, because it controls rubric structure rather than role assignment. Role rows (<code>Teammate Review for {RoleName}</code>) appear only when both <code>Is role based?</code> is enabled in Review Strategy and <code>review_rubric_varies_by_role</code> is enabled in Rubrics, and at least one duty is assigned. This two-gate design means an instructor explicitly opts into role-specific rubric rows and does not get them as an automatic side-effect of enabling role-based mode.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|1000px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls across two tabs: (1) Review Strategy tab owns role assignment — enabling role mode (<code>Is role based?</code>), selecting duties from a dropdown, adding/removing duties (optimistically), inline duty creation via DutyEditor modal, and editing per-role member limits via an inline number input in the assigned roles table that fires <code>PATCH .../limit</code> on blur; (2) Rubrics tab owns <code>review_rubric_varies_by_role</code> checkbox alongside the existing round- and topic-variation checkboxes, and dynamically renders one teammate review row per assigned role when both that checkbox and role mode are active. Duplicate duty state declarations introduced by an upstream merge were removed; the entire role assignment flow was consolidated into a single consistent state path.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Added Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Added API integration method for duty updates and refreshes team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extended team member payload typing to include role/duty metadata required by the student UI.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

====6) Optimistic add/remove for role assignment====
When an instructor adds or removes a duty from an assignment, the UI updates immediately without waiting for the API response. If the request fails, the change is rolled back and the previous state is restored. This keeps the editor responsive for operations that are expected to succeed in the common case.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles from the dropdown — they appear immediately in the table (optimistic update).
# Click <code>Create a new role</code> if needed, fill in the role name, then confirm.
# Edit the <code>Max members</code> value inline in the assigned roles table; click away to save.
# Navigate to Rubrics.
# Enable <code>review_rubric_varies_by_role</code>.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered for each assigned role.
# Uncheck <code>review_rubric_varies_by_role</code> and verify role rows disappear.
# Return to Review Strategy, disable <code>Is role based?</code>, and verify role controls are hidden.

==Future Work==
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T16:26:22Z

Psubram3: /* Previous Issues */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

====Assignment-Scoped Role Configuration====
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

====Complete Assignment-Duty API Lifecycle====
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

====Assignment Payload Role Context====
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

====Instructor Workflow in Assignment Editor====
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

====Role-Driven Rubric Behavior====
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

====Student Role Validation by Assignment Scope====
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

====Validation and Regression Coverage====
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

====Data Model Mismatch====
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

====Missing Assignment-Duty Lifecycle API====
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

====Disconnected Role Configuration and Rubric Rendering====
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

====Missing Role Data in Assignment Serializer====
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|1000px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T16:25:54Z

Psubram3: /* Requirements */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

====Assignment-Scoped Role Configuration====
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

====Complete Assignment-Duty API Lifecycle====
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

====Assignment Payload Role Context====
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

====Instructor Workflow in Assignment Editor====
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

====Role-Driven Rubric Behavior====
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

====Student Role Validation by Assignment Scope====
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

====Validation and Regression Coverage====
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|1000px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:50:35Z

Psubram3: /* Sequence Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|1000px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:50:19Z

Psubram3: /* Sequence Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|1500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:50:04Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|1000px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:48:56Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|large|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:48:44Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

File:2614 er.png

2026-04-28T06:46:39Z

Psubram3: Psubram3 uploaded a new version of File:2614 er.png

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:38:32Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|left|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:38:13Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|center|ER Diagram]]
 

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:37:41Z

Psubram3: /* Sequence Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|center|ER Diagram for Role-based reviewing]]

==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:37:15Z

Psubram3: /* Sequence Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|center|ER Diagram for Role-based reviewing]]

==Sequence Diagram==
==Sequence Diagram==
[[File:2614_seq.png|thumb|left|500px|Sequence Diagram]]
 

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:35:58Z

Psubram3: /* Sequence Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|center|ER Diagram for Role-based reviewing]]

==Sequence Diagram==
[[File:2614_seq.png|thumb|500px|Sequence Diagram]]

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:35:03Z

Psubram3:

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==ER Diagram==

[[File:2614_er.png|thumb|500px|center|ER Diagram for Role-based reviewing]]

==Sequence Diagram==
[[File:2614_seq.png|thumb|500px|center|ER Diagram for Role-based reviewing]]

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:33:30Z

Psubram3: /* ER Diagram */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==ER Diagram==

[[File:2614_er.png|alt=ER Diagram for Role-based reviewing|center|frame|ER Diagram]]

==Sequence Diagram==

<pre>
sequenceDiagram
participant UI as AssignmentEditor (Frontend)
participant API as Rails API
participant DB as MySQL

UI->>API: GET /duties/accessible_duties
API->>DB: Fetch accessible duties
DB-->>API: duties[]
API-->>UI: duties[]

UI->>API: POST /assignments/:id/duties {duty_id}
API->>DB: Upsert assignments_duties
DB-->>API: mapping list
API-->>UI: assignment_duties[]

UI->>API: PATCH /assignments/:id/duties/:duty_id/limit {max_members_for_duty}
API->>DB: Update limit
DB-->>API: updated mapping
API-->>UI: updated mapping

UI->>UI: Recompute Rubrics role rows
</pre>

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

File:2614 seq.png

2026-04-28T06:31:38Z

Psubram3:

File:2614 er.png

2026-04-28T06:30:53Z

Psubram3:

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:24:55Z

Psubram3: /* UI Test Flow */

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
# Open Assignment Editor.
# Go to Review Strategy.
# Enable <code>Is role based?</code>.
# Assign one or more existing roles.
# Click <code>Create a new role</code> if needed, add role name, then create it.
# Set <code>Max members</code> for assigned roles.
# Navigate to Rubrics.
# Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
# Disable role-based mode and verify role controls/rows are hidden.

==ER Diagram==

<pre>
erDiagram
ASSIGNMENT ||--o{ ASSIGNMENTS_DUTY : configures
DUTY ||--o{ ASSIGNMENTS_DUTY : assigned_as
USER ||--o{ DUTY : creates
ASSIGNMENT ||--o{ ASSIGNMENT_PARTICIPANT : has
DUTY ||--o{ ASSIGNMENT_PARTICIPANT : selected_by

ASSIGNMENT {
int id PK
string name
int instructor_id
}

DUTY {
int id PK
string name
int instructor_id FK
bool private
}

ASSIGNMENTS_DUTY {
int assignment_id FK
int duty_id FK
int max_members_for_duty
}

ASSIGNMENT_PARTICIPANT {
int id PK
int parent_id FK
int user_id FK
int duty_id FK
}
</pre>

==Sequence Diagram==

<pre>
sequenceDiagram
participant UI as AssignmentEditor (Frontend)
participant API as Rails API
participant DB as MySQL

UI->>API: GET /duties/accessible_duties
API->>DB: Fetch accessible duties
DB-->>API: duties[]
API-->>UI: duties[]

UI->>API: POST /assignments/:id/duties {duty_id}
API->>DB: Upsert assignments_duties
DB-->>API: mapping list
API-->>UI: assignment_duties[]

UI->>API: PATCH /assignments/:id/duties/:duty_id/limit {max_members_for_duty}
API->>DB: Update limit
DB-->>API: updated mapping
API-->>UI: updated mapping

UI->>UI: Recompute Rubrics role rows
</pre>

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-28T06:22:32Z

Psubram3:

==About Expertiza==
[http://expertiza.ncsu.edu/ Expertiza] is an open-source learning and assessment platform built on [http://rubyonrails.org/ Ruby on Rails], designed around collaborative, project-based courses. Instructors use Expertiza to design assignments, define team structures, configure submission and review stages, and customize rubrics for different pedagogical goals. Students use the platform to form teams, submit artifacts, review peer work, and receive iterative feedback.

One of Expertiza's core strengths is that it treats peer review as a configurable workflow rather than a one-size-fits-all form. In real classroom settings, however, student contributions are often role-specific (for example, frontend, backend, testing, documentation). A generic teammate review model does not always capture this nuance. This project addresses that gap by improving how Expertiza models and configures role-based reviewing at assignment level.

==Introduction==
This project reimplements role-based reviewing in the new Expertiza system, covering both the instructor-facing configuration workflow and the student-facing role declaration capability. The goal is to make role-aware peer review a first-class, reliable feature rather than a partially implemented concept spread across disconnected parts of the codebase.

On the instructor side, the assignment editor is extended so that when role-based reviewing is enabled, an instructor can attach duty definitions to an assignment, set per-role member limits, create new duties inline, and see the Rubrics tab automatically reflect those choices through dynamically generated role-specific teammate review rows. On the student side, a team participant can declare their assigned duty within a team, with the backend enforcing that only duties the instructor has configured for that assignment are selectable.

To support both workflows coherently, the implementation addresses three core problems: role limits must be stored at assignment-duty granularity rather than globally on the duty, the API must provide a complete and predictable assignment-duty lifecycle, and role configuration must live in one place so that rubric rendering is always driven by persisted state rather than ephemeral client-side logic.

==Requirements==
The reimplementation was shaped by the need to make role-based reviewing functional across data, API, and UI layers, covering both instructors configuring assignments and students participating in teams.

===Assignment-Scoped Role Configuration===
A duty like "Frontend" carries different meaning across different assignments. In one assignment it may accommodate two team members; in another, only one. Storing role limits globally on the duty record makes it impossible to express this variation without workarounds. The requirement is therefore to model and persist role constraints at the assignment-duty level, not the duty level, so that each assignment's configuration is independent.

===Complete Assignment-Duty API Lifecycle===
The frontend needs to be able to read which duties are assigned to an assignment, attach a new duty, remove a duty, and update the member limit for an assigned duty — without going through ad hoc endpoints or re-using endpoints built for other purposes. A coherent, RESTful assignment-duty API surface was required so that frontend actions map directly to backend operations.

===Assignment Payload Role Context===
For the frontend to render role-aware rubric rows deterministically, the assignment serializer must include which duties are attached and what their limits are. Without this, the client would need separate API calls to reconstruct role context on every render — adding latency and creating cache-consistency risk.

===Instructor Workflow in Assignment Editor===
Instructors should not need to navigate away to a separate roles management page to configure role-based reviewing for an assignment. The assignment editor itself must support enabling role-based mode, selecting from existing duties, creating new duties inline, setting per-role member limits, and removing duties — all from the Review Strategy tab.

===Role-Driven Rubric Behavior===
When role-based mode is active and duties are assigned, the Rubrics tab should automatically surface per-role teammate review rows (one row per role, named <code>Teammate Review for {RoleName}</code>). If role-based mode is disabled or no duties are assigned, these rows must not appear. The rubric must be a consumer of role configuration, not a place to manage it.

===Student Role Validation by Assignment Scope===
When a team participant selects their role, the backend must verify that the chosen duty is actually assigned to that participant's assignment. This prevents a student from selecting a role that the instructor never configured, and it ensures that participant duty records remain consistent with the assignment's role setup.

===Validation and Regression Coverage===
Backend request specs must cover successful operations, invalid input, unauthorized access, and cross-scope validation failures. Frontend tests must confirm that role-based controls and rubric rows appear and disappear correctly as assignment state changes, without breaking existing non-role-based rubric behavior.

==Previous Issues==
Before this work, the role-based reviewing feature existed in fragments — data model fields, a duty management page, and some controller stubs — but the pieces did not form a working end-to-end workflow. The issues fell into four connected categories.

===Data Model Mismatch===
The <code>duties</code> table stored a <code>max_members</code> field directly on the duty record, treating role limits as global properties of the role itself. This is semantically wrong: how many "Frontend" developers an assignment needs is an assignment-level decision, not a fact about the Frontend role in general. As a consequence, the same duty could not carry different limits across different assignments without data duplication or workarounds. The <code>assignments_duties</code> join table existed but did not carry the limit field, so the actual per-assignment constraint had nowhere clean to live.

===Missing Assignment-Duty Lifecycle API===
The application had a <code>DutiesController</code> for managing duty records globally, but there was no scoped controller or endpoint set for managing which duties are attached to a specific assignment. The frontend had no clean path to add, remove, or update the limit for a duty in the context of one assignment. Any integration that existed relied on general-purpose endpoints being used in non-standard ways, making the contract fragile and hard to maintain.

===Disconnected Role Configuration and Rubric Rendering===
Role setup and rubric behavior were not linked in any defined way. Whether a rubric row appeared for a given role depended on front-end state that was not reliably populated from the assignment payload. Role-related UI controls were scattered, and there was no clear rule about which tab owned role configuration and which tab consumed it. This made it easy for the UI to get into states where role controls were visible but non-functional, or rubric rows appeared when they should not.

===Missing Role Data in Assignment Serializer===
The assignment serializer returned general assignment metadata but did not include which duties were assigned to the assignment or what their per-assignment limits were. This meant the frontend could not reconstruct role context from the standard assignment payload. Rendering role-aware rubric rows deterministically required either additional API calls or client-side state that could drift out of sync with the backend.

==Design / Proposed Solution==

===Data Model Design===
The central design decision is where role limits live. The existing <code>duties</code> table held a global <code>max_members</code> field, which implied a role limit is a property of the role itself. This is incorrect — it is a property of how that role is used within a particular assignment. Two assignments can reuse the same "Frontend" duty and set different limits independently.

The solution is to move the limit into the join table. <code>assignments_duties</code> already models the relationship between assignments and duties; adding <code>max_members_for_duty</code> to this table gives each assignment its own limit per duty without touching the duty record. The duty remains a reusable, shared definition; the assignment-duty mapping carries the assignment-specific constraint.

The <code>assignment_participants</code> table already had a <code>duty_id</code> foreign key column to record a student's declared role. The design retains this and enforces at the API level that any <code>duty_id</code> written to a participant record must correspond to a duty that is actually mapped to that participant's assignment via <code>assignments_duties</code>. This keeps the data consistent without adding extra columns or tables.

===API Design===
The table below lists every new or modified API endpoint introduced by this project, including request parameters and response shape.

====Assignment-Duty Management (<code>AssignmentsDutiesController</code>)====
These endpoints are nested under assignments and form the complete lifecycle for managing which roles exist for an assignment.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/assignments/:assignment_id/duties</code>
| —
| <code>[{ duty_id, duty_name, max_members_for_duty }]</code>
| Returns all duty mappings currently attached to the assignment
|-
| POST
| <code>/assignments/:assignment_id/duties</code>
| <code>{ duty_id: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Attaches an existing duty to the assignment; idempotent — repeated calls do not create duplicates
|-
| DELETE
| <code>/assignments/:assignment_id/duties/:id</code>
| —
| <code>204 No Content</code>
| Removes the duty mapping; <code>:id</code> is the <code>duty_id</code>; returns <code>404</code> if the duty is not mapped to this assignment
|-
| PATCH
| <code>/assignments/:assignment_id/duties/:id/limit</code>
| <code>{ max_members_for_duty: integer }</code>
| <code>{ duty_id, duty_name, max_members_for_duty }</code>
| Updates the per-assignment role limit; returns <code>422</code> if limit is less than 1; returns <code>404</code> if duty not mapped
|}

Authorization: all four endpoints require the authenticated user to be the instructor of the assignment. Requests from other roles return <code>403</code>.

====Participant Duty Update (<code>TeamsParticipantsController</code>)====
This endpoint allows a student to declare their role within a team.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| PATCH
| <code>/teams/:team_id/participants/:id/duty</code>
| <code>{ duty_id: integer }</code>
| <code>{ id, user_id, duty_id, ... }</code>
| Updates the participant's declared duty; validates that the selected duty is mapped to the participant's assignment; returns <code>422</code> on invalid duty
|}

====Accessible Duties (<code>DutiesController</code>)====
Used by the assignment editor to populate the role picker with duties the current user has access to.

{| class="wikitable" style="width: 100%;"
! Method !! Endpoint !! Request Body !! Response !! Notes
|-
| GET
| <code>/duties/accessible_duties</code>
| —
| <code>[{ id, name }]</code>
| Returns duties created by the current instructor or marked as public
|}

====Assignment Serializer Contract====
The assignment payload returned by <code>AssignmentsController#show</code> is extended with role context so the frontend does not need additional calls to render role-aware Rubrics:

<pre>
{
"id": 1,
"name": "Project 1",
...
"has_role_based_review": true,
"assignment_duties": [
{ "duty_id": 3, "duty_name": "Frontend", "max_members_for_duty": 2 },
{ "duty_id": 5, "duty_name": "Backend", "max_members_for_duty": 1 }
]
}
</pre>

The frontend reads <code>assignment_duties</code> to populate rubric rows and role controls. No separate fetch is needed after the assignment loads.

===UI Design===
Role configuration is owned entirely by the Review Strategy tab. Enabling the <code>Is role based?</code> toggle reveals the role management panel, where the instructor can select an existing duty from a dropdown, add it to the assignment, create a new duty inline if needed, set a per-role member limit, and remove duties. All of this is contained in one place without leaving the assignment editor.

The Rubrics tab is a pure consumer of this configuration. It reads the list of assigned duties from the assignment state and generates one teammate review row per role, named <code>Teammate Review for {RoleName}</code>. If role-based mode is off or no duties are assigned, no role rows appear. The Rubrics tab has no role management widgets of its own. This separation means an instructor cannot accidentally configure roles in two places, and rubric rows always reflect what was actually saved.

===SOLID Principles Applied===

====Single Responsibility====
Each class and controller has one clearly bounded job. <code>AssignmentsDutiesController</code> handles only the assignment-duty mapping lifecycle — it does not touch the global duty definition or the assignment itself beyond looking it up. <code>TeamsParticipantsController</code> handles participant operations and is extended only to validate and persist the duty selection. The <code>AssignmentSerializer</code> is responsible for shaping the assignment payload; role data is added to it without mixing in any controller logic.

====Open/Closed====
The system is extended without modifying stable, working code. The <code>AssignmentsController</code> and its core CRUD behavior are untouched — role context is added through the serializer. New endpoints are introduced in a new, nested controller rather than by adding role-specific actions to the existing <code>DutiesController</code>. The Rubrics component in the frontend is extended by reading new fields from the assignment payload, not by coupling it to role management state.

====Liskov Substitution====
The <code>AssignmentsDuty</code> model behaves as a standard ActiveRecord join model. It can be substituted anywhere an ActiveRecord object is expected without breaking callers. The validation and limit logic lives in the controller layer, keeping the model interface clean and predictable.

====Interface Segregation====
The assignment-duty API surface is intentionally narrow and separate from the global duties API. Role management for an assignment is entirely self-contained under <code>/assignments/:id/duties</code>. The global <code>DutiesController</code> handles duty creation and listing; the assignment-specific controller handles only the mapping. Frontend components are not forced to consume a large combined interface — the role picker fetches accessible duties, and the assignment editor fetches assignment duties independently.

====Dependency Inversion====
The Rubrics component does not depend on role management UI state or on specific duty records. It depends on the assignment data contract (specifically the <code>assignment_duties</code> array from the serializer). As long as that contract holds, Rubrics renders correctly regardless of how the underlying duties were created or which controller delivered them. This makes the rubric rendering logic testable in isolation and decoupled from the rest of the editor.

==Implementation==

===Backend files changed===
* <code>reimplementation-back-end/app/controllers/assignments_duties_controller.rb</code> - New controller implementing the full assignment-duty lifecycle: index, create, destroy, and update_limit, with authorization checks and input validation on each action.
* <code>reimplementation-back-end/app/controllers/teams_participants_controller.rb</code> - Extended with an <code>update_duty</code> action that validates the selected duty belongs to the participant's assignment before persisting the change.
* <code>reimplementation-back-end/app/serializers/assignment_serializer.rb</code> - Extended to include <code>has_role_based_review</code> and a nested <code>assignment_duties</code> array carrying each duty's id, name, and per-assignment member limit.
* <code>reimplementation-back-end/config/routes.rb</code> - Added nested resource routes for <code>duties</code> under <code>assignments</code>, including the custom <code>patch :limit</code> member route, and the <code>update_duty</code> route under team participants.
* <code>reimplementation-back-end/db/schema.rb</code> - Added <code>max_members_for_duty</code> column to <code>assignments_duties</code> to store per-assignment role limits at the correct level of granularity.
* <code>reimplementation-back-end/spec/requests/api/v1/assignments_duties_controller_spec.rb</code> - Request specs covering successful operations, invalid input (422), unauthorized access (403), and non-mapped duty lookups (404).
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Request specs for the participant duty update path, including cross-assignment validation and auth cases.
* <code>reimplementation-front-end/src/pages/Student Teams/StudentTeamView.tsx</code> - Add Role column and role selector for each team participant so students can declare or update their duty from assignment-scoped duties.
* <code>reimplementation-front-end/src/hooks/useStudentTeam.ts</code> - Add API integration method for duty updates and refresh team state after role change.
* <code>reimplementation-front-end/src/types</code> (or related team interfaces) - Extend team member payload typing to include role/duty metadata required by the student UI.
* <code>reimplementation-back-end/spec/requests/api/v1/teams_participants_controller_spec.rb</code> - Expand request specs to cover student-facing UI-driven cases for valid duty updates, invalid assignment duty selection, and authorization edge cases.

===Frontend files changed===
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.tsx</code> - Added role-based controls in Review Strategy for enabling role mode, attaching existing duties, inline duty creation, per-role limit updates, and syncing assignment duties state.
* <code>reimplementation-front-end/src/pages/Assignments/AssignmentEditor.test.tsx</code> - Added behavior tests validating conditional role controls and dynamic rubric row rendering for role-based assignments.

===Key implementation decisions and their rationale===

====1) Assignment-duty as the role-limit owner====
Role limits are stored at assignment-duty granularity. This supports real course usage where one role can have different limits across assignments.

====2) Enforced relation validation on participant duty updates====
When a participant duty is updated, backend validation ensures the selected duty is assigned to that participant's assignment. This prevents invalid cross-assignment role references.

====3) Inline role creation in assignment editor====
Instead of forcing instructors to navigate away to a separate role page, the UI supports creating a role in place. This reduces friction and keeps the assignment configuration flow uninterrupted.

====4) Conditional role UI====
Role controls appear only when role-based mode is enabled. This keeps the UI minimal in non-role-based assignments and avoids accidental role operations.

====5) Rubric rows generated from assignment role data====
Rubrics read from configured assignment duties and generate role-specific rows dynamically. This ensures rubric behavior reflects persisted configuration, not stale client-only state.

==Testing Plan==

===Backend testing===
Request specs cover functional and defensive cases:
* Assignment payload includes role metadata.
* Limit update success and persistence.
* Invalid limit returns <code>422</code>.
* Non-assigned duty update returns <code>404</code>.
* Unauthorized modification returns <code>403</code>.

Primary files:
* <code>spec/requests/api/v1/assignments_duties_controller_spec.rb</code>
* <code>spec/requests/api/v1/teams_participants_controller_spec.rb</code>

===Frontend testing===
Executed test command:
* <code>npm run test -- src/pages/Assignments/AssignmentEditor.test.tsx --run</code>

Behavior validated:
* Rubrics round-variation behavior remains correct.
* Role-specific teammate rows appear only when role-based mode is enabled and roles exist.
* Review Strategy role controls are visible only in role-based mode.
* Inline create-role entry flow visibility and control behavior are correct.

==UI Test Flow==
Use the following instructor flow to validate behavior manually:
1. Open Assignment Editor.
2. Go to Review Strategy.
3. Enable <code>Is role based?</code>.
4. Assign one or more existing roles.
5. Click <code>Create a new role</code> if needed, add role name, then create it.
6. Set <code>Max members</code> for assigned roles.
7. Navigate to Rubrics.
8. Confirm rows <code>Teammate Review for {RoleName}</code> are rendered.
9. Disable role-based mode and verify role controls/rows are hidden.

==ER Diagram==

<pre>
erDiagram
ASSIGNMENT ||--o{ ASSIGNMENTS_DUTY : configures
DUTY ||--o{ ASSIGNMENTS_DUTY : assigned_as
USER ||--o{ DUTY : creates
ASSIGNMENT ||--o{ ASSIGNMENT_PARTICIPANT : has
DUTY ||--o{ ASSIGNMENT_PARTICIPANT : selected_by

ASSIGNMENT {
int id PK
string name
int instructor_id
}

DUTY {
int id PK
string name
int instructor_id FK
bool private
}

ASSIGNMENTS_DUTY {
int assignment_id FK
int duty_id FK
int max_members_for_duty
}

ASSIGNMENT_PARTICIPANT {
int id PK
int parent_id FK
int user_id FK
int duty_id FK
}
</pre>

==Sequence Diagram==

<pre>
sequenceDiagram
participant UI as AssignmentEditor (Frontend)
participant API as Rails API
participant DB as MySQL

UI->>API: GET /duties/accessible_duties
API->>DB: Fetch accessible duties
DB-->>API: duties[]
API-->>UI: duties[]

UI->>API: POST /assignments/:id/duties {duty_id}
API->>DB: Upsert assignments_duties
DB-->>API: mapping list
API-->>UI: assignment_duties[]

UI->>API: PATCH /assignments/:id/duties/:duty_id/limit {max_members_for_duty}
API->>DB: Update limit
DB-->>API: updated mapping
API-->>UI: updated mapping

UI->>UI: Recompute Rubrics role rows
</pre>

==Future Work==
* Student-facing role selection UX in team pages.
* Team-level role-capacity enforcement UX feedback.
* Additional integrated end-to-end tests across instructor and student workflows.

==References==
* Fall 2016 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing
* Fall 2017 role-based reviewing: https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-14T02:07:03Z

Psubram3: /* Design Document: E2614. Role-based reviewing */

== 1. Project Overview ==
Expertiza currently supports assigning roles (duties) to an assignment (e.g., Frontend, Backend, Tester). These roles can be selected in the Review Strategy tab when creating or editing an assignment. However, the system does not yet fully integrate roles into the review process or student workflow.

The goal of this project is to implement a complete role-based reviewing system in the Expertiza reimplementation, where:
* Instructors assign roles to an assignment and set limits on how many students can take each role.
* Students select their specific role within their team from the available options.
* Rubrics dynamically adapt based on the roles assigned to the team members.
* Reviews become role-specific, allowing for targeted feedback based on a student's contribution.

== 2. Problem Statement ==
The current reimplementation has basic support for role-based flags but lacks the functional integration required for a complete workflow:
* '''UI Gaps:''' The Rubrics tab does not respond to the "Is role based?" setting. Students have no interface to select or view their roles within a team.
* '''Logic Gaps:''' There is no enforcement of role limits (e.g., only 1 "Tester" per team). Rubrics remain generic regardless of the role being reviewed.
* '''Schema Issues:''' The <code>max_members_for_duty</code> field is incorrectly placed in the global <code>duties</code> table instead of the assignment-specific <code>assignments_duties</code> table.

== 3. Proposed Changes ==

=== 3.1. Database Schema Updates ===
We need to ensure the schema supports assignment-specific role constraints.
* '''Migration 1:''' Move <code>max_members_for_duty</code> from <code>duties</code> to <code>assignments_duties</code>.
** <code>remove_column :duties, :max_members_for_duty</code>
** <code>add_column :assignments_duties, :max_members_for_duty, :integer, default: 1</code>
* '''Association Verification:''' Ensure <code>Participant</code> (or <code>AssignmentParticipant</code>) has a <code>duty_id</code> column to store the selected role for that assignment.

=== 3.2. Backend API Enhancements ===
* '''Assignments Controller:'''
** Update <code>show</code> and <code>index</code> actions to include assigned duties (<code>assignments_duties</code>) and their constraints in the JSON response.
** Ensure the <code>update</code> action correctly handles saving the <code>duty_based</code> flag and the associated duties.
* '''Participants Controller:'''
** Add an action <code>update_duty</code> to allow a student to select or change their role.
** Implement validation logic: Ensure the selected duty belongs to the assignment and the <code>max_members_for_duty</code> limit for the team has not been reached.
* '''Questionnaires Controller:'''
** Expose an endpoint to fetch role-specific teammate review rubrics.

=== 3.3. Instructor Interface (Frontend) ===
* '''Assignment Editor (Review Strategy Tab):'''
** Enhance the "Is role based?" section to allow instructors to not only select duties but also set the <code>max_members_for_duty</code> for each duty in that specific assignment.
* '''Assignment Editor (Rubrics Tab):'''
** Implement conditional logic: If <code>duty_based</code> is true, dynamically render rows for each assigned duty (e.g., "Teammate Review for Frontend", "Teammate Review for Backend").
** Allow the instructor to assign a different questionnaire to each role-based rubric row.

=== 3.4. Student Interface (Frontend) ===
* '''''Your Team' Page:'''
** Add a "Role" column to the team members table.
** For the current user: Display a dropdown containing all roles assigned to the assignment.
** For teammates: Display their selected role as read-only text (or "Not Selected").
** Implement an "Update Role" trigger that calls the backend API and updates the local state/UI upon success.

=== 3.5. Serializer Updates ===
* '''ParticipantSerializer:'''
** Include <code>duty_id</code> and <code>duty_name</code> in the JSON response so the frontend can display role information.
** Example: <code>{ id: 5, user: {...}, duty_id: 2, duty_name: "Frontend", authorization: "student" }</code>
* '''AssignmentSerializer:'''
** Expose the <code>is_role_based</code> flag so the frontend knows when to show role-related UI.
** Include the list of assigned duties with their <code>max_members_for_duty</code> limits.
** Example: <code>{ id: 1, name: "Assignment 1", is_role_based: true, duties: [{id: 1, name: "Frontend", max_members_for_duty: 2}, ...] }</code>

== 4. Design Principles ==
* '''Consistency:''' Use the same expandable table and modal patterns established in the E2608 hierarchy task.
* '''Single Responsibility:''' Keep role-selection logic within the <code>Participant</code> context and rubric-generation logic within the <code>Assignment</code> context.
* '''DRY (Don't Repeat Yourself):''' Reuse the existing <code>Table</code> and <code>Form</code> components for the new UI elements.

== 5. Testing Plan ==

=== 5.1. Unit & Functional Tests (Backend) ===
* '''RSpec:'''
** Verify <code>AssignmentDuty</code> correctly stores and retrieves <code>max_members_for_duty</code>.
** Test that <code>Participant#update_duty</code> fails if the role limit is exceeded for the team.
** Verify API responses contain the necessary nested role data.

=== 5.2. Integration & UI Tests (Frontend) ===
* '''Instructor Flow:'''
** Create an assignment, enable "Is role based", add 2 duties, and verify 2 extra rubric rows appear in the Rubrics tab.
* '''Student Flow:'''
** Join a team, navigate to "Your Team", select a role from the dropdown, refresh the page, and verify the role persists.
** Attempt to select a role that has already reached its <code>max_members_for_duty</code> limit (if applicable) and verify the error handling.

== 6. Relevant Links ==
* '''Historical Reference (Fall 2016):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing CSC/ECE_517_Fall_2016_E1676]
* '''Historical Reference (Fall 2017):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing CSC/ECE_517_Fall_2017/E1798]

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-14T02:05:04Z

Psubram3: /* Design Document: E2614. Role-based reviewing */

= Design Document: E2614. Role-based reviewing =

== 1. Project Overview ==
Expertiza currently supports assigning roles (duties) to an assignment (e.g., Frontend, Backend, Tester). These roles can be selected in the Review Strategy tab when creating or editing an assignment. However, the system does not yet fully integrate roles into the review process or student workflow.

The goal of this project is to implement a complete role-based reviewing system in the Expertiza reimplementation, where:
* Instructors assign roles to an assignment and set limits on how many students can take each role.
* Students select their specific role within their team from the available options.
* Rubrics dynamically adapt based on the roles assigned to the team members.
* Reviews become role-specific, allowing for targeted feedback based on a student's contribution.

== 2. Problem Statement ==
The current reimplementation has basic support for role-based flags but lacks the functional integration required for a complete workflow:
* '''UI Gaps:''' The Rubrics tab does not respond to the "Is role based?" setting. Students have no interface to select or view their roles within a team.
* '''Logic Gaps:''' There is no enforcement of role limits (e.g., only 1 "Tester" per team). Rubrics remain generic regardless of the role being reviewed.
* '''Schema Issues:''' The <code>max_members_for_duty</code> field is incorrectly placed in the global <code>duties</code> table instead of the assignment-specific <code>assignments_duties</code> table.

== 3. Proposed Changes ==

=== 3.1. Database Schema Updates ===
We need to ensure the schema supports assignment-specific role constraints.
* '''Migration 1:''' Move <code>max_members_for_duty</code> from <code>duties</code> to <code>assignments_duties</code>.
** <code>remove_column :duties, :max_members_for_duty</code>
** <code>add_column :assignments_duties, :max_members_for_duty, :integer, default: 1</code>
* '''Association Verification:''' Ensure <code>Participant</code> (or <code>AssignmentParticipant</code>) has a <code>duty_id</code> column to store the selected role for that assignment.

=== 3.2. Backend API Enhancements ===
* '''Assignments Controller:'''
** Update <code>show</code> and <code>index</code> actions to include assigned duties (<code>assignments_duties</code>) and their constraints in the JSON response.
** Ensure the <code>update</code> action correctly handles saving the <code>duty_based</code> flag and the associated duties.
* '''Participants Controller:'''
** Add an action <code>update_duty</code> to allow a student to select or change their role.
** Implement validation logic: Ensure the selected duty belongs to the assignment and the <code>max_members_for_duty</code> limit for the team has not been reached.
* '''Questionnaires Controller:'''
** Expose an endpoint to fetch role-specific teammate review rubrics.

=== 3.3. Instructor Interface (Frontend) ===
* '''Assignment Editor (Review Strategy Tab):'''
** Enhance the "Is role based?" section to allow instructors to not only select duties but also set the <code>max_members_for_duty</code> for each duty in that specific assignment.
* '''Assignment Editor (Rubrics Tab):'''
** Implement conditional logic: If <code>duty_based</code> is true, dynamically render rows for each assigned duty (e.g., "Teammate Review for Frontend", "Teammate Review for Backend").
** Allow the instructor to assign a different questionnaire to each role-based rubric row.

=== 3.4. Student Interface (Frontend) ===
* '''''Your Team' Page:'''
** Add a "Role" column to the team members table.
** For the current user: Display a dropdown containing all roles assigned to the assignment.
** For teammates: Display their selected role as read-only text (or "Not Selected").
** Implement an "Update Role" trigger that calls the backend API and updates the local state/UI upon success.

=== 3.5. Serializer Updates ===
* '''ParticipantSerializer:'''
** Include <code>duty_id</code> and <code>duty_name</code> in the JSON response so the frontend can display role information.
** Example: <code>{ id: 5, user: {...}, duty_id: 2, duty_name: "Frontend", authorization: "student" }</code>
* '''AssignmentSerializer:'''
** Expose the <code>is_role_based</code> flag so the frontend knows when to show role-related UI.
** Include the list of assigned duties with their <code>max_members_for_duty</code> limits.
** Example: <code>{ id: 1, name: "Assignment 1", is_role_based: true, duties: [{id: 1, name: "Frontend", max_members_for_duty: 2}, ...] }</code>

=== 3.6. API Endpoint Specifications ===
* '''GET /assignments/:id'''
** Response: Must include <code>is_role_based</code>, <code>duties</code> array with <code>max_members_for_duty</code> values.
* '''POST /participants/:id/duty'''
** Request: <code>{ duty_id: 2 }</code>
** Response: Updated participant with <code>duty_id</code> and <code>duty_name</code>.
** Validation: Return 422 if duty limit exceeded or duty not assigned to assignment.
* '''GET /participants/:id'''
** Response: Must include <code>duty_id</code> and <code>duty_name</code>.

== 4. Design Principles ==
* '''Consistency:''' Use the same expandable table and modal patterns established in the E2608 hierarchy task.
* '''Single Responsibility:''' Keep role-selection logic within the <code>Participant</code> context and rubric-generation logic within the <code>Assignment</code> context.
* '''DRY (Don't Repeat Yourself):''' Reuse the existing <code>Table</code> and <code>Form</code> components for the new UI elements.

== 5. Testing Plan ==

=== 5.1. Unit & Functional Tests (Backend) ===
* '''RSpec:'''
** Verify <code>AssignmentDuty</code> correctly stores and retrieves <code>max_members_for_duty</code>.
** Test that <code>Participant#update_duty</code> fails if the role limit is exceeded for the team.
** Verify API responses contain the necessary nested role data.

=== 5.2. Integration & UI Tests (Frontend) ===
* '''Instructor Flow:'''
** Create an assignment, enable "Is role based", add 2 duties, and verify 2 extra rubric rows appear in the Rubrics tab.
* '''Student Flow:'''
** Join a team, navigate to "Your Team", select a role from the dropdown, refresh the page, and verify the role persists.
** Attempt to select a role that has already reached its <code>max_members_for_duty</code> limit (if applicable) and verify the error handling.

== 6. Relevant Links ==
* '''Historical Reference (Fall 2016):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing CSC/ECE_517_Fall_2016_E1676]
* '''Historical Reference (Fall 2017):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing CSC/ECE_517_Fall_2017/E1798]

CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing

2026-04-14T01:58:15Z

Psubram3: Created page with "= Design Document: E2614. Role-based reviewing = == 1. Project Overview == Expertiza currently supports assigning roles (duties) to an assignment (e.g., Frontend, Backend, Tester). These roles can be selected in the Review Strategy tab when creating or editing an assignment. However, the system does not yet fully integrate roles into the review process or student workflow. The goal of this project is to implement a complete role-based reviewing system in the Expertiza..."

= Design Document: E2614. Role-based reviewing =

== 1. Project Overview ==
Expertiza currently supports assigning roles (duties) to an assignment (e.g., Frontend, Backend, Tester). These roles can be selected in the Review Strategy tab when creating or editing an assignment. However, the system does not yet fully integrate roles into the review process or student workflow.

The goal of this project is to implement a complete role-based reviewing system in the Expertiza reimplementation, where:
* Instructors assign roles to an assignment and set limits on how many students can take each role.
* Students select their specific role within their team from the available options.
* Rubrics dynamically adapt based on the roles assigned to the team members.
* Reviews become role-specific, allowing for targeted feedback based on a student's contribution.

== 2. Problem Statement ==
The current reimplementation has basic support for role-based flags but lacks the functional integration required for a complete workflow:
* '''UI Gaps:''' The Rubrics tab does not respond to the "Is role based?" setting. Students have no interface to select or view their roles within a team.
* '''Logic Gaps:''' There is no enforcement of role limits (e.g., only 1 "Tester" per team). Rubrics remain generic regardless of the role being reviewed.
* '''Schema Issues:''' The <code>max_members_for_duty</code> field is incorrectly placed in the global <code>duties</code> table instead of the assignment-specific <code>assignments_duties</code> table.

== 3. Proposed Changes ==

=== 3.1. Database Schema Updates ===
We need to ensure the schema supports assignment-specific role constraints.
* '''Migration 1:''' Move <code>max_members_for_duty</code> from <code>duties</code> to <code>assignments_duties</code>.
** <code>remove_column :duties, :max_members_for_duty</code>
** <code>add_column :assignments_duties, :max_members_for_duty, :integer, default: 1</code>
* '''Association Verification:''' Ensure <code>Participant</code> (or <code>AssignmentParticipant</code>) has a <code>duty_id</code> column to store the selected role for that assignment.

=== 3.2. Backend API Enhancements ===
* '''Assignments Controller:'''
** Update <code>show</code> and <code>index</code> actions to include assigned duties (<code>assignments_duties</code>) and their constraints in the JSON response.
** Ensure the <code>update</code> action correctly handles saving the <code>duty_based</code> flag and the associated duties.
* '''Participants Controller:'''
** Add an action <code>update_duty</code> to allow a student to select or change their role.
** Implement validation logic: Ensure the selected duty belongs to the assignment and the <code>max_members_for_duty</code> limit for the team has not been reached.
* '''Questionnaires Controller:'''
** Expose an endpoint to fetch role-specific teammate review rubrics.

=== 3.3. Instructor Interface (Frontend) ===
* '''Assignment Editor (Review Strategy Tab):'''
** Enhance the "Is role based?" section to allow instructors to not only select duties but also set the <code>max_members_for_duty</code> for each duty in that specific assignment.
* '''Assignment Editor (Rubrics Tab):'''
** Implement conditional logic: If <code>duty_based</code> is true, dynamically render rows for each assigned duty (e.g., "Teammate Review for Frontend", "Teammate Review for Backend").
** Allow the instructor to assign a different questionnaire to each role-based rubric row.

=== 3.4. Student Interface (Frontend) ===
* '''''Your Team' Page:'''
** Add a "Role" column to the team members table.
** For the current user: Display a dropdown containing all roles assigned to the assignment.
** For teammates: Display their selected role as read-only text (or "Not Selected").
** Implement an "Update Role" trigger that calls the backend API and updates the local state/UI upon success.

=== 3.5. Serializer Updates ===
* '''ParticipantSerializer:'''
** Include <code>duty_id</code> and <code>duty_name</code> in the JSON response so the frontend can display role information.
** Example: <code>{ id: 5, user: {...}, duty_id: 2, duty_name: "Frontend", authorization: "student" }</code>
* '''AssignmentSerializer:'''
** Expose the <code>is_role_based</code> flag so the frontend knows when to show role-related UI.
** Include the list of assigned duties with their <code>max_members_for_duty</code> limits.
** Example: <code>{ id: 1, name: "Assignment 1", is_role_based: true, duties: [{id: 1, name: "Frontend", max_members_for_duty: 2}, ...] }</code>

=== 3.6. API Endpoint Specifications ===
* '''GET /assignments/:id'''
** Response: Must include <code>is_role_based</code>, <code>duties</code> array with <code>max_members_for_duty</code> values.
* '''POST /participants/:id/duty'''
** Request: <code>{ duty_id: 2 }</code>
** Response: Updated participant with <code>duty_id</code> and <code>duty_name</code>.
** Validation: Return 422 if duty limit exceeded or duty not assigned to assignment.
* '''GET /participants/:id'''
** Response: Must include <code>duty_id</code> and <code>duty_name</code>.

=== 3.7. Edge Cases & Conflicts ===
* '''Role Limit Exceeded:''' If a student attempts to select a role where <code>max_members_for_duty</code> is already met, return a 422 error with message: "This role has reached its maximum member limit."
* '''Role Deleted Mid-Semester:''' If an instructor deletes a role that students have already selected, handle gracefully:
** Do not allow new students to select that role.
** Existing students keep their role assignment (soft delete recommended).
** Display warning in UI: "This role is no longer available for new selections."
* '''Role Toggle Off:''' If an instructor disables role-based reviewing after students selected roles:
** Role data is retained in the database but hidden from the UI.
** If re-enabled, previously selected roles are restored.
* '''Multiple Students Same Role:''' System prevents if <code>max_members_for_duty = 1</code>, but this must be enforced at the database level (transaction safety).

=== 3.8. Backward Compatibility ===
* '''Non-role-based assignments''' must continue functioning unchanged.
* All role-related UI components (Role column, dynamic rubric rows) must be '''conditionally rendered''':
** Only show if <code>is_role_based = true</code> AND at least one duty is assigned.
** Instructors who do not enable role-based reviewing see no changes to their workflows.
* '''Participant serialization:''' Include <code>duty_id</code> as <code>null</code> for non-role-based assignments.

== 4. Design Principles ==
* '''Consistency:''' Use the same expandable table and modal patterns established in the E2608 hierarchy task.
* '''Single Responsibility:''' Keep role-selection logic within the <code>Participant</code> context and rubric-generation logic within the <code>Assignment</code> context.
* '''DRY (Don't Repeat Yourself):''' Reuse the existing <code>Table</code> and <code>Form</code> components for the new UI elements.

== 5. Testing Plan ==

=== 5.1. Unit & Functional Tests (Backend) ===
* '''RSpec:'''
** Verify <code>AssignmentDuty</code> correctly stores and retrieves <code>max_members_for_duty</code>.
** Test that <code>Participant#update_duty</code> fails if the role limit is exceeded for the team.
** Verify API responses contain the necessary nested role data.

=== 5.2. Integration & UI Tests (Frontend) ===
* '''Instructor Flow:'''
** Create an assignment, enable "Is role based", add 2 duties, and verify 2 extra rubric rows appear in the Rubrics tab.
* '''Student Flow:'''
** Join a team, navigate to "Your Team", select a role from the dropdown, refresh the page, and verify the role persists.
** Attempt to select a role that has already reached its <code>max_members_for_duty</code> limit (if applicable) and verify the error handling.

== 6. Relevant Links ==
* '''Historical Reference (Fall 2016):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2016_E1676_Role-based_reviewing CSC/ECE_517_Fall_2016_E1676]
* '''Historical Reference (Fall 2017):''' [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2017/E1798_Role-based_Reviewing CSC/ECE_517_Fall_2017/E1798]

CSC/ECE 517 Spring 2026

2026-04-14T01:54:52Z

Psubram3:

* [[CSC/ECE 517 Spring 2026 - E2600. Reimplement review_mapping_controller]]
* [[CSC/ECE 517 Spring 2026 - E2601. Reimplement student quizzes]]
* [[CSC/ECE 517 Spring 2026 - E2602. Reimplement student task view]]
* [[CSC/ECE 517 Spring 2026 - E2603. Implement ViewSubmissions frontend]]
* [[CSC/ECE 517 Spring 2026 - E2604. Finish Password Resets]]
* [[CSC/ECE 517 Spring 2026 - E2606. Finishing Import and Export helper module]]
* [[CSC/ECE 517 Spring 2026 - E2607. ResponseController Frontend]]
* [[CSC/ECE 517 Spring 2026 - E2609. Review calibration]]
* [[CSC/ECE 517 Spring 2026 - E2610. Teams hierarchy testing]]
* [[CSC/ECE 517 Spring 2026 - E2615. Testing User model and Users controller]]
* [[CSC/ECE 517 Spring 2026 - E2617. Testing Questionnaire and Course Models]]
* [[CSC/ECE 517 Spring 2026 - E2614. Role-based reviewing]]

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-04-06T02:22:36Z

Psubram3: /* Verification and Testing */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The E2608 requirement was to implement a reusable hierarchical list display template for three specific Expertiza views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The project description also identified that existing hierarchy handling relied on Node-based superstructure. The required direction was to reduce that dependency by using direct database queries for parent and child objects, returning hierarchy-ready JSON from the backend, and rendering nested views on the frontend with a consistent template.

In scope, this meant implementing the three hierarchy views above, ensuring they are backed by appropriate parent/child queries, and presenting them in clear expandable/grouped UI patterns.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Implement a seamless nested display of assignments within the Courses view, removing the need for a separate "All Assignments" fetch and improving UI responsiveness.
=== Backend Implementation ===
* Optimized Data Retrieval: Updated the CoursesController#index method to perform eager loading of assignments using Course.includes(:assignments).
* Hierarchy-Ready JSON: Modified the API response to embed nested assignment data within the course objects using as_json(include: :assignments). This significantly reduces the number of network requests required to render the hierarchy.

=== Frontend Implementation ===
* Expandable Table Pattern: Integrated a reusable expandable row pattern in the Courses component. Courses now act as parent nodes that can be expanded to reveal their respective assignments.
* Nested Component Architecture: Developed the CourseAssignments component to handle the rendering of the sub-table. This component provides assignment-specific actions (Edit, Delete, Create Teams, etc.) directly within the course context.
* State-Aware Deletion: Modified the assignment deletion flow (AssignmentDelete.tsx) to update the parent course data locally upon success. This prevents a full page refetch and ensures the UI remains consistent and performant after data modifications.
* Unified Action Handlers: Implemented a consistent set of action icons and handlers for assignments, including quick access to Participant management and Team creation, all nested within the parent course row.
=== Significance ===
These changes move the application away from a fragmented data-loading model to a unified parent-child relationship. By handling the hierarchy at the database query level and mirroring it in the UI with an expandable pattern, the user experience is more intuitive, and the codebase is more maintainable.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.
[[File:E2608_Courses.png|thumb|center|800px|Verification of Courses]]

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

[[File:E2608_questionnaire.png|thumb|center|800px|Verification of Questionnaire]]
=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.
[[File:E2608_Teams.png|thumb|center|800px|Verification of Teams]]

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

File:E2608 questionnaire.png

2026-04-06T02:22:09Z

Psubram3:

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-04-06T02:21:20Z

Psubram3: /* Verification and Testing */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The E2608 requirement was to implement a reusable hierarchical list display template for three specific Expertiza views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The project description also identified that existing hierarchy handling relied on Node-based superstructure. The required direction was to reduce that dependency by using direct database queries for parent and child objects, returning hierarchy-ready JSON from the backend, and rendering nested views on the frontend with a consistent template.

In scope, this meant implementing the three hierarchy views above, ensuring they are backed by appropriate parent/child queries, and presenting them in clear expandable/grouped UI patterns.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Implement a seamless nested display of assignments within the Courses view, removing the need for a separate "All Assignments" fetch and improving UI responsiveness.
=== Backend Implementation ===
* Optimized Data Retrieval: Updated the CoursesController#index method to perform eager loading of assignments using Course.includes(:assignments).
* Hierarchy-Ready JSON: Modified the API response to embed nested assignment data within the course objects using as_json(include: :assignments). This significantly reduces the number of network requests required to render the hierarchy.

=== Frontend Implementation ===
* Expandable Table Pattern: Integrated a reusable expandable row pattern in the Courses component. Courses now act as parent nodes that can be expanded to reveal their respective assignments.
* Nested Component Architecture: Developed the CourseAssignments component to handle the rendering of the sub-table. This component provides assignment-specific actions (Edit, Delete, Create Teams, etc.) directly within the course context.
* State-Aware Deletion: Modified the assignment deletion flow (AssignmentDelete.tsx) to update the parent course data locally upon success. This prevents a full page refetch and ensures the UI remains consistent and performant after data modifications.
* Unified Action Handlers: Implemented a consistent set of action icons and handlers for assignments, including quick access to Participant management and Team creation, all nested within the parent course row.
=== Significance ===
These changes move the application away from a fragmented data-loading model to a unified parent-child relationship. By handling the hierarchy at the database query level and mirroring it in the UI with an expandable pattern, the user experience is more intuitive, and the codebase is more maintainable.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.
[[File:E2608_Courses.png|thumb|center|800px|Verification of Courses]]

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.
[[File:E2608_Teams.png|thumb|center|800px|Verification of Teams]]

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

File:E2608 Teams.png

2026-04-06T02:19:04Z

Psubram3:

File:E2608 Courses.png

2026-04-06T02:18:42Z

Psubram3:

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-04-06T02:15:21Z

Psubram3: /* Backend Implementation */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The E2608 requirement was to implement a reusable hierarchical list display template for three specific Expertiza views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The project description also identified that existing hierarchy handling relied on Node-based superstructure. The required direction was to reduce that dependency by using direct database queries for parent and child objects, returning hierarchy-ready JSON from the backend, and rendering nested views on the frontend with a consistent template.

In scope, this meant implementing the three hierarchy views above, ensuring they are backed by appropriate parent/child queries, and presenting them in clear expandable/grouped UI patterns.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Implement a seamless nested display of assignments within the Courses view, removing the need for a separate "All Assignments" fetch and improving UI responsiveness.
=== Backend Implementation ===
* Optimized Data Retrieval: Updated the CoursesController#index method to perform eager loading of assignments using Course.includes(:assignments).
* Hierarchy-Ready JSON: Modified the API response to embed nested assignment data within the course objects using as_json(include: :assignments). This significantly reduces the number of network requests required to render the hierarchy.

=== Frontend Implementation ===
* Expandable Table Pattern: Integrated a reusable expandable row pattern in the Courses component. Courses now act as parent nodes that can be expanded to reveal their respective assignments.
* Nested Component Architecture: Developed the CourseAssignments component to handle the rendering of the sub-table. This component provides assignment-specific actions (Edit, Delete, Create Teams, etc.) directly within the course context.
* State-Aware Deletion: Modified the assignment deletion flow (AssignmentDelete.tsx) to update the parent course data locally upon success. This prevents a full page refetch and ensures the UI remains consistent and performant after data modifications.
* Unified Action Handlers: Implemented a consistent set of action icons and handlers for assignments, including quick access to Participant management and Team creation, all nested within the parent course row.
=== Significance ===
These changes move the application away from a fragmented data-loading model to a unified parent-child relationship. By handling the hierarchy at the database query level and mirroring it in the UI with an expandable pattern, the user experience is more intuitive, and the codebase is more maintainable.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-04-06T02:14:51Z

Psubram3: /* View 1: Course -> Assignment Hierarchy */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The E2608 requirement was to implement a reusable hierarchical list display template for three specific Expertiza views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The project description also identified that existing hierarchy handling relied on Node-based superstructure. The required direction was to reduce that dependency by using direct database queries for parent and child objects, returning hierarchy-ready JSON from the backend, and rendering nested views on the frontend with a consistent template.

In scope, this meant implementing the three hierarchy views above, ensuring they are backed by appropriate parent/child queries, and presenting them in clear expandable/grouped UI patterns.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Implement a seamless nested display of assignments within the Courses view, removing the need for a separate "All Assignments" fetch and improving UI responsiveness.
=== Backend Implementation ===

* Optimized Data Retrieval: Updated the CoursesController#index method to perform eager loading of assignments using Course.includes(:assignments).
* Hierarchy-Ready JSON: Modified the API response to embed nested assignment data within the course objects using as_json(include: :assignments). This significantly reduces the number of network requests required to render the
hierarchy.

=== Frontend Implementation ===
* Expandable Table Pattern: Integrated a reusable expandable row pattern in the Courses component. Courses now act as parent nodes that can be expanded to reveal their respective assignments.
* Nested Component Architecture: Developed the CourseAssignments component to handle the rendering of the sub-table. This component provides assignment-specific actions (Edit, Delete, Create Teams, etc.) directly within the course context.
* State-Aware Deletion: Modified the assignment deletion flow (AssignmentDelete.tsx) to update the parent course data locally upon success. This prevents a full page refetch and ensures the UI remains consistent and performant after data modifications.
* Unified Action Handlers: Implemented a consistent set of action icons and handlers for assignments, including quick access to Participant management and Team creation, all nested within the parent course row.
=== Significance ===
These changes move the application away from a fragmented data-loading model to a unified parent-child relationship. By handling the hierarchy at the database query level and mirroring it in the UI with an expandable pattern, the user experience is more intuitive, and the codebase is more maintainable.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T03:08:07Z

Psubram3: /* Problem Statement */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The E2608 requirement was to implement a reusable hierarchical list display template for three specific Expertiza views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The project description also identified that existing hierarchy handling relied on Node-based superstructure. The required direction was to reduce that dependency by using direct database queries for parent and child objects, returning hierarchy-ready JSON from the backend, and rendering nested views on the frontend with a consistent template.

In scope, this meant implementing the three hierarchy views above, ensuring they are backed by appropriate parent/child queries, and presenting them in clear expandable/grouped UI patterns.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T03:06:34Z

Psubram3: /* Project Description (E2608) */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:56:56Z

Psubram3: /* Problem Statement */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:56:41Z

Psubram3:

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:54:47Z

Psubram3: /* View 3: Team -> Team Member Hierarchy */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== About Expertiza ==

Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students, TAs, instructors, admins) and complex assignment structures.

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

=== Significance of these changes ===

These changes are significant because they move the teams view away from static or fallback-only data and make it reflect the real assignment context from the database. By filtering teams using <code>parent_id</code> and <code>types</code>, the backend now returns only the teams that actually belong to the selected hierarchy context. The eager loading also improves efficiency by reducing unnecessary queries when team members are rendered.

From a design perspective, this aligns the teams view with the overall E2608 objective of removing unnecessary hierarchy plumbing and replacing it with direct association-based queries and hierarchy-ready responses. It also makes the frontend easier to validate, because the displayed team-member relationships now match the actual persisted data instead of a page-specific mock structure.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:53:17Z

Psubram3: /* View 3: Team -> Team Member Hierarchy */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== About Expertiza ==

Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students, TAs, instructors, admins) and complex assignment structures.

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Backend code snippet ===

The following code snippet shows the core backend change that made the teams API hierarchy-aware:

<pre>
def index
@teams = Team.includes(:users, { teams_participants: :participant })

if params[:parent_id].present?
@teams = @teams.where(parent_id: params[:parent_id])
end

if params[:types].present?
requested_types = params[:types].is_a?(Array) ? params[:types] : params[:types].to_s.split(',')
normalized_types = requested_types.map(&:strip).reject(&:blank?)
@teams = @teams.where(type: normalized_types) if normalized_types.any?
end

@teams = @teams.order(:name, :id)
render json: @teams, each_serializer: TeamSerializer
end
</pre>

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:48:55Z

Psubram3: /* Verification and Testing */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== About Expertiza ==

Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students, TAs, instructors, admins) and complex assignment structures.

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

== Verification and Testing ==

The hosted deployment for our project is available at:

<pre>
http://152.7.177.90:3000/
</pre>

=== UI Testing for Course -> Assignment Hierarchy ===

Log in to the hosted system and navigate to the Courses page. Verify that a course row can be expanded to display the assignments that belong to that course. Also verify that after deleting an assignment, the assignment list updates correctly within the course hierarchy.

=== UI Testing for Questionnaire Type -> Questionnaire Hierarchy ===

Log in as an administrator and navigate to the Questionnaires page. Verify that questionnaire types are shown as parent categories and that each type can be expanded to display the questionnaires in that category. Also verify that the admin workflow for creating, editing, updating, and deleting questionnaires works correctly for the supported questionnaire types.

=== UI Testing for Team -> Team Member Hierarchy ===

Navigate to an assignment's Create Teams page and verify that the page displays real team data rather than fallback sample data. For Assignment <code>1</code>, verify that Team 1 and Team 9 are shown with the correct members, and confirm that the correct members appear under the correct team for the selected assignment context.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:40:46Z

Psubram3: /* CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display */

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== About Expertiza ==

Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students, TAs, instructors, admins) and complex assignment structures.

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

== Verification and Testing ==

=== Frontend ===

=== Backend ===

=== UI validation flow ===

</pre>
# Validate each hierarchy page:
#* Courses page: course rows expand to assignments.
#* Questionnaires page: type rows expand to questionnaires.
#* Create Teams page: team rows expand or otherwise display the correct members for the selected assignment.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation

CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display

2026-03-31T02:38:05Z

Psubram3: Created page with "= CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display = '''Mentors:''' Ed Gehringer and Akhilsai Chittipolu This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams. __TOC__ == About Expertiza == Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students,..."

= CSC/ECE 517 Spring 2026 - E2608. Hierarchical list display =

'''Mentors:''' Ed Gehringer and Akhilsai Chittipolu

This page documents our group implementation for E2608 (Hierarchical List Display) across Courses, Questionnaires, and Teams.

__TOC__

== About Expertiza ==

Expertiza is an open-source Ruby on Rails platform for assignment management, team formation, topic signup, submissions, and peer review workflows. The system supports multiple user roles (students, TAs, instructors, admins) and complex assignment structures.

== Problem Statement ==

The mentor requirement for E2608 was to implement hierarchical list rendering in a consistent pattern across major modules.

Required hierarchy views:

* Course -> Assignments
* Questionnaire Type -> Questionnaires
* Team -> Team Members

The goal was to avoid one-off custom node components and instead apply a reusable hierarchical table pattern.

== Project Description (E2608) ==

Expertiza frequently displays hierarchical data:

* Courses with nested assignments
* Questionnaire types with nested questionnaires
* Courses/assignments with nested teams and team members

Historically, these hierarchies were represented with a Node superstructure where each entity had an associated Node and parent pointer. This introduced additional object management and coupling that was not strictly necessary for rendering parent-child lists.

The project objective was to design and implement a reusable hierarchical display template where:

* Backend performs direct database queries for parent and child data.
* Backend returns JSON payloads suitable for hierarchy rendering.
* Frontend applies a common expandable-list pattern while allowing view-specific presentation styles.

In short, the project moves hierarchy rendering from Node-centric wiring to query-and-render patterns for maintainability and consistency.

== Current Implementation (Before E2608) ==

Before this work, hierarchical data existed in the domain model but was not consistently presented as a parent-child UI pattern across modules.

Typical behavior before E2608:

* Different pages used different data-loading styles, including separate API fetches for related entities.
* Some views depended on fallback/static sample structures when complete nested payloads were unavailable.
* Parent-child relationships were not always exposed in a way that made generic expandable tables straightforward.
* Hierarchical behavior varied by page rather than following one reusable template.

== Drawbacks in Previous Implementation ==

The pre-E2608 behavior created several practical issues:

* Inconsistent user experience: hierarchy expansion behavior differed across pages.
* Additional client complexity: pages needed extra mapping/fetch orchestration to build nested displays.
* Higher coupling to page-specific logic instead of reusable table patterns.
* Harder validation against real backend hierarchy data in some flows.
* More chance of stale UI state when child lists were refetched separately.

== Shared Team Architecture Decision ==

Before implementation, the team agreed on a common hierarchy approach:

* Use eager loading on the backend to fetch parent-child data in fewer queries.
* Return hierarchy-ready JSON (parents with embedded child collections) so frontend pages do minimal reshaping.
* Keep a consistent UX goal for expandable/collapsible hierarchy views, while allowing page-specific rendering style (table expansion or embedded dropdown lists).

This shared approach keeps data retrieval efficient and makes hierarchy rendering consistent with the mentor's requested template style, without forcing a single UI widget across all pages.

== Our Contribution ==

We implemented a unified hierarchical-list strategy across three views and aligned backend payloads with frontend rendering needs.

Summary of what we delivered:

* Unified parent-child rendering approach for three major modules.
* Backend responses shaped to support hierarchy directly, with eager-loaded associations where applicable.
* Frontend pages updated to consume nested or hierarchy-aware data using view-appropriate UI patterns.
* Verification using both UI behavior and real database checks.

== View 1: Course -> Assignment Hierarchy ==

=== Goal ===

Display assignments nested under their parent courses without CourseNode/AssignmentNode style custom hierarchy components.

=== Implemented work ===

* Backend updated to return courses with associated assignments in one response.
* Frontend updated to consume nested assignment data from course payload.
* Frontend no longer depends on separate all-assignments fetch for this view.
* Minor delete-flow refinement: after successful assignment delete, assignment is removed from local frontend data instead of refetching assignments only.

=== Result ===

Course rows can expand into assignment lists through the common hierarchy pattern.

== View 2: Questionnaire Type -> Questionnaire Hierarchy ==

=== Goal ===

Group questionnaires by questionnaire type and display questionnaires nested under each type.

=== Implemented work ===

* Implemented hierarchical questionnaire list from the Admin view.
* Admin can create, edit, update, and delete questionnaires in these types:
** Review
** Metareview
** Author feedback
** Teammate Review
** Survey
** Assignment survey
** Global survey
** Course survey
** Bookmark rating
** Quiz
* In questionnaire listing, admin can expand a dropdown per type to see the embedded list of questionnaire instances for that category.

=== Result ===

Questionnaire browsing follows the same parent-child model used in the other E2608 modules.

== View 3: Team -> Team Member Hierarchy ==

=== Goal ===

Display team members nested under teams for a selected assignment context using real backend data.

=== Backend implementation ===

# Teams filtering in index:
#* Added <code>parent_id</code> filtering support.
#* Added <code>types</code> filtering support (<code>AssignmentTeam</code>, <code>MentoredTeam</code>, etc.).
#* Added deterministic ordering by <code>name</code> and <code>id</code>.
#* Added eager loading with users and team-participant associations.
# Team serialization:
#* Added <code>parent_id</code> in team JSON payload for hierarchy-aware consumers.
# Backward-compatible params:
#* Added <code>parent_id</code> acceptance in team params.
#* Preserved compatibility by mapping <code>assignment_id</code> to <code>parent_id</code> when needed.

=== Frontend implementation ===

# Added dedicated Create Teams loader:
#* Loads teams using assignment context and allowed team types.
#* Loads assignment participants.
#* Maps API data into <code>initialTeams</code> and <code>initialUnassigned</code> structures required by the view.
# Route wiring:
#* Create Teams route switched to the new loader so it uses real backend data instead of fallback-only behavior.

=== Real-data verification ===

Verified against DB via Docker Rails runner for Assignment id <code>1</code>:

* Team 1 (<code>parent_id=1</code>):
** cameron_fahey / Prince Langosh VM
** rickie.hamill / Rep. Rosena Paucek
** elease / Myrl Durgan
* Team 9 (<code>parent_id=1</code>):
** jacinda / Joshua Raynor
** lydia.monahan / Edward Jacobi
** eddie / Halley Schinner VM

This confirmed end-to-end data correctness for the team hierarchy view.

== Verification and Testing ==

=== Frontend ===

=== Backend ===

=== UI validation flow ===

</pre>
# Validate each hierarchy page:
#* Courses page: course rows expand to assignments.
#* Questionnaires page: type rows expand to questionnaires.
#* Create Teams page: team rows expand or otherwise display the correct members for the selected assignment.

== References ==

* Expertiza GitHub repository
* Expertiza project wiki
* RSpec documentation
* Vitest documentation