Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-22T21:45:26Z

Akumarm: /* Edit Rubric */

==E2538 Reimplementing Questionnaire Page==

__TOC__

==About Expertiza==
Expertiza is an open-source web application currently built using [http://rubyonrails.org/ Ruby on Rails] and led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Designed for educational use, it enables instructors to manage assignments, rubrics, and participants, as well as assign grades and monitor student progress. Students can submit various types of learning objects, form teams, conduct peer evaluations, and review feedback from both peers and instructors. Originally developed at NC State, Expertiza is now used in select courses there and by faculty at other institutions, offering a flexible platform to enhance active learning and feedback in academic settings.

The reimplementation of Expertiza aims to mimic and enhance the application’s existing functionality with clean, well-structured code, while transitioning to a front-end application written in React and Typescipt integrated with a Ruby on Rails back-end.

==Project Overview==
The goal of this project is to implement the Questionnaire Management Dashboard and Create/Edit Rubric pages in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

While adhering to the following best practices:

*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Backend Integration==

The frontend interacts with several key resources exposed by the backend through a RESTful API. The structure of each model's associated database table lets us define Typescript interfaces, transform request/response payloads and promote type safety.

===Models===

====Questionnaire====

The <code>Questionnaire</code> model forms the foundation of the Create/Edit form functionality, storing necessary attributes for each questionnaire. These fields are used to construct a form for editing or creating a rubric and to prepopulate the form when editing an existing rubric.

The backend database also includes a table of <code>questionnaire_types</code>, access to which would allow the Questionnaire Management Dashboard to dynamically render all available categories of questionnaires and enable users to initiate the creation process based on a selected type.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the questionnaire
|-
| name || The name/title of the questionnaire
|-
| instructor_id || Foreign key referencing the instructor who created it
|-
| private || Boolean indicating if the questionnaire is private
|-
| min_question_score || Minimum score that can be given to any question
|-
| max_question_score || Maximum score that can be given to any question
|-
| questionnaire_type || The type/category of questionnaire (e.g., Survey, Teammate Review)
|-
| display_type || Field for specifying how to display the questionnaire
|-
| instruction_loc || Field for custom instructions location or reference
|-
| created_at || Timestamp of questionnaire creation
|-
| updated_at || Timestamp of last update
|}

====Item====

The <code>Item</code> model represents individual items (or questions) within a questionnaire and includes attributes that should be included when adding an item to a particular questionnaire.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the item
|-
| txt || The text of the item/question
|-
| weight || The relative importance or weight of the item
|-
| seq || The sequence/order of the item in the questionnaire
|-
| question_type || Foreign key referencing the type of question
|-
| size || Size attribute for text-based answers (e.g., text area size)
|-
| alternatives || Possible answer choices (comma-separated for multiple-choice)
|-
| break_before || Boolean indicating whether to insert a page break before the item
|-
| max_label || Optional label for the maximum scale value
|-
| min_label || Optional label for the minimum scale value
|-
| created_at || Timestamp of item creation
|-
| updated_at || Timestamp of last update
|-
| questionnaire_id || Foreign key referencing the associated questionnaire
|}

===API Endpoints===

To facilitate interaction with the backend, the frontend uses a pre-configured <code>axiosClient</code>, which abstracts the base API URL and port number. This client is defined in the <code>utils/axios_client.ts</code> file and reused throughout the project for API communication. For questionnaire management, several key API routes are accessed using this client. For example, <code>GET /questionnaires/:id</code> fetches detailed data for editing a selected questionnaire. When creating or updating a questionnaire, the application uses <code>POST /questionnaires</code> and <code>PUT /questionnaires/:id</code>, respectively.

{| class="wikitable"
|+
! HTTP Method !! Endpoint !! Description
|-
| GET || /questionnaires || Fetches a list of all questionnaires
|-
| GET || /questionnaires/:id || Fetches a specific questionnaire by ID
|-
| POST || /questionnaires || Creates a new questionnaire
|-
| PUT || /questionnaires/:id || Updates an existing questionnaire
|-
| DELETE || /questionnaires/:id || Deletes a specific questionnaire
|-
| GET || /questions || Retrieves a list of all questions (items)
|-
| GET || /questions/:id || Retrieves a specific item, along with its rendered display
|-
| POST || /questions || Creates a new item for a questionnaire
|-
| PUT || /questions/:id || Updates an existing item
|}

==Implementation==
===User Interface===

====Manage Questionnaires====

To navigate to the Questionnaire Management Dashboard, Questionnaire from the Manage dropdown from any page on Expertiza.

To be consistent with other management pages (for Users, Courses, Assignements) in the reimplementation front end, a table of questionnaires belonging to the logged-in instructor is visible on the page. From this page, you may create, edit, or delete a questionnaire.

To create a new questionnaire, click on the Create button in the top left corner of the page.

[[File:ManagementDashboard.png | 700px]]

====Type Selection====

When the Create button is selected from the top of the Questionnaire Management Dashboard, a pop-up appears with the available questionnaire types. To create a questionnaire of a given type, select the "+" botton in the row of the desired type.

[[File:TypeSelection.png | 700px]]

====Questionnaire Form====

Once a type has been selected, the user is directed to the appropriate form to create a questionnaire of the selected type. The user can include a variable number of items to the questionnaire at the time of creation. The required fields for an item is determined by the item type. For example, a scale type item required minimum and maximum values for its scale.

[[File:Questionnaire Form.png | 700px]]

Once a form field has been touched, the application alerts the user of missing required fields. Failure to provide appropriate values will prevent form submission.

[[File:Screenshot 2025-04-22 at 10.12.22 AM.png | 700px]]

Upon successful submission, the newly-created questionnaire will appear in the list of questionnaires in the Questionnaire Management Dashboard.

[[File:Editquestionnaireselect.png | 700px]]

To edit a questionnaire, select the edit icon next to the questionnaire you want to edit. You will be directed to a form with the existing questionnaire and items filled in.

[[File:Editquestionnaire.png | 700px]]

===QuestionnaireUtils.ts===
The <code>QuestionnaireUtils.ts</code> file serves as a utility module for handling questionnaire-related functionality in the application, including interfaces, data transformation methods, and back-end data retrieval. This file helps maintain clear separation of concerns, type safety, and adherence to design principles such as the Single Responsibility Principle (SRP).

===QuestionnaireForm.tsx===
The <code>QuestionnaireForm.tsx</code> file is a React component that provides a form interface for creating or editing questionnaires. It integrates with Formik for form state management and validation, utilizing React Bootstrap for UI elements.

The form fields are strongly typed using Formik's <code>Field</code> components and the <code>QuestionnaireFormValues</code> interface, ensuring that the data entered by the user adheres to the correct structure.
*Name: A text field for entering the questionnaire name.
*Type: A hidden input used to specify the type of the questionnaire selected from the Questionnaire Management Dashboard and to be passed to the back-end.
*Private: A checkbox to indicate whether the questionnaire is private.
*Minimum/Maximum Question Scores: Numeric fields for setting the minimum and maximum scores for questions.

The form delegates the responsibility of handling questionnaire items to the <code>QuestionnaireItemsFieldArray</code> component, which allows users to add or remove items dynamically and keeps each component focused on a single responsibility.

===QuestionnaireTypes.tsx===
This component renders a table that displays different types of questionnaires. Each row provides an action to navigate to the corresponding creation page for the selected questionnaire type. The <code>Table</code> component from <code>components/Table/Table</code> is used in adherence with the DRY Principle and the provided design guidelines.

==Code Changes Summary==
{| class="wikitable"
! File !! Method / Function !! Before !! After / Changes Introduced !! Commit Summary
|-
| App.tsx || Routing to /questionnaire and /edit-questionnaire || Not defined or incomplete || Added `ProtectedRoute` wrappers and proper routing to `Questionnaire` and `EditQuestionnaire` || Updated App.tsx
|-
| Questionnaire.tsx || render(), type grouping || Basic list display || Grouped by type, added "+" button for creating new rubrics || Update Questionnaire.tsx
|-
| Questionnaire.tsx || Add rubric handler || Not implemented || Clicking "+" navigates to `edit-questionnaire` with type parameter || More UI updates
|-
| EditQuestionnaire.tsx || Form handling & API integration || Static layout || Full integration with axios POST/PUT calls to backend || updated interface so it can now update backend
|-
| EditQuestionnaire.tsx || Questionnaire name editing || Not available || Name can now be edited from the UI || More functionality updates
|-
| EditQuestionnaire.tsx || Display and manage rubric items || Static list || Dynamically displays and adds rubric items || Properly displays items and properly adds items
|-
| questionnaire.tsx || Icons and UI elements || No icons || Edit, delete, and copy icons added for each row || More UI updates, including icons
|-
| axios_client.ts || axios client usage || Not standardized || Shared axiosClient used for API calls across all pages || Integrated across changes
|}

==Files Modified==
The following files were created or modified to implement the questionnaire dashboard and rubric management UI in React with TypeScript:

*<code>src/pages/Questionnaire/questionnaire.tsx</code> – Implements the Questionnaire Management Dashboard UI and groups questionnaires by type with "+" action buttons.
*<code>src/pages/EditQuestionnaire/Questionnaire.tsx</code> – Create/Edit Rubric page that handles full form logic and submission.
*<code>src/App.tsx</code> – Updated routing to include new paths: <code>/questionnaire</code> and <code>/edit-questionnaire</code>, protected via <code>ProtectedRoute</code>.
*<code>src/assets/icons/</code> – Added new UI icons for edit, delete, and copy actions in the questionnaire list.
*<code>src/utils/axios_client.ts</code> – Preconfigured <code>axios</code> instance used throughout the frontend for API interactions.
*<code>package.json</code> and <code>package-lock.json</code> – Updated dependencies for React Bootstrap, Formik, and icon support.

Note: The previously separate files like <code>QuestionnaireForm.tsx</code>, <code>QuestionnaireItemsFieldArray.tsx</code>, and <code>QuestionnaireUtils.tsx</code> were refactored and consolidated into <code>EditQuestionnaire/Questionnaire.tsx</code> for improved maintainability.

==Test Plan - Manual Testing Strategy==
====Login Credentials====
To login to the application, use the following credentials:
* username: instructor6
* password: password

====Questionnaire Dashboard Loading====
* Visit <code>/questionnaire</code> and confirm that all types of questionnaires are displayed.
* "+" button next to each type should open the rubric creation form with the correct type preselected.

====Form Functionality====
* Enter name, min/max scores, and toggle the private/public checkbox.
* Dynamically add or remove criteria.
* Submit the form to create a new rubric and confirm it reflects on the dashboard.

====Edit Rubric====
* Click on an existing rubric's "Edit" icon to load it in the edit form.
* Modify any field (name, score range, criteria) and resubmit.
* Confirm updated rubric details persist and are displayed correctly.

====Form Validation====
* Leave required fields empty and confirm that validation messages are displayed.
* Enter invalid values (e.g., <code>max_score < min_score</code>) and confirm appropriate warnings are shown.

====API Communication====
* Verify that form submissions trigger <code>POST /questionnaires</code> or <code>PUT /questionnaires/:id</code>.
* Confirm that response handling updates the UI appropriately (e.g., rerenders list on successful save).

====UI Testing====
* Confirm that the layout is responsive across desktop, tablet, and mobile devices.
* Ensure accessibility: keyboard navigation works, form fields are properly labeled, and ARIA roles are used where needed.

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, Questionnaire Management Dashboard]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, Create/Edit Rubric Page]
*[https://github.com/Michael-Anderson-NCSU/reimplementation-front-end, Project Repo]
*[http://152.7.176.255:8080 VCL Deployment]
*[https://github.com/expertiza/reimplementation-front-end/pull/98, Pull Request]

=====Demo Video=====
*[https://youtu.be/eVViM9_Gg80, Demo Video]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-22T21:13:56Z

Akumarm:

==E2538 Reimplementing Questionnaire Page==

__TOC__

==About Expertiza==
Expertiza is an open-source web application currently built using [http://rubyonrails.org/ Ruby on Rails] and led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Designed for educational use, it enables instructors to manage assignments, rubrics, and participants, as well as assign grades and monitor student progress. Students can submit various types of learning objects, form teams, conduct peer evaluations, and review feedback from both peers and instructors. Originally developed at NC State, Expertiza is now used in select courses there and by faculty at other institutions, offering a flexible platform to enhance active learning and feedback in academic settings.

The reimplementation of Expertiza aims to mimic and enhance the application’s existing functionality with clean, well-structured code, while transitioning to a front-end application written in React and Typescipt integrated with a Ruby on Rails back-end.

==Project Overview==
The goal of this project is to implement the Questionnaire Management Dashboard and Create/Edit Rubric pages in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

While adhering to the following best practices:

*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Backend Integration==

The frontend interacts with several key resources exposed by the backend through a RESTful API. The structure of each model's associated database table lets us define Typescript interfaces, transform request/response payloads and promote type safety.

===Models===

====Questionnaire====

The <code>Questionnaire</code> model forms the foundation of the Create/Edit form functionality, storing necessary attributes for each questionnaire. These fields are used to construct a form for editing or creating a rubric and to prepopulate the form when editing an existing rubric.

The backend database also includes a table of <code>questionnaire_types</code>, access to which would allow the Questionnaire Management Dashboard to dynamically render all available categories of questionnaires and enable users to initiate the creation process based on a selected type.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the questionnaire
|-
| name || The name/title of the questionnaire
|-
| instructor_id || Foreign key referencing the instructor who created it
|-
| private || Boolean indicating if the questionnaire is private
|-
| min_question_score || Minimum score that can be given to any question
|-
| max_question_score || Maximum score that can be given to any question
|-
| questionnaire_type || The type/category of questionnaire (e.g., Survey, Teammate Review)
|-
| display_type || Field for specifying how to display the questionnaire
|-
| instruction_loc || Field for custom instructions location or reference
|-
| created_at || Timestamp of questionnaire creation
|-
| updated_at || Timestamp of last update
|}

====Item====

The <code>Item</code> model represents individual items (or questions) within a questionnaire and includes attributes that should be included when adding an item to a particular questionnaire.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the item
|-
| txt || The text of the item/question
|-
| weight || The relative importance or weight of the item
|-
| seq || The sequence/order of the item in the questionnaire
|-
| question_type || Foreign key referencing the type of question
|-
| size || Size attribute for text-based answers (e.g., text area size)
|-
| alternatives || Possible answer choices (comma-separated for multiple-choice)
|-
| break_before || Boolean indicating whether to insert a page break before the item
|-
| max_label || Optional label for the maximum scale value
|-
| min_label || Optional label for the minimum scale value
|-
| created_at || Timestamp of item creation
|-
| updated_at || Timestamp of last update
|-
| questionnaire_id || Foreign key referencing the associated questionnaire
|}

===API Endpoints===

To facilitate interaction with the backend, the frontend uses a pre-configured <code>axiosClient</code>, which abstracts the base API URL and port number. This client is defined in the <code>utils/axios_client.ts</code> file and reused throughout the project for API communication. For questionnaire management, several key API routes are accessed using this client. For example, <code>GET /questionnaires/:id</code> fetches detailed data for editing a selected questionnaire. When creating or updating a questionnaire, the application uses <code>POST /questionnaires</code> and <code>PUT /questionnaires/:id</code>, respectively.

{| class="wikitable"
|+
! HTTP Method !! Endpoint !! Description
|-
| GET || /questionnaires || Fetches a list of all questionnaires
|-
| GET || /questionnaires/:id || Fetches a specific questionnaire by ID
|-
| POST || /questionnaires || Creates a new questionnaire
|-
| PUT || /questionnaires/:id || Updates an existing questionnaire
|-
| DELETE || /questionnaires/:id || Deletes a specific questionnaire
|-
| GET || /questions || Retrieves a list of all questions (items)
|-
| GET || /questions/:id || Retrieves a specific item, along with its rendered display
|-
| POST || /questions || Creates a new item for a questionnaire
|-
| PUT || /questions/:id || Updates an existing item
|}

==Implementation==
===User Interface===

====Manage Questionnaires====

To navigate to the Questionnaire Management Dashboard, Questionnaire from the Manage dropdown from any page on Expertiza.

To be consistent with other management pages (for Users, Courses, Assignements) in the reimplementation front end, a table of questionnaires belonging to the logged-in instructor is visible on the page. From this page, you may create, edit, or delete a questionnaire.

To create a new questionnaire, click on the Create button in the top left corner of the page.

[[File:ManagementDashboard.png | 700px]]

====Type Selection====

When the Create button is selected from the top of the Questionnaire Management Dashboard, a pop-up appears with the available questionnaire types. To create a questionnaire of a given type, select the "+" botton in the row of the desired type.

[[File:TypeSelection.png | 700px]]

====Questionnaire Form====

Once a type has been selected, the user is directed to the appropriate form to create a questionnaire of the selected type. The user can include a variable number of items to the questionnaire at the time of creation. The required fields for an item is determined by the item type. For example, a scale type item required minimum and maximum values for its scale.

[[File:Questionnaire Form.png | 700px]]

Once a form field has been touched, the application alerts the user of missing required fields. Failure to provide appropriate values will prevent form submission.

[[File:Screenshot 2025-04-22 at 10.12.22 AM.png | 700px]]

Upon successful submission, the newly-created questionnaire will appear in the list of questionnaires in the Questionnaire Management Dashboard.

[[File:Editquestionnaireselect.png | 700px]]

To edit a questionnaire, select the edit icon next to the questionnaire you want to edit. You will be directed to a form with the existing questionnaire and items filled in.

[[File:Editquestionnaire.png | 700px]]

===QuestionnaireUtils.ts===
The <code>QuestionnaireUtils.ts</code> file serves as a utility module for handling questionnaire-related functionality in the application, including interfaces, data transformation methods, and back-end data retrieval. This file helps maintain clear separation of concerns, type safety, and adherence to design principles such as the Single Responsibility Principle (SRP).

===QuestionnaireForm.tsx===
The <code>QuestionnaireForm.tsx</code> file is a React component that provides a form interface for creating or editing questionnaires. It integrates with Formik for form state management and validation, utilizing React Bootstrap for UI elements.

The form fields are strongly typed using Formik's <code>Field</code> components and the <code>QuestionnaireFormValues</code> interface, ensuring that the data entered by the user adheres to the correct structure.
*Name: A text field for entering the questionnaire name.
*Type: A hidden input used to specify the type of the questionnaire selected from the Questionnaire Management Dashboard and to be passed to the back-end.
*Private: A checkbox to indicate whether the questionnaire is private.
*Minimum/Maximum Question Scores: Numeric fields for setting the minimum and maximum scores for questions.

The form delegates the responsibility of handling questionnaire items to the <code>QuestionnaireItemsFieldArray</code> component, which allows users to add or remove items dynamically and keeps each component focused on a single responsibility.

===QuestionnaireTypes.tsx===
This component renders a table that displays different types of questionnaires. Each row provides an action to navigate to the corresponding creation page for the selected questionnaire type. The <code>Table</code> component from <code>components/Table/Table</code> is used in adherence with the DRY Principle and the provided design guidelines.

==Code Changes Summary==
{| class="wikitable"
! File !! Method / Function !! Before !! After / Changes Introduced !! Commit Summary
|-
| App.tsx || Routing to /questionnaire and /edit-questionnaire || Not defined or incomplete || Added `ProtectedRoute` wrappers and proper routing to `Questionnaire` and `EditQuestionnaire` || Updated App.tsx
|-
| Questionnaire.tsx || render(), type grouping || Basic list display || Grouped by type, added "+" button for creating new rubrics || Update Questionnaire.tsx
|-
| Questionnaire.tsx || Add rubric handler || Not implemented || Clicking "+" navigates to `edit-questionnaire` with type parameter || More UI updates
|-
| EditQuestionnaire.tsx || Form handling & API integration || Static layout || Full integration with axios POST/PUT calls to backend || updated interface so it can now update backend
|-
| EditQuestionnaire.tsx || Questionnaire name editing || Not available || Name can now be edited from the UI || More functionality updates
|-
| EditQuestionnaire.tsx || Display and manage rubric items || Static list || Dynamically displays and adds rubric items || Properly displays items and properly adds items
|-
| questionnaire.tsx || Icons and UI elements || No icons || Edit, delete, and copy icons added for each row || More UI updates, including icons
|-
| axios_client.ts || axios client usage || Not standardized || Shared axiosClient used for API calls across all pages || Integrated across changes
|}

==Files Modified==
The following files were created or modified to implement the questionnaire dashboard and rubric management UI in React with TypeScript:

*<code>src/pages/Questionnaire/questionnaire.tsx</code> – Implements the Questionnaire Management Dashboard UI and groups questionnaires by type with "+" action buttons.
*<code>src/pages/EditQuestionnaire/Questionnaire.tsx</code> – Create/Edit Rubric page that handles full form logic and submission.
*<code>src/App.tsx</code> – Updated routing to include new paths: <code>/questionnaire</code> and <code>/edit-questionnaire</code>, protected via <code>ProtectedRoute</code>.
*<code>src/assets/icons/</code> – Added new UI icons for edit, delete, and copy actions in the questionnaire list.
*<code>src/utils/axios_client.ts</code> – Preconfigured <code>axios</code> instance used throughout the frontend for API interactions.
*<code>package.json</code> and <code>package-lock.json</code> – Updated dependencies for React Bootstrap, Formik, and icon support.

Note: The previously separate files like <code>QuestionnaireForm.tsx</code>, <code>QuestionnaireItemsFieldArray.tsx</code>, and <code>QuestionnaireUtils.tsx</code> were refactored and consolidated into <code>EditQuestionnaire/Questionnaire.tsx</code> for improved maintainability.

==Test Plan - Manual Testing Strategy==
====Login Credentials====
To login to the application, use the following credentials:
* username: instructor6
* password: password

====Questionnaire Dashboard Loading====
* Visit <code>/questionnaire</code> and confirm that all types of questionnaires are displayed.
* "+" button next to each type should open the rubric creation form with the correct type preselected.

====Form Functionality====
* Enter name, min/max scores, and toggle the private/public checkbox.
* Dynamically add or remove criteria.
* Submit the form to create a new rubric and confirm it reflects on the dashboard.

====Edit Rubric====
* Click on an existing rubric's ✏️ icon to load it in the edit form.
* Modify any field (name, score range, criteria) and resubmit.
* Confirm updated rubric details persist and are displayed correctly.

====Form Validation====
* Leave required fields empty and confirm that validation messages are displayed.
* Enter invalid values (e.g., <code>max_score < min_score</code>) and confirm appropriate warnings are shown.

====API Communication====
* Verify that form submissions trigger <code>POST /questionnaires</code> or <code>PUT /questionnaires/:id</code>.
* Confirm that response handling updates the UI appropriately (e.g., rerenders list on successful save).

====UI Testing====
* Confirm that the layout is responsive across desktop, tablet, and mobile devices.
* Ensure accessibility: keyboard navigation works, form fields are properly labeled, and ARIA roles are used where needed.

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, Questionnaire Management Dashboard]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, Create/Edit Rubric Page]
*[https://github.com/Michael-Anderson-NCSU/reimplementation-front-end, Project Repo]
*[http://152.7.176.255:8080 VCL Deployment]
*[https://github.com/expertiza/reimplementation-front-end/pull/98, Pull Request]

=====Demo Video=====
*[https://youtu.be/eVViM9_Gg80, Demo Video]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-22T21:09:57Z

Akumarm:

==E2538 Reimplementing Questionnaire Page==

__TOC__

==About Expertiza==
Expertiza is an open-source web application currently built using [http://rubyonrails.org/ Ruby on Rails] and led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Designed for educational use, it enables instructors to manage assignments, rubrics, and participants, as well as assign grades and monitor student progress. Students can submit various types of learning objects, form teams, conduct peer evaluations, and review feedback from both peers and instructors. Originally developed at NC State, Expertiza is now used in select courses there and by faculty at other institutions, offering a flexible platform to enhance active learning and feedback in academic settings.

The reimplementation of Expertiza aims to mimic and enhance the application’s existing functionality with clean, well-structured code, while transitioning to a front-end application written in React and Typescipt integrated with a Ruby on Rails back-end.

==Project Overview==
The goal of this project is to implement the Questionnaire Management Dashboard and Create/Edit Rubric pages in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

While adhering to the following best practices:

*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Backend Integration==

The frontend interacts with several key resources exposed by the backend through a RESTful API. The structure of each model's associated database table lets us define Typescript interfaces, transform request/response payloads and promote type safety.

===Models===

====Questionnaire====

The <code>Questionnaire</code> model forms the foundation of the Create/Edit form functionality, storing necessary attributes for each questionnaire. These fields are used to construct a form for editing or creating a rubric and to prepopulate the form when editing an existing rubric.

The backend database also includes a table of <code>questionnaire_types</code>, access to which would allow the Questionnaire Management Dashboard to dynamically render all available categories of questionnaires and enable users to initiate the creation process based on a selected type.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the questionnaire
|-
| name || The name/title of the questionnaire
|-
| instructor_id || Foreign key referencing the instructor who created it
|-
| private || Boolean indicating if the questionnaire is private
|-
| min_question_score || Minimum score that can be given to any question
|-
| max_question_score || Maximum score that can be given to any question
|-
| questionnaire_type || The type/category of questionnaire (e.g., Survey, Teammate Review)
|-
| display_type || Field for specifying how to display the questionnaire
|-
| instruction_loc || Field for custom instructions location or reference
|-
| created_at || Timestamp of questionnaire creation
|-
| updated_at || Timestamp of last update
|}

====Item====

The <code>Item</code> model represents individual items (or questions) within a questionnaire and includes attributes that should be included when adding an item to a particular questionnaire.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the item
|-
| txt || The text of the item/question
|-
| weight || The relative importance or weight of the item
|-
| seq || The sequence/order of the item in the questionnaire
|-
| question_type || Foreign key referencing the type of question
|-
| size || Size attribute for text-based answers (e.g., text area size)
|-
| alternatives || Possible answer choices (comma-separated for multiple-choice)
|-
| break_before || Boolean indicating whether to insert a page break before the item
|-
| max_label || Optional label for the maximum scale value
|-
| min_label || Optional label for the minimum scale value
|-
| created_at || Timestamp of item creation
|-
| updated_at || Timestamp of last update
|-
| questionnaire_id || Foreign key referencing the associated questionnaire
|}

===API Endpoints===

To facilitate interaction with the backend, the frontend uses a pre-configured <code>axiosClient</code>, which abstracts the base API URL and port number. This client is defined in the <code>utils/axios_client.ts</code> file and reused throughout the project for API communication. For questionnaire management, several key API routes are accessed using this client. For example, <code>GET /questionnaires/:id</code> fetches detailed data for editing a selected questionnaire. When creating or updating a questionnaire, the application uses <code>POST /questionnaires</code> and <code>PUT /questionnaires/:id</code>, respectively.

{| class="wikitable"
|+
! HTTP Method !! Endpoint !! Description
|-
| GET || /questionnaires || Fetches a list of all questionnaires
|-
| GET || /questionnaires/:id || Fetches a specific questionnaire by ID
|-
| POST || /questionnaires || Creates a new questionnaire
|-
| PUT || /questionnaires/:id || Updates an existing questionnaire
|-
| DELETE || /questionnaires/:id || Deletes a specific questionnaire
|-
| GET || /questions || Retrieves a list of all questions (items)
|-
| GET || /questions/:id || Retrieves a specific item, along with its rendered display
|-
| POST || /questions || Creates a new item for a questionnaire
|-
| PUT || /questions/:id || Updates an existing item
|}

==Implementation==
===User Interface===

====Manage Questionnaires====

To navigate to the Questionnaire Management Dashboard, Questionnaire from the Manage dropdown from any page on Expertiza.

To be consistent with other management pages (for Users, Courses, Assignements) in the reimplementation front end, a table of questionnaires belonging to the logged-in instructor is visible on the page. From this page, you may create, edit, or delete a questionnaire.

To create a new questionnaire, click on the Create button in the top left corner of the page.

[[File:ManagementDashboard.png | 700px]]

====Type Selection====

When the Create button is selected from the top of the Questionnaire Management Dashboard, a pop-up appears with the available questionnaire types. To create a questionnaire of a given type, select the "+" botton in the row of the desired type.

[[File:TypeSelection.png | 700px]]

====Questionnaire Form====

Once a type has been selected, the user is directed to the appropriate form to create a questionnaire of the selected type. The user can include a variable number of items to the questionnaire at the time of creation. The required fields for an item is determined by the item type. For example, a scale type item required minimum and maximum values for its scale.

[[File:Questionnaire Form.png | 700px]]

Once a form field has been touched, the application alerts the user of missing required fields. Failure to provide appropriate values will prevent form submission.

[[File:Screenshot 2025-04-22 at 10.12.22 AM.png | 700px]]

Upon successful submission, the newly-created questionnaire will appear in the list of questionnaires in the Questionnaire Management Dashboard.

[[File:Editquestionnaireselect.png | 700px]]

To edit a questionnaire, select the edit icon next to the questionnaire you want to edit. You will be directed to a form with the existing questionnaire and items filled in.

[[File:Editquestionnaire.png | 700px]]

===QuestionnaireUtils.ts===
The <code>QuestionnaireUtils.ts</code> file serves as a utility module for handling questionnaire-related functionality in the application, including interfaces, data transformation methods, and back-end data retrieval. This file helps maintain clear separation of concerns, type safety, and adherence to design principles such as the Single Responsibility Principle (SRP).

===QuestionnaireForm.tsx===
The <code>QuestionnaireForm.tsx</code> file is a React component that provides a form interface for creating or editing questionnaires. It integrates with Formik for form state management and validation, utilizing React Bootstrap for UI elements.

The form fields are strongly typed using Formik's <code>Field</code> components and the <code>QuestionnaireFormValues</code> interface, ensuring that the data entered by the user adheres to the correct structure.
*Name: A text field for entering the questionnaire name.
*Type: A hidden input used to specify the type of the questionnaire selected from the Questionnaire Management Dashboard and to be passed to the back-end.
*Private: A checkbox to indicate whether the questionnaire is private.
*Minimum/Maximum Question Scores: Numeric fields for setting the minimum and maximum scores for questions.

The form delegates the responsibility of handling questionnaire items to the <code>QuestionnaireItemsFieldArray</code> component, which allows users to add or remove items dynamically and keeps each component focused on a single responsibility.

===QuestionnaireTypes.tsx===
This component renders a table that displays different types of questionnaires. Each row provides an action to navigate to the corresponding creation page for the selected questionnaire type. The <code>Table</code> component from <code>components/Table/Table</code> is used in adherence with the DRY Principle and the provided design guidelines.

==Code Changes Summary==
{| class="wikitable"
! File !! Method / Function !! Before !! After / Changes Introduced !! Commit Summary
|-
| App.tsx || Routing to /questionnaire and /edit-questionnaire || Not defined or incomplete || Added `ProtectedRoute` wrappers and proper routing to `Questionnaire` and `EditQuestionnaire` || Updated App.tsx
|-
| Questionnaire.tsx || render(), type grouping || Basic list display || Grouped by type, added "+" button for creating new rubrics || Update Questionnaire.tsx
|-
| Questionnaire.tsx || Add rubric handler || Not implemented || Clicking "+" navigates to `edit-questionnaire` with type parameter || More UI updates
|-
| EditQuestionnaire.tsx || Form handling & API integration || Static layout || Full integration with axios POST/PUT calls to backend || updated interface so it can now update backend
|-
| EditQuestionnaire.tsx || Questionnaire name editing || Not available || Name can now be edited from the UI || More functionality updates
|-
| EditQuestionnaire.tsx || Display and manage rubric items || Static list || Dynamically displays and adds rubric items || Properly displays items and properly adds items
|-
| questionnaire.tsx || Icons and UI elements || No icons || Edit, delete, and copy icons added for each row || More UI updates, including icons
|-
| axios_client.ts || axios client usage || Not standardized || Shared axiosClient used for API calls across all pages || Integrated across changes
|}

==Files Modified==
The following files were created or modified to implement the questionnaire dashboard and rubric management UI in React with TypeScript:

*<code>src/pages/Questionnaires/Questionnaires.tsx</code> – Implements the Questionnaire Management Dashboard UI.
*<code>src/pages/Questionnaires/QuestionnaireTypes.tsx</code> – List of questionnaire types that may be created by the user.
*<code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> – Create/Edit Rubric page that encapsultes form.
*<code>src/pages/Questionnaires/QuestionnaireForm.tsx</code> – Form component for creating or editing questionnaires.
*<code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> – Supporting form component to dynamically create or update questionnaire items.
*<code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> – Utility functions and interfaces for questionnaires.
*<code>src/App.tsx</code> – Updated routing to include new questionnaire pages.
*<code>src/assets/icons/</code> – Added new UI icons for editing, deleting, and copying questionnaires.
*<code>src/utils/axios_client.ts</code> – Preconfigured axios instance used throughout the frontend for API calls.
*<code>package.json</code> and <code>package-lock.json</code> – Updated dependencies for icons, React Bootstrap, and Formik support.

==Test Plan - Manual Testing Strategy==
====Login Credentials====
To login to the application, use the following credentials:
* username: instructor6
* password: password

====Questionnaire Dashboard Loading====
*Visit /questionnaire and confirm that all types of questionnaires are displayed.
*"+" button next to each type should open the rubric creation form for that type.

====Form Functionality====
*Enter name, min/max scores, toggle private/public checkbox.
*Dynamically add/remove criteria.
*Submit form to create a new rubric and confirm it reflects in the backend.

====Edit Rubric====
*Click on any existing rubric to load it in the edit form.
*Edit fields and submit changes. Confirm updated data is persisted.

====Form Validation====
*Leave required fields empty and confirm validation errors appear.
*Enter invalid values (e.g., max < min) and confirm appropriate messages.

====API Communication====
*Verified POST/PUT requests are correctly formatted.
*Backend updates reflected in UI after reload.

====UI Testing====
*Confirm responsiveness across desktop, tablet, and mobile.
*Check accessibility: keyboard navigation, proper labeling.

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, Questionnaire Management Dashboard]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, Create/Edit Rubric Page]
*[https://github.com/Michael-Anderson-NCSU/reimplementation-front-end, Project Repo]
*[http://152.7.176.255:8080 VCL Deployment]
*[https://github.com/expertiza/reimplementation-front-end/pull/98, Pull Request]

=====Demo Video=====
*[https://youtu.be/eVViM9_Gg80, Demo Video]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-22T21:01:44Z

Akumarm:

==E2538 Reimplementing Questionnaire Page==

__TOC__

==About Expertiza==
Expertiza is an open-source web application currently built using [http://rubyonrails.org/ Ruby on Rails] and led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Designed for educational use, it enables instructors to manage assignments, rubrics, and participants, as well as assign grades and monitor student progress. Students can submit various types of learning objects, form teams, conduct peer evaluations, and review feedback from both peers and instructors. Originally developed at NC State, Expertiza is now used in select courses there and by faculty at other institutions, offering a flexible platform to enhance active learning and feedback in academic settings.

The reimplementation of Expertiza aims to mimic and enhance the application’s existing functionality with clean, well-structured code, while transitioning to a front-end application written in React and Typescipt integrated with a Ruby on Rails back-end.

==Project Overview==
The goal of this project is to implement the Questionnaire Management Dashboard and Create/Edit Rubric pages in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

While adhering to the following best practices:

*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Backend Integration==

The frontend interacts with several key resources exposed by the backend through a RESTful API. The structure of each model's associated database table lets us define Typescript interfaces, transform request/response payloads and promote type safety.

===Models===

====Questionnaire====

The <code>Questionnaire</code> model forms the foundation of the Create/Edit form functionality, storing necessary attributes for each questionnaire. These fields are used to construct a form for editing or creating a rubric and to prepopulate the form when editing an existing rubric.

The backend database also includes a table of <code>questionnaire_types</code>, access to which would allow the Questionnaire Management Dashboard to dynamically render all available categories of questionnaires and enable users to initiate the creation process based on a selected type.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the questionnaire
|-
| name || The name/title of the questionnaire
|-
| instructor_id || Foreign key referencing the instructor who created it
|-
| private || Boolean indicating if the questionnaire is private
|-
| min_question_score || Minimum score that can be given to any question
|-
| max_question_score || Maximum score that can be given to any question
|-
| questionnaire_type || The type/category of questionnaire (e.g., Survey, Teammate Review)
|-
| display_type || Field for specifying how to display the questionnaire
|-
| instruction_loc || Field for custom instructions location or reference
|-
| created_at || Timestamp of questionnaire creation
|-
| updated_at || Timestamp of last update
|}

====Item====

The <code>Item</code> model represents individual items (or questions) within a questionnaire and includes attributes that should be included when adding an item to a particular questionnaire.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the item
|-
| txt || The text of the item/question
|-
| weight || The relative importance or weight of the item
|-
| seq || The sequence/order of the item in the questionnaire
|-
| question_type || Foreign key referencing the type of question
|-
| size || Size attribute for text-based answers (e.g., text area size)
|-
| alternatives || Possible answer choices (comma-separated for multiple-choice)
|-
| break_before || Boolean indicating whether to insert a page break before the item
|-
| max_label || Optional label for the maximum scale value
|-
| min_label || Optional label for the minimum scale value
|-
| created_at || Timestamp of item creation
|-
| updated_at || Timestamp of last update
|-
| questionnaire_id || Foreign key referencing the associated questionnaire
|}

===API Endpoints===

To facilitate interaction with the backend, the frontend uses a pre-configured <code>axiosClient</code>, which abstracts the base API URL and port number. This client is defined in the <code>utils/axios_client.ts</code> file and reused throughout the project for API communication. For questionnaire management, several key API routes are accessed using this client. For example, <code>GET /questionnaires/:id</code> fetches detailed data for editing a selected questionnaire. When creating or updating a questionnaire, the application uses <code>POST /questionnaires</code> and <code>PUT /questionnaires/:id</code>, respectively.

{| class="wikitable"
|+
! HTTP Method !! Endpoint !! Description
|-
| GET || /questionnaires || Fetches a list of all questionnaires
|-
| GET || /questionnaires/:id || Fetches a specific questionnaire by ID
|-
| POST || /questionnaires || Creates a new questionnaire
|-
| PUT || /questionnaires/:id || Updates an existing questionnaire
|-
| DELETE || /questionnaires/:id || Deletes a specific questionnaire
|-
| GET || /questions || Retrieves a list of all questions (items)
|-
| GET || /questions/:id || Retrieves a specific item, along with its rendered display
|-
| POST || /questions || Creates a new item for a questionnaire
|-
| PUT || /questions/:id || Updates an existing item
|}

==Implementation==
===User Interface===

====Manage Questionnaires====

To navigate to the Questionnaire Management Dashboard, Questionnaire from the Manage dropdown from any page on Expertiza.

To be consistent with other management pages (for Users, Courses, Assignements) in the reimplementation front end, a table of questionnaires belonging to the logged-in instructor is visible on the page. From this page, you may create, edit, or delete a questionnaire.

To create a new questionnaire, click on the Create button in the top left corner of the page.

[[File:ManagementDashboard.png | 700px]]

====Type Selection====

When the Create button is selected from the top of the Questionnaire Management Dashboard, a pop-up appears with the available questionnaire types. To create a questionnaire of a given type, select the "+" botton in the row of the desired type.

[[File:TypeSelection.png | 700px]]

====Questionnaire Form====

Once a type has been selected, the user is directed to the appropriate form to create a questionnaire of the selected type. The user can include a variable number of items to the questionnaire at the time of creation. The required fields for an item is determined by the item type. For example, a scale type item required minimum and maximum values for its scale.

[[File:Questionnaire Form.png | 700px]]

Once a form field has been touched, the application alerts the user of missing required fields. Failure to provide appropriate values will prevent form submission.

[[File:Screenshot 2025-04-22 at 10.12.22 AM.png | 700px]]

Upon successful submission, the newly-created questionnaire will appear in the list of questionnaires in the Questionnaire Management Dashboard.

[[File:Editquestionnaireselect.png | 700px]]

To edit a questionnaire, select the edit icon next to the questionnaire you want to edit. You will be directed to a form with the existing questionnaire and items filled in.

[[File:Editquestionnaire.png | 700px]]

===QuestionnaireUtils.ts===
The <code>QuestionnaireUtils.ts</code> file serves as a utility module for handling questionnaire-related functionality in the application, including interfaces, data transformation methods, and back-end data retrieval. This file helps maintain clear separation of concerns, type safety, and adherence to design principles such as the Single Responsibility Principle (SRP).

===QuestionnaireForm.tsx===
The <code>QuestionnaireForm.tsx</code> file is a React component that provides a form interface for creating or editing questionnaires. It integrates with Formik for form state management and validation, utilizing React Bootstrap for UI elements.

The form fields are strongly typed using Formik's <code>Field</code> components and the <code>QuestionnaireFormValues</code> interface, ensuring that the data entered by the user adheres to the correct structure.
*Name: A text field for entering the questionnaire name.
*Type: A hidden input used to specify the type of the questionnaire selected from the Questionnaire Management Dashboard and to be passed to the back-end.
*Private: A checkbox to indicate whether the questionnaire is private.
*Minimum/Maximum Question Scores: Numeric fields for setting the minimum and maximum scores for questions.

The form delegates the responsibility of handling questionnaire items to the <code>QuestionnaireItemsFieldArray</code> component, which allows users to add or remove items dynamically and keeps each component focused on a single responsibility.

===QuestionnaireTypes.tsx===
This component renders a table that displays different types of questionnaires. Each row provides an action to navigate to the corresponding creation page for the selected questionnaire type. The <code>Table</code> component from <code>components/Table/Table</code> is used in adherence with the DRY Principle and the provided design guidelines.

==Files Modified==
The following files were created or modified to implement the questionnaire dashboard and rubric management UI in React with TypeScript:

*<code>src/pages/Questionnaires/Questionnaires.tsx</code> – Implements the Questionnaire Management Dashboard UI.
*<code>src/pages/Questionnaires/QuestionnaireTypes.tsx</code> – List of questionnaire types that may be created by the user.
*<code>src/pages/Questionnaires/QuestionnaireEditor.tsx</code> – Create/Edit Rubric page that encapsultes form.
*<code>src/pages/Questionnaires/QuestionnaireForm.tsx</code> – Form component for creating or editing questionnaires.
*<code>src/pages/Questionnaires/QuestionnaireItemsFieldArray.tsx</code> – Supporting form component to dynamically create or update questionnaire items.
*<code>src/pages/Questionnaires/QuestionnaireUtils.tsx</code> – Utility functions and interfaces for questionnaires.
*<code>src/App.tsx</code> – Updated routing to include new questionnaire pages.
*<code>src/assets/icons/</code> – Added new UI icons for editing, deleting, and copying questionnaires.
*<code>src/utils/axios_client.ts</code> – Preconfigured axios instance used throughout the frontend for API calls.
*<code>package.json</code> and <code>package-lock.json</code> – Updated dependencies for icons, React Bootstrap, and Formik support.

==Test Plan - Manual Testing Strategy==
====Login Credentials====
To login to the application, use the following credentials:
* username: instructor6
* password: password

====Questionnaire Dashboard Loading====
*Visit /questionnaire and confirm that all types of questionnaires are displayed.
*"+" button next to each type should open the rubric creation form for that type.

====Form Functionality====
*Enter name, min/max scores, toggle private/public checkbox.
*Dynamically add/remove criteria.
*Submit form to create a new rubric and confirm it reflects in the backend.

====Edit Rubric====
*Click on any existing rubric to load it in the edit form.
*Edit fields and submit changes. Confirm updated data is persisted.

====Form Validation====
*Leave required fields empty and confirm validation errors appear.
*Enter invalid values (e.g., max < min) and confirm appropriate messages.

====API Communication====
*Verified POST/PUT requests are correctly formatted.
*Backend updates reflected in UI after reload.

====UI Testing====
*Confirm responsiveness across desktop, tablet, and mobile.
*Check accessibility: keyboard navigation, proper labeling.

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, Questionnaire Management Dashboard]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, Create/Edit Rubric Page]
*[https://github.com/Michael-Anderson-NCSU/reimplementation-front-end, Project Repo]
*[http://152.7.176.255:8080 VCL Deployment]
*[https://github.com/expertiza/reimplementation-front-end/pull/98, Pull Request]

=====Demo Video=====
*[https://youtu.be/eVViM9_Gg80, Demo Video]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-22T00:47:24Z

Akumarm:

==E2538 Reimplementing Questionnaire Page==

__TOC__

==About Expertiza==
Expertiza is an open-source web application currently built using [http://rubyonrails.org/ Ruby on Rails] and led by [https://www.csc.ncsu.edu/people/efg Dr. Edward Gehringer]. Designed for educational use, it enables instructors to manage assignments, rubrics, and participants, as well as assign grades and monitor student progress. Students can submit various types of learning objects, form teams, conduct peer evaluations, and review feedback from both peers and instructors. Originally developed at NC State, Expertiza is now used in select courses there and by faculty at other institutions, offering a flexible platform to enhance active learning and feedback in academic settings.

The reimplementation of Expertiza aims to mimic and enhance the application’s existing functionality with clean, well-structured code, while transitioning to a front-end application written in React and Typescipt integrated with a Ruby on Rails back-end.

==Project Overview==
The goal of this project is to implement the Questionnaire Management Dashboard and Create/Edit Rubric pages in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

While adhering to the following best practices:

*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Backend Integration==

The frontend interacts with several key resources exposed by the backend through a RESTful API. The structure of each model's associated database table lets us define Typescript interfaces, transform request/response payloads and promote type safety.

===Models===

====Questionnaire====

The <code>Questionnaire</code> model forms the foundation of the Create/Edit form functionality, storing necessary attributes for each questionnaire. These fields are used to construct a form for editing or creating a rubric and to prepopulate the form when editing an existing rubric.

The backend database also includes a table of <code>questionnaire_types</code>, access to which would allow the Questionnaire Management Dashboard to dynamically render all available categories of questionnaires and enable users to initiate the creation process based on a selected type.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the questionnaire
|-
| name || The name/title of the questionnaire
|-
| instructor_id || Foreign key referencing the instructor who created it
|-
| private || Boolean indicating if the questionnaire is private
|-
| min_question_score || Minimum score that can be given to any question
|-
| max_question_score || Maximum score that can be given to any question
|-
| questionnaire_type || The type/category of questionnaire (e.g., Survey, Teammate Review)
|-
| display_type || Field for specifying how to display the questionnaire
|-
| instruction_loc || Field for custom instructions location or reference
|-
| created_at || Timestamp of questionnaire creation
|-
| updated_at || Timestamp of last update
|}

====Item====

The <code>Item</code> model represents individual items (or questions) within a questionnaire and includes attributes that should be included when adding an item to a particular questionnaire.

{| class="wikitable"
! Attribute !! Description
|-
| id || Unique identifier for the item
|-
| txt || The text of the item/question
|-
| weight || The relative importance or weight of the item
|-
| seq || The sequence/order of the item in the questionnaire
|-
| question_type || Foreign key referencing the type of question
|-
| size || Size attribute for text-based answers (e.g., text area size)
|-
| alternatives || Possible answer choices (comma-separated for multiple-choice)
|-
| break_before || Boolean indicating whether to insert a page break before the item
|-
| max_label || Optional label for the maximum scale value
|-
| min_label || Optional label for the minimum scale value
|-
| created_at || Timestamp of item creation
|-
| updated_at || Timestamp of last update
|-
| questionnaire_id || Foreign key referencing the associated questionnaire
|}

===API Endpoints===

To facilitate interaction with the backend, the frontend uses a pre-configured <code>axiosClient</code>, which abstracts the base API URL and port number. This client is defined in the <code>utils/axios_client.ts</code> file and reused throughout the project for API communication. For questionnaire management, several key API routes are accessed using this client. For example, <code>GET /questionnaires/:id</code> fetches detailed data for editing a selected questionnaire. When creating or updating a questionnaire, the application uses <code>POST /questionnaires</code> and <code>PUT /questionnaires/:id</code>, respectively.

{| class="wikitable"
|+
! HTTP Method !! Endpoint !! Description
|-
| GET || /questionnaires || Fetches a list of all questionnaires
|-
| GET || /questionnaires/:id || Fetches a specific questionnaire by ID
|-
| POST || /questionnaires || Creates a new questionnaire
|-
| PUT || /questionnaires/:id || Updates an existing questionnaire
|-
| DELETE || /questionnaires/:id || Deletes a specific questionnaire
|-
| GET || /questions || Retrieves a list of all questions (items)
|-
| GET || /questions/:id || Retrieves a specific item, along with its rendered display
|-
| POST || /questions || Creates a new item for a questionnaire
|-
| PUT || /questions/:id || Updates an existing item
|}

==Implementation==

===QuestionnaireUtils.ts===
The <code>QuestionnaireUtils.ts</code> file serves as a utility module for handling questionnaire-related functionality in the application, including interfaces, data transformation methods, and back-end data retrieval. This file helps maintain clear separation of concerns, type safety, and adherence to design principles such as the Single Responsibility Principle (SRP).

===QuestionnaireForm.tsx===
The <code>QuestionnaireForm.tsx</code> file is a React component that provides a form interface for creating or editing questionnaires. It integrates with Formik for form state management and validation, utilizing React Bootstrap for UI elements.

The form fields are strongly typed using Formik's <code>Field</code> components and the <code>QuestionnaireFormValues</code> interface, ensuring that the data entered by the user adheres to the correct structure.
*Name: A text field for entering the questionnaire name.
*Type: A hidden input used to specify the type of the questionnaire selected from the Questionnaire Management Dashboard and to be passed to the back-end.
*Private: A checkbox to indicate whether the questionnaire is private.
*Minimum/Maximum Question Scores: Numeric fields for setting the minimum and maximum scores for questions.

The form delegates the responsibility of handling questionnaire items to the <code>QuestionnaireItemsFieldArray</code> component, which allows users to add or remove items dynamically and keeps each component focused on a single responsibility.

===QuestionnaireType.tsx===
This component renders a table that displays different types of questionnaires. Each row provides an action to navigate to the corresponding creation page for the selected questionnaire type. The <code>Table</code> component from <code>components/Table/Table</code> is used in adherence with the DRY Principle and the provided design guidelines.

==Files Modified==
The following files were created or modified to implement the questionnaire dashboard and rubric management UI in React with TypeScript:

*<code>src/pages/Questionnaire/questionnaire.tsx</code> – Implements the Questionnaire Management Dashboard UI.
*<code>src/pages/EditQuestionnaire/Questionnaire.tsx</code> – Implements the Create/Edit Rubric page with full form support.
*<code>src/App.tsx</code> – Updated routing to include new questionnaire pages.
*<code>src/assets/icons/</code> – Added new UI icons for editing, deleting, and copying questionnaires.
*<code>src/utils/axios_client.ts</code> – Preconfigured axios instance used throughout the frontend for API calls.
*<code>package.json</code> and <code>package-lock.json</code> – Updated dependencies for icons, React Bootstrap, and Formik support.

==Test Plan - Manual Testing Strategy==

====Questionnaire Dashboard Loading====
*Visit /questionnaire and confirm that all types of questionnaires are displayed.
*"+" button next to each type should open the rubric creation form for that type.

====Form Functionality====
*Enter name, min/max scores, toggle private/public checkbox.
*Dynamically add/remove criteria.
*Submit form to create a new rubric and confirm it reflects in the backend.

====Edit Rubric====
*Click on any existing rubric to load it in the edit form.
*Edit fields and submit changes. Confirm updated data is persisted.

====Form Validation====
*Leave required fields empty and confirm validation errors appear.
*Enter invalid values (e.g., max < min) and confirm appropriate messages.

====API Communication====
*Verified POST/PUT requests are correctly formatted.
*Backend updates reflected in UI after reload.

====UI Testing====
*Confirm responsiveness across desktop, tablet, and mobile.
*Check accessibility: keyboard navigation, proper labeling.

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, Questionnaire Management Dashboard]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, Create/Edit Rubric Page]
*[https://github.com/mmviola1/reimplementation-front-end-E2538 Project Repo]
=====Demo Video=====
*[, Demo Video]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T19:09:30Z

Akumarm:

==Project Requirement==
The goal of this project is to implement the Questionnaire Page in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

==Best Practices==
*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
===Questionnaire Management Dashboard===

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

===Create/Edit Rubric Page===

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Class UML Diagram==

==Implementation==
===Views===
===Model===
===Controller===

==Files Modified==

==Test Plan==
===Testing Views===
===Testing Model===
===Testing Controller===

==Test Coverage==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, 1]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, 2]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T19:06:04Z

Akumarm:

==Project Requirement==
The goal of this project is to implement the Questionnaire Page in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

==Best Practices==
*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
1) Questionnaire Management Dashboard

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

2) Create/Edit Rubric Page

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Class UML Diagram==

==Implementation==
===Views===
===Model===
===Controller===

==Files Modified==

==Test Plan==
===Testing Views===
===Testing Model===
===Testing Controller===

==Test Coverage==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, 1]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, 2]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:58:04Z

Akumarm: /* What Needs to be Done? */

==Introduction==

==Project Requirement==
The goal of this project is to implement the Questionnaire Page in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

==Best Practices==
*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
1) Questionnaire Management Dashboard

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

2) Create/Edit Rubric Page

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

[[File:Picx2x.png | 700px]]

==Class UML Diagram==

==Implementation==

==Files Modified==

==Test Plan==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, 1]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, 2]

File:Picx2x.png

2025-04-02T18:57:28Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:57:06Z

Akumarm: /* What Needs to be Done? */

==Introduction==

==Project Requirement==
The goal of this project is to implement the Questionnaire Page in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

==Best Practices==
*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
1) Questionnaire Management Dashboard (First Screenshot)

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

[[File:Picx1x.png | 700px]]

2) Create/Edit Rubric Page (Second Screenshot)

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

==Class UML Diagram==

==Implementation==

==Files Modified==

==Test Plan==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, 1]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, 2]

File:Picx1x.png

2025-04-02T18:55:50Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:54:58Z

Akumarm:

==Introduction==

==Project Requirement==
The goal of this project is to implement the Questionnaire Page in Expertiza by reimplementing its frontend using React with TypeScript, while integrating it with the existing Ruby on Rails backend APIs in the reimplementation backend repo. The new implementation will improve user experience, maintainability, and scalability while preserving core functionalities.

This project covers:

* Developing a React-based UI for managing questionnaire rubrics.

* Enabling navigation to a new page when clicking the "+" button to create a specific rubric for a questionnaire type.

* Ensuring seamless API integration with the reimplementation backend repo.

* Managing user sessions and authentication securely.

==Best Practices==
*Component Reusability (DRY Principle): Design reusable and modular components to avoid duplication and simplify maintenance, adhering to the "Don't Repeat Yourself" principle.

*Separation of Concerns: Keep the UI, state management, and business logic separated. Use container components for state and logic and presentational components for rendering.

*Responsive and Accessible Design: Ensure the UI adapts to different devices and meets accessibility standards (e.g., ARIA roles, keyboard navigation, and proper contrast).

*Type Safety with TypeScript: Use TypeScript interfaces and types to ensure data consistency, reduce runtime errors.

*Single Responsibility Principle: Each component or function should have a single, well-defined purpose to improve clarity, testability, and scalability.

==What Needs to be Done?==
1) Questionnaire Management Dashboard (First Screenshot)

Displays a list of questionnaire types (Review, Metareview, Author Feedback, etc.)
* Each questionnaire type has a "+" button, which, when clicked, navigates to a new page for creating a specific rubric for that questionnaire type.
* Data is fetched dynamically from the backend.

2) Create/Edit Rubric Page (Second Screenshot)

This page is displayed when a user clicks the "+" button from the dashboard.

Allows users to:
* Enter a name for the rubric.
* Define min/max item scores.
* Set the review visibility (private/public).
* Add criteria for evaluation.
* Submit the form to create a new rubric for the selected questionnaire type.

==Class UML Diagram==

==Implementation==

==Files Modified==

==Test Plan==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==
*[https://expertiza.ncsu.edu/tree_display/list?currCtlr=Questionnaires, 1]
*[https://expertiza.ncsu.edu/questionnaires/new?model=ReviewQuestionnaire&private=1, 2]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:48:25Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:45:00Z

Akumarm:

==Introduction==

==Project Requirement==

==Best Practices==

==Implementation==

==Files Modified==

==Test Plan==

==Team==
=====Mentor=====
*Prathyusha Kodali - pkodali

=====Members=====
*Ashwin Muniswamy - akumarm
*Michael Anderson - mwander5
*Martina Viola - mmviola

==Reference Links==

CSC/ECE 517 Spring 2025

2025-04-02T18:14:40Z

Akumarm:

* [[CSC/ECE 517 Spring 2025 - E2503. Refactor the Team hierarchy]]
* [[CSC/ECE 517 Spring 2025 - E2504. Mentor-meeting management]]
* [[CSC/ECE 517 Spring 2025 - E2505. Testing Answer Tagging]]
* [[CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service]]
* [[CSC/ECE 517 Spring 2025 - E2509. Reimplement feedback_response_map.rb]]
* [[CSC/ECE 517 Spring 2025 - E2519. Implement view for results of bidding]]
* [[CSC/ECE 517 Spring 2025 - E2522. Enhancing UI Consistency in Expertiza 1]]
* [[CSC/ECE 517 Spring 2025 - E2520. Reimplement heatgrid UI for reviews]]
* [[CSC/ECE 517 Spring 2025 - E2517. Reimplement internationalization (frontend + backend)]]
* [[CSC/ECE 517 Spring 2025 - E2523: Enhancing UI Consistency in Expertiza 2]]
* [[CSC/ECE 517 Spring 2025 - E2515: Reimplement student_teams_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2501: Refactor review_mapping_helper.rb]]
* [[CSC/ECE 517 Spring 2025 - E2502: Refactor review_mapping_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2512. Reimplement responses controller]]
* [[CSC/ECE 517 Spring 2025 - E2510. Reimplement grades_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2507. Reimplement back end for submission records]]
* [[CSC/ECE 517 Spring 2025 - E2514. Reimplement student_quizzes_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2518. Reimplement password resets (frontend + backend)]]
* [[CSC/ECE 517 Spring 2025 - E2516. Reimplement teams_users_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2511. Reimplement participants_controller.rb]]
* [[CSC/ECE 517 Spring 2025 - E2521. UI for View submissions/assign grades (except heatgrid)]]
* [[CSC/ECE 517 Spring 2025 - E2513. Reimplement sign_up_topic.rb as project_topic.rb]]
* [[CSC/ECE 517 Spring 2025 - E2506. Implement testing for new Bookmarks Controller]]
* [[CSC/ECE 517 Spring 2025 - E2527. Mentor-meeting management: assignments with topics]]
* [[CSC/ECE 517 Spring 2025 - E2532. Reimplement Missing ResponseMap Subclasses]]

== Final Projects ==
* [[CSC/ECE 517 Spring 2025 - E2539 Reimplement Student Task View (Frontend + Backend)]]
* [[CSC/ECE 517 Spring 2025 - E2521 UI for View submissions/assign grades (except heatgrid)]]
* [[CSC/ECE 517 Spring 2025 - E2530 Reimplement Grades Controller (Frontend + Backend)]]
* [[CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza]]

CSC/ECE 517 Spring 2025 - E2538 Reimplementing Questionnaire Page in Expertiza

2025-04-02T18:13:45Z

Akumarm: Created page with "==Project Overview== === ''Background'' === === ''Objectives'' ==="

==Project Overview==
=== ''Background'' ===

=== ''Objectives'' ===

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T03:11:21Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X9x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:X1x1.png|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:X2x.png|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:X3x.png|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:File4.png|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

[[File:X5x.png|700px]]

====== Private Methods ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:X6x.png|700px]]

[[File:X7x.png|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics. If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:X5x.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

 

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

 

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
* Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

File:X9x.png

2025-03-25T03:10:19Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:57:32Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X8x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:X1x1.png|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:X2x.png|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:X3x.png|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:File4.png|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

[[File:X5x.png|700px]]

====== Private Methods ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:X6x.png|700px]]

[[File:X7x.png|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:X8x.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:X5x.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

 

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

 

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
* Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:55:19Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:X8x.png|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:X1x1.png|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:X2x.png|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:X3x.png|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:File4.png|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

[[File:X5x.png|700px]]

====== Private Methods ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:X6x.png|700px]]

[[File:X7x.png|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:X8x.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:X5x.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

File:X8x.png

2025-03-25T02:53:29Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:32:45Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:X1x1.png|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:X2x.png|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:X3x.png|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:File4.png|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

[[File:X5x.png|700px]]

====== Private Methods ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:X6x.png|700px]]

[[File:X7x.png|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:X5x.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:X5x.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

File:X7x.png

2025-03-25T02:31:05Z

Akumarm:

File:X6x.png

2025-03-25T02:30:51Z

Akumarm:

File:X5x.png

2025-03-25T02:30:12Z

Akumarm:

File:X3x.png

2025-03-25T02:29:32Z

Akumarm:

File:X2x.png

2025-03-25T02:28:47Z

Akumarm:

File:X1x1.png

2025-03-25T02:26:06Z

Akumarm:

File:File7.png

2025-03-25T02:19:20Z

Akumarm: Akumarm uploaded a new version of File:File7.png

File:File6.png

2025-03-25T02:19:09Z

Akumarm: Akumarm uploaded a new version of File:File6.png

File:File5.png

2025-03-25T02:18:58Z

Akumarm: Akumarm uploaded a new version of File:File5.png

File:File4.png

2025-03-25T02:18:47Z

Akumarm:

File:3.png

2025-03-25T02:18:22Z

Akumarm: Akumarm uploaded a new version of File:3.png

IS-A and HAS-A Rules of Inheritance

File:File2.png

2025-03-25T02:18:11Z

Akumarm: Akumarm uploaded a new version of File:File2.png

File:File1.png

2025-03-25T02:17:50Z

Akumarm: Akumarm uploaded a new version of File:File1.png

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:15:24Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

====== Private Methods ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:Updated_action_allowed.JPG|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:15:00Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

====== Private Methods: fallback_algorithm ======

* sorted_topic_queue – Sorts topics based on the number of team members and returns them in descending order
* assign_topics – Iterates through reviewers and assigns topics from the sorted queue, ensuring balanced distribution
* find_available_topic – Selects an available topic for a reviewer while avoiding self-selected topics
* reviewer_team_id – Retrieves the team ID associated with a given reviewer
* find_reviewer_user_id – Fetches the user ID for a given reviewer
* fetch_self_topic – Gets the topic that the user has self-selected for an assignment
* fetch_team_id – Finds the team ID for a given user in an assignment
* fetch_team_bids – Retrieves all bid records associated with a specific team
* format_bid – Converts a bid record into a structured format with topic ID, priority, and a formatted timestamp

[[File:Updated_action_allowed.JPG|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:10:59Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The model includes 13 methods that manage the review bidding process. The public methods handle bidding data retrieval, review topic assignment, and fallback allocation. The private methods support these functions by fetching user and team data, sorting topics, and formatting bid details.

====== Method: bidding_data ======

Collects bidding data for an assignment, including topics, max allowed proposals, and individual reviewer bids.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_review_topics ======

Assigns reviewers to topics based on matched preferences and clears previous assignments.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: assign_topic_to_reviewer ======

Assigns a single topic to a reviewer by linking them to a team under that topic.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: reviewer_bidding_data ======

Retrieves bid details for a specific reviewer, including self-selected topics and bid priorities.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: fallback_algorithm ======

Assigns topics to reviewers using a fallback approach when the initial bidding fails.

[[File:Updated_action_allowed.JPG|700px]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T02:05:50Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Model'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method private: index ======

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:55:15Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
=====''Previous Implementations''=====
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=====''Relevant Links''=====
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:53:58Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

''Relevant Links''
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:53:20Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:51:40Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
[[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review#Objectives]], 
[[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review 1]], [[https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review 2]] 
''Bidding Interface Implementation Pull Request'': [[https://github.com/expertiza/expertiza/pull/778 3]]

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:50:43Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG|700px]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG|700px]]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG|700px]]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG|700px]]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG|700px]]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG|700px]]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG|700px]]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

[[File:code-climate.png|700px]]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
[[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review#Objectives]], 
[[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review 1]], [[https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review 2]] 
''Bidding Interface Implementation Pull Request'': [[https://github.com/expertiza/expertiza/pull/778 3]]

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': 
''Expertiza Server'': 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

File:Code-climate.png

2025-03-25T01:47:39Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-25T01:45:37Z

Akumarm:

==Project Overview==
=== ''Background'' ===
The previous implementation of the bidding service was hosted on peerlogic by a former student. The University no longer has access to this hosting service, and is requiring a new solution. It is also asked that the webservice accept a better and cleaner json format which is easier to interpret and read.

=== ''Objectives'' ===
# Reimplement trading cycles on a webservice
# Figure out a new hosting solution for the BiddingService web service. (VCL)
# Host the webservice on VCL
# Using tmux, figure out a way to keep the process running with a production wsgi service compatible with Flask.
# Create new tests for the repository
# Create a list of required packages that future maintainers can install easily
# Create a tests directory that users can test the functionality of the code with
# Modularize the code further, eliminate code smells.
# Refactor existing backend logic to account for the new json format
# Refactor existing backend code to send HTTP requests to the correct IP address
# Refactor existing frontend code to provide a list for users to select multiple topics on the frontend
# Allow users to prioritize their topic selection on the frontend
# Users should not be allowed to bid on their review topics on the frontend
# Display the results of the matched topics on the frontend

=== ''Previous Work'' ===
There have been three previous implementations: 
Fall 2019 [http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review here] 
Spring 2020 [https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2020 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review here] 
Fall 2024 [https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2024_-_E2508._Reimplement_bidding-algorithm_web_service here] 

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': https://github.com/expertiza/expertiza/pull/2931 
''Web Service Server'': 152.7.178.10:8080/match_topics 

=== ''Files Modified'' ===
This is a list of all the files added or changed in completing this project. 
 
''Changed'': 

*app/app.py - accomodated for changes in JsonParser
*app/json_parser.py - moved functions out due to SRP
*app/topics_matcher.py

 
''Added'': 
*app/tests/sample.json - Sample input for the tests.

*app/tests/test_assignment.py Test File to test forms of input - tests both a successful and unsuccessful input

*app/utils/popular_topics.py - Json Parser SRP violation - moved to own file
*app/utils/student_priorities.py - Json Parser SRP violation - moved to own file
*app/utils/topic_priorities.py - Json Parser SRP violation - moved to own file

*setup.py - required for wsgi
*wsgi.py - for hosting the server via gunicorn on VCL.
*.gitignore - to ignore anything that we may not want pushed (mostly for venv)
*requirements.txt - a list of requirements made easy for future maintainers

=== ''Webservice'' ===
===== ''app'' =====

The entry point to the Web service is the app.py file where we have the POST Method match_topics.
This receives the input in a json format from Expertiza. The input will contain a list of task ids, and then an Object of users, which each contain their student id and correlated bids that they made. Each bid contains a task id, a priority, and a timestamp. The input format was reworked to align to this style since it made more sense to have each student have a list of bids instead of the previous implementation which did not have this case.

 
[[File:App2508.png|700px]]

 

===== ''json parser'' =====
The json parser converts the json into a Dictionary. The previous implementation also had the parser create a preferences dictionary for the Student to store their topic preferences and one for Topics to store list of topics which have been selected by students and also the priority for the selection using the Timestamps. However, this was removed due to the Single Responsibility Principle. We felt the json parser was doing too much and should only be parsing the json!

[[File:init_parser.png|700px]]

 
The student priorities function in its own file, moved due to SRP.

[[File:student_prio.png|700px]]

 

The topic priorities function in its own file, moved due to SRP.

[[File:topic_priorities.png|700px]]

 

===== ''Test Input'' =====

Sample Test case: 
Case: There are a few very popular topics and the students who bid for them and bid early should receive it.
Popular Topics: 3969, 3971, 3972

{
{
"tid": [4427, 4428, 4429, 4430],
"users": {
"40763": {
"bids": [
{ "tid": 4430, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4428, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4427, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4429
},
"40764": {
"bids": [
{ "tid": 4429, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:16:34 EST -05:00" },
{ "tid": 4430, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:16:35 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:16:37 EST -05:00" }
],
"otid": 4427
},
"40765": {
"bids": [
{ "tid": 4427, "priority": 3, "timestamp": "Sun, 15 Nov 2020 17:17:15 EST -05:00" },
{ "tid": 4428, "priority": 1, "timestamp": "Sun, 15 Nov 2020 17:17:16 EST -05:00" },
{ "tid": 4429, "priority": 2, "timestamp": "Sun, 15 Nov 2020 17:17:17 EST -05:00" }
],
"otid": 4428
}
},
"max_accepted_proposals": 3
}

 

===== ''Output'' =====

Since there is competition for these topics, the algorithm recognizes this and makes sure to assign them only to the students who bid for it.
Other students who picked other topics or did not pick anything are assigned different topics.

{
"40763": [
4427,
4428,
4430
],
"40764": [
4428,
4430,
4429
],
"40765": [
4429,
4427,
4430
]
}

=== ''Controller'' ===

The controller includes 8 methods that handle the review bidding process. The public methods cover authorization, rendering views, saving user bids, and coordinating review assignment. The private methods support these functions by abstracting data gathering and algorithm coordination logic.

====== Method: action_allowed? ======

This method controls user access to controller actions. It allows 'Instructor', 'Teaching Assistant', 'Administrator', 'Super-Administrator', and 'Student' roles to access show, set_priority, and index. Other actions are restricted to non-student roles. It ensures proper permissions for accessing review bidding features.

[[File:Updated_action_allowed.JPG]]

====== Method: index ======

This method gathers information for the "Your Work" page, where users can view their assigned reviews. It checks user identity, retrieves associated reviews, and counts completed reviews. The view rendered is sign_up_sheet/review_bids_others_work.View: others_work.html.erb

[[File:Updated_controller_index.JPG]]

====== Method: show ======

This method renders the bidding page where users select topics they'd prefer to review. It fetches the assignment, available topics, and any existing bids. Already assigned or signed-up topics are excluded. The page also lists any assigned reviews.View: show.html.erb

[[File:Updated_controller_show.JPG]]

====== Method: set_priority ======

This method stores or updates a participant's topic preferences. It removes old bids not in the current selection and creates or updates the remaining bids with new priorities. This method is triggered when users submit their topic rankings on the bidding page.

[[File:Updated_controller_set_priority.JPG]]

====== Method: assign_bidding ======

This method coordinates the assignment of review topics. It gathers reviewer IDs and invokes the bidding algorithm using a service. It validates the output and uses ReviewBid.assign_review_topics to perform the actual assignment. Bidding is then disabled.

[[File:Assign_bidding.JPG]]

====== Method: fetch_reviewer_ids (Private) ======

This helper method retrieves all AssignmentParticipant IDs for a given assignment. These IDs represent the reviewers participating in the bidding process.

====== Method: process_bidding (Private) ======
This helper method delegates the logic for running the bidding algorithm to the service class ReviewBiddingAlgorithmService. It takes the assignment ID and list of reviewers as input and returns matched topic assignments.

====== Method: ensure_valid_topics (Private) ======
This method ensures that all reviewers have valid topic assignment entries, even if the algorithm returns nothing (e.g., due to web service failure). It initializes empty topic arrays for any missing reviewers.

[[File:Controller_private_methods.JPG]]

=== ''Service'' ===

The ReviewBiddingAlgorithmService is a service object responsible for handling communication between the application and the external web service that executes the review bidding algorithm. It prepares bidding data, sends it to the web service, processes the response, and provides a fallback mechanism in case of failure.

This service allows to encapsulate all logic required to interact with the external topic-matching web service. It separates the algorithm execution concerns from the controller, improving modularity, testability, and maintainability of the code.

====== Method: self.process_bidding ======

This is the primary entry point for the controller. It accepts the assignment_id and a list of reviewer_ids, then prepares the bidding data by calling ReviewBid.bidding_data(...). It passes the data to the web service by calling run_bidding_algorithm. If the web service is unavailable or fails, the method logs an error and falls back to an internal method: ReviewBid.fallback_algorithm. The result is returned as a hash mapping reviewer IDs to arrays of assigned topic IDs.

====== Method: self.run_bidding_algorithm ======

This method retrieves the review bidding web service URL from the app configuration (config/webservices.yml) and calls the internal send_bidding_request method to make the actual request.It logs the outgoing URL for debugging and delegates the response parsing.

====== Private Method: send_bidding_request ======

This private class method handles the HTTP POST request using RestClient. It sends the bidding data as JSON and expects a JSON response. If the request fails due to a connection error, server error, or timeout, the method logs the exception and returns false, allowing the caller to trigger a fallback.

[[File:Review_bidding_algorithm_service.JPG]]

=== Fallback Algorithm ===
===== ''Introduction'' =====

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

===== ''Solution'' =====
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

===== ''When is this Used?'' =====
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

===== ''How Does the Fallback Algorithm Work?'' =====
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

===== ''Implementation - Controller Code (Triggering the Fallback)'' =====
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

===== ''Implementation - Model Code (Fallback Algorithm)'' =====
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

===== ''RSpec Testing of Fallback Algorithm'' =====
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

==Test Plan==
This section outlines the test plan for this project including testing scenarios/edge cases, the manual testing plan, and the automatic/RSpec testing plan.

=== ''Testing Scenarios'' ===
This section outlines the various bidding scenarios that could occur. These scenarios should be tested in either '''Manual Testing''' or '''Automatic Testing'''.

==== Basic Bidding Scenario ====
*Reviewers bid on multiple projects at different times
** Bidding algorithm should give priority to reviewers that bid first and should assign based on reviewers ranking

==== Edge Cases ====
* All reviewers bid on the same project
** If different time stamps: bidding algorithm should give priority to reviewers that bid first
** If same time stamps: bidding algorithm should assign reviews randomly
* None of the reviews bid on any projects
** Bidding algorithm should assign reviews randomly
* Reviewer bids on their own project
** Bidding algorithm should not allow a reviewer to bid on their own project and should have validation to prevent assigning a reviewer their own project
* None of the reviewers bid on a specific project
** Bidding algorithm should still assign reviewers to this project

=== ''Manual Testing'' ===
Manual testing should be preformed on an Expertiza server and webserver platform 

==== Manual Testing Plan for Expertiza Server ====
* test that an instructor can allow review bidding for an assignment
* test that server routes correctly when review bidding is allowed
** test that task box links to bidding page before algorithm is run
** test that assignment->others work links to bidding page before algorithm is run
** test that task box links to review page with bidding information after algorithm is run
** test that assignment->others work links to review page with bidding information after algorithm is run
* test that the bidding UI is implemented as expected
* test that a participant can bid on projects to review
** test that a participant can move projects into the bidding column
** test that a participant can reorder projects in the bidding column
** test that a participant's bidding preferences save
** test that a participant can't bid for their own topic
* test that run algorithm button calls webserver with correct information and returns review assignments for each user

==== Directions for Manual Testing of Expertiza Server ====
1. Go to [http://152.7.99.70:8081/ testing server] 
2. Log in as username: '''instructor6''' password: '''password''' 
3. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''General''' tab make sure '''Has teams?''' and '''Has topics?''' are checked
:# In the '''Topics''' tab check '''Allow review to choose which topic to review?''' then click '''save'''
:# In the '''Topics''' tab select '''Bidding''' then click '''save'''
4. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# This UI is based on '''instructor6''' being a '''participant''' assigned to topic '''Topic4'''
::# The UI blocks user from bidding on their own project
::# Check that user can bid on topics and reorder bids
::# Check that users topic preferences save on page refresh
::# Impersonate other participants and repeat bidding UI tests ('''student7601''', '''student7602''', '''student7603''', '''student7604''', '''student7605''', '''student7606''', '''student7607''', '''student7608''', '''student7609'')
5. Go to '''Manage''' -> '''Assignments''' -> '''E2085 Manual Testing''' -> '''edit''' (pencil symbol)
:# In the '''Topics''' tab click '''Run Review Algorithm''' button
6. Go to '''Assignments'''
:# '''E2085 Manual Testing review''' task should be listed in the main assignments box
::# '''E2085 Manual Testing review''' should now link to the reviewing page
::# The number of required reviews should already be displayed
::# A '''Request Another Review''' button should be present unless reviews listed is equal to the number of reviews allowed
::# '''Begin''' a review and test '''save''' and '''submit'''

==== Manual Testing Demo Video for Expertiza Server ====
Video demonstration of manual testing: [https://www.screencast.com/t/0rSg1zDW here]

=== ''Automatic/PyTest Testing '' ===
Pytest tests are written for the webservice to test a well formed and a malformed request.

=== ''Automatic/RSpec Testing '' ===
RSpec tests will need to be refactored according to the changes that we make in the expertiza repository. 

==== RSpec Testing Plan ====
These RSpec tests will need to:
* test basic functionality of review bids controller
* test basic functionality of review bid model

==== Directions for RSpec Testing ====
:# on personal device using [https://github.com/ncsu-ngw/expertiza forked repo]
:# Run the following commands:

# review bids controller:
bundle exec rspec spec/controllers/review_bids_controller_spec.rb

# review bidding algorithm service:
bundle exec rspec spec/services/review_bidding_algorithm_service_spec.rb

# review bid model:
bundle exec rspec spec/models/review_bid_spec.rb

==== RSpec Testing Demo Video ====
Video demonstration of RSpec tests passing: [https://www.screencast.com/t/uSWZHSX8s here]
 

==Test Coverage==
Code Climate: [https://codeclimate.com/github/expertiza/expertiza/pull/2931 here]

==Team==

'''Mentor:''' Janice Uwujaren (juwujar) 

Ashwin Muniswamy (akumarm) 
Arturo Serdan (aaserdan) 
Nicholas Winsen (nwinsen) 

 

==Resources==
''Previous Implementations'':
[[https://wiki.expertiza.ncsu.edu/index.php?title=CSC/ECE_517_Fall_2020_-_E2085._Allow_reviewers_to_bid_on_what_to_review#Objectives]], 
[[http://wiki.expertiza.ncsu.edu/index.php/CSC/ECE_517_Fall_2019_-_E1986._Allow_reviewers_to_bid_on_what_to_review 1]], [[https://expertiza.csc.ncsu.edu/index.php/CSC/ECE_517_Spring_2020_-_E2021._Allow_reviewers_to_bid_on_what_to_review 2]] 
''Bidding Interface Implementation Pull Request'': [[https://github.com/expertiza/expertiza/pull/778 3]]

=== ''Relevant Links'' ===
''Github Repository for Expertiza'': https://github.com/ncsu-ngw/expertiza/tree/e2508-reimplement-bidding-algorithm-web-service 
''Github Repository for Web service'': https://github.com/ncsu-ngw/BiddingService 
''Pull Request'': 
''Expertiza Server'': 
''Web Service Server'': 152.7.178.10:8080/match_topics 
''Video Demo'': https://app.screencast.com/vaiJnWpHf0r07

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-24T22:30:13Z

Akumarm:

User:Akumarm

2025-03-24T22:29:12Z

Akumarm:

== Fallback Algorithm ==
=== ''Introduction'' ===

The Fallback Algorithm in Expertiza is designed to ensure automatic topic assignment when the primary Bidding Algorithm fails due to Web Service unavailability.

Normally, Expertiza allows reviewers to bid on topics, and the ''ReviewBiddingAlgorithmService'' processes these bids to assign topics. However, when this web service ''fails'' (due to API downtime, server issues, or unexpected errors), the system must switch to fallback and automatically assign topics to reviewers.

=== ''Solution'' ===
It is triggered when the web service is unavailable. It ensures fair topic assignment by:
* Prioritizing topics with the largest teams.
* Using a round-robin approach to distribute topics among reviewers.
* Ensuring reviewers do not get their own team’s topic.

=== ''When is this Used?'' ===
* The ReviewBiddingAlgorithmService fails due to an API issue.
* The web service times out or returns an error.
* Unexpected exceptions occur in the bidding process.

Instead of stopping the review process, the system automatically falls-back to an internal algorithm to distribute topics.

=== ''How Does the Fallback Algorithm Work?'' ===
The algorithm follows these **four main steps:
* Fetch available topics – Retrieves all topics for the given assignment.
* Sort topics by team size – Topics with more members are given priority.
* Create a topic queue – Topics are arranged in descending order of team size.
* Assign topics in a round-robin manner – Reviewers are assigned topics while avoiding their own team's topic.

This ensures ''fair and balanced'' distribution of topics.

=== ''Implementation - Controller Code (Triggering the Fallback)'' ===
If the primary bidding service fails, the system catches the error and calls the Fallback Algorithm.

[[File:Controller-code.png|700px]]

Key Takeaway: If ''ReviewBiddingAlgorithmService'' fails, the system automatically calls fallback_algorithm.

=== ''Implementation - Model Code (Fallback Algorithm)'' ===
This method ensures fair topic assignment when the bidding system fails.

[[File:Model-code.png|700px]]

Key Takeaway: This function ensures every reviewer receives a topic without requiring manual intervention.

=== ''RSpec Testing of Fallback Algorithm'' ===
To verify correctness, we use unit tests in ''review_bid_spec.rb''

The Fallback Algorithm ensures that ''topics are assigned fairly'' even when the primary bidding service fails. By prioritizing ''larger teams'', ''avoiding self-review'', and using a ''round-robin strategy'', the fallback mechanism keeps the review process smooth and automatic.

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-24T22:28:13Z

Akumarm:

CSC/ECE 517 Spring 2025 - E2508. Reimplement bidding-algorithm web service

2025-03-24T22:24:53Z

Akumarm: