Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-12-06T16:45:36Z

Dananth:

== Introduction ==
The '''Review Grading Dashboard''' is a new unified interface in Expertiza that modernizes the grading workflow by consolidating reviewer details, review statuses, computed scores, word-volume metrics, and instructor grading inputs into a single, sortable, and interactive dashboard. Built as part of the reimplementation project, this dashboard uses a modern REST API, reusable React components, and a clean architecture aligned with the new Expertiza design philosophy.

This document provides a **highly detailed technical explanation** of the backend logic, API design, data structures, architectural patterns, and internal workflows—intended for developers building or extending the Review Grading feature.

== Background ==
Code repositories:
* [https://github.com/deekshithanantha/reimplementation-front-end Frontend Repository]
* [https://github.com/deekshithanantha/reimplementation-back-end Backend Repository]

Legacy Expertiza scattered review information across many pages. The new dashboard replaces this fragmented approach with a single data-driven, API-powered interface.

== Problem Statement ==
Before this redesign:
* Instructors had to open **each review individually**.
* Completion status, scores, and team mappings were on **different pages**.
* No central place existed to **see scores**, **assign grades**, or **visualize review quality**.
* No way existed to export all review results at once.

== Requirements ==

=== Core Functional Requirements ===
* Dashboard must fetch all review data using a **single API call**.
* Must render:
** Reviewer details
** Assigned teams and review completion states
** Per-round scores
** Metrics on unique word usage
** Inline grading + comments
* CSV export must reflect **exactly what instructors see**.
* Must support multi-round review assignments.

=== Technical Requirements ===
* Data must be produced using **optimized queries**, minimal N+1 loading.
* Must use existing scoring method: <code>aggregate_questionnaire_score</code>.
* All metric calculations must be done server-side to ensure reproducibility.
* All API responses must follow reimplementation JSON standards.
* Frontend must use modular React components with predictable props.

----
==Demo==
===Demo Video===
[[File:2555-thumbnail.jpg|thumb|center|link=https://youtu.be/TZWUdbBrFA8|Click to watch on YouTube]]

== Design Document ==
=== Images ===
[[File:E2562.png|1000px]]
[[File:E2562_wiremock1.jpeg|1000px]]

----

== ✦ Technical Design: Deep Backend Explanation (Option A Expanded) ==

=== 1. Data Aggregation Workflow ===
The dashboard requires combining information from several Expertiza models:

{| class="wikitable"
! Model !! Purpose
|-
| <tt>Participant</tt> || Represents the reviewer as part of an assignment
|-
| <tt>ReviewResponseMap</tt> || Specifies which team a participant must review
|-
| <tt>Response</tt> || Stores the actual review answers and timestamps
|-
| <tt>Assignment</tt> || Determines the review rounds and questionnaires
|-
| <tt>Team</tt> || Represents the team being reviewed
|}

Because these models are spread across separate tables, the controller performs structured join operations:

<pre>
Participant
.includes(:user)
.includes(review_response_maps:
[:reviewee, response: [:scores, :comments]])
</pre>

This drastically reduces SQL calls, avoiding the classic N+1 problem from the legacy system.

=== 2. Score Computation ===
The dashboard must compute weighted scores. This is done using:

<pre>
response.aggregate_questionnaire_score
</pre>

Internally, this:
* Fetches each question’s max score
* Normalizes each response
* Computes weighted total

The dashboard does **not** recalculate scoring logic—only aggregates output.

=== 3. Review “Volume” Metric ===
Implemented in <tt>ResponseVolumeMixin</tt>:

<pre>
def volume
text = answers.pluck(:comments).join(" ")
normalized = text.downcase.gsub(/[^a-z0-9\s]/i, '')
tokens = normalized.split.uniq
tokens.count
end
</pre>

Technical details:
* Strips punctuation
* Splits on whitespace
* De-duplicates tokens using Ruby’s <tt>uniq</tt>
* Returns integer count of unique words

=== 4. Multi-Round Review Handling ===
Assignments may have multiple review rounds.
The dashboard must show one score + one metric per round.

Algorithm:
# Identify the round using <code>Response.round</code>.
# Group responses by <code>reviewer_id</code> and <code>round</code>.
# For each group:
## Compute aggregate score.
## Compute volume metric.
## Compute completion status.

=== 5. Dashboard API JSON Structure ===

The API returns structured JSON:

<pre>
{
"reviewers": [
{
"id": 12,
"username": "jdoe",
"fullname": "John Doe",
"reviews_assigned": 3,
"reviews_completed": 2,
"teams_reviewed": [
{ "team_id": 5, "team_name": "Team 1", "status": "done" },
{ "team_id": 6, "team_name": "Team 2", "status": "pending" }
],
"round_data": [
{
"round": 1,
"score": 88.6,
"volume": 73,
"average_volume": 65
}
],
"grade": null,
"comment": ""
}
]
}
</pre>

=== 6. CSV Export Internal Logic ===

The CSV generator produces:

<pre>
Reviewer Username,
Reviewer Name,
Team Reviewed,
Round 1 Score,
Round 1 Volume,
Round 2 Score,
Round 2 Volume,
Grade,
Comments
</pre>

Technical details:
* Columns vary based on number of rounds.
* Uses Ruby <code>CSV.generate</code>.
* Includes computed averages, not raw text.

----

== ✦ System Architecture (Option C Expanded) ==

=== 1. High-Level Architecture Diagram ===

<pre>
+-------------------+ +-----------------------+
| React Frontend | | Rails API Backend |
+---------+---------+ +-----------+-----------+
| |
| GET /review_dashboard_data |
+-------------------------------->+
| |
| JSON: reviewers, scores, |
| metrics, grades |
<--------------------------------+
| |
| POST /assign_review_grade |
+-------------------------------->+
| |
| GET /export_reviews_csv |
+-------------------------------->+
</pre>

=== 2. Detailed Component Interaction Diagram ===

<pre>
React Dashboard
|
|-- calls ApiService.fetchDashboardData()
| |
| |-- axios GET /review_dashboard_data
| |
| |-- receives structured reviewer JSON
|
|-- renders ReviewTable
| |
| |-- for each row, render:
| - Reviewer identity
| - Review counts
| - Scores (per round)
| - MetricsChart (Recharts)
| - GradeInput
| - CommentInput
|
|-- on grade input:
| |
| |-- axios POST /assign_review_grade
|
|-- on export click:
|
|-- axios GET /export_reviews_csv
|
|-- triggers browser file download
</pre>

=== 3. Backend Internal Flow ===

<pre>
ReviewGradingController#index
|
|-- loads Participants for assignment
|-- loads ReviewResponseMaps
|-- joins Users, Teams, Responses
|-- computes score/volume per round
|-- builds JSON structure
|-- returns response
</pre>

=== 4. Error Handling & Data Failure Modes ===
Backend handles:
* Missing responses → score = null, volume = null
* Late submissions → status = "late"
* No reviews assigned → empty arrays
* Invalid grade → HTTP 422

Frontend handles:
* Empty dashboard → “No reviewers found”
* Fallback UI if metrics chart cannot render
* Retry option for failed grade submissions

=== 5. Performance Considerations ===
* Uses <code>includes</code> to prevent N+1 queries.
* Computes all heavy metrics ahead of time on backend.
* JSON payload optimized to only include necessary fields.
* Recharts renders only visible metrics (virtual scrolling optional).

----

== Data Flow ==
<pre>
Frontend (React)
↓ GET /review_dashboard_data

Backend (Rails)
→ Aggregates Participant / Team / Response data
→ Computes:
• Score per round
• Unique-word volume
• Average volume per round
→ Returns JSON

Frontend
→ Renders reviewer rows + charts
→ Provides inline grading

POST /assign_review_grade
→ Updates grade + comment

GET /export_reviews_csv
→ Downloads CSV file
</pre>

----

== Test Plan ==

=== Backend Technical Tests ===
* Validate round grouping logic.
* Validate unique word calculation (stopword edge cases).
* Ensure response-to-round mapping is correct.
* Test every API error condition:
** invalid grade
** missing participant
** missing response
** incorrect assignment id
** CSV generator with zero reviewers

=== Frontend (Technical) Tests ===
* Test MetricsChart with:
** zero volume
** extremely large review text
** missing average
** multi-round assignments
* Test sorting stability (ascending/descending).
* Test grade input debounce + retry.

----

== Team Members ==
* '''Deekshith Anantha'''
* '''Srinidhi'''
* '''Abhishek Rao'''
* Mentor: '''Ishani Rajput'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-12-03T15:25:32Z

Dananth:

== Introduction ==
The '''Review Grading Dashboard''' is a new unified interface in Expertiza that modernizes the grading workflow by consolidating reviewer details, review statuses, computed scores, word-volume metrics, and instructor grading inputs into a single, sortable, and interactive dashboard. Built as part of the reimplementation project, this dashboard uses a modern REST API, reusable React components, and a clean architecture aligned with the new Expertiza design philosophy.

This document provides a **highly detailed technical explanation** of the backend logic, API design, data structures, architectural patterns, and internal workflows—intended for developers building or extending the Review Grading feature.

== Background ==
Code repositories:
* [https://github.com/deekshithanantha/reimplementation-front-end Frontend Repository]
* [https://github.com/deekshithanantha/reimplementation-back-end Backend Repository]

Legacy Expertiza scattered review information across many pages. The new dashboard replaces this fragmented approach with a single data-driven, API-powered interface.

== Problem Statement ==
Before this redesign:
* Instructors had to open **each review individually**.
* Completion status, scores, and team mappings were on **different pages**.
* No central place existed to **see scores**, **assign grades**, or **visualize review quality**.
* No way existed to export all review results at once.

== Requirements ==

=== Core Functional Requirements ===
* Dashboard must fetch all review data using a **single API call**.
* Must render:
** Reviewer details
** Assigned teams and review completion states
** Per-round scores
** Metrics on unique word usage
** Inline grading + comments
* CSV export must reflect **exactly what instructors see**.
* Must support multi-round review assignments.

=== Technical Requirements ===
* Data must be produced using **optimized queries**, minimal N+1 loading.
* Must use existing scoring method: <code>aggregate_questionnaire_score</code>.
* All metric calculations must be done server-side to ensure reproducibility.
* All API responses must follow reimplementation JSON standards.
* Frontend must use modular React components with predictable props.

----

== Design Document ==
== Images ==
[[File:E2562.png|1000px]]
[[File:E2562_wiremock1.jpeg|1000px]]

----

== ✦ Technical Design: Deep Backend Explanation (Option A Expanded) ==

=== 1. Data Aggregation Workflow ===
The dashboard requires combining information from several Expertiza models:

{| class="wikitable"
! Model !! Purpose
|-
| <tt>Participant</tt> || Represents the reviewer as part of an assignment
|-
| <tt>ReviewResponseMap</tt> || Specifies which team a participant must review
|-
| <tt>Response</tt> || Stores the actual review answers and timestamps
|-
| <tt>Assignment</tt> || Determines the review rounds and questionnaires
|-
| <tt>Team</tt> || Represents the team being reviewed
|}

Because these models are spread across separate tables, the controller performs structured join operations:

<pre>
Participant
.includes(:user)
.includes(review_response_maps:
[:reviewee, response: [:scores, :comments]])
</pre>

This drastically reduces SQL calls, avoiding the classic N+1 problem from the legacy system.

=== 2. Score Computation ===
The dashboard must compute weighted scores. This is done using:

<pre>
response.aggregate_questionnaire_score
</pre>

Internally, this:
* Fetches each question’s max score
* Normalizes each response
* Computes weighted total

The dashboard does **not** recalculate scoring logic—only aggregates output.

=== 3. Review “Volume” Metric ===
Implemented in <tt>ResponseVolumeMixin</tt>:

<pre>
def volume
text = answers.pluck(:comments).join(" ")
normalized = text.downcase.gsub(/[^a-z0-9\s]/i, '')
tokens = normalized.split.uniq
tokens.count
end
</pre>

Technical details:
* Strips punctuation
* Splits on whitespace
* De-duplicates tokens using Ruby’s <tt>uniq</tt>
* Returns integer count of unique words

=== 4. Multi-Round Review Handling ===
Assignments may have multiple review rounds.
The dashboard must show one score + one metric per round.

Algorithm:
# Identify the round using <code>Response.round</code>.
# Group responses by <code>reviewer_id</code> and <code>round</code>.
# For each group:
## Compute aggregate score.
## Compute volume metric.
## Compute completion status.

=== 5. Dashboard API JSON Structure ===

The API returns structured JSON:

<pre>
{
"reviewers": [
{
"id": 12,
"username": "jdoe",
"fullname": "John Doe",
"reviews_assigned": 3,
"reviews_completed": 2,
"teams_reviewed": [
{ "team_id": 5, "team_name": "Team 1", "status": "done" },
{ "team_id": 6, "team_name": "Team 2", "status": "pending" }
],
"round_data": [
{
"round": 1,
"score": 88.6,
"volume": 73,
"average_volume": 65
}
],
"grade": null,
"comment": ""
}
]
}
</pre>

=== 6. CSV Export Internal Logic ===

The CSV generator produces:

<pre>
Reviewer Username,
Reviewer Name,
Team Reviewed,
Round 1 Score,
Round 1 Volume,
Round 2 Score,
Round 2 Volume,
Grade,
Comments
</pre>

Technical details:
* Columns vary based on number of rounds.
* Uses Ruby <code>CSV.generate</code>.
* Includes computed averages, not raw text.

----

== ✦ System Architecture (Option C Expanded) ==

=== 1. High-Level Architecture Diagram ===

<pre>
+-------------------+ +-----------------------+
| React Frontend | | Rails API Backend |
+---------+---------+ +-----------+-----------+
| |
| GET /review_dashboard_data |
+-------------------------------->+
| |
| JSON: reviewers, scores, |
| metrics, grades |
<--------------------------------+
| |
| POST /assign_review_grade |
+-------------------------------->+
| |
| GET /export_reviews_csv |
+-------------------------------->+
</pre>

=== 2. Detailed Component Interaction Diagram ===

<pre>
React Dashboard
|
|-- calls ApiService.fetchDashboardData()
| |
| |-- axios GET /review_dashboard_data
| |
| |-- receives structured reviewer JSON
|
|-- renders ReviewTable
| |
| |-- for each row, render:
| - Reviewer identity
| - Review counts
| - Scores (per round)
| - MetricsChart (Recharts)
| - GradeInput
| - CommentInput
|
|-- on grade input:
| |
| |-- axios POST /assign_review_grade
|
|-- on export click:
|
|-- axios GET /export_reviews_csv
|
|-- triggers browser file download
</pre>

=== 3. Backend Internal Flow ===

<pre>
ReviewGradingController#index
|
|-- loads Participants for assignment
|-- loads ReviewResponseMaps
|-- joins Users, Teams, Responses
|-- computes score/volume per round
|-- builds JSON structure
|-- returns response
</pre>

=== 4. Error Handling & Data Failure Modes ===
Backend handles:
* Missing responses → score = null, volume = null
* Late submissions → status = "late"
* No reviews assigned → empty arrays
* Invalid grade → HTTP 422

Frontend handles:
* Empty dashboard → “No reviewers found”
* Fallback UI if metrics chart cannot render
* Retry option for failed grade submissions

=== 5. Performance Considerations ===
* Uses <code>includes</code> to prevent N+1 queries.
* Computes all heavy metrics ahead of time on backend.
* JSON payload optimized to only include necessary fields.
* Recharts renders only visible metrics (virtual scrolling optional).

----

== Data Flow ==
<pre>
Frontend (React)
↓ GET /review_dashboard_data

Backend (Rails)
→ Aggregates Participant / Team / Response data
→ Computes:
• Score per round
• Unique-word volume
• Average volume per round
→ Returns JSON

Frontend
→ Renders reviewer rows + charts
→ Provides inline grading

POST /assign_review_grade
→ Updates grade + comment

GET /export_reviews_csv
→ Downloads CSV file
</pre>

----

== Test Plan ==

=== Backend Technical Tests ===
* Validate round grouping logic.
* Validate unique word calculation (stopword edge cases).
* Ensure response-to-round mapping is correct.
* Test every API error condition:
** invalid grade
** missing participant
** missing response
** incorrect assignment id
** CSV generator with zero reviewers

=== Frontend (Technical) Tests ===
* Test MetricsChart with:
** zero volume
** extremely large review text
** missing average
** multi-round assignments
* Test sorting stability (ascending/descending).
* Test grade input debounce + retry.

----

== Team Members ==
* '''Deekshith Anantha'''
* '''Srinidhi'''
* '''Abhishek Rao'''
* Mentor: '''Ishani Rajput'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-11T04:39:47Z

Dananth:

== Background ==
The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

== Implementation ==
=== Frontend ===
[[File:E2562.png|1000px]]

* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

== Design and Architecture ==
This project will follow the established architecture of the reimplementation effort, which is a Client-Server Architecture.

'''Backend (Server):''' A <tt>Rails API</tt> will expose new endpoints to provide data and handle grading.
'''Frontend (Client):''' A <tt>React + TypeScript</tt> application will consume the API and render the interactive dashboard.

=== Design Principles ===
* '''Single Responsibility Principle (SRP):''' The backend (Rails) is responsible only for business logic and data persistence. The frontend (React) is responsible only for presentation and user interaction. The <tt>Response</tt> model will handle score calculation, while the new <tt>ReviewGradingController</tt> will handle data aggregation.
* '''Don't Repeat Yourself (DRY):''' We will not write new code to calculate review scores. We will strictly reuse the existing <tt>aggregate_questionnaire_score</tt> method available in the <tt>Response</tt> object, as specified in the project requirements.

=== Design Patterns ===
* '''Facade Pattern:''' The new backend API will act as a Facade. The frontend will make a single API call (e.g., <tt>GET /api/v1/review_dashboard_data</tt>) to fetch all necessary data. This endpoint will hide the complexity of gathering information from multiple models (<tt>Participants</tt>, <tt>Responses</tt>, <tt>Teams</tt>, <tt>Assignments</tt>), simplifying frontend logic.
* '''Mixin (Ruby Concern):''' The project specification suggests a "''mixin''" to calculate review "volume". We will implement this as a Ruby Concern (<tt>ResponseVolumeMixin</tt>) and include it in the <tt>Response</tt> model. This adheres to SRP by separating the volume calculation logic from the core responsibilities of the <tt>Response</tt> model.
* '''Component-Based Architecture:''' The frontend will be built using reusable React components. The <tt>ReviewGradingDashboard</tt> will be a parent component composed of:
** A reusable <tt>Table</tt> component.
** A new <tt>MetricsChart</tt> component (using <tt>Recharts</tt>) to display the volume bar graph.
** Reusable <tt>GradeInput</tt> components.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-10T22:34:32Z

Dananth: /* Frontend */

== Background ==
The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

== Implementation ==
=== Frontend ===
[[File:E2562.png|1000px]]

* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-10T22:34:19Z

Dananth: /* Frontend */

== Background ==
The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

== Implementation ==
=== Frontend ===
[[File:E2562.png|500px]]

* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-10T22:33:59Z

Dananth: /* Frontend */

== Background ==
The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

== Implementation ==
=== Frontend ===
[[File:E2562.png|500px|thumb|left|Caption]]

* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-10T22:33:26Z

Dananth:

== Background ==
The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

== Implementation ==
=== Frontend ===
[[File:E2562.png|200px|thumb|left|Caption]]
* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''

File:E2562.png

2025-11-10T22:29:34Z

Dananth:

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-07T03:26:23Z

Dananth: /* Team Members */

= SC/ECE 517 Fall 2025 – E2562. Review Grading Dashboard =

This page contains information about '''E2562. Review Grading Dashboard''', which is a project in CSC/ECE 517 Fall 2025.

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

== Background ==
'''Expertiza''' is an open-source application built on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams and peer review each other’s work.

The frontend is written in '''TypeScript (React)''', while the backend uses '''Ruby on Rails'''. The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

----

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

----

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

----

== Implementation ==
=== Frontend ===
* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

----

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

----

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

----

== Team Members ==
* ''' Deekshith Anantha'''
* ''' Srinidhi'''
* '''Abhishek Rao'''
----

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-07T03:24:42Z

Dananth:

= SC/ECE 517 Fall 2025 – E2562. Review Grading Dashboard =

This page contains information about '''E2562. Review Grading Dashboard''', which is a project in CSC/ECE 517 Fall 2025.

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

== Background ==
'''Expertiza''' is an open-source application built on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams and peer review each other’s work.

The frontend is written in '''TypeScript (React)''', while the backend uses '''Ruby on Rails'''. The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

----

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

----

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

----

== Implementation ==
=== Frontend ===
* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

----

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

----

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

----

== Team Members ==
* '''Deekshith Anantha''' – Frontend development, chart integration, UI/UX testing
(Additional members can be added as applicable.)

----

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-07T03:24:20Z

Dananth:

= SC/ECE 517 Fall 2025 – E2562. Review Grading Dashboard =

This page contains information about '''E2562. Review Grading Dashboard''', which is a project in CSC/ECE 517 Fall 2025.

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

----

== Background ==
'''Expertiza''' is an open-source application built on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams and peer review each other’s work.

The frontend is written in '''TypeScript (React)''', while the backend uses '''Ruby on Rails'''. The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

----

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

----

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

----

== Implementation ==
=== Frontend ===
* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

----

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

----

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

----

== Team Members ==
* '''Deekshith Anantha''' – Frontend development, chart integration, UI/UX testing
(Additional members can be added as applicable.)

----

CSC/ECE 517 Fall 2025 - E2562. Review grading dashboard

2025-11-07T03:23:32Z

Dananth: Created page with "= SC/ECE 517 Fall 2025 – E2562. Review Grading Dashboard = This page contains information about '''E2562. Review Grading Dashboard''', which is a project in CSC/ECE 517 Fall 2025. Please see below for a description of the design of the project. == Contents == 1. Background 2. Problem Statement 3. Requirements 3.1 Core Requirements 3.2 Design Requirements..."

= SC/ECE 517 Fall 2025 – E2562. Review Grading Dashboard =

This page contains information about '''E2562. Review Grading Dashboard''', which is a project in CSC/ECE 517 Fall 2025.

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

== Contents ==
1. [[#Background|Background]]
2. [[#Problem_Statement|Problem Statement]]
3. [[#Requirements|Requirements]]
3.1 [[#Core_Requirements|Core Requirements]]
3.2 [[#Design_Requirements|Design Requirements]]
4. [[#Implementation|Implementation]]
5. [[#Results|Results]]
6. [[#Test_Plan|Test Plan]]
6.1 [[#Manual_Testing|Manual Testing]]
6.2 [[#Automated_Testing|Automated Testing]]
7. [[#Team_Members|Team Members]]

----

== Background ==
'''Expertiza''' is an open-source application built on the Ruby on Rails framework. Instructors can create and manage assignments, and students can form teams and peer review each other’s work.

The frontend is written in '''TypeScript (React)''', while the backend uses '''Ruby on Rails'''. The codebase for this reimplementation effort can be found in the following repositories:

* [https://github.com/AnvithaReddyGutha/reimplementation-front-end Frontend Repository (reimplementation-front-end)]
* [https://github.com/AnvithaReddyGutha/reimplementation-back-end Backend Repository (reimplementation-back-end)]

The '''Review Grading Dashboard''' is a modernized instructor interface that simplifies grading peer reviews by consolidating key review information, grading tools, and performance metrics into a single, sortable page.

----

== Problem Statement ==
The current Expertiza system makes grading peer reviews cumbersome and inefficient. Review data such as reviewer details, completion status, and scores are scattered across multiple pages, forcing instructors to navigate between views to assign grades.

The goal of this project is to design and implement a dedicated '''Review Grading Dashboard''' that provides instructors and TAs with a unified page to:
* View all reviews submitted by students.
* Check review completion status and assigned scores.
* Analyze review metrics such as “volume” (unique word usage).
* Enter grades and comments for reviews.
* Export review scores and grades to a CSV file.

This dashboard serves as the central grading hub for instructors, replacing the older fragmented grading workflow.

----

== Requirements ==

=== Core Requirements ===
* The dashboard is accessible only to users with the '''Instructor''' or '''TA''' role.
* The dashboard displays a table containing the following columns:
** '''Reviewer:''' Username and full name of the reviewer.
** '''Reviews Done:''' Number of reviews completed out of the total assigned.
** '''Team Reviewed:''' Each reviewed team, color-coded by review completion status (e.g., done, pending, late).
** '''Scores:''' Weighted average review scores per round, calculated via the existing `aggregate_questionnaire_score` method.
** '''Metrics:''' A column chart comparing the number of unique words used by the reviewer to the average review volume.
** '''Grade:''' Text box for instructors to enter a numeric grade.
** '''Comments:''' Text box for instructors to write feedback or grading rationale.

* Each column should be sortable (e.g., Reviewer, Reviews Done, Scores).
* Table rows should have alternating background colors for readability.
* A button should allow instructors to '''export all grades and scores as a CSV file'''.
* If there are multiple review rounds, display one score and metric per round.

=== Design Requirements ===
* Follow the same design guidelines as the [https://github.com/AnvithaReddyGutha/reimplementation-front-end/blob/main/design_document.md reimplementation-front-end design document].
* Use compact column widths to prevent unnecessary wrapping.
* Implement hover tooltips to show extended reviewer or metric details.
* Use consistent UI elements (text boxes, buttons) from the existing frontend.
* For the "Metrics" column chart:
** '''Charting library:''' Recharts (React-based, lightweight, responsive).
** The chart should compare each student’s review “volume” with the average.
* Maintain color accessibility and responsiveness across devices.

----

== Implementation ==
=== Frontend ===
* Implemented using React + TypeScript as part of the reimplementation front-end.
* Fetch review and grading data from new API endpoints.
* Use '''Recharts''' for the Metrics visualization.
* Build a sortable, paginated table with reusable table and form components.

=== Backend ===
* Implemented using Ruby on Rails.
* Create the following REST API endpoints:
** `/api/v1/review_dashboard_data` (GET) – Fetch all review-related data.
** `/api/v1/assign_review_grade` (POST) – Submit grades and comments.
** `/api/v1/export_reviews_csv` (GET) – Export data to CSV.

* Optionally add a '''ResponseVolumeMixin''' to the `Response` model to calculate “volume,” defined as the count of unique words in a student’s review.

=== Data Flow ===
<pre>
Frontend (React)
↓ GET /review_dashboard_data
Backend (Rails)
→ Returns JSON with reviewer info, scores, and metrics
Frontend
↓ Renders sortable table + charts
Instructor Input
→ POST /assign_review_grade
Backend
→ Stores grade + supports CSV export
</pre>

----

== Results ==
(To be completed upon implementation)

Expected outcomes:
* A clean, sortable dashboard interface for instructors.
* Visual metrics to compare review quality and engagement.
* Streamlined grading workflow with direct input and CSV export.

----

== Test Plan ==

=== Manual Testing ===
# Log in as an instructor or TA.
# Navigate to the course dashboard and click the '''Review Grading Dashboard''' link.
# Verify that:
## Reviewer names, teams reviewed, and completion status are displayed correctly.
## Team color codes correspond to review completion.
## Scores are accurate per round.
## The metrics chart renders correctly using Recharts.
## Grades and comments can be entered and saved successfully.
# Click the “Export CSV” button and ensure the CSV file contains accurate data.
# Test sorting functionality for multiple columns.
# Confirm that alternating row colors and hover highlights appear correctly.

=== Automated Testing ===
* '''Backend (RSpec):'''
** Test API responses for correctness and completeness.
** Validate `volume()` method returns expected unique word count.
** Verify CSV export structure and content.

* '''Frontend (Jest + React Testing Library):'''
** Test rendering of dashboard table and Recharts components.
** Verify sorting and input functionalities.
** Mock API calls to test grade submission.

----

== Team Members ==
* '''Deekshith Anantha''' – Frontend development, chart integration, UI/UX testing
(Additional members can be added as applicable.)

----

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-31T17:54:48Z

Dananth: /* References */

__TOC__

== Introduction ==

=== Background ===
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

=== Motivation ===
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

=== Tasks Accomplished ===
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

===Files Modified and Created===

* app/models/project_topic.rb
* app/models/signed_up_team.rb
* app/controllers/api/v1/project_topics_controller.rb
* app/controllers/api/v1/signed_up_teams_controller.rb
* app/serializers/project_topic_serializer.rb
* app/serializers/signed_up_team_serializer.rb
* spec/models/project_topic_spec.rb
* spec/models/signed_up_team_spec.rb
* spec/requests/project_topics_spec.rb
* spec/requests/signed_up_teams_spec.rb

==Demo==
===Demo Video===
[[File:2555-thumbnail.jpg|thumb|center|link=https://www.youtube.com/watch?v=3zYt2hguXbY|Click to watch on YouTube]]

== Problem Analysis ==

=== Issues with the Previous Implementation are as follows ===

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

== Implementation ==

=== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

=== Core Functionality Implemented ===

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

=== Key Backend Improvements ===

=== ProjectTopic Model ===
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

=== SignedUpTeam Model ===
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

=== Frontend Improvements ===

=== Topic signup page for students ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}

=== Admin page to CRUD Assignment Topics ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}

=== Database Migrations ===
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

=== Testing ===

=== RSpec Tests (Backend) ===
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

=== Manual Tests (UI) ===
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

== Impact Analysis ==

=== Summary of Changes ===
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

=== Achievements ===
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

== Future Work ==
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

== Conclusion ==
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

== References ==
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-30T23:01:01Z

Dananth: /* Demo Video */

__TOC__

== Introduction ==

=== Background ===
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

=== Motivation ===
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

=== Tasks Accomplished ===
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

===Files Modified and Created===

* app/models/project_topic.rb
* app/models/signed_up_team.rb
* app/controllers/api/v1/project_topics_controller.rb
* app/controllers/api/v1/signed_up_teams_controller.rb
* app/serializers/project_topic_serializer.rb
* app/serializers/signed_up_team_serializer.rb
* spec/models/project_topic_spec.rb
* spec/models/signed_up_team_spec.rb
* spec/requests/project_topics_spec.rb
* spec/requests/signed_up_teams_spec.rb

==Demo==
===Demo Video===
[[File:2555-thumbnail.jpg|thumb|center|link=https://www.youtube.com/watch?v=3zYt2hguXbY|Click to watch on YouTube]]

== Problem Analysis ==

=== Issues with the Previous Implementation are as follows ===

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

== Implementation ==

=== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

=== Core Functionality Implemented ===

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

=== Key Backend Improvements ===

=== ProjectTopic Model ===
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

=== SignedUpTeam Model ===
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

=== Frontend Improvements ===

=== Topic signup page for students ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}

=== Admin page to CRUD Assignment Topics ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}

=== Database Migrations ===
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

=== Testing ===

=== RSpec Tests (Backend) ===
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

=== Manual Tests (UI) ===
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

== Impact Analysis ==

=== Summary of Changes ===
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

=== Achievements ===
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

== Future Work ==
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

== Conclusion ==
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

== References ==
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-30T22:53:23Z

Dananth:

__TOC__

== Introduction ==

=== Background ===
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

=== Motivation ===
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

=== Tasks Accomplished ===
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

===Files Modified and Created===

* app/models/project_topic.rb
* app/models/signed_up_team.rb
* app/controllers/api/v1/project_topics_controller.rb
* app/controllers/api/v1/signed_up_teams_controller.rb
* app/serializers/project_topic_serializer.rb
* app/serializers/signed_up_team_serializer.rb
* spec/models/project_topic_spec.rb
* spec/models/signed_up_team_spec.rb
* spec/requests/project_topics_spec.rb
* spec/requests/signed_up_teams_spec.rb

==Demo==
===Demo Video===
[[File:2555-thumbnail.jpg|thumb|center|link=https://www.youtube.com/watch?v=WW0EyVHA43k|Click to watch on YouTube]]

== Problem Analysis ==

=== Issues with the Previous Implementation are as follows ===

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

== Implementation ==

=== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

=== Core Functionality Implemented ===

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

=== Key Backend Improvements ===

=== ProjectTopic Model ===
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

=== SignedUpTeam Model ===
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

=== Frontend Improvements ===

=== Topic signup page for students ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}

=== Admin page to CRUD Assignment Topics ===
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}

=== Database Migrations ===
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

=== Testing ===

=== RSpec Tests (Backend) ===
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

=== Manual Tests (UI) ===
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

== Impact Analysis ==

=== Summary of Changes ===
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

=== Achievements ===
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

== Future Work ==
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

== Conclusion ==
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

== References ==
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-30T22:38:23Z

Dananth: /* AssignmentEditPage Component */

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== Topic signup page for students ====
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}

==== Admin page to CRUD Assignment Topics ====
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-30T22:35:22Z

Dananth: /* StudentTasks Component */

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_edit.png|800px|caption]]
|}

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-30T22:34:53Z

Dananth: /* AssignmentEditPage Component */

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Topics_signup_page_for_students.png|800px|Topics_signup_page_for_students]]
|}
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_SelectionPage.png|800px|thumb|left|Caption]]
|}
{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Admin_topic_edit.png|800px|caption]]
|}

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

File:Admin topic edit.png

2025-10-30T22:24:42Z

Dananth:

File:Admin topic SelectionPage.png

2025-10-30T22:23:10Z

Dananth:

File:Topics signup page for students.png

2025-10-30T22:19:50Z

Dananth:

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T01:17:48Z

Dananth:

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
<syntaxhighlight lang="typescript">
// Manages overall state for assignment editing
const AssignmentEditPage = () => {
// ... hooks for fetching data (assignment, topics), state for active tab, topic settings, topics data ...

// Fetch assignment details on load
useEffect(() => {
if (id) fetchAssignment({ url: `/assignments/${id}` });
}, [id, fetchAssignment]);

// Update local state when assignment data is loaded (e.g., name, allow_bookmarks)
useEffect(() => {
if (assignmentResponse?.data) {
setAssignmentName(assignmentResponse.data.name || "");
setTopicSettings(prev => ({ ...prev, allowBookmarks: assignmentResponse.data.allow_bookmarks }));
}
}, [assignmentResponse]);

// Fetch topics when assignment ID is known
useEffect(() => {
if (id) fetchTopics({ url: `/project_topics?assignment_id=${id}` });
}, [id, fetchTopics]);

// Process fetched topics into format needed by TopicsTable
useEffect(() => {
if (topicsResponse?.data) {
// ... transform backend topic structure to frontend TopicData structure ...
setTopicsData(transformedTopics);
}
}, [topicsResponse]);

// Handler for topic setting changes (e.g., checkboxes)
const handleTopicSettingChange = useCallback((setting: string, value: boolean) => {
setTopicSettings((prev) => ({ ...prev, [setting]: value }));
// Persist allowBookmarks change immediately
if (setting === 'allowBookmarks' && id) {
updateAssignment({ /* ... PATCH request data ... */ });
}
}, [id, updateAssignment]);

// Handlers for topic CRUD operations (passed down to TopicsTab)
const handleDeleteTopic = useCallback((topicId: string) => {
// ... call deleteTopic API ...
}, [id, deleteTopic]);
// ... other handlers (create, edit, drop team) ...

// Renders the content based on the active tab state
const renderTabContent = () => {
switch (activeTab) {
case "topics":
return <TopicsTab /* pass props: settings, data, handlers */ />;
// ... other cases for RubricsTab, DueDatesTab etc. ...
}
};

return (
// ... JSX for layout, tab buttons, calling renderTabContent ...
);
};
</syntaxhighlight>

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T01:17:20Z

Dananth:

__TOC__

== E XXXX. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Created RESTful API endpoints to manage topics and team signups.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
<syntaxhighlight lang="typescript">
// Manages overall state for assignment editing
const AssignmentEditPage = () => {
// ... hooks for fetching data (assignment, topics), state for active tab, topic settings, topics data ...

// Fetch assignment details on load
useEffect(() => {
if (id) fetchAssignment({ url: `/assignments/${id}` });
}, [id, fetchAssignment]);

// Update local state when assignment data is loaded (e.g., name, allow_bookmarks)
useEffect(() => {
if (assignmentResponse?.data) {
setAssignmentName(assignmentResponse.data.name || "");
setTopicSettings(prev => ({ ...prev, allowBookmarks: assignmentResponse.data.allow_bookmarks }));
}
}, [assignmentResponse]);

// Fetch topics when assignment ID is known
useEffect(() => {
if (id) fetchTopics({ url: `/project_topics?assignment_id=${id}` });
}, [id, fetchTopics]);

// Process fetched topics into format needed by TopicsTable
useEffect(() => {
if (topicsResponse?.data) {
// ... transform backend topic structure to frontend TopicData structure ...
setTopicsData(transformedTopics);
}
}, [topicsResponse]);

// Handler for topic setting changes (e.g., checkboxes)
const handleTopicSettingChange = useCallback((setting: string, value: boolean) => {
setTopicSettings((prev) => ({ ...prev, [setting]: value }));
// Persist allowBookmarks change immediately
if (setting === 'allowBookmarks' && id) {
updateAssignment({ /* ... PATCH request data ... */ });
}
}, [id, updateAssignment]);

// Handlers for topic CRUD operations (passed down to TopicsTab)
const handleDeleteTopic = useCallback((topicId: string) => {
// ... call deleteTopic API ...
}, [id, deleteTopic]);
// ... other handlers (create, edit, drop team) ...

// Renders the content based on the active tab state
const renderTabContent = () => {
switch (activeTab) {
case "topics":
return <TopicsTab /* pass props: settings, data, handlers */ />;
// ... other cases for RubricsTab, DueDatesTab etc. ...
}
};

return (
// ... JSX for layout, tab buttons, calling renderTabContent ...
);
};
</syntaxhighlight>

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T01:09:59Z

Dananth:

==E2552. Reimplementation of ProjectTopic and SignedUpTeam==

This page provides a description of the Expertiza-based OSS project completed as part of the reimplementation effort for Fall 2025.

**TOC**

===About Expertiza===

[[http://expertiza.ncsu.edu/](http://expertiza.ncsu.edu/) Expertiza] is an open-source educational web application developed on the [[http://rubyonrails.org/](http://rubyonrails.org/) Ruby on Rails] framework. It enables instructors to create assignments, manage teams, and facilitate peer reviews. Students can sign up for topics, form teams, submit work, and review peers’ submissions. The new reimplementation of Expertiza separates the back end and front end — with a Rails API providing REST endpoints and a React/TypeScript front end consuming those APIs.

===Problem Statement===

In the existing Expertiza system, the topic signup mechanism was implemented using legacy classes such as `SignUpTopic` and `SignedUpTeam`. This implementation was tightly coupled to the MVC structure, contained redundant logic, lacked proper validation, and offered limited flexibility for team-based topic management.

The goal of this project (E2552) was to **reimplement ProjectTopic and SignedUpTeam** in the modern Expertiza architecture, aligning with RESTful API principles and React-driven UI. The backend was built on Rails API, and the frontend was developed in React with TypeScript.

The following tasks were accomplished:

* Reimplemented `ProjectTopic` and `SignedUpTeam` models with ActiveRecord relationships and validations.
* Created RESTful API endpoints to manage topics and team signups.
* Implemented controllers with robust error handling, transaction safety, and parameter validation.
* Added RSpec test coverage for all new controllers, models, and routes.
* Built the corresponding React front-end components for viewing, signing up for, and managing topics.

===Backend Implementation===

====Files Modified and Created====

* **app/models/project_topic.rb**
* **app/models/signed_up_team.rb**
* **app/controllers/api/v1/project_topics_controller.rb**
* **app/controllers/api/v1/signed_up_teams_controller.rb**
* **app/serializers/project_topic_serializer.rb**
* **app/serializers/signed_up_team_serializer.rb**
* **spec/models/project_topic_spec.rb**
* **spec/models/signed_up_team_spec.rb**
* **spec/requests/project_topics_spec.rb**
* **spec/requests/signed_up_teams_spec.rb**

====Key Features Implemented====

* **ProjectTopic model**

* Represents a topic that students or teams can sign up for.
* Includes fields such as `topic_identifier`, `topic_name`, `max_choosers`, `category`, `description`, and `link`.
* Associations:

* `has_many :signed_up_teams`
* `has_many :teams, through: :signed_up_teams`
* Validations ensure that topic name, identifier, and slot count are always present and valid.
* Scopes added to filter available and full topics.

* **SignedUpTeam model**

* Connects a team with a project topic.
* Contains foreign keys `team_id` and `project_topic_id`.
* Includes methods for checking waitlist status and slot availability.
* Adds validation to prevent over-signing beyond max_choosers.
* Includes transaction-based signup to ensure atomic slot allocation.

* **Controllers**

* Implemented RESTful endpoints:

* `GET /api/v1/project_topics` — List all topics for a given assignment.
* `POST /api/v1/project_topics` — Create a new project topic.
* `PATCH /api/v1/project_topics/:id` — Update topic details.
* `DELETE /api/v1/project_topics/:id` — Remove a topic.
* `POST /api/v1/signed_up_teams` — Sign a team up for a topic.
* `DELETE /api/v1/signed_up_teams/:id` — Remove a team from a topic.
* Implemented strong parameters for input validation.
* Added custom error messages for invalid signups and slot constraints.
* Ensured all database operations run in transactions for consistency.

* **Serializers**

* Added serializers for both models to return clean JSON for frontend consumption.
* Serialized attributes include topic metadata, associated teams, and available slots.

* **RSpec Testing**

* Added unit tests for all models and request specs for controllers.
* Tests verify successful CRUD operations, validation errors, and edge cases (like signing up when no slots are available).

====Example Snippet====

<pre>
# POST /api/v1/signed_up_teams
def create
team_id = params[:team_id]
topic = ProjectTopic.find(params[:project_topic_id])

if topic.available_slots?
SignedUpTeam.transaction do
SignedUpTeam.create!(team_id: team_id, project_topic_id: topic.id)
end
render json: { message: 'Team successfully signed up!' }, status: :created
else
render json: { error: 'No slots available for this topic.' }, status: :unprocessable_entity
end
end
</pre>

===Frontend Implementation===

====Files Modified and Created====

* **src/pages/ProjectTopics.tsx**
* **src/components/TopicTable.tsx**
* **src/components/TopicRow.tsx**
* **src/api/projectTopics.ts**
* **src/api/signedUpTeams.ts**

====Key Features====

* Implemented the Project Topic view in React/TypeScript to display topics fetched from the backend.
* Added a reusable **TopicTable** component to list all topics, including columns for:

* Topic ID
* Topic name (linked if a URL is provided)
* Max choosers and available slots
* Waitlist count
* Implemented signup and withdrawal buttons that trigger API requests to the backend.
* Added loading and error states for better UX.
* Integrated the API layer with Axios for RESTful communication.
* Used React hooks (`useState`, `useEffect`) to manage data and side effects.
* Ensured responsiveness and accessibility according to Expertiza design standards.

====UI Features====

* Instructors can:

* Create, edit, and delete topics.
* View signed-up and waitlisted teams.
* Students can:

* View available topics.
* Sign up for a topic or withdraw from one.
* See waitlist status and slot availability.
* Added conditional rendering for available slots and disabled signup if a topic is full.

===Testing===

====Backend Testing====

* Implemented RSpec tests covering:

* Model validations and associations.
* API request success/failure responses.
* Transaction rollback on failed signups.
* All tests passed successfully:

<pre>
$ rspec spec
Finished in 4.82 seconds
52 examples, 0 failures
</pre>

====Frontend Testing====

* Verified API integration manually using local backend.
* Used Jest and React Testing Library for component testing.
* Ensured UI correctly reflects backend responses for:

* Available slots
* Waitlist updates
* Topic creation and deletion

===Impact and Improvements===

* The new implementation decouples topic and team logic from the legacy system.
* Enforces data integrity using validations and transaction safety.
* Adds clear separation of concerns between backend logic and UI presentation.
* Provides a scalable, maintainable structure for future Expertiza features such as bookmarks and partner advertisements.

===Future Work===

* Add pagination and filtering for large topic lists.
* Implement bookmarking feature and partner advertisements.
* Introduce instructor analytics dashboard for topic statistics.
* Integrate full end-to-end Cypress tests once frontend is deployed.

===References===
#[[https://github.com/expertiza/reimplementation-back-end](https://github.com/expertiza/reimplementation-back-end) Expertiza Reimplementation Backend Repository]
#[[https://github.com/expertiza/reimplementation-front-end](https://github.com/expertiza/reimplementation-front-end) Expertiza Reimplementation Frontend Repository]
#[[https://wiki.expertiza.ncsu.edu/index.php/Expertiza](https://wiki.expertiza.ncsu.edu/index.php/Expertiza) Expertiza Wiki]
#[[http://rspec.info](http://rspec.info) RSpec Documentation]
#[[http://wikis.lib.ncsu.edu/index.php/Documentation_on_Database_Tables](http://wikis.lib.ncsu.edu/index.php/Documentation_on_Database_Tables) Expertiza Database Tables Documentation]

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:59:53Z

Dananth: /* Key Backend Improvements */

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===
Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Centralizing business logic within models for better separation of concerns and testability.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

==== Files ====
'''New Backend Files Created:'''
* `app/controllers/project_topics_controller.rb`
* `app/models/project_topic.rb`
* `db/migrate/20250319015434_rename_sign_up_topics_to_project_topics.rb`
* `db/migrate/20250321222753_rename_sign_up_topic_to_project_topic_in_signed_up_teams.rb`
* `db/migrate/20251028200538_add_allow_bookmarks_to_assignments.rb`
* `spec/factories/project_topics.rb`
* `spec/models/project_topic_spec.rb`
* `spec/models/signed_up_team_spec.rb`
* `spec/routing/project_topics_routing_spec.rb`

'''Modified Backend Files:'''
* `.ruby-version`, `Gemfile`, `Gemfile.lock`
* `app/controllers/assignments_controller.rb`
* `app/controllers/signed_up_teams_controller.rb`
* `app/models/assignment.rb`
* `app/models/bookmark.rb`
* `app/models/signed_up_team.rb`
* `app/models/user.rb`
* `config/routes.rb`
* `db/migrate/20231129050431_create_sign_up_topics.rb` (Renamed table)
* `db/schema.rb`
* `db/seeds.rb`
* `docker-compose.yml`
* `spec/factories/assignments.rb`
* `spec/models/due_date_spec.rb`
* `spec/rails_helper.rb`
* `swagger/v1/swagger.yaml`

'''Deleted Backend Files:'''
* `app/controllers/sign_up_topics_controller.rb`
* `app/models/sign_up_topic.rb`
* `spec/routing/sign_up_topics_routing_spec.rb`

'''New Frontend Files Created:'''
* `public/assets/icons/Check-icon.png`
* `src/pages/Assignments/AssignmentEditPage.tsx`
* `src/pages/Assignments/components/TopicsTable.tsx`
* `src/pages/Assignments/tabs/DueDatesTab.tsx`
* `src/pages/Assignments/tabs/EtcTab.tsx`
* `src/pages/Assignments/tabs/GeneralTab.tsx` (Note: This might be redundant if general editing stays in AssignmentEditor)
* `src/pages/Assignments/tabs/ReviewStrategyTab.tsx`
* `src/pages/Assignments/tabs/RubricsTab.tsx`
* `src/pages/Assignments/tabs/TopicsTab.tsx`
* `src/pages/StudentTasks/StudentTasks.tsx`

'''Modified Frontend Files:'''
* `src/App.tsx` (Routing changes)
* `src/components/Table/Table.tsx` (Added selected row styling)
* `src/hooks/useAPI.ts` (Minor adjustment to isLoading)
* `src/layout/Header.tsx` (Conditional assignments link for students)
* `src/pages/Assignments/Assignment.tsx` (Adjusted to accommodate new edit page link)
* `src/pages/Assignments/AssignmentEditor.tsx` (Potentially simplified if general settings move to GeneralTab)

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

===== Key Backend Improvements =====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
<syntaxhighlight lang="typescript">
// Manages overall state for assignment editing
const AssignmentEditPage = () => {
// ... hooks for fetching data (assignment, topics), state for active tab, topic settings, topics data ...

// Fetch assignment details on load
useEffect(() => {
if (id) fetchAssignment({ url: `/assignments/${id}` });
}, [id, fetchAssignment]);

// Update local state when assignment data is loaded (e.g., name, allow_bookmarks)
useEffect(() => {
if (assignmentResponse?.data) {
setAssignmentName(assignmentResponse.data.name || "");
setTopicSettings(prev => ({ ...prev, allowBookmarks: assignmentResponse.data.allow_bookmarks }));
}
}, [assignmentResponse]);

// Fetch topics when assignment ID is known
useEffect(() => {
if (id) fetchTopics({ url: `/project_topics?assignment_id=${id}` });
}, [id, fetchTopics]);

// Process fetched topics into format needed by TopicsTable
useEffect(() => {
if (topicsResponse?.data) {
// ... transform backend topic structure to frontend TopicData structure ...
setTopicsData(transformedTopics);
}
}, [topicsResponse]);

// Handler for topic setting changes (e.g., checkboxes)
const handleTopicSettingChange = useCallback((setting: string, value: boolean) => {
setTopicSettings((prev) => ({ ...prev, [setting]: value }));
// Persist allowBookmarks change immediately
if (setting === 'allowBookmarks' && id) {
updateAssignment({ /* ... PATCH request data ... */ });
}
}, [id, updateAssignment]);

// Handlers for topic CRUD operations (passed down to TopicsTab)
const handleDeleteTopic = useCallback((topicId: string) => {
// ... call deleteTopic API ...
}, [id, deleteTopic]);
// ... other handlers (create, edit, drop team) ...

// Renders the content based on the active tab state
const renderTabContent = () => {
switch (activeTab) {
case "topics":
return <TopicsTab /* pass props: settings, data, handlers */ />;
// ... other cases for RubricsTab, DueDatesTab etc. ...
}
};

return (
// ... JSX for layout, tab buttons, calling renderTabContent ...
);
};
</syntaxhighlight>

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

=== Code Repositories ===
'''Backend PR:''' ''(Insert Link to Backend PR)''
'''Frontend PR:''' ''(Insert Link to Frontend PR)''

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:58:57Z

Dananth: /* Introduction */

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===
Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Centralizing business logic within models for better separation of concerns and testability.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

==== Files ====
'''New Backend Files Created:'''
* `app/controllers/project_topics_controller.rb`
* `app/models/project_topic.rb`
* `db/migrate/20250319015434_rename_sign_up_topics_to_project_topics.rb`
* `db/migrate/20250321222753_rename_sign_up_topic_to_project_topic_in_signed_up_teams.rb`
* `db/migrate/20251028200538_add_allow_bookmarks_to_assignments.rb`
* `spec/factories/project_topics.rb`
* `spec/models/project_topic_spec.rb`
* `spec/models/signed_up_team_spec.rb`
* `spec/routing/project_topics_routing_spec.rb`

'''Modified Backend Files:'''
* `.ruby-version`, `Gemfile`, `Gemfile.lock`
* `app/controllers/assignments_controller.rb`
* `app/controllers/signed_up_teams_controller.rb`
* `app/models/assignment.rb`
* `app/models/bookmark.rb`
* `app/models/signed_up_team.rb`
* `app/models/user.rb`
* `config/routes.rb`
* `db/migrate/20231129050431_create_sign_up_topics.rb` (Renamed table)
* `db/schema.rb`
* `db/seeds.rb`
* `docker-compose.yml`
* `spec/factories/assignments.rb`
* `spec/models/due_date_spec.rb`
* `spec/rails_helper.rb`
* `swagger/v1/swagger.yaml`

'''Deleted Backend Files:'''
* `app/controllers/sign_up_topics_controller.rb`
* `app/models/sign_up_topic.rb`
* `spec/routing/sign_up_topics_routing_spec.rb`

'''New Frontend Files Created:'''
* `public/assets/icons/Check-icon.png`
* `src/pages/Assignments/AssignmentEditPage.tsx`
* `src/pages/Assignments/components/TopicsTable.tsx`
* `src/pages/Assignments/tabs/DueDatesTab.tsx`
* `src/pages/Assignments/tabs/EtcTab.tsx`
* `src/pages/Assignments/tabs/GeneralTab.tsx` (Note: This might be redundant if general editing stays in AssignmentEditor)
* `src/pages/Assignments/tabs/ReviewStrategyTab.tsx`
* `src/pages/Assignments/tabs/RubricsTab.tsx`
* `src/pages/Assignments/tabs/TopicsTab.tsx`
* `src/pages/StudentTasks/StudentTasks.tsx`

'''Modified Frontend Files:'''
* `src/App.tsx` (Routing changes)
* `src/components/Table/Table.tsx` (Added selected row styling)
* `src/hooks/useAPI.ts` (Minor adjustment to isLoading)
* `src/layout/Header.tsx` (Conditional assignments link for students)
* `src/pages/Assignments/Assignment.tsx` (Adjusted to accommodate new edit page link)
* `src/pages/Assignments/AssignmentEditor.tsx` (Potentially simplified if general settings move to GeneralTab)

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
<syntaxhighlight lang="typescript">
// Manages overall state for assignment editing
const AssignmentEditPage = () => {
// ... hooks for fetching data (assignment, topics), state for active tab, topic settings, topics data ...

// Fetch assignment details on load
useEffect(() => {
if (id) fetchAssignment({ url: `/assignments/${id}` });
}, [id, fetchAssignment]);

// Update local state when assignment data is loaded (e.g., name, allow_bookmarks)
useEffect(() => {
if (assignmentResponse?.data) {
setAssignmentName(assignmentResponse.data.name || "");
setTopicSettings(prev => ({ ...prev, allowBookmarks: assignmentResponse.data.allow_bookmarks }));
}
}, [assignmentResponse]);

// Fetch topics when assignment ID is known
useEffect(() => {
if (id) fetchTopics({ url: `/project_topics?assignment_id=${id}` });
}, [id, fetchTopics]);

// Process fetched topics into format needed by TopicsTable
useEffect(() => {
if (topicsResponse?.data) {
// ... transform backend topic structure to frontend TopicData structure ...
setTopicsData(transformedTopics);
}
}, [topicsResponse]);

// Handler for topic setting changes (e.g., checkboxes)
const handleTopicSettingChange = useCallback((setting: string, value: boolean) => {
setTopicSettings((prev) => ({ ...prev, [setting]: value }));
// Persist allowBookmarks change immediately
if (setting === 'allowBookmarks' && id) {
updateAssignment({ /* ... PATCH request data ... */ });
}
}, [id, updateAssignment]);

// Handlers for topic CRUD operations (passed down to TopicsTab)
const handleDeleteTopic = useCallback((topicId: string) => {
// ... call deleteTopic API ...
}, [id, deleteTopic]);
// ... other handlers (create, edit, drop team) ...

// Renders the content based on the active tab state
const renderTabContent = () => {
switch (activeTab) {
case "topics":
return <TopicsTab /* pass props: settings, data, handlers */ />;
// ... other cases for RubricsTab, DueDatesTab etc. ...
}
};

return (
// ... JSX for layout, tab buttons, calling renderTabContent ...
);
};
</syntaxhighlight>

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

=== Code Repositories ===
'''Backend PR:''' ''(Insert Link to Backend PR)''
'''Frontend PR:''' ''(Insert Link to Frontend PR)''

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:58:02Z

Dananth:

__TOC__

== E 2552. Refactoring Topics and Enhancing Assignment Management ==

=== Introduction ===

==== Background ====
Expertiza utilizes a system for instructors to define topics within assignments, allowing students (often in teams) to sign up for these topics. The previous implementation, centered around the `SignUpTopic` model and associated controllers (`SignUpTopicsController`, `SignedUpTeamsController`), lacked clarity in naming and had business logic distributed across controllers rather than encapsulated within models. Furthermore, the user interface for managing assignment topics by instructors and for students signing up for topics required modernization and improved functionality.

==== Motivation ====
This project aimed to improve the maintainability, clarity, and functionality of the topic management and signup features within Expertiza. Key motivations included:
* Renaming core components (`SignUpTopic` -> `ProjectTopic`) to better reflect their purpose.
* Centralizing business logic within models for better separation of concerns and testability.
* Creating a more intuitive and feature-rich interface for instructors managing assignment topics.
* Developing a dedicated and user-friendly interface for students to view, select, and manage their topic signups.
* Introducing features like bookmarking topics and streamlining the student signup/drop process.
* Updating dependencies to keep the application current.

==== Tasks Accomplished ====
* Renamed `SignUpTopic` to `ProjectTopic` throughout the backend (models, controllers, routes, tests, database).
* Refactored `ProjectTopic` and `SignedUpTeam` models to encapsulate business logic (topic creation/update/deletion, team signup/waitlisting, slot management, student signup/drop).
* Removed `SignUpTopicsController` and implemented `ProjectTopicsController` using the refactored model logic.
* Refactored `SignedUpTeamsController` to utilize new model methods and added new actions (`drop_topic`, `drop_team_from_topic`).
* Added `allow_bookmarks` attribute to the `Assignment` model and associated backend/frontend logic.
* Created a new frontend page (`AssignmentEditPage.tsx`) with a tabbed interface for instructors to manage assignments, including a dedicated "Topics" tab.
* Implemented modals for creating, editing, importing, and deleting topics on the frontend.
* Developed a reusable `TopicsTable.tsx` component for displaying topics in instructor and student views.
* Created a new frontend page (`StudentTasks.tsx`) for students to view assignment topics, bookmark (if enabled), and sign up/drop topics.
* Updated backend dependencies (Rails, Puma, Nokogiri, etc.) and Docker configuration.
* Added/updated RSpec tests for `ProjectTopic` and `SignedUpTeam` models and updated relevant existing tests.
* Updated Swagger API documentation.

==== Files ====
'''New Backend Files Created:'''
* `app/controllers/project_topics_controller.rb`
* `app/models/project_topic.rb`
* `db/migrate/20250319015434_rename_sign_up_topics_to_project_topics.rb`
* `db/migrate/20250321222753_rename_sign_up_topic_to_project_topic_in_signed_up_teams.rb`
* `db/migrate/20251028200538_add_allow_bookmarks_to_assignments.rb`
* `spec/factories/project_topics.rb`
* `spec/models/project_topic_spec.rb`
* `spec/models/signed_up_team_spec.rb`
* `spec/routing/project_topics_routing_spec.rb`

'''Modified Backend Files:'''
* `.ruby-version`, `Gemfile`, `Gemfile.lock`
* `app/controllers/assignments_controller.rb`
* `app/controllers/signed_up_teams_controller.rb`
* `app/models/assignment.rb`
* `app/models/bookmark.rb`
* `app/models/signed_up_team.rb`
* `app/models/user.rb`
* `config/routes.rb`
* `db/migrate/20231129050431_create_sign_up_topics.rb` (Renamed table)
* `db/schema.rb`
* `db/seeds.rb`
* `docker-compose.yml`
* `spec/factories/assignments.rb`
* `spec/models/due_date_spec.rb`
* `spec/rails_helper.rb`
* `swagger/v1/swagger.yaml`

'''Deleted Backend Files:'''
* `app/controllers/sign_up_topics_controller.rb`
* `app/models/sign_up_topic.rb`
* `spec/routing/sign_up_topics_routing_spec.rb`

'''New Frontend Files Created:'''
* `public/assets/icons/Check-icon.png`
* `src/pages/Assignments/AssignmentEditPage.tsx`
* `src/pages/Assignments/components/TopicsTable.tsx`
* `src/pages/Assignments/tabs/DueDatesTab.tsx`
* `src/pages/Assignments/tabs/EtcTab.tsx`
* `src/pages/Assignments/tabs/GeneralTab.tsx` (Note: This might be redundant if general editing stays in AssignmentEditor)
* `src/pages/Assignments/tabs/ReviewStrategyTab.tsx`
* `src/pages/Assignments/tabs/RubricsTab.tsx`
* `src/pages/Assignments/tabs/TopicsTab.tsx`
* `src/pages/StudentTasks/StudentTasks.tsx`

'''Modified Frontend Files:'''
* `src/App.tsx` (Routing changes)
* `src/components/Table/Table.tsx` (Added selected row styling)
* `src/hooks/useAPI.ts` (Minor adjustment to isLoading)
* `src/layout/Header.tsx` (Conditional assignments link for students)
* `src/pages/Assignments/Assignment.tsx` (Adjusted to accommodate new edit page link)
* `src/pages/Assignments/AssignmentEditor.tsx` (Potentially simplified if general settings move to GeneralTab)

=== Problem Analysis ===

==== Issues with Previous Implementation ====

==== Naming Convention ====
The name `SignUpTopic` was ambiguous. Renaming to `ProjectTopic` clarifies that these are topics related to the core project/assignment work students sign up for.

==== Distributed Business Logic ====
Logic for creating topics, signing up teams, managing waitlists, and checking slots was spread across `SignUpTopicsController` and `SignedUpTeamsController`. This violated the principle of "fat model, skinny controller", making the code harder to understand, test, and maintain.

==== Inefficient Data Fetching ====
Frontend components often needed to make multiple API calls or perform calculations (like available slots) that could be handled more efficiently on the backend. The previous `SignUpTopic` API didn't provide computed data like assigned/waitlisted teams directly.

==== Lack of Dedicated Student View ====
Students lacked a clear, dedicated interface to view available topics for an assignment and manage their selection. The signup process was not streamlined.

==== Inconsistent Assignment Editing ====
The existing `AssignmentEditor` modal combined general settings with links to other management pages (like topics, participants) in an ad-hoc manner. A more structured approach was needed.

=== Implementation ===

==== Architecture Decisions ===
* '''Model-Centric Logic:''' Shifted primary business logic for topic management and team signups into the `ProjectTopic` and `SignedUpTeam` models, respectively. Controllers now primarily handle request/response flow and delegate actions to the models.
* '''Dedicated Edit Page (Frontend):''' Created a new full page (`AssignmentEditPage`) for editing assignments instead of using a modal, allowing for a more complex, tabbed interface.
* '''Reusable Table Component (Frontend):''' Developed `TopicsTable` to handle the display and core interactions for topics in different contexts (instructor vs. student), promoting DRY principles.
* '''API Enhancements:''' Modified the `ProjectTopic` index endpoint (`/api/v1/project_topics`) to accept `assignment_id` and return topics with computed data (`to_json_with_computed_data`), reducing frontend calculation needs. Added specific endpoints for student signup (`sign_up_student`) and dropping topics (`drop_topic`, `drop_team_from_topic`).

==== Core Functionality Implemented ====

{| class="wikitable"
! Feature !! Backend Changes !! Frontend Changes
|-
| '''Topic Renaming''' || Renamed `SignUpTopic` model, controller, routes, DB table to `ProjectTopic`. Updated associations. || Updated API endpoints used.
|-
| '''Topic Management (Instructor)''' || `ProjectTopicsController` CRUD actions delegating to `ProjectTopic` model methods (`create_topic_with_assignment`, `update_topic`, `delete_by_assignment_and_topic_ids`). API returns computed data. || New `AssignmentEditPage` with `TopicsTab`. Uses `TopicsTable` (instructor mode). Modals for create, edit, import, delete. API calls for CRUD.
|-
| '''Team Signup Logic''' || `ProjectTopic` methods (`sign_team_up`, `drop_team`, `promote_waitlisted_team`). `SignedUpTeam` methods (`create_signed_up_team`, `remove_team_signups`). || Instructor view shows assigned/waitlisted teams in `TopicsTable` details. Drop team button calls backend.
|-
| '''Student Signup/Drop''' || `SignedUpTeamsController` actions (`sign_up_student`, `drop_topic`) delegating to `SignedUpTeam` model methods (`sign_up_student_for_topic`, `drop_topic_for_student`). Automatic handling of switching topics. || New `StudentTasks` page. Uses `TopicsTable` (student mode). Select/deselect buttons trigger API calls. Optimistic UI updates for slots. Displays current selection.
|-
| '''Topic Bookmarking''' || Added `allow_bookmarks` boolean to `Assignment`. Added `project_topic_params` permit `allow_bookmarks` in `AssignmentsController`. || `AssignmentEditPage` allows instructors to toggle `allow_bookmarks` (persisted via PATCH). `StudentTasks` shows bookmark toggle if `allow_bookmarks` is true (local state for now).
|-
| '''Assignment Editing UI''' || N/A || New `AssignmentEditPage` with tabbed structure. `AssignmentEditor` might be simplified or removed for general settings.
|-
| '''Dependency Updates''' || Updated Ruby, Rails, Puma, Nokogiri etc. Added required gems. || N/A
|}

==== Key Backend Improvements ====

==== ProjectTopic Model ====
<syntaxhighlight lang="ruby">
# Handles team signup, considering available slots and waitlisting
# Renamed from signup_team for clarity
def sign_team_up(team)
return false if signed_up_teams.exists?(team: team)
ActiveRecord::Base.transaction do
signed_up_team = signed_up_teams.create!(
team: team,
is_waitlisted: !slot_available?
)
# Remove team from other waitlists if confirmed here
remove_from_waitlist(team) unless signed_up_team.is_waitlisted?
true
end
rescue ActiveRecord::RecordInvalid
false
end

# Handles dropping a team and promoting waitlisted if necessary
def drop_team(team)
signed_up_team = signed_up_teams.find_by(team: team)
return unless signed_up_team
team_confirmed = !signed_up_team.is_waitlisted?
signed_up_team.destroy!
promote_waitlisted_team if team_confirmed # Promote only if a confirmed slot opened
end

# Calculates available slots
def available_slots
max_choosers - confirmed_teams_count
end

# Checks if slots are positive
def slot_available?
available_slots.positive?
end

# Business logic for creation, moved from controller
def self.create_topic_with_assignment(topic_params, assignment_id, micropayment = nil)
# ... (find assignment, build topic, save, return hash { success:, message:, topic:/errors: })
end

# Business logic for update, moved from controller
def update_topic(topic_params)
# ... (update attributes, return hash { success:, message:, topic:/errors: })
end

# Returns enhanced JSON including computed fields
def to_json_with_computed_data
as_json.merge(
available_slots: available_slots,
confirmed_teams: confirmed_teams.map { |team| # ... format team data },
waitlisted_teams: waitlisted_teams.map { |team| # ... format team data }
)
end

private

# Helper for promotion logic
def promote_waitlisted_team
# ... (find earliest waitlisted team, update is_waitlisted to false, remove from other waitlists)
end

# Helper to remove team from other topics' waitlists
def remove_from_waitlist(team)
team.signed_up_teams.waitlisted.where.not(project_topic_id: id).destroy_all
end
</syntaxhighlight>

==== SignedUpTeam Model ====
<syntaxhighlight lang="ruby">
# Scope for confirmed signups
scope :confirmed, -> { where(is_waitlisted: false) }
# Scope for waitlisted signups
scope :waitlisted, -> { where(is_waitlisted: true) }

belongs_to :project_topic # Updated association
# ... validations ...

# Business logic for student signup, including dropping previous topic
def self.sign_up_student_for_topic(user_id, topic_id)
team_id = get_team_participants(user_id) # Find student's team
return { success: false, message: "User is not part of any team" } unless team_id

# Drop any existing topic signups for this team FIRST
drop_existing_signups_for_team(team_id)

# Sign up for the new topic using create_signed_up_team (which calls topic.sign_team_up)
signed_up_team = create_signed_up_team(topic_id, team_id)

if signed_up_team
{ success: true, message: "Signed up team successful!", signed_up_team: signed_up_team, available_slots: signed_up_team.project_topic.available_slots }
else
{ success: false, message: "Failed to sign up for topic. Topic may be full or already signed up." }
end
end

# Business logic for dropping a topic
def self.drop_topic_for_student(user_id, topic_id)
team_id = get_team_participants(user_id)
# ... (find topic, team, signed_up_team record) ...
return { success: false, message: "Team is not signed up for this topic" } unless signed_up_team

# Delegate drop logic to ProjectTopic
project_topic.drop_team(team)

{ success: true, message: "Successfully dropped topic!", available_slots: project_topic.available_slots }
end

# Helper to find and drop existing signups before signing up for a new one
private
def self.drop_existing_signups_for_team(team_id)
existing_signups = where(team_id: team_id)
existing_signups.each do |signup|
signup.project_topic.drop_team(signup.team) # Use ProjectTopic's drop method
end
end
</syntaxhighlight>

==== Frontend Improvements ====

==== AssignmentEditPage Component ====
<syntaxhighlight lang="typescript">
// Manages overall state for assignment editing
const AssignmentEditPage = () => {
// ... hooks for fetching data (assignment, topics), state for active tab, topic settings, topics data ...

// Fetch assignment details on load
useEffect(() => {
if (id) fetchAssignment({ url: `/assignments/${id}` });
}, [id, fetchAssignment]);

// Update local state when assignment data is loaded (e.g., name, allow_bookmarks)
useEffect(() => {
if (assignmentResponse?.data) {
setAssignmentName(assignmentResponse.data.name || "");
setTopicSettings(prev => ({ ...prev, allowBookmarks: assignmentResponse.data.allow_bookmarks }));
}
}, [assignmentResponse]);

// Fetch topics when assignment ID is known
useEffect(() => {
if (id) fetchTopics({ url: `/project_topics?assignment_id=${id}` });
}, [id, fetchTopics]);

// Process fetched topics into format needed by TopicsTable
useEffect(() => {
if (topicsResponse?.data) {
// ... transform backend topic structure to frontend TopicData structure ...
setTopicsData(transformedTopics);
}
}, [topicsResponse]);

// Handler for topic setting changes (e.g., checkboxes)
const handleTopicSettingChange = useCallback((setting: string, value: boolean) => {
setTopicSettings((prev) => ({ ...prev, [setting]: value }));
// Persist allowBookmarks change immediately
if (setting === 'allowBookmarks' && id) {
updateAssignment({ /* ... PATCH request data ... */ });
}
}, [id, updateAssignment]);

// Handlers for topic CRUD operations (passed down to TopicsTab)
const handleDeleteTopic = useCallback((topicId: string) => {
// ... call deleteTopic API ...
}, [id, deleteTopic]);
// ... other handlers (create, edit, drop team) ...

// Renders the content based on the active tab state
const renderTabContent = () => {
switch (activeTab) {
case "topics":
return <TopicsTab /* pass props: settings, data, handlers */ />;
// ... other cases for RubricsTab, DueDatesTab etc. ...
}
};

return (
// ... JSX for layout, tab buttons, calling renderTabContent ...
);
};
</syntaxhighlight>

==== StudentTasks Component ====
<syntaxhighlight lang="typescript">
// Page for students to sign up for topics
const StudentTasks: React.FC = () => {
// ... hooks for fetching (assignments, topics), signing up, dropping ...
// ... state for bookmarks, selectedTopic, loading states, optimistic updates ...

// Fetch assignment and then topics
useEffect(() => { /* ... fetch assignment data ... */ }, [/* dependencies */]);
useEffect(() => { /* ... fetch topics based on assignment id ... */ }, [/* dependencies */]);

// Process topics data, applying optimistic updates
const topics = useMemo(() => {
// ... map topicsResponse.data, check optimisticSlotChanges map ...
}, [/* dependencies */]);

// Check if bookmarks allowed
const allowBookmarks = useMemo(() => {
// ... check assignmentResponse.data.allow_bookmarks ...
}, [assignmentResponse]);

// Handle selecting/deselecting a topic
const handleTopicSelect = useCallback(async (topicId: string) => {
if (selectedTopic === topicId) { // Deselecting
// Optimistically update slots (+1)
// Set selectedTopic to null
// Call dropAPI
} else { // Selecting a new topic
// Optimistically update slots (-1 for new, +1 for old if exists)
// Call dropAPI for old topic if selectedTopic is not null
// Set selectedTopic to topicId
// Call signUpAPI
}
}, [/* dependencies: selectedTopic, currentUser, dropAPI, signUpAPI, topics */]);

// Handle bookmark toggle (local state)
const handleBookmarkToggle = useCallback((topicId: string) => { /* ... update bookmarkedTopics set ... */ }, []);

// Prepare data for TopicsTable
const topicRows: TopicRow[] = useMemo(() => topics.map(t => ({ /* ... map topic data ... */ })), [topics]);

// ... return JSX ...
return (
<Container>
{/* ... Title, Current Selection display ... */}
{topicsLoading ? <Spinner /> : topicsError ? <Alert variant="danger">{topicsError}</Alert> : (
<TopicsTable
data={topicRows}
mode="student"
onBookmarkToggle={handleBookmarkToggle}
onSelectTopic={handleTopicSelect}
isSigningUp={isSigningUp}
selectedTopicId={selectedTopic}
showBookmarks={allowBookmarks}
// ... other props ...
/>
)}
</Container>
);
};
</syntaxhighlight>

==== Database Migrations ====
* Renamed `sign_up_topics` table to `project_topics`.
* Updated `signed_up_teams` table: renamed `sign_up_topic_id` foreign key to `project_topic_id` and updated index name.
* Added `allow_bookmarks` boolean column to `assignments` table.
* Renamed `teams_users` join table to `teams_participants`.

==== Testing ====

==== RSpec Tests (Backend) ====
* '''ProjectTopic Model (`project_topic_spec.rb`):''' Added extensive tests covering:
* `sign_team_up`: Confirmed vs. waitlisted based on `max_choosers`, removal from other waitlists.
* `drop_team`: Team removal, promotion of earliest waitlisted team.
* `available_slots`, `slot_available?`: Correct calculations before/after signups/drops.
* `confirmed_teams`, `waitlisted_teams`: Correct retrieval and ordering.
* Validations: Presence of `topic_name`, non-negative `max_choosers` (including zero).
* '''SignedUpTeam Model (`signed_up_team_spec.rb`):''' Added tests covering:
* Validations: Presence of topic/team, uniqueness scope.
* Scopes: `:confirmed`, `:waitlisted`.
* Class methods: Signup logic delegation, removal logic, participant/topic finding.
* Waitlisting behavior when topic is full.
* '''Updates:''' Modified existing tests (e.g., `due_date_spec.rb`) to reference `ProjectTopic`.

==== Manual Tests (UI) ====
* '''Instructor Flow:''' Verified assignment editing via `/assignments/edit/:id`, topic creation/editing/deletion/import via modals, toggling `allow_bookmarks`, dropping teams from topics.
* '''Student Flow:''' Verified topic viewing via `/student_tasks/:assignmentId`, selecting/deselecting topics (including automatic drop of previous), bookmarking (when enabled), correct display of slots and waitlists, disabled selection for full topics.

=== Impact Analysis ===

==== Summary of Changes ====
* '''Backend:''' Major refactoring of topic-related models and controllers, database schema changes, new API endpoints, updated dependencies. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily models, controllers, specs, migrations).
* '''Frontend:''' New assignment editing page with tabbed UI, new student task page for topic signup, reusable `TopicsTable` component, new routes. Approximately [Count Lines] lines added/modified across [Count Files] files (primarily in `src/pages/Assignments`, `src/pages/StudentTasks`, `src/components`).

==== Achievements ====
* ✓ Successfully refactored `SignUpTopic` to `ProjectTopic` for improved clarity.
* ✓ Centralized business logic in models, resulting in cleaner controllers.
* ✓ Implemented a modern, tabbed interface for assignment editing.
* ✓ Created a dedicated, streamlined UI for student topic signup.
* ✓ Added topic bookmarking functionality.
* ✓ Enhanced API endpoints for better data provision to the frontend.
* ✓ Updated key dependencies (Rails 8).
* ✓ Added comprehensive RSpec tests for new model logic.

=== Future Work ===
* '''Frontend Bookmark Persistence:''' Implement API calls to save/load student topic bookmarks instead of using local state.
* '''Partner Ad Feature:''' Fully implement the "Apply to partner ad" functionality hinted at in `TopicsTab`.
* '''Complete Assignment Tabs:''' Implement the remaining tabs in `AssignmentEditPage` (Rubrics, Review Strategy, Due Dates, Etc.).
* '''Refine General Tab/AssignmentEditor:''' Decide whether general assignment settings remain in `AssignmentEditor` modal or move entirely to a "General" tab within `AssignmentEditPage`.
* '''Error Handling (Frontend):''' Enhance user feedback for API errors during topic operations (create/edit/delete/signup/drop).
* '''Authorization Checks:''' Ensure robust authorization checks are in place for all new/modified backend endpoints.

=== Conclusion ===
This project successfully refactored the core topic management and signup system in Expertiza, replacing `SignUpTopic` with `ProjectTopic` and significantly improving the underlying logic by moving it into the models. New frontend interfaces provide a much-improved experience for both instructors managing topics and students signing up for them. The addition of features like topic bookmarking and a streamlined student signup flow enhances usability. The changes establish a more maintainable and understandable codebase for future development.

=== References ===
# [https://github.com/expertiza/expertiza Expertiza on GitHub]
# [https://expertiza.ncsu.edu/ The live Expertiza website]
# [http://wikis.lib.ncsu.edu/index.php/Expertiza Expertiza project documentation wiki]
# ''(Add links to your specific project fork/PRs if needed)''
# [https://guides.rubyonrails.org/ Ruby on Rails Guides]
# [https://react.dev/ React Documentation]
# [https://relishapp.com/rspec Rspec Documentation]

=== Code Repositories ===
'''Backend PR:''' ''(Insert Link to Backend PR)''
'''Frontend PR:''' ''(Insert Link to Frontend PR)''

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:55:46Z

Dananth: /* Peer Review Information */

This wiki page describes the changes made for the '''E2552 OSS assignment''' in Fall 2025 for CSC/ECE 517.

== About Expertiza ==

Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend.

== Description of the current project (E2552) ==

This project focuses on the reimplementation of the '''Project Topic''' and '''Signed Up Team''' functionalities within Expertiza. In Expertiza, assignments can require students or teams to choose a topic. The <code>ProjectTopic</code> class (originally <code>SignUpTopic</code>) manages these topics, and when a team selects one, a <code>SignedUpTeam</code> object is created to link the team and the topic.

This project involved integrating and refining backend code previously developed (but not merged) in project E2513 and implementing the corresponding frontend interface for both instructors and students. The backend work included renaming classes and methods based on prior feedback, improving code structure using ActiveRecord features, optimizing logic, and adding validations. The frontend work involved creating new UI components in React/Typescript to manage and display topics, handle topic selection/signup, and provide distinct views for instructors and students, closely mirroring the existing Expertiza interface.

== Files modified/created in current project ==

'''Backend (Ruby on Rails API):''' 
* '''Models:'''
** <code>app/models/project_topic.rb</code> (Created, replacing <code>sign_up_topic.rb</code>)
** <code>app/models/signed_up_team.rb</code> (Modified extensively)
** <code>app/models/assignment.rb</code> (Modified associations)
** <code>app/models/bookmark.rb</code> (Modified association comment)
** <code>app/models/user.rb</code> (Modified associations)
** <code>app/models/sign_up_topic.rb</code> (Deleted)
* '''Controllers:'''
** <code>app/controllers/project_topics_controller.rb</code> (Created, replacing <code>sign_up_topics_controller.rb</code>)
** <code>app/controllers/signed_up_teams_controller.rb</code> (Modified extensively)
** <code>app/controllers/assignments_controller.rb</code> (Modified <code>assignment_params</code>, comment)
** <code>app/controllers/sign_up_topics_controller.rb</code> (Deleted)
* '''Database:'''
** Migrations created/modified for renaming tables/columns (<code>sign_up_topic</code> -> <code>project_topic</code>) and adding <code>allow_bookmarks</code> to assignments.
** <code>db/schema.rb</code> (Updated)
** <code>db/seeds.rb</code> (Updated to use <code>ProjectTopic</code>, added test student)
* '''Configuration:'''
** <code>config/routes.rb</code> (Updated for <code>project_topics</code> and <code>signed_up_teams</code> endpoints)
* '''Tests (RSpec):'''
** <code>spec/models/project_topic_spec.rb</code> (Created)
** <code>spec/models/signed_up_team_spec.rb</code> (Created)
** <code>spec/models/due_date_spec.rb</code> (Modified)
** <code>spec/routing/project_topics_routing_spec.rb</code> (Created)
** <code>spec/factories/project_topics.rb</code> (Created)
** <code>spec/rails_helper.rb</code> (Minor configuration change)
** <code>spec/routing/sign_up_topics_routing_spec.rb</code> (Deleted)
* '''Dependencies:''' <code>Gemfile</code>, <code>Gemfile.lock</code> (Updated versions, added/removed gems)
* '''Swagger Documentation:''' <code>swagger/v1/swagger.yaml</code> (Updated paths and definitions)
* '''Docker:''' <code>docker-compose.yml</code> (Updated command)

'''Frontend (React/Typescript):''' 
* '''Pages:'''
** <code>src/pages/Assignments/AssignmentEditPage.tsx</code> (Created - Main page for editing assignments with tabs)
** <code>src/pages/Assignments/tabs/TopicsTab.tsx</code> (Created - Instructor view for managing topics)
** <code>src/pages/Assignments/tabs/RubricsTab.tsx</code>, <code>ReviewStrategyTab.tsx</code>, <code>DueDatesTab.tsx</code>, <code>EtcTab.tsx</code>, <code>GeneralTab.tsx</code> (Created - Placeholder tabs)
** <code>src/pages/StudentTasks/StudentTasks.tsx</code> (Created - Student view for signing up for topics)
** <code>src/pages/Assignments/Assignment.tsx</code> (Modified - Integrated new edit page link)
** <code>src/pages/Assignments/AssignmentEditor.tsx</code> (Modified - Simplified, as detailed editing moved to <code>AssignmentEditPage</code>)
* '''Components:'''
** <code>src/components/Table/Table.tsx</code> (Modified - Added row highlighting for selected topics)
** <code>src/pages/Assignments/components/TopicsTable.tsx</code> (Created - Reusable table component for displaying topics)
* '''Routing:'''
** <code>src/App.tsx</code> (Modified - Added routes for <code>AssignmentEditPage</code> and <code>StudentTasks</code>)
* '''Layout:'''
** <code>src/layout/Header.tsx</code> (Modified - Conditionally show Assignments link for students)
* '''Hooks:'''
** <code>src/hooks/useAPI.ts</code> (Modified - Minor change in <code>then</code> block)
* '''Assets:'''
** <code>public/assets/icons/Check-icon.png</code> (Added)

== List of changes / Features Implemented ==

Based on the project description and feedback from E2513: 
'''Backend:''' 
# '''Renamed <code>SignUpTopic</code> to <code>ProjectTopic</code>:''' Refactored the model, controller, routes, database table, associations, and tests to use the new naming convention consistently.
# '''Refactored <code>SignedUpTeam</code> Logic:''' Moved business logic from the controller into the <code>SignedUpTeam</code> and <code>ProjectTopic</code> models, utilizing ActiveRecord features like transactions and scopes. Implemented methods for signing up students/teams, dropping topics, finding participants, and handling waitlists.
# '''Addressed E2513 Feedback:''' 
#* Renamed <code>signup_team</code> method to <code>sign_team_up</code> in <code>ProjectTopic</code>.
#* Renamed <code>signup_for_topic</code> method to <code>sign_up_for_topic</code> in <code>SignedUpTeam</code>.
#* Addressed DRY violation between <code>find_team_participants</code> and <code>find_project_topic_team_users</code>.
#* Ensured files terminate with a newline.
# '''Updated <code>Assignment</code> Model:''' Added <code>allow_bookmarks</code> attribute and updated associations related to topics.
# '''API Endpoints:''' Created/updated API endpoints for CRUD operations on <code>ProjectTopic</code> and actions related to <code>SignedUpTeam</code> (signup, drop topic).
# '''Testing:''' Added comprehensive RSpec tests for <code>ProjectTopic</code> and <code>SignedUpTeam</code> models. Updated existing tests (<code>due_date_spec.rb</code>). Added routing specs.

'''Frontend:''' 
# '''New Assignment Edit Page:''' Created <code>AssignmentEditPage</code> with a tabbed interface for editing assignments.
# '''Instructor Topics Tab:''' Implemented <code>TopicsTab</code> component allowing instructors to:
#* View/manage topics via <code>TopicsTable</code>.
#* Configure topic settings (e.g., allow bookmarks).
#* View assigned/waitlisted teams and drop teams.
#* Toggle display of user names/IDs.
#* Create, import, edit, delete topics via modals.
#* View bookmark counts.
#* Access Partner Ad functionality (UI added).
# '''Student Task/Signup Page:''' Created <code>StudentTasks</code> page allowing students to:
#* View available topics via <code>TopicsTable</code>.
#* See available slots and waitlist numbers.
#* View their selected topic.
#* Select/deselect (drop) a topic.
#* Bookmark topics (if enabled).
# '''Reusable <code>TopicsTable</code> Component:''' Developed adaptable table for student/instructor views with row expansion, selection, and custom actions.
# '''API Integration:''' Connected frontend components to backend API for fetching/updating topics, assignment settings, and handling signups/drops.
# '''UI Enhancements:''' Added selected topic highlighting, action icons, and modals for various operations.

== Testing Details==

=== Backend (RSpec) ===
New spec files (<code>project_topic_spec.rb</code>, <code>signed_up_team_spec.rb</code>) were created with extensive test coverage for the core models, including various scenarios like signup, waitlisting, dropping teams, and validations. Existing specs (<code>due_date_spec.rb</code>) were updated. Routing specs were added. Tests confirmed the refactored code integrates correctly.

=== UI Testing ===

Manual testing was performed following scenarios for instructors and students:

'''Instructor UI:''' 
# Login as instructor6.
# Navigate to an assignment (e.g., "OSS project & documentation") and click 'Edit'.
# Go to the 'Topics' tab.
# '''Verify topic list display:''' Check columns (Checkbox, ID, Name, Questionnaire, Slots, Available, Waitlist, Bookmarks, Actions).
# '''Verify topic settings:''' Test checkboxes, especially 'Allow participants to create bookmarks?'. Backend save confirmed via API call.
# '''Test topic actions:'''
#* Create a new topic via 'New topic' button/modal.
#* Edit an existing topic via edit icon/modal.
#* Delete topic(s) via delete icon or selecting checkboxes and using 'Delete selected topics'.
#* Import topics via 'Import topics' button/modal.
# Expand a topic row to view assigned/waitlisted teams. Test dropping a team via 'X' icon.
# Test 'Display User Names' toggle.

'''Student UI:''' 
# Login as teststudent.
# Navigate to 'Assignments' via header link.
# Verify signup sheet loads.
# '''Verify topic list display:''' Check columns (ID, Name, Available Slots, Num. on Waitlist, Bookmarks [if enabled], Actions).
# '''Test topic selection:''' Click checkmark icon. Verify 'Your topic(s)' updates, row highlights yellow, slots update optimistically, and API call is made.
# '''Test topic deselection (drop):''' Click 'X' icon on selected topic row. Verify topic is dropped, highlighting removed, slots update, and API call is made.
# '''Test bookmarking (if enabled):''' Click bookmark icon to toggle status.
# Verify actions are disabled for full topics (0 available slots).

== Scope for future improvement ==
# '''Complete Placeholder Tabs:''' Implement functionality for 'Rubrics', 'Review Strategy', 'Due Dates', and 'Etc.' tabs in instructor view.
# '''Partner Ad Backend:''' Implement backend logic for partner ads and applications.
# '''Bookmark Implementation:''' Fully implement bookmark creation/viewing functionality.
# '''Topic Suggestions:''' Implement student topic suggestion feature.
# '''Bidding Features:''' Implement topic/reviewer bidding.
# '''Refined UI/UX:''' Enhance UI based on feedback, e.g., team display within rows.
# '''Automated Frontend Testing:''' Add

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:55:36Z

Dananth: /* Expertiza Background */

This wiki page describes the changes made for the '''E2552 OSS assignment''' in Fall 2025 for CSC/ECE 517.

== Peer Review Information ==

For users intending to view the deployed Expertiza associated with this assignment, the credentials are below:
* Instructor login: username -> admin, password -> password123
* Student login: username -> teststudent, password -> password123
* ''(Add other relevant student logins if needed)''

== About Expertiza ==

Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend.

== Description of the current project (E2552) ==

This project focuses on the reimplementation of the '''Project Topic''' and '''Signed Up Team''' functionalities within Expertiza. In Expertiza, assignments can require students or teams to choose a topic. The <code>ProjectTopic</code> class (originally <code>SignUpTopic</code>) manages these topics, and when a team selects one, a <code>SignedUpTeam</code> object is created to link the team and the topic.

This project involved integrating and refining backend code previously developed (but not merged) in project E2513 and implementing the corresponding frontend interface for both instructors and students. The backend work included renaming classes and methods based on prior feedback, improving code structure using ActiveRecord features, optimizing logic, and adding validations. The frontend work involved creating new UI components in React/Typescript to manage and display topics, handle topic selection/signup, and provide distinct views for instructors and students, closely mirroring the existing Expertiza interface.

== Files modified/created in current project ==

'''Backend (Ruby on Rails API):''' 
* '''Models:'''
** <code>app/models/project_topic.rb</code> (Created, replacing <code>sign_up_topic.rb</code>)
** <code>app/models/signed_up_team.rb</code> (Modified extensively)
** <code>app/models/assignment.rb</code> (Modified associations)
** <code>app/models/bookmark.rb</code> (Modified association comment)
** <code>app/models/user.rb</code> (Modified associations)
** <code>app/models/sign_up_topic.rb</code> (Deleted)
* '''Controllers:'''
** <code>app/controllers/project_topics_controller.rb</code> (Created, replacing <code>sign_up_topics_controller.rb</code>)
** <code>app/controllers/signed_up_teams_controller.rb</code> (Modified extensively)
** <code>app/controllers/assignments_controller.rb</code> (Modified <code>assignment_params</code>, comment)
** <code>app/controllers/sign_up_topics_controller.rb</code> (Deleted)
* '''Database:'''
** Migrations created/modified for renaming tables/columns (<code>sign_up_topic</code> -> <code>project_topic</code>) and adding <code>allow_bookmarks</code> to assignments.
** <code>db/schema.rb</code> (Updated)
** <code>db/seeds.rb</code> (Updated to use <code>ProjectTopic</code>, added test student)
* '''Configuration:'''
** <code>config/routes.rb</code> (Updated for <code>project_topics</code> and <code>signed_up_teams</code> endpoints)
* '''Tests (RSpec):'''
** <code>spec/models/project_topic_spec.rb</code> (Created)
** <code>spec/models/signed_up_team_spec.rb</code> (Created)
** <code>spec/models/due_date_spec.rb</code> (Modified)
** <code>spec/routing/project_topics_routing_spec.rb</code> (Created)
** <code>spec/factories/project_topics.rb</code> (Created)
** <code>spec/rails_helper.rb</code> (Minor configuration change)
** <code>spec/routing/sign_up_topics_routing_spec.rb</code> (Deleted)
* '''Dependencies:''' <code>Gemfile</code>, <code>Gemfile.lock</code> (Updated versions, added/removed gems)
* '''Swagger Documentation:''' <code>swagger/v1/swagger.yaml</code> (Updated paths and definitions)
* '''Docker:''' <code>docker-compose.yml</code> (Updated command)

'''Frontend (React/Typescript):''' 
* '''Pages:'''
** <code>src/pages/Assignments/AssignmentEditPage.tsx</code> (Created - Main page for editing assignments with tabs)
** <code>src/pages/Assignments/tabs/TopicsTab.tsx</code> (Created - Instructor view for managing topics)
** <code>src/pages/Assignments/tabs/RubricsTab.tsx</code>, <code>ReviewStrategyTab.tsx</code>, <code>DueDatesTab.tsx</code>, <code>EtcTab.tsx</code>, <code>GeneralTab.tsx</code> (Created - Placeholder tabs)
** <code>src/pages/StudentTasks/StudentTasks.tsx</code> (Created - Student view for signing up for topics)
** <code>src/pages/Assignments/Assignment.tsx</code> (Modified - Integrated new edit page link)
** <code>src/pages/Assignments/AssignmentEditor.tsx</code> (Modified - Simplified, as detailed editing moved to <code>AssignmentEditPage</code>)
* '''Components:'''
** <code>src/components/Table/Table.tsx</code> (Modified - Added row highlighting for selected topics)
** <code>src/pages/Assignments/components/TopicsTable.tsx</code> (Created - Reusable table component for displaying topics)
* '''Routing:'''
** <code>src/App.tsx</code> (Modified - Added routes for <code>AssignmentEditPage</code> and <code>StudentTasks</code>)
* '''Layout:'''
** <code>src/layout/Header.tsx</code> (Modified - Conditionally show Assignments link for students)
* '''Hooks:'''
** <code>src/hooks/useAPI.ts</code> (Modified - Minor change in <code>then</code> block)
* '''Assets:'''
** <code>public/assets/icons/Check-icon.png</code> (Added)

== List of changes / Features Implemented ==

Based on the project description and feedback from E2513: 
'''Backend:''' 
# '''Renamed <code>SignUpTopic</code> to <code>ProjectTopic</code>:''' Refactored the model, controller, routes, database table, associations, and tests to use the new naming convention consistently.
# '''Refactored <code>SignedUpTeam</code> Logic:''' Moved business logic from the controller into the <code>SignedUpTeam</code> and <code>ProjectTopic</code> models, utilizing ActiveRecord features like transactions and scopes. Implemented methods for signing up students/teams, dropping topics, finding participants, and handling waitlists.
# '''Addressed E2513 Feedback:''' 
#* Renamed <code>signup_team</code> method to <code>sign_team_up</code> in <code>ProjectTopic</code>.
#* Renamed <code>signup_for_topic</code> method to <code>sign_up_for_topic</code> in <code>SignedUpTeam</code>.
#* Addressed DRY violation between <code>find_team_participants</code> and <code>find_project_topic_team_users</code>.
#* Ensured files terminate with a newline.
# '''Updated <code>Assignment</code> Model:''' Added <code>allow_bookmarks</code> attribute and updated associations related to topics.
# '''API Endpoints:''' Created/updated API endpoints for CRUD operations on <code>ProjectTopic</code> and actions related to <code>SignedUpTeam</code> (signup, drop topic).
# '''Testing:''' Added comprehensive RSpec tests for <code>ProjectTopic</code> and <code>SignedUpTeam</code> models. Updated existing tests (<code>due_date_spec.rb</code>). Added routing specs.

'''Frontend:''' 
# '''New Assignment Edit Page:''' Created <code>AssignmentEditPage</code> with a tabbed interface for editing assignments.
# '''Instructor Topics Tab:''' Implemented <code>TopicsTab</code> component allowing instructors to:
#* View/manage topics via <code>TopicsTable</code>.
#* Configure topic settings (e.g., allow bookmarks).
#* View assigned/waitlisted teams and drop teams.
#* Toggle display of user names/IDs.
#* Create, import, edit, delete topics via modals.
#* View bookmark counts.
#* Access Partner Ad functionality (UI added).
# '''Student Task/Signup Page:''' Created <code>StudentTasks</code> page allowing students to:
#* View available topics via <code>TopicsTable</code>.
#* See available slots and waitlist numbers.
#* View their selected topic.
#* Select/deselect (drop) a topic.
#* Bookmark topics (if enabled).
# '''Reusable <code>TopicsTable</code> Component:''' Developed adaptable table for student/instructor views with row expansion, selection, and custom actions.
# '''API Integration:''' Connected frontend components to backend API for fetching/updating topics, assignment settings, and handling signups/drops.
# '''UI Enhancements:''' Added selected topic highlighting, action icons, and modals for various operations.

== Testing Details==

=== Backend (RSpec) ===
New spec files (<code>project_topic_spec.rb</code>, <code>signed_up_team_spec.rb</code>) were created with extensive test coverage for the core models, including various scenarios like signup, waitlisting, dropping teams, and validations. Existing specs (<code>due_date_spec.rb</code>) were updated. Routing specs were added. Tests confirmed the refactored code integrates correctly.

=== UI Testing ===

Manual testing was performed following scenarios for instructors and students:

'''Instructor UI:''' 
# Login as instructor6.
# Navigate to an assignment (e.g., "OSS project & documentation") and click 'Edit'.
# Go to the 'Topics' tab.
# '''Verify topic list display:''' Check columns (Checkbox, ID, Name, Questionnaire, Slots, Available, Waitlist, Bookmarks, Actions).
# '''Verify topic settings:''' Test checkboxes, especially 'Allow participants to create bookmarks?'. Backend save confirmed via API call.
# '''Test topic actions:'''
#* Create a new topic via 'New topic' button/modal.
#* Edit an existing topic via edit icon/modal.
#* Delete topic(s) via delete icon or selecting checkboxes and using 'Delete selected topics'.
#* Import topics via 'Import topics' button/modal.
# Expand a topic row to view assigned/waitlisted teams. Test dropping a team via 'X' icon.
# Test 'Display User Names' toggle.

'''Student UI:''' 
# Login as teststudent.
# Navigate to 'Assignments' via header link.
# Verify signup sheet loads.
# '''Verify topic list display:''' Check columns (ID, Name, Available Slots, Num. on Waitlist, Bookmarks [if enabled], Actions).
# '''Test topic selection:''' Click checkmark icon. Verify 'Your topic(s)' updates, row highlights yellow, slots update optimistically, and API call is made.
# '''Test topic deselection (drop):''' Click 'X' icon on selected topic row. Verify topic is dropped, highlighting removed, slots update, and API call is made.
# '''Test bookmarking (if enabled):''' Click bookmark icon to toggle status.
# Verify actions are disabled for full topics (0 available slots).

== Scope for future improvement ==
# '''Complete Placeholder Tabs:''' Implement functionality for 'Rubrics', 'Review Strategy', 'Due Dates', and 'Etc.' tabs in instructor view.
# '''Partner Ad Backend:''' Implement backend logic for partner ads and applications.
# '''Bookmark Implementation:''' Fully implement bookmark creation/viewing functionality.
# '''Topic Suggestions:''' Implement student topic suggestion feature.
# '''Bidding Features:''' Implement topic/reviewer bidding.
# '''Refined UI/UX:''' Enhance UI based on feedback, e.g., team display within rows.
# '''Automated Frontend Testing:''' Add

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:54:20Z

Dananth: /* Peer Review Information */

This wiki page describes the changes made for the '''E2552 OSS assignment''' in Fall 2025 for CSC/ECE 517.

== Peer Review Information ==

For users intending to view the deployed Expertiza associated with this assignment, the credentials are below:
* Instructor login: username -> admin, password -> password123
* Student login: username -> teststudent, password -> password123
* ''(Add other relevant student logins if needed)''

== Expertiza Background==

Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend.

== Description of the current project (E2552) ==

This project focuses on the reimplementation of the '''Project Topic''' and '''Signed Up Team''' functionalities within Expertiza. In Expertiza, assignments can require students or teams to choose a topic. The <code>ProjectTopic</code> class (originally <code>SignUpTopic</code>) manages these topics, and when a team selects one, a <code>SignedUpTeam</code> object is created to link the team and the topic.

This project involved integrating and refining backend code previously developed (but not merged) in project E2513 and implementing the corresponding frontend interface for both instructors and students. The backend work included renaming classes and methods based on prior feedback, improving code structure using ActiveRecord features, optimizing logic, and adding validations. The frontend work involved creating new UI components in React/Typescript to manage and display topics, handle topic selection/signup, and provide distinct views for instructors and students, closely mirroring the existing Expertiza interface.

== Files modified/created in current project ==

'''Backend (Ruby on Rails API):''' 
* '''Models:'''
** <code>app/models/project_topic.rb</code> (Created, replacing <code>sign_up_topic.rb</code>)
** <code>app/models/signed_up_team.rb</code> (Modified extensively)
** <code>app/models/assignment.rb</code> (Modified associations)
** <code>app/models/bookmark.rb</code> (Modified association comment)
** <code>app/models/user.rb</code> (Modified associations)
** <code>app/models/sign_up_topic.rb</code> (Deleted)
* '''Controllers:'''
** <code>app/controllers/project_topics_controller.rb</code> (Created, replacing <code>sign_up_topics_controller.rb</code>)
** <code>app/controllers/signed_up_teams_controller.rb</code> (Modified extensively)
** <code>app/controllers/assignments_controller.rb</code> (Modified <code>assignment_params</code>, comment)
** <code>app/controllers/sign_up_topics_controller.rb</code> (Deleted)
* '''Database:'''
** Migrations created/modified for renaming tables/columns (<code>sign_up_topic</code> -> <code>project_topic</code>) and adding <code>allow_bookmarks</code> to assignments.
** <code>db/schema.rb</code> (Updated)
** <code>db/seeds.rb</code> (Updated to use <code>ProjectTopic</code>, added test student)
* '''Configuration:'''
** <code>config/routes.rb</code> (Updated for <code>project_topics</code> and <code>signed_up_teams</code> endpoints)
* '''Tests (RSpec):'''
** <code>spec/models/project_topic_spec.rb</code> (Created)
** <code>spec/models/signed_up_team_spec.rb</code> (Created)
** <code>spec/models/due_date_spec.rb</code> (Modified)
** <code>spec/routing/project_topics_routing_spec.rb</code> (Created)
** <code>spec/factories/project_topics.rb</code> (Created)
** <code>spec/rails_helper.rb</code> (Minor configuration change)
** <code>spec/routing/sign_up_topics_routing_spec.rb</code> (Deleted)
* '''Dependencies:''' <code>Gemfile</code>, <code>Gemfile.lock</code> (Updated versions, added/removed gems)
* '''Swagger Documentation:''' <code>swagger/v1/swagger.yaml</code> (Updated paths and definitions)
* '''Docker:''' <code>docker-compose.yml</code> (Updated command)

'''Frontend (React/Typescript):''' 
* '''Pages:'''
** <code>src/pages/Assignments/AssignmentEditPage.tsx</code> (Created - Main page for editing assignments with tabs)
** <code>src/pages/Assignments/tabs/TopicsTab.tsx</code> (Created - Instructor view for managing topics)
** <code>src/pages/Assignments/tabs/RubricsTab.tsx</code>, <code>ReviewStrategyTab.tsx</code>, <code>DueDatesTab.tsx</code>, <code>EtcTab.tsx</code>, <code>GeneralTab.tsx</code> (Created - Placeholder tabs)
** <code>src/pages/StudentTasks/StudentTasks.tsx</code> (Created - Student view for signing up for topics)
** <code>src/pages/Assignments/Assignment.tsx</code> (Modified - Integrated new edit page link)
** <code>src/pages/Assignments/AssignmentEditor.tsx</code> (Modified - Simplified, as detailed editing moved to <code>AssignmentEditPage</code>)
* '''Components:'''
** <code>src/components/Table/Table.tsx</code> (Modified - Added row highlighting for selected topics)
** <code>src/pages/Assignments/components/TopicsTable.tsx</code> (Created - Reusable table component for displaying topics)
* '''Routing:'''
** <code>src/App.tsx</code> (Modified - Added routes for <code>AssignmentEditPage</code> and <code>StudentTasks</code>)
* '''Layout:'''
** <code>src/layout/Header.tsx</code> (Modified - Conditionally show Assignments link for students)
* '''Hooks:'''
** <code>src/hooks/useAPI.ts</code> (Modified - Minor change in <code>then</code> block)
* '''Assets:'''
** <code>public/assets/icons/Check-icon.png</code> (Added)

== List of changes / Features Implemented ==

Based on the project description and feedback from E2513: 
'''Backend:''' 
# '''Renamed <code>SignUpTopic</code> to <code>ProjectTopic</code>:''' Refactored the model, controller, routes, database table, associations, and tests to use the new naming convention consistently.
# '''Refactored <code>SignedUpTeam</code> Logic:''' Moved business logic from the controller into the <code>SignedUpTeam</code> and <code>ProjectTopic</code> models, utilizing ActiveRecord features like transactions and scopes. Implemented methods for signing up students/teams, dropping topics, finding participants, and handling waitlists.
# '''Addressed E2513 Feedback:''' 
#* Renamed <code>signup_team</code> method to <code>sign_team_up</code> in <code>ProjectTopic</code>.
#* Renamed <code>signup_for_topic</code> method to <code>sign_up_for_topic</code> in <code>SignedUpTeam</code>.
#* Addressed DRY violation between <code>find_team_participants</code> and <code>find_project_topic_team_users</code>.
#* Ensured files terminate with a newline.
# '''Updated <code>Assignment</code> Model:''' Added <code>allow_bookmarks</code> attribute and updated associations related to topics.
# '''API Endpoints:''' Created/updated API endpoints for CRUD operations on <code>ProjectTopic</code> and actions related to <code>SignedUpTeam</code> (signup, drop topic).
# '''Testing:''' Added comprehensive RSpec tests for <code>ProjectTopic</code> and <code>SignedUpTeam</code> models. Updated existing tests (<code>due_date_spec.rb</code>). Added routing specs.

'''Frontend:''' 
# '''New Assignment Edit Page:''' Created <code>AssignmentEditPage</code> with a tabbed interface for editing assignments.
# '''Instructor Topics Tab:''' Implemented <code>TopicsTab</code> component allowing instructors to:
#* View/manage topics via <code>TopicsTable</code>.
#* Configure topic settings (e.g., allow bookmarks).
#* View assigned/waitlisted teams and drop teams.
#* Toggle display of user names/IDs.
#* Create, import, edit, delete topics via modals.
#* View bookmark counts.
#* Access Partner Ad functionality (UI added).
# '''Student Task/Signup Page:''' Created <code>StudentTasks</code> page allowing students to:
#* View available topics via <code>TopicsTable</code>.
#* See available slots and waitlist numbers.
#* View their selected topic.
#* Select/deselect (drop) a topic.
#* Bookmark topics (if enabled).
# '''Reusable <code>TopicsTable</code> Component:''' Developed adaptable table for student/instructor views with row expansion, selection, and custom actions.
# '''API Integration:''' Connected frontend components to backend API for fetching/updating topics, assignment settings, and handling signups/drops.
# '''UI Enhancements:''' Added selected topic highlighting, action icons, and modals for various operations.

== Testing Details==

=== Backend (RSpec) ===
New spec files (<code>project_topic_spec.rb</code>, <code>signed_up_team_spec.rb</code>) were created with extensive test coverage for the core models, including various scenarios like signup, waitlisting, dropping teams, and validations. Existing specs (<code>due_date_spec.rb</code>) were updated. Routing specs were added. Tests confirmed the refactored code integrates correctly.

=== UI Testing ===

Manual testing was performed following scenarios for instructors and students:

'''Instructor UI:''' 
# Login as instructor6.
# Navigate to an assignment (e.g., "OSS project & documentation") and click 'Edit'.
# Go to the 'Topics' tab.
# '''Verify topic list display:''' Check columns (Checkbox, ID, Name, Questionnaire, Slots, Available, Waitlist, Bookmarks, Actions).
# '''Verify topic settings:''' Test checkboxes, especially 'Allow participants to create bookmarks?'. Backend save confirmed via API call.
# '''Test topic actions:'''
#* Create a new topic via 'New topic' button/modal.
#* Edit an existing topic via edit icon/modal.
#* Delete topic(s) via delete icon or selecting checkboxes and using 'Delete selected topics'.
#* Import topics via 'Import topics' button/modal.
# Expand a topic row to view assigned/waitlisted teams. Test dropping a team via 'X' icon.
# Test 'Display User Names' toggle.

'''Student UI:''' 
# Login as teststudent.
# Navigate to 'Assignments' via header link.
# Verify signup sheet loads.
# '''Verify topic list display:''' Check columns (ID, Name, Available Slots, Num. on Waitlist, Bookmarks [if enabled], Actions).
# '''Test topic selection:''' Click checkmark icon. Verify 'Your topic(s)' updates, row highlights yellow, slots update optimistically, and API call is made.
# '''Test topic deselection (drop):''' Click 'X' icon on selected topic row. Verify topic is dropped, highlighting removed, slots update, and API call is made.
# '''Test bookmarking (if enabled):''' Click bookmark icon to toggle status.
# Verify actions are disabled for full topics (0 available slots).

== Scope for future improvement ==
# '''Complete Placeholder Tabs:''' Implement functionality for 'Rubrics', 'Review Strategy', 'Due Dates', and 'Etc.' tabs in instructor view.
# '''Partner Ad Backend:''' Implement backend logic for partner ads and applications.
# '''Bookmark Implementation:''' Fully implement bookmark creation/viewing functionality.
# '''Topic Suggestions:''' Implement student topic suggestion feature.
# '''Bidding Features:''' Implement topic/reviewer bidding.
# '''Refined UI/UX:''' Enhance UI based on feedback, e.g., team display within rows.
# '''Automated Frontend Testing:''' Add

CSC/ECE 517 Fall 2025 - E2552. ProjectTopic and SignedUpTeam

2025-10-29T00:53:35Z

Dananth: Created page with "This wiki page describes the changes made for the '''E2552 OSS assignment''' in Fall 2025 for CSC/ECE 517. == Peer Review Information == For users intending to view the deployed Expertiza associated with this assignment, the credentials are below: * Instructor login: username -> instructor6, password -> password * Student login: username -> teststudent, password -> password123 * ''(Add other relevant student logins if needed)'' == Expertiza Background== Expertiza is..."

This wiki page describes the changes made for the '''E2552 OSS assignment''' in Fall 2025 for CSC/ECE 517.

== Peer Review Information ==

For users intending to view the deployed Expertiza associated with this assignment, the credentials are below:
* Instructor login: username -> instructor6, password -> password
* Student login: username -> teststudent, password -> password123
* ''(Add other relevant student logins if needed)''

== Expertiza Background==

Expertiza is an educational web application created and maintained by the joint efforts of the students and the faculty at NCSU. It’s an open source project developed on Ruby on Rails platform and its code is available on Github. It allows students to review each other’s work and improve their work upon this feedback. The current effort involves reimplementing the application with a Ruby on Rails API backend and a React/Typescript frontend.

== Description of the current project (E2552) ==

This project focuses on the reimplementation of the '''Project Topic''' and '''Signed Up Team''' functionalities within Expertiza. In Expertiza, assignments can require students or teams to choose a topic. The <code>ProjectTopic</code> class (originally <code>SignUpTopic</code>) manages these topics, and when a team selects one, a <code>SignedUpTeam</code> object is created to link the team and the topic.

This project involved integrating and refining backend code previously developed (but not merged) in project E2513 and implementing the corresponding frontend interface for both instructors and students. The backend work included renaming classes and methods based on prior feedback, improving code structure using ActiveRecord features, optimizing logic, and adding validations. The frontend work involved creating new UI components in React/Typescript to manage and display topics, handle topic selection/signup, and provide distinct views for instructors and students, closely mirroring the existing Expertiza interface.

== Files modified/created in current project ==

'''Backend (Ruby on Rails API):''' 
* '''Models:'''
** <code>app/models/project_topic.rb</code> (Created, replacing <code>sign_up_topic.rb</code>)
** <code>app/models/signed_up_team.rb</code> (Modified extensively)
** <code>app/models/assignment.rb</code> (Modified associations)
** <code>app/models/bookmark.rb</code> (Modified association comment)
** <code>app/models/user.rb</code> (Modified associations)
** <code>app/models/sign_up_topic.rb</code> (Deleted)
* '''Controllers:'''
** <code>app/controllers/project_topics_controller.rb</code> (Created, replacing <code>sign_up_topics_controller.rb</code>)
** <code>app/controllers/signed_up_teams_controller.rb</code> (Modified extensively)
** <code>app/controllers/assignments_controller.rb</code> (Modified <code>assignment_params</code>, comment)
** <code>app/controllers/sign_up_topics_controller.rb</code> (Deleted)
* '''Database:'''
** Migrations created/modified for renaming tables/columns (<code>sign_up_topic</code> -> <code>project_topic</code>) and adding <code>allow_bookmarks</code> to assignments.
** <code>db/schema.rb</code> (Updated)
** <code>db/seeds.rb</code> (Updated to use <code>ProjectTopic</code>, added test student)
* '''Configuration:'''
** <code>config/routes.rb</code> (Updated for <code>project_topics</code> and <code>signed_up_teams</code> endpoints)
* '''Tests (RSpec):'''
** <code>spec/models/project_topic_spec.rb</code> (Created)
** <code>spec/models/signed_up_team_spec.rb</code> (Created)
** <code>spec/models/due_date_spec.rb</code> (Modified)
** <code>spec/routing/project_topics_routing_spec.rb</code> (Created)
** <code>spec/factories/project_topics.rb</code> (Created)
** <code>spec/rails_helper.rb</code> (Minor configuration change)
** <code>spec/routing/sign_up_topics_routing_spec.rb</code> (Deleted)
* '''Dependencies:''' <code>Gemfile</code>, <code>Gemfile.lock</code> (Updated versions, added/removed gems)
* '''Swagger Documentation:''' <code>swagger/v1/swagger.yaml</code> (Updated paths and definitions)
* '''Docker:''' <code>docker-compose.yml</code> (Updated command)

'''Frontend (React/Typescript):''' 
* '''Pages:'''
** <code>src/pages/Assignments/AssignmentEditPage.tsx</code> (Created - Main page for editing assignments with tabs)
** <code>src/pages/Assignments/tabs/TopicsTab.tsx</code> (Created - Instructor view for managing topics)
** <code>src/pages/Assignments/tabs/RubricsTab.tsx</code>, <code>ReviewStrategyTab.tsx</code>, <code>DueDatesTab.tsx</code>, <code>EtcTab.tsx</code>, <code>GeneralTab.tsx</code> (Created - Placeholder tabs)
** <code>src/pages/StudentTasks/StudentTasks.tsx</code> (Created - Student view for signing up for topics)
** <code>src/pages/Assignments/Assignment.tsx</code> (Modified - Integrated new edit page link)
** <code>src/pages/Assignments/AssignmentEditor.tsx</code> (Modified - Simplified, as detailed editing moved to <code>AssignmentEditPage</code>)
* '''Components:'''
** <code>src/components/Table/Table.tsx</code> (Modified - Added row highlighting for selected topics)
** <code>src/pages/Assignments/components/TopicsTable.tsx</code> (Created - Reusable table component for displaying topics)
* '''Routing:'''
** <code>src/App.tsx</code> (Modified - Added routes for <code>AssignmentEditPage</code> and <code>StudentTasks</code>)
* '''Layout:'''
** <code>src/layout/Header.tsx</code> (Modified - Conditionally show Assignments link for students)
* '''Hooks:'''
** <code>src/hooks/useAPI.ts</code> (Modified - Minor change in <code>then</code> block)
* '''Assets:'''
** <code>public/assets/icons/Check-icon.png</code> (Added)

== List of changes / Features Implemented ==

Based on the project description and feedback from E2513: 
'''Backend:''' 
# '''Renamed <code>SignUpTopic</code> to <code>ProjectTopic</code>:''' Refactored the model, controller, routes, database table, associations, and tests to use the new naming convention consistently.
# '''Refactored <code>SignedUpTeam</code> Logic:''' Moved business logic from the controller into the <code>SignedUpTeam</code> and <code>ProjectTopic</code> models, utilizing ActiveRecord features like transactions and scopes. Implemented methods for signing up students/teams, dropping topics, finding participants, and handling waitlists.
# '''Addressed E2513 Feedback:''' 
#* Renamed <code>signup_team</code> method to <code>sign_team_up</code> in <code>ProjectTopic</code>.
#* Renamed <code>signup_for_topic</code> method to <code>sign_up_for_topic</code> in <code>SignedUpTeam</code>.
#* Addressed DRY violation between <code>find_team_participants</code> and <code>find_project_topic_team_users</code>.
#* Ensured files terminate with a newline.
# '''Updated <code>Assignment</code> Model:''' Added <code>allow_bookmarks</code> attribute and updated associations related to topics.
# '''API Endpoints:''' Created/updated API endpoints for CRUD operations on <code>ProjectTopic</code> and actions related to <code>SignedUpTeam</code> (signup, drop topic).
# '''Testing:''' Added comprehensive RSpec tests for <code>ProjectTopic</code> and <code>SignedUpTeam</code> models. Updated existing tests (<code>due_date_spec.rb</code>). Added routing specs.

'''Frontend:''' 
# '''New Assignment Edit Page:''' Created <code>AssignmentEditPage</code> with a tabbed interface for editing assignments.
# '''Instructor Topics Tab:''' Implemented <code>TopicsTab</code> component allowing instructors to:
#* View/manage topics via <code>TopicsTable</code>.
#* Configure topic settings (e.g., allow bookmarks).
#* View assigned/waitlisted teams and drop teams.
#* Toggle display of user names/IDs.
#* Create, import, edit, delete topics via modals.
#* View bookmark counts.
#* Access Partner Ad functionality (UI added).
# '''Student Task/Signup Page:''' Created <code>StudentTasks</code> page allowing students to:
#* View available topics via <code>TopicsTable</code>.
#* See available slots and waitlist numbers.
#* View their selected topic.
#* Select/deselect (drop) a topic.
#* Bookmark topics (if enabled).
# '''Reusable <code>TopicsTable</code> Component:''' Developed adaptable table for student/instructor views with row expansion, selection, and custom actions.
# '''API Integration:''' Connected frontend components to backend API for fetching/updating topics, assignment settings, and handling signups/drops.
# '''UI Enhancements:''' Added selected topic highlighting, action icons, and modals for various operations.

== Testing Details==

=== Backend (RSpec) ===
New spec files (<code>project_topic_spec.rb</code>, <code>signed_up_team_spec.rb</code>) were created with extensive test coverage for the core models, including various scenarios like signup, waitlisting, dropping teams, and validations. Existing specs (<code>due_date_spec.rb</code>) were updated. Routing specs were added. Tests confirmed the refactored code integrates correctly.

=== UI Testing ===

Manual testing was performed following scenarios for instructors and students:

'''Instructor UI:''' 
# Login as instructor6.
# Navigate to an assignment (e.g., "OSS project & documentation") and click 'Edit'.
# Go to the 'Topics' tab.
# '''Verify topic list display:''' Check columns (Checkbox, ID, Name, Questionnaire, Slots, Available, Waitlist, Bookmarks, Actions).
# '''Verify topic settings:''' Test checkboxes, especially 'Allow participants to create bookmarks?'. Backend save confirmed via API call.
# '''Test topic actions:'''
#* Create a new topic via 'New topic' button/modal.
#* Edit an existing topic via edit icon/modal.
#* Delete topic(s) via delete icon or selecting checkboxes and using 'Delete selected topics'.
#* Import topics via 'Import topics' button/modal.
# Expand a topic row to view assigned/waitlisted teams. Test dropping a team via 'X' icon.
# Test 'Display User Names' toggle.

'''Student UI:''' 
# Login as teststudent.
# Navigate to 'Assignments' via header link.
# Verify signup sheet loads.
# '''Verify topic list display:''' Check columns (ID, Name, Available Slots, Num. on Waitlist, Bookmarks [if enabled], Actions).
# '''Test topic selection:''' Click checkmark icon. Verify 'Your topic(s)' updates, row highlights yellow, slots update optimistically, and API call is made.
# '''Test topic deselection (drop):''' Click 'X' icon on selected topic row. Verify topic is dropped, highlighting removed, slots update, and API call is made.
# '''Test bookmarking (if enabled):''' Click bookmark icon to toggle status.
# Verify actions are disabled for full topics (0 available slots).

== Scope for future improvement ==
# '''Complete Placeholder Tabs:''' Implement functionality for 'Rubrics', 'Review Strategy', 'Due Dates', and 'Etc.' tabs in instructor view.
# '''Partner Ad Backend:''' Implement backend logic for partner ads and applications.
# '''Bookmark Implementation:''' Fully implement bookmark creation/viewing functionality.
# '''Topic Suggestions:''' Implement student topic suggestion feature.
# '''Bidding Features:''' Implement topic/reviewer bidding.
# '''Refined UI/UX:''' Enhance UI based on feedback, e.g., team display within rows.
# '''Automated Frontend Testing:''' Add