Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T21:27:44Z

Mbenkar: /* teams_participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

Renamed method from name to username.

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

Renamed method from fullname to name.

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

Did not reimplement this method - use team’s topic getter instead.

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

Did not reimplement this method - moved to responsible team mailer class.

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

Did not reimplement this method - use can_review instead since able_to_review simply delegates to an existing database field provided by ActiveRecord.

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

Did not reimplement this method - moved to responsible team mailer class.

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>self.sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

Did not reimplement this method - use built-in Rails sorting instead.

===='''<code>self.export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

Replaced call to user.name with call to participant.name.

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

Replaced call to team.teams_users.empty? With team.teams_participants.empty?.

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

Did not reimplement this method - it was a stubbed method in TeamsUser.

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

Replaced the parameters ‘user_id’ and ‘team_id’ with ‘participant’, since participant objects contain team information.

===='''<code>self.first_by_team_id</code> Method'''====

'''Description'''

Returns the first TeamsUser record associated with the given team ID.

'''Changes Made'''

Replaced calls to TeamsUser.where() with TeamsParticipant.where().

===='''<code>self.team_empty?</code> Method'''====

'''Description'''

Returns whether the specified team has no members by checking for the absence of associated TeamsUser records.

'''Changes Made'''

Replaced calls to TeamsUser.where() with TeamsParticipant.where().

===='''<code>self.add_member_to_invited_team</code> Method'''====

'''Description'''

Adds an invited user to the invitee’s team for a given assignment if the invitee belongs to a matching team.

'''Changes Made'''

Replaced the parameters ‘invitee_user_id’, ‘invited_user_id’ and ‘assignment_id’ with ‘invitee_participant_id’ and ‘invited_participant_id’, since participant objects contain assignment information.

===='''<code>self.team_id</code> Method'''====

'''Description'''

Returns the team ID associated with the given user and assignment, if such a team exists.

'''Changes Made'''

Replaced the parameters ‘assignment_id’ and ‘user_id’ with ‘participant’, since participant objects contain assignment information.

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T21:04:51Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

Renamed method from name to username.

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

Renamed method from fullname to name.

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

Did not reimplement this method - use team’s topic getter instead.

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

Did not reimplement this method - moved to responsible team mailer class.

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

Did not reimplement this method - use can_review instead since able_to_review simply delegates to an existing database field provided by ActiveRecord.

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

Did not reimplement this method - moved to responsible team mailer class.

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>self.sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

Did not reimplement this method - use built-in Rails sorting instead.

===='''<code>self.export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

No functional changes were made; the method was reimplemented as is.

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

===='''<code>self.first_by_team_id</code> Method'''====

'''Description'''

Returns the first TeamsUser record associated with the given team ID.

'''Changes Made'''

===='''<code>self.team_empty?</code> Method'''====

'''Description'''

Returns whether the specified team has no members by checking for the absence of associated TeamsUser records.

'''Changes Made'''

===='''<code>self.add_member_to_invited_team</code> Method'''====

'''Description'''

Adds an invited user to the invitee’s team for a given assignment if the invitee belongs to a matching team.

'''Changes Made'''

===='''<code>self.team_id</code> Method'''====

'''Description'''

Returns the team ID associated with the given user and assignment, if such a team exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:59:05Z

Mbenkar: /* teams_participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>self.sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>self.export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

===='''<code>self.first_by_team_id</code> Method'''====

'''Description'''

Returns the first TeamsUser record associated with the given team ID.

'''Changes Made'''

===='''<code>self.team_empty?</code> Method'''====

'''Description'''

Returns whether the specified team has no members by checking for the absence of associated TeamsUser records.

'''Changes Made'''

===='''<code>self.add_member_to_invited_team</code> Method'''====

'''Description'''

Adds an invited user to the invitee’s team for a given assignment if the invitee belongs to a matching team.

'''Changes Made'''

===='''<code>self.team_id</code> Method'''====

'''Description'''

Returns the team ID associated with the given user and assignment, if such a team exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:53:11Z

Mbenkar: /* sort_by_name Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>self.sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>self.export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:53:00Z

Mbenkar: /* export Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>self.export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:52:46Z

Mbenkar: /* export_fields Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>self.export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:51:27Z

Mbenkar: /* teams_participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

===='''<code>name</code> Method'''====

'''Description'''

Returns the user's name, appending "(Mentor)" if the user is recognized as a mentor in the system.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Removes the corresponding TeamUserNode and delete the team if this was the last user associated with it.

'''Changes Made'''

===='''<code>get_team_members</code> Method'''====

'''Description'''

(No implementation present) – Placeholder for a method intended to retrieve members of a specific team.

'''Changes Made'''

===='''<code>self.remove_team</code> Method'''====

'''Description'''

Removes the TeamsUser entry that links the specified user and team, if it exists.

'''Changes Made'''

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:45:52Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:44:34Z

Mbenkar: /* name Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Returns the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:50Z

Mbenkar: /* fullname Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Returns the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:38Z

Mbenkar: /* handle Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Returns the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:31Z

Mbenkar: /* delete Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Deletes the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:26Z

Mbenkar: /* force_delete Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroys all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:18Z

Mbenkar: /* mail_assigned_reviewers Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Sends email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:13Z

Mbenkar: /* topic_name Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Returns the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:09Z

Mbenkar: /* able_to_review Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Returns whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:43:04Z

Mbenkar: /* email Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Sends a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:42:59Z

Mbenkar: /* authorization Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determines the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:42:55Z

Mbenkar: /* sort_by_name Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sorts a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:42:49Z

Mbenkar: /* export Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Exports participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:42:44Z

Mbenkar: /* export_fields Method */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Returns a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:41:01Z

Mbenkar: /* team_participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===teams_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:37:29Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===team_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:33:04Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

===='''<code>name</code> Method'''====

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

===='''<code>fullname</code> Method'''====

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

===='''<code>handle</code> Method'''====

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

===='''<code>delete</code> Method'''====

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

===='''<code>force_delete</code> Method'''====

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

===='''<code>topic_name</code> Method'''====

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

===='''<code>mail_assigned_reviewers</code> Method'''====

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

===='''<code>able_to_review</code> Method'''====

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

===='''<code>email</code> Method'''====

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

===='''<code>authorization</code> Method'''====

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

===='''<code>sort_by_name</code> Method'''====

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

===='''<code>export</code> Method'''====

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

===='''<code>export_fields</code> Method'''====

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===team_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:31:00Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

===='''<code>team</code> Method'''====

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

===='''<code>responses</code> Method'''====
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

'''<code>name</code> Method'''

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

'''<code>fullname</code> Method'''

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

'''<code>handle</code> Method'''

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

'''<code>delete</code> Method'''

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

'''<code>force_delete</code> Method'''

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

'''<code>topic_name</code> Method'''

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

'''<code>mail_assigned_reviewers</code> Method'''

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

'''<code>able_to_review</code> Method'''

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

'''<code>email</code> Method'''

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

'''<code>authorization</code> Method'''

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

'''<code>sort_by_name</code> Method'''

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

'''<code>export</code> Method'''

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

'''<code>export_fields</code> Method'''

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===team_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:30:38Z

Mbenkar: /* team Method */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:29:42Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

==='''<code>team</code> Method'''===

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

'''<code>responses</code> Method'''
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

'''<code>name</code> Method'''

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

'''<code>fullname</code> Method'''

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

'''<code>handle</code> Method'''

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

'''<code>delete</code> Method'''

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

'''<code>force_delete</code> Method'''

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

'''<code>topic_name</code> Method'''

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

'''<code>mail_assigned_reviewers</code> Method'''

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

'''<code>able_to_review</code> Method'''

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

'''<code>email</code> Method'''

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

'''<code>authorization</code> Method'''

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

'''<code>sort_by_name</code> Method'''

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

'''<code>export</code> Method'''

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

'''<code>export_fields</code> Method'''

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===team_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:28:31Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:23:43Z

Mbenkar: /* participant.rb Reimplementation */

==Introduction==
This project reimplements the Team and Participant hierarchies within the new Expertiza system. It introduces cleaner, modular structures for Participant, AssignmentParticipant, CourseParticipant, and a new TeamsParticipant class (replacing TeamsUser). The redesign also addresses legacy code smells and shifts logic to follow SOLID principles, improving maintainability, testability, and extensibility.

==Requirements==
* '''Reimplement Participant-related Classes:''' Fully reimplement the Participant, AssignmentParticipant, and CourseParticipant classes using clean object-oriented design, ensuring each class has a well-defined responsibility and follows SOLID principles.
* '''Introduce TeamsParticipant:''' Replace the existing TeamsUser class with a new TeamsParticipant class that clearly defines the relationship between teams and participants while preserving necessary fields.
* '''Refactor the Team Hierarchy:''' Integrate the Team hierarchy refactoring from OSS Project 3, improving upon it by addressing feedback provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.
* '''Address Code Smells and Design Flaws:''' Eliminate all SRP violations and code smells from the original Participant, AssignmentParticipant, and CourseParticipant implementations.
* '''Write Comprehensive Tests:''' Implement thorough RSpec tests for all model behaviors, including edge cases.

==Existing Issues==
1. '''Participant Hierarchy Violations'''

The current implementations of <code> [https://github.com/expertiza/expertiza/blob/main/app/models/participant.rb participant.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_participant.rb assignment_participant.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_participant.rb course_participant.rb] </code> contain multiple issues that must be addressed:
* Refactor code to fully comply with the Single Responsibility Principle (SRP).
* Eliminate code smells such as misplaced methods.
* Write sufficient RSpec tests to verify correct behavior under various conditions.
* Enhance inline documentation and comments to clearly explain:
** The purpose of each method.
** Justification for retaining or removing existing logic.
** Any key design decisions made during the implementation.

2. '''TeamsParticipant Replacement'''

The current <code> [https://github.com/expertiza/expertiza/blob/main/app/models/teams_user.rb teams_user.rb] </code> class lacks proper structure and clarity in its associations. It will be replaced with a new TeamsParticipant class that:
* Preserves the existing behavior and relationships.
* Cleans up design inconsistencies.
* Introduces better encapsulation and naming for maintainability.

3. '''Team Hierarchy Refactor'''

The existing <code> [https://github.com/expertiza/expertiza/blob/main/app/models/team.rb team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/assignment_team.rb assignment_team.rb] </code>, <code> [https://github.com/expertiza/expertiza/blob/main/app/models/course_team.rb course_team.rb] </code>, and <code> [https://github.com/expertiza/expertiza/blob/main/app/models/mentored_team.rb mentored_team.rb] </code> classes require rework to align with the updated architecture:
* Reimplement these classes using the clean design introduced in OSS Project 3.
* Address key feedback from <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>, such as:
** Rename methods like user? to more expressive terms like has_as_member? to improve clarity.
** Remove or clearly justify any commented-out legacy code.
** Refactor create_new_team() to better reflect intent (e.g., assign_team_to_topic) and clean up legacy logic based on outdated user-team assumptions.

==Design / Proposed Solution==
===team.rb Reimplementation===
In the new team.rb implementation, we renamed is_member? to has_as_member?. The original method name implied that the team was a member of the user, rather than the other way around. Additionally, we moved the add_participant() method from AssignmentTeam to Team to apply the Factory Method Pattern. This change allows both CourseTeam and AssignmentTeam to reuse the same logic for participant creation while deferring type-specific behavior (like selecting the correct Participant subclass) to the factory method. All of this was done based on the feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised Team class and its role:
====<code>has_as_member?</code> Method ====
''' Description '''

This method checks whether a given user is a member of the team.

''' Changes Made '''

Renamed from is_member? to has_as_member? for clarity.

====<code>add_participant</code> Method ====
''' Description '''

Adds a Participant to the team, given a user object. It first checks if a corresponding participant already exists, and if not, creates a new one using the appropriate subclass, either AssignmentParticipant or CourseParticipant.

''' Changes Made '''

Moved from AssignmentTeam to the parent Team class to promote reuse and apply the Factory Method Pattern.

===assignment_team.rb Reimplementation===

===course_team.rb Reimplementation===

===mentored_team.rb Reimplementation===
In the new mentored_team.rb implementation, we decided to remove the MentorManagement class and integrate its functionality directly into MentoredTeam and change add_member() to take participant instead of user and assignment id. This decision was made not only to improve cohesion and eliminate unnecessary indirection, but also to address structural feedback from the instructor provided in <code> [https://github.com/expertiza/expertiza/pull/2941 Pull Request #2941] </code>.

Below is a breakdown of each method that was changed/added in the revised MentoredTeam class and its role:
====<code>add_member</code> Method ====
''' Description '''

Adds a participant to the team using the superclass implementation and then automatically assigns a mentor to the team if the conditions are met (such as minimum team size and absence of an existing mentor).

''' Changes Made '''

Changed from add_member(user, assignment_id = nil) to add_member(participant), since the participant contains all this information.

====<code>import_team_members</code> Method ====
''' Description '''

Takes a hash of team member names and iterates through them. For each valid name, it looks up the corresponding user, ensures they are not already on the team, finds their AssignmentParticipant, and adds them to the team via add_member. It also triggers mentor assignment as part of this process.

''' Changes Made '''

Changed the call inside it for add_member(user, assignment_id = nil) to add_member(participant).

====<code>assign_mentor</code> Method ====
''' Description '''

A private method that encapsulates the full logic of mentor assignment. It checks several conditions (e.g., whether mentoring is enabled, team has a topic, mentor already exists, etc.). If all conditions are satisfied, it selects an available mentor using the select_mentor method and adds them to the team, followed by notification emails.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>select_mentor</code> Method ====
''' Description '''

A private method that implements the algorithm for choosing the most suitable mentor. It selects among participants marked as mentors for the given assignment and returns the one who is currently mentoring the fewest teams. Ties are automatically broken by Hash#sort_by. This ensures a balanced distribution of mentor assignments.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>zip_mentors_with_team_count</code> Method ====
''' Description '''

A private method that generates a mapping of mentor user_ids to the number of teams each is currently mentoring, used by the select_mentor method. It performs a grouped count on the TeamsUser table and returns a sorted list of mentors by workload.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>mentors_for_assignment</code> Method ====
''' Description '''

A private method that returns all Participant records for a given assignment where the participant has can_mentor: true. This filters potential mentor candidates from the larger participant pool and serves as the base query for mentor selection logic.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_team_of_mentor_assignment</code> Method ====
''' Description '''

A private method that sends an email notification to all members of a team informing them that a mentor has been assigned. The message includes the mentor’s name and email, the assignment name, and a list of team members.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

====<code>notify_mentor_of_assignment</code> Method ====
''' Description '''

A private method that sends an email to the newly assigned mentor notifying them of their assignment. The email includes the assignment name and a full list of current team members to help the mentor familiarize themselves with the team.

''' Changes Made '''

No functional changes were made; the method was simply moved from MentorManagement to MentoredTeam.

===participant.rb Reimplementation===
In the new implementation of the Participant model, we refactored several methods to improve clarity, maintainability, and alignment with the Single Responsibility Principle (SRP). The topic_name method was removed, as topics are associated with teams rather than participants, making its presence in Participant a design inconsistency. We also relocated the mail_assigned_reviewers method to a dedicated mailer class, where notification logic more appropriately belongs. The authorization method was renamed for clarity, and sort_by_name was eliminated due to its overly narrow use case and lack of general applicability. These changes help decouple responsibilities and make the class easier to test and extend.

Below is a breakdown of each method that was changed/added in the revised Participant class and its role:

'''<code>team</code> Method'''

'''Description'''

Retrieves the team associated with the current user by finding their `TeamsUser` record and returning the linked team, if it exists.

'''Changes Made'''

'''<code>responses</code> Method'''
'''Description'''

Returns a list of responses by mapping each response map associated with the participant to its corresponding response.

'''Changes Made'''

'''<code>name</code> Method'''

'''Description'''

Return the participant’s name by delegating the call to the associated user’s `name` method, optionally passing an IP address.

'''Changes Made'''

'''<code>fullname</code> Method'''

'''Description'''

Return the participant’s full name by delegating the call to the associated user’s fullname method, optionally passing an IP address.

'''Changes Made'''

'''<code>handle</code> Method'''

'''Description'''

Return the participant’s handle unless anonymized view is enabled, in which case return a generic placeholder.

'''Changes Made'''

'''<code>delete</code> Method'''

'''Description'''

Delete the participant if no associated response maps or team exist, or if forced; otherwise, raise an exception.

'''Changes Made'''

'''<code>force_delete</code> Method'''

'''Description'''

Destroy all associated response maps and remove the team if this is the last participant; then delete the participant itself.

'''Changes Made'''

'''<code>topic_name</code> Method'''

'''Description'''

Return the participant’s topic name if available, or a centered em dash placeholder if not.

'''Changes Made'''

'''<code>mail_assigned_reviewers</code> Method'''

'''Description'''

Send email notifications to all reviewers assigned to the participant’s team for a given assignment.

'''Changes Made'''

'''<code>able_to_review</code> Method'''

'''Description'''

Return whether the participant is able to review, delegating to can_review.

'''Changes Made'''

'''<code>email</code> Method'''

'''Description'''

Send a registration email to the participant with assignment details, name, and login credentials.

'''Changes Made'''

'''<code>authorization</code> Method'''

'''Description'''

Determine the participant’s authorization level (e.g., mentor, reviewer, submitter) based on permission flags.

'''Changes Made'''

'''<code>sort_by_name</code> Method'''

'''Description'''

Sort a list of participants by their associated user’s name in a case-insensitive manner.

'''Changes Made'''

'''<code>export</code> Method'''

'''Description'''

Export participant data to a CSV file based on the selected options for personal details, role, parent, email settings, and handle.

'''Changes Made'''

'''<code>export_fields</code> Method'''

'''Description'''

Return a list of CSV header fields to include in the export, based on the provided options.

'''Changes Made'''

===assignment_participant.rb Reimplementation===

===course_participant.rb Reimplementation===

===team_participant.rb Reimplementation===
We also reimplemented TeamsUser as TeamsParticipant, in alignment with the updated domain terminology and to better reflect the association between users and teams within a given context. While the new TeamsParticipant model includes a user_id field for compatibility, it is no longer central to the functionality. This shift allows the new system to more clearly represent the team-participant relationship and lays the groundwork for better encapsulation and extensibility in future enhancements.

Below is a breakdown of each method in TeamsUser that was reimplemented in the new TeamsParticipant class and its role:

==SOLID Principle(s)==
'''Single Responsibility Principle:''' "A class should only have one responsibility and should never have more than one reason to change."

There are many violations of the Single Responsibility Principle (SRP) across all Participant classes. For example, AssignmentParticipant contains methods like reviews() and get_reviewer(), which should be the responsibility of the Team class. Similarly, Participant includes mail_assigned_reviewers() and email(), which should belong to the Mailer class.

==Test Plan==
We will write tests to ensure that all model validations function correctly for each class, including Participant, AssignmentParticipant, CourseParticipant, TeamsParticipant, and all team-related models. We will verify that belongs_to, has_many, and other associations are correctly configured and that no orphaned or dangling records remain after creation or deletion. Special attention will be given to business logic, particularly methods reused or inherited across subclasses. Additionally, we will test edge conditions like minimum team size thresholds, permission flags (e.g., can_mentor), and mentor-selection criteria to ensure the intended behavior is preserved.

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

==Links==
* Link to reimplementation-back-end Expertiza Repository: https://github.com/expertiza/reimplementation-back-end
* Link to Forked Repository: https://github.com/AhmedOHassan/reimplementation-back-end
* Link to Pull Request:
* Link to Video Walkthrough:

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:05:57Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:03:29Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:03:02Z

Mbenkar: /* team_participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:02:10Z

Mbenkar: /* team_participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:01:57Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T19:01:09Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T18:47:36Z

Mbenkar: /* team_participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2526 Reimplement Teams and Participant hierarchies

2025-04-06T18:47:15Z

Mbenkar: /* participant.rb Reimplementation */

CSC/ECE 517 Spring 2025 - E2503. Refactor the Team hierarchy

2025-03-26T18:16:44Z

Mbenkar: added more details in MentoredTeam method list and problem/solution sections

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

'''Relevant Links:'''
* Link to Expertiza Repository: https://github.com/expertiza/expertiza
* Link to Forked Repository: https://github.com/AhmedOHassan/expertiza
* Link to Pull Request: https://github.com/expertiza/expertiza/pull/2941

= Expertiza Background =
Expertiza is an open-source project built using the Ruby on Rails MVC framework, designed to facilitate peer review and collaborative learning. The project has undergone multiple iterations, with ongoing efforts focused on refactoring the existing codebase to improve maintainability, efficiency, and scalability. Additionally, there are initiatives aimed at reimplementing a new version of Expertiza to enhance its architecture and functionality.

= About Team/CourseTeam/AssignmentTeam/MentoredTeam =
The Team hierarchy contains the classes that hold teams of students enrolled in Expertiza. Teams can reserve topics and submit work. There are currently four classes in the team hierarchy: Team, CourseTeam, AssignmentTeam, and MentoredTeam. Instances of the Team superclass should never be created since any actual team will be a member of one of the three other classes. CourseTeams stay together for the entire course duration and work on all assignments together. Although some instructors choose not to use CourseTeams, others employ Team-Based Learning and do benefit from using CourseTeams. It is possible to both copy CourseTeams into AssignmentTeams, and vice-versa. Any team formed to take part in an assignment will be an AssignmentTeam, unless the assignment is set up to automatically assign mentors to teams. In this case, the assignment teams will be created as MentoredTeams (a subclass of AssignmentTeam) which has a designated member known as the mentor.

= Problem Statement =
The Team hierarchy in Expertiza is responsible for managing student teams, allowing them to reserve topics, submit work, and, in some cases, review other teams' submissions. However, the current implementation is overly complex, with redundant methods and unnecessary dependencies. The Team class has 27 methods, many of which should be refactored or removed, while AssignmentTeam contains 36 methods, several of which duplicate functionality from the superclass. Additionally, the system currently models team members as Users, but the new design will transition to Participants, requiring updates to team membership logic.

= Tasks =
'''Refactoring the Team Hierarchy'''
* Prevent direct instantiation of Team, ensuring all actual teams belong to CourseTeam, AssignmentTeam, or MentoredTeam.
* Move only the core shared functionalities to the Team and reduce the method count.
* Eliminate Redundant Methods in AssignmentTeam and CourseTeam.
* Identify duplicate methods across Team, AssignmentTeam, and CourseTeam.
* Ensure CourseTeam and AssignmentTeam override import/export functionality from Team instead of defining separate versions.

'''Transition from Users to Participants '''
* Modify add_member and related methods to work with CourseParticipants and AssignmentParticipants instead of Users.
* Ensure teams enforce correct membership rules (e.g., CourseTeam only accepts CourseParticipants).

'''Optimizing Team Copying'''
* Ensure clear and efficient handling of copying between AssignmentTeam and CourseTeam.
* Consolidate logic for copying members across different team types.

'''Improving Method Clarity and Encapsulation'''
* Convert class methods like size into instance methods.
* Standardize method naming conventions for clarity (e.g., avoid inconsistencies like copy_members vs. copy_content).

'''Removing Unused and Inefficient Code'''
* Identify and remove any unused methods in Team, AssignmentTeam, and CourseTeam.
* Remove commented-out or deprecated code that no longer serves a purpose.
* Simplify methods that are overly complex by leveraging helper functions where necessary.

'''Testing and Code Validation'''
* Update tests to reflect the refactored team hierarchy and ensure correctness.
* Remove or rewrite tests that validate methods no longer in use.

= Plan of Work =
We began by listing all of the methods belonging to each class in the Team hierarchy. Next, we met with our mentor (Dr. Gehringer) and reviewed every single method’s readability, maintainability, and adherence to best practices (SOLID principles, DRY, etc.). Once we organized the methods by class, we assigned groups of methods as tasks amongst team members and began refactoring existing methods while making sure existing test cases still passed and new tests were added as needed.

= Implementation =
'''Refactor Team Model'''
* Methods involved:
** self.allowed_types
** self.team_operation
** self.responses
** author_names
** user?(user)
** add_member(user, _assignment_id = nil)
** self.size(team_id)
** copy_members(new_team)
** self.check_for_existing(parent, name, team_type)
** self.randomize_all_by_parent(parent, team_type, min_team_size)
** self.create_team_from_single_users(min_team_size, parent, team_type, users)
** self.assign_single_users_to_teams(min_team_size, parent, teams, users)
** self.generate_team_name(_team_name_prefix = “”)
** self.create_team_and_node(id)
** self.create_team_with_users(parent_id, user_ids)
** self.remove_user_from_previous_team(parent_id, user_id)
** self.find_team_users(assignment_id, user_id)

* Problems/Solutions:
** The refactoring efforts addressed several key issues in Expertiza's codebase, including redundancy, unclear naming, and inefficient implementations.
** Unnecessary methods and parameters were removed or consolidated, improving code clarity and maintainability.
** Naming conventions were refined to better reflect functionality, and certain methods were moved to more appropriate classes, such as CourseTeam and AssignmentTeam.
** The use of ActiveRecord's dependent destroy was implemented to ensure proper cleanup of associated records.
** Additionally, alternative implementations were suggested to simplify logic, such as replacing redundant methods with built-in Rails queries and using uniqueness validation instead of manual checks.
** Improvements were proposed for import/export methods.

* Changes:
** Moved parent_entity_type and self.find_parent_entity(id) from CourseTeam to Team.
[[File:2503-0.png]]
** Renamed author_names to member_names.
[[File:2503-1.png]]
** Removed unnecessary parameter from add_member; replaced size with instance method; CourseTeam’s add_participant method was removed, and CourseTeam inherits Team.add_member instead.
[[File:2503-2.png]]
** Renamed randomize_all_by_parent to create_random_teams.
[[File:2503-3.png]]
** Renamed create_team_from_single_users to team_from_users.
[[File:2503-4.png]]
** No changes to self.handle_duplicate.
[[File:2503-5.png]]
** Added optional user_ids parameter to facilitate removal of create_team_with_users method to avoid redundancy.
[[File:2503-6.png]]

'''Refactor CourseTeam Model'''
* Methods involved:
** parent_model
** self.parent_model(id)
** assignment_id
** self.prototype
** copy(assignment_id)
** add_participant(course_id, user)
** self.import(row, course_id, options)
** self.export(csv, parent_id, options)
** self.export_fields(options)
** add_member(user, _id, = nil)

* Problems/Solutions:
** parent_model: Replaced with parent_entity_type() and find_parent_entity(id) in the Team class for clarity, since it duplicated functionality.
** self.parent_model(id) - Logic was moved to Team.find_parent_entity(id) to consolidate redundant behavior.
** assignment_id - No changes made; it correctly returns nil to indicate it's not an AssignmentTeam.
** self.prototype - Removed because it's unnecessary—creating a new instance with CourseTeam.new is sufficient.
** copy(assignment_id) - Refactored and renamed to copy_to_assignment() for clarity.
** add_participant(course_id, user) - Removed, as this responsibility already exists in the Course class.
** self.import(row, course_id, options) - Left unchanged since it appropriately overrides Team.import().
** self.export(csv, parent_id, options) - Left unchanged as it overrides Team.export() correctly.
** self.export_fields(options) - Left unchanged because it’s used in export_file_controller.rb for file exports.
** add_member(user, _id = nil) - Removed due to duplication; the Team class already implements add_member().

* Changes:
** Refactored the code and now the method called copy_to_assignment()
[[File:2503-7.png]]

'''Refactor AssignmentTeam Model'''
* Changes:
** assign_reviewer left as is [no change]
** get_reviewer() was renamed to reviewer()
** reviewed_by left() as is [no change]
** topic() renamed to topic_id()
[[File:2503-8.png]]
** files() refactored to use an iterator-based approach
[[File:2503-9.png]]
** For set.export_fields(), enabled fields to be an explicit return value to improve readability
** self.remove_team_by_id left as is, very concise; “unless nil” check ensures safety
** path() was refactored to avoid string concatenation
** set_team_directory_num() was refactored method name to match behavior
[[File:2503-10.png]]
** Refactored method name to match behavior
[[File:2503-11.png]]

'''Refactor MentoredTeam Model'''
* Methods involved:
** add_member(user, assignment_id = nil)
** import_team_members(row_hash)

* Problems/Solutions:
** Refactored add_member since most the functionality is already in Team.add_member(), and it just needs to overwrite it to add the assigning a mentor functionality to MentoredTeam
** import_team_members isn't changed since it calls add_member(user, parent_id) which is not similar to what is in the Team.import_team_members()

* Changes:
** Refactored add_member to override Team.add_member to handle assigning a mentor
[[File:2503-12.png]]
= Test Plan =
This project involves refactoring the Team hierarchy, ensuring that existing functionality remains unchanged while improving structure and maintainability. Since the refactor involves modifying class structures, consolidating redundant methods, and introducing better encapsulation, the following steps were taken to validate correctness:
* Refactored RSpec test files to reflect changes in class structure, method names, and logic updates.
* Ran the test suite after each major change to verify that functionality remained consistent across Team, CourseTeam, AssignmentTeam, and MentoredTeam.
* Ensured that core team operations (adding/removing members, copying teams, importing/exporting teams) worked as expected by validating test outputs against pre-refactor results.
* Ensured all refactored classes maintained high test coverage, targeting at least 90% coverage in Team, AssignmentTeam, and CourseTeam.
* Ensured that removed methods were either unnecessary or replaced with equivalent logic in the refactored structure.
* Validated UI functionality by testing that teams were correctly displayed, managed, and interacted with in the system.
[[File:I1.png]]

CSC/ECE 517 Spring 2025 - E2503. Refactor the Team hierarchy

2025-03-26T18:12:28Z

Mbenkar: added problem/solution list for CourseTeam

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

'''Relevant Links:'''
* Link to Expertiza Repository: https://github.com/expertiza/expertiza
* Link to Forked Repository: https://github.com/AhmedOHassan/expertiza
* Link to Pull Request: https://github.com/expertiza/expertiza/pull/2941

= Expertiza Background =
Expertiza is an open-source project built using the Ruby on Rails MVC framework, designed to facilitate peer review and collaborative learning. The project has undergone multiple iterations, with ongoing efforts focused on refactoring the existing codebase to improve maintainability, efficiency, and scalability. Additionally, there are initiatives aimed at reimplementing a new version of Expertiza to enhance its architecture and functionality.

= About Team/CourseTeam/AssignmentTeam/MentoredTeam =
The Team hierarchy contains the classes that hold teams of students enrolled in Expertiza. Teams can reserve topics and submit work. There are currently four classes in the team hierarchy: Team, CourseTeam, AssignmentTeam, and MentoredTeam. Instances of the Team superclass should never be created since any actual team will be a member of one of the three other classes. CourseTeams stay together for the entire course duration and work on all assignments together. Although some instructors choose not to use CourseTeams, others employ Team-Based Learning and do benefit from using CourseTeams. It is possible to both copy CourseTeams into AssignmentTeams, and vice-versa. Any team formed to take part in an assignment will be an AssignmentTeam, unless the assignment is set up to automatically assign mentors to teams. In this case, the assignment teams will be created as MentoredTeams (a subclass of AssignmentTeam) which has a designated member known as the mentor.

= Problem Statement =
The Team hierarchy in Expertiza is responsible for managing student teams, allowing them to reserve topics, submit work, and, in some cases, review other teams' submissions. However, the current implementation is overly complex, with redundant methods and unnecessary dependencies. The Team class has 27 methods, many of which should be refactored or removed, while AssignmentTeam contains 36 methods, several of which duplicate functionality from the superclass. Additionally, the system currently models team members as Users, but the new design will transition to Participants, requiring updates to team membership logic.

= Tasks =
'''Refactoring the Team Hierarchy'''
* Prevent direct instantiation of Team, ensuring all actual teams belong to CourseTeam, AssignmentTeam, or MentoredTeam.
* Move only the core shared functionalities to the Team and reduce the method count.
* Eliminate Redundant Methods in AssignmentTeam and CourseTeam.
* Identify duplicate methods across Team, AssignmentTeam, and CourseTeam.
* Ensure CourseTeam and AssignmentTeam override import/export functionality from Team instead of defining separate versions.

'''Transition from Users to Participants '''
* Modify add_member and related methods to work with CourseParticipants and AssignmentParticipants instead of Users.
* Ensure teams enforce correct membership rules (e.g., CourseTeam only accepts CourseParticipants).

'''Optimizing Team Copying'''
* Ensure clear and efficient handling of copying between AssignmentTeam and CourseTeam.
* Consolidate logic for copying members across different team types.

'''Improving Method Clarity and Encapsulation'''
* Convert class methods like size into instance methods.
* Standardize method naming conventions for clarity (e.g., avoid inconsistencies like copy_members vs. copy_content).

'''Removing Unused and Inefficient Code'''
* Identify and remove any unused methods in Team, AssignmentTeam, and CourseTeam.
* Remove commented-out or deprecated code that no longer serves a purpose.
* Simplify methods that are overly complex by leveraging helper functions where necessary.

'''Testing and Code Validation'''
* Update tests to reflect the refactored team hierarchy and ensure correctness.
* Remove or rewrite tests that validate methods no longer in use.

= Plan of Work =
We began by listing all of the methods belonging to each class in the Team hierarchy. Next, we met with our mentor (Dr. Gehringer) and reviewed every single method’s readability, maintainability, and adherence to best practices (SOLID principles, DRY, etc.). Once we organized the methods by class, we assigned groups of methods as tasks amongst team members and began refactoring existing methods while making sure existing test cases still passed and new tests were added as needed.

= Implementation =
'''Refactor Team Model'''
* Methods involved:
** self.allowed_types
** self.team_operation
** self.responses
** author_names
** user?(user)
** add_member(user, _assignment_id = nil)
** self.size(team_id)
** copy_members(new_team)
** self.check_for_existing(parent, name, team_type)
** self.randomize_all_by_parent(parent, team_type, min_team_size)
** self.create_team_from_single_users(min_team_size, parent, team_type, users)
** self.assign_single_users_to_teams(min_team_size, parent, teams, users)
** self.generate_team_name(_team_name_prefix = “”)
** self.create_team_and_node(id)
** self.create_team_with_users(parent_id, user_ids)
** self.remove_user_from_previous_team(parent_id, user_id)
** self.find_team_users(assignment_id, user_id)

* Problems/Solutions:
** The refactoring efforts addressed several key issues in Expertiza's codebase, including redundancy, unclear naming, and inefficient implementations.
** Unnecessary methods and parameters were removed or consolidated, improving code clarity and maintainability.
** Naming conventions were refined to better reflect functionality, and certain methods were moved to more appropriate classes, such as CourseTeam and AssignmentTeam.
** The use of ActiveRecord's dependent destroy was implemented to ensure proper cleanup of associated records.
** Additionally, alternative implementations were suggested to simplify logic, such as replacing redundant methods with built-in Rails queries and using uniqueness validation instead of manual checks.
** Improvements were proposed for import/export methods.

* Changes:
** Moved parent_entity_type and self.find_parent_entity(id) from CourseTeam to Team.
[[File:2503-0.png]]
** Renamed author_names to member_names.
[[File:2503-1.png]]
** Removed unnecessary parameter from add_member; replaced size with instance method; CourseTeam’s add_participant method was removed, and CourseTeam inherits Team.add_member instead.
[[File:2503-2.png]]
** Renamed randomize_all_by_parent to create_random_teams.
[[File:2503-3.png]]
** Renamed create_team_from_single_users to team_from_users.
[[File:2503-4.png]]
** No changes to self.handle_duplicate.
[[File:2503-5.png]]
** Added optional user_ids parameter to facilitate removal of create_team_with_users method to avoid redundancy.
[[File:2503-6.png]]

'''Refactor CourseTeam Model'''
* Methods involved:
** parent_model
** self.parent_model(id)
** assignment_id
** self.prototype
** copy(assignment_id)
** add_participant(course_id, user)
** self.import(row, course_id, options)
** self.export(csv, parent_id, options)
** self.export_fields(options)
** add_member(user, _id, = nil)

* Problems/Solutions:
** parent_model: Replaced with parent_entity_type() and find_parent_entity(id) in the Team class for clarity, since it duplicated functionality.
** self.parent_model(id) - Logic was moved to Team.find_parent_entity(id) to consolidate redundant behavior.
** assignment_id - No changes made; it correctly returns nil to indicate it's not an AssignmentTeam.
** self.prototype - Removed because it's unnecessary—creating a new instance with CourseTeam.new is sufficient.
** copy(assignment_id) - Refactored and renamed to copy_to_assignment() for clarity.
** add_participant(course_id, user) - Removed, as this responsibility already exists in the Course class.
** self.import(row, course_id, options) - Left unchanged since it appropriately overrides Team.import().
** self.export(csv, parent_id, options) - Left unchanged as it overrides Team.export() correctly.
** self.export_fields(options) - Left unchanged because it’s used in export_file_controller.rb for file exports.
** add_member(user, _id = nil) - Removed due to duplication; the Team class already implements add_member().

* Changes:
** Refactored the code and now the method called copy_to_assignment()
[[File:2503-7.png]]

'''Refactor AssignmentTeam Model'''
* Changes:
** assign_reviewer left as is [no change]
** get_reviewer() was renamed to reviewer()
** reviewed_by left() as is [no change]
** topic() renamed to topic_id()
[[File:2503-8.png]]
** files() refactored to use an iterator-based approach
[[File:2503-9.png]]
** For set.export_fields(), enabled fields to be an explicit return value to improve readability
** self.remove_team_by_id left as is, very concise; “unless nil” check ensures safety
** path() was refactored to avoid string concatenation
** set_team_directory_num() was refactored method name to match behavior
[[File:2503-10.png]]
** Refactored method name to match behavior
[[File:2503-11.png]]

'''Refactor MentoredTeam Model'''
* Changes:
** Refactored add_member to override Team.add_member to handle assigning a mentor
[[File:2503-12.png]]
= Test Plan =
This project involves refactoring the Team hierarchy, ensuring that existing functionality remains unchanged while improving structure and maintainability. Since the refactor involves modifying class structures, consolidating redundant methods, and introducing better encapsulation, the following steps were taken to validate correctness:
* Refactored RSpec test files to reflect changes in class structure, method names, and logic updates.
* Ran the test suite after each major change to verify that functionality remained consistent across Team, CourseTeam, AssignmentTeam, and MentoredTeam.
* Ensured that core team operations (adding/removing members, copying teams, importing/exporting teams) worked as expected by validating test outputs against pre-refactor results.
* Ensured all refactored classes maintained high test coverage, targeting at least 90% coverage in Team, AssignmentTeam, and CourseTeam.
* Ensured that removed methods were either unnecessary or replaced with equivalent logic in the refactored structure.
* Validated UI functionality by testing that teams were correctly displayed, managed, and interacted with in the system.
[[File:I1.png]]

CSC/ECE 517 Spring 2025 - E2503. Refactor the Team hierarchy

2025-03-26T18:00:43Z

Mbenkar: added remaining screenshots

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

'''Relevant Links:'''
* Link to Expertiza Repository: https://github.com/expertiza/expertiza
* Link to Forked Repository: https://github.com/AhmedOHassan/expertiza
* Link to Pull Request: https://github.com/expertiza/expertiza/pull/2941

= Expertiza Background =
Expertiza is an open-source project built using the Ruby on Rails MVC framework, designed to facilitate peer review and collaborative learning. The project has undergone multiple iterations, with ongoing efforts focused on refactoring the existing codebase to improve maintainability, efficiency, and scalability. Additionally, there are initiatives aimed at reimplementing a new version of Expertiza to enhance its architecture and functionality.

= About Team/CourseTeam/AssignmentTeam/MentoredTeam =
The Team hierarchy contains the classes that hold teams of students enrolled in Expertiza. Teams can reserve topics and submit work. There are currently four classes in the team hierarchy: Team, CourseTeam, AssignmentTeam, and MentoredTeam. Instances of the Team superclass should never be created since any actual team will be a member of one of the three other classes. CourseTeams stay together for the entire course duration and work on all assignments together. Although some instructors choose not to use CourseTeams, others employ Team-Based Learning and do benefit from using CourseTeams. It is possible to both copy CourseTeams into AssignmentTeams, and vice-versa. Any team formed to take part in an assignment will be an AssignmentTeam, unless the assignment is set up to automatically assign mentors to teams. In this case, the assignment teams will be created as MentoredTeams (a subclass of AssignmentTeam) which has a designated member known as the mentor.

= Problem Statement =
The Team hierarchy in Expertiza is responsible for managing student teams, allowing them to reserve topics, submit work, and, in some cases, review other teams' submissions. However, the current implementation is overly complex, with redundant methods and unnecessary dependencies. The Team class has 27 methods, many of which should be refactored or removed, while AssignmentTeam contains 36 methods, several of which duplicate functionality from the superclass. Additionally, the system currently models team members as Users, but the new design will transition to Participants, requiring updates to team membership logic.

= Tasks =
'''Refactoring the Team Hierarchy'''
* Prevent direct instantiation of Team, ensuring all actual teams belong to CourseTeam, AssignmentTeam, or MentoredTeam.
* Move only the core shared functionalities to the Team and reduce the method count.
* Eliminate Redundant Methods in AssignmentTeam and CourseTeam.
* Identify duplicate methods across Team, AssignmentTeam, and CourseTeam.
* Ensure CourseTeam and AssignmentTeam override import/export functionality from Team instead of defining separate versions.

'''Transition from Users to Participants '''
* Modify add_member and related methods to work with CourseParticipants and AssignmentParticipants instead of Users.
* Ensure teams enforce correct membership rules (e.g., CourseTeam only accepts CourseParticipants).

'''Optimizing Team Copying'''
* Ensure clear and efficient handling of copying between AssignmentTeam and CourseTeam.
* Consolidate logic for copying members across different team types.

'''Improving Method Clarity and Encapsulation'''
* Convert class methods like size into instance methods.
* Standardize method naming conventions for clarity (e.g., avoid inconsistencies like copy_members vs. copy_content).

'''Removing Unused and Inefficient Code'''
* Identify and remove any unused methods in Team, AssignmentTeam, and CourseTeam.
* Remove commented-out or deprecated code that no longer serves a purpose.
* Simplify methods that are overly complex by leveraging helper functions where necessary.

'''Testing and Code Validation'''
* Update tests to reflect the refactored team hierarchy and ensure correctness.
* Remove or rewrite tests that validate methods no longer in use.

= Plan of Work =
We began by listing all of the methods belonging to each class in the Team hierarchy. Next, we met with our mentor (Dr. Gehringer) and reviewed every single method’s readability, maintainability, and adherence to best practices (SOLID principles, DRY, etc.). Once we organized the methods by class, we assigned groups of methods as tasks amongst team members and began refactoring existing methods while making sure existing test cases still passed and new tests were added as needed.

= Implementation =
'''Refactor Team Model'''
* Methods involved:
** self.allowed_types
** self.team_operation
** self.responses
** author_names
** user?(user)
** add_member(user, _assignment_id = nil)
** self.size(team_id)
** copy_members(new_team)
** self.check_for_existing(parent, name, team_type)
** self.randomize_all_by_parent(parent, team_type, min_team_size)
** self.create_team_from_single_users(min_team_size, parent, team_type, users)
** self.assign_single_users_to_teams(min_team_size, parent, teams, users)
** self.generate_team_name(_team_name_prefix = “”)
** self.create_team_and_node(id)
** self.create_team_with_users(parent_id, user_ids)
** self.remove_user_from_previous_team(parent_id, user_id)
** self.find_team_users(assignment_id, user_id)

* Problems/Solutions:
** The refactoring efforts addressed several key issues in Expertiza's codebase, including redundancy, unclear naming, and inefficient implementations.
** Unnecessary methods and parameters were removed or consolidated, improving code clarity and maintainability.
** Naming conventions were refined to better reflect functionality, and certain methods were moved to more appropriate classes, such as CourseTeam and AssignmentTeam.
** The use of ActiveRecord's dependent destroy was implemented to ensure proper cleanup of associated records.
** Additionally, alternative implementations were suggested to simplify logic, such as replacing redundant methods with built-in Rails queries and using uniqueness validation instead of manual checks.
** Improvements were proposed for import/export methods.

* Changes:
** Moved parent_entity_type and self.find_parent_entity(id) from CourseTeam to Team.
[[File:2503-0.png]]
** Renamed author_names to member_names.
[[File:2503-1.png]]
** Removed unnecessary parameter from add_member; replaced size with instance method; CourseTeam’s add_participant method was removed, and CourseTeam inherits Team.add_member instead.
[[File:2503-2.png]]
** Renamed randomize_all_by_parent to create_random_teams.
[[File:2503-3.png]]
** Renamed create_team_from_single_users to team_from_users.
[[File:2503-4.png]]
** No changes to self.handle_duplicate.
[[File:2503-5.png]]
** Added optional user_ids parameter to facilitate removal of create_team_with_users method to avoid redundancy.
[[File:2503-6.png]]

'''Refactor CourseTeam Model'''
* Changes:
** Refactored the code and now the method called copy_to_assignment()
[[File:2503-7.png]]

'''Refactor AssignmentTeam Model'''
* Changes:
** assign_reviewer left as is [no change]
** get_reviewer() was renamed to reviewer()
** reviewed_by left() as is [no change]
** topic() renamed to topic_id()
[[File:2503-8.png]]
** files() refactored to use an iterator-based approach
[[File:2503-9.png]]
** For set.export_fields(), enabled fields to be an explicit return value to improve readability
** self.remove_team_by_id left as is, very concise; “unless nil” check ensures safety
** path() was refactored to avoid string concatenation
** set_team_directory_num() was refactored method name to match behavior
[[File:2503-10.png]]
** Refactored method name to match behavior
[[File:2503-11.png]]

'''Refactor MentoredTeam Model'''
* Changes:
** Refactored add_member to override Team.add_member to handle assigning a mentor
[[File:2503-12.png]]
= Test Plan =
This project involves refactoring the Team hierarchy, ensuring that existing functionality remains unchanged while improving structure and maintainability. Since the refactor involves modifying class structures, consolidating redundant methods, and introducing better encapsulation, the following steps were taken to validate correctness:
* Refactored RSpec test files to reflect changes in class structure, method names, and logic updates.
* Ran the test suite after each major change to verify that functionality remained consistent across Team, CourseTeam, AssignmentTeam, and MentoredTeam.
* Ensured that core team operations (adding/removing members, copying teams, importing/exporting teams) worked as expected by validating test outputs against pre-refactor results.
* Ensured all refactored classes maintained high test coverage, targeting at least 90% coverage in Team, AssignmentTeam, and CourseTeam.
* Ensured that removed methods were either unnecessary or replaced with equivalent logic in the refactored structure.
* Validated UI functionality by testing that teams were correctly displayed, managed, and interacted with in the system.
[[File:I1.png]]

File:2503-12.png

2025-03-26T17:55:32Z

Mbenkar:

File:2503-11.png

2025-03-26T17:55:24Z

Mbenkar:

File:2503-10.png

2025-03-26T17:55:16Z

Mbenkar:

File:2503-9.png

2025-03-26T17:55:07Z

Mbenkar:

File:2503-8.png

2025-03-26T17:55:00Z

Mbenkar:

File:2503-7.png

2025-03-26T17:54:49Z

Mbenkar:

File:2503-6.png

2025-03-26T17:54:38Z

Mbenkar:

CSC/ECE 517 Spring 2025 - E2503. Refactor the Team hierarchy

2025-03-26T17:53:42Z

Mbenkar: added screenshots 2503-1 -> 2503-5

= Team Information =
'''Mentor:'''
* Ed Gehringer

'''Team Members:'''
* Ahmed Hassan (aohassan)

* Rameez Malik (remalik)

* Moaad Benkaraache (mbenkar)

'''Relevant Links:'''
* Link to Expertiza Repository: https://github.com/expertiza/expertiza
* Link to Forked Repository: https://github.com/AhmedOHassan/expertiza
* Link to Pull Request: https://github.com/expertiza/expertiza/pull/2941

= Expertiza Background =
Expertiza is an open-source project built using the Ruby on Rails MVC framework, designed to facilitate peer review and collaborative learning. The project has undergone multiple iterations, with ongoing efforts focused on refactoring the existing codebase to improve maintainability, efficiency, and scalability. Additionally, there are initiatives aimed at reimplementing a new version of Expertiza to enhance its architecture and functionality.

= About Team/CourseTeam/AssignmentTeam/MentoredTeam =
The Team hierarchy contains the classes that hold teams of students enrolled in Expertiza. Teams can reserve topics and submit work. There are currently four classes in the team hierarchy: Team, CourseTeam, AssignmentTeam, and MentoredTeam. Instances of the Team superclass should never be created since any actual team will be a member of one of the three other classes. CourseTeams stay together for the entire course duration and work on all assignments together. Although some instructors choose not to use CourseTeams, others employ Team-Based Learning and do benefit from using CourseTeams. It is possible to both copy CourseTeams into AssignmentTeams, and vice-versa. Any team formed to take part in an assignment will be an AssignmentTeam, unless the assignment is set up to automatically assign mentors to teams. In this case, the assignment teams will be created as MentoredTeams (a subclass of AssignmentTeam) which has a designated member known as the mentor.

= Problem Statement =
The Team hierarchy in Expertiza is responsible for managing student teams, allowing them to reserve topics, submit work, and, in some cases, review other teams' submissions. However, the current implementation is overly complex, with redundant methods and unnecessary dependencies. The Team class has 27 methods, many of which should be refactored or removed, while AssignmentTeam contains 36 methods, several of which duplicate functionality from the superclass. Additionally, the system currently models team members as Users, but the new design will transition to Participants, requiring updates to team membership logic.

= Tasks =
'''Refactoring the Team Hierarchy'''
* Prevent direct instantiation of Team, ensuring all actual teams belong to CourseTeam, AssignmentTeam, or MentoredTeam.
* Move only the core shared functionalities to the Team and reduce the method count.
* Eliminate Redundant Methods in AssignmentTeam and CourseTeam.
* Identify duplicate methods across Team, AssignmentTeam, and CourseTeam.
* Ensure CourseTeam and AssignmentTeam override import/export functionality from Team instead of defining separate versions.

'''Transition from Users to Participants '''
* Modify add_member and related methods to work with CourseParticipants and AssignmentParticipants instead of Users.
* Ensure teams enforce correct membership rules (e.g., CourseTeam only accepts CourseParticipants).

'''Optimizing Team Copying'''
* Ensure clear and efficient handling of copying between AssignmentTeam and CourseTeam.
* Consolidate logic for copying members across different team types.

'''Improving Method Clarity and Encapsulation'''
* Convert class methods like size into instance methods.
* Standardize method naming conventions for clarity (e.g., avoid inconsistencies like copy_members vs. copy_content).

'''Removing Unused and Inefficient Code'''
* Identify and remove any unused methods in Team, AssignmentTeam, and CourseTeam.
* Remove commented-out or deprecated code that no longer serves a purpose.
* Simplify methods that are overly complex by leveraging helper functions where necessary.

'''Testing and Code Validation'''
* Update tests to reflect the refactored team hierarchy and ensure correctness.
* Remove or rewrite tests that validate methods no longer in use.

= Plan of Work =
We began by listing all of the methods belonging to each class in the Team hierarchy. Next, we met with our mentor (Dr. Gehringer) and reviewed every single method’s readability, maintainability, and adherence to best practices (SOLID principles, DRY, etc.). Once we organized the methods by class, we assigned groups of methods as tasks amongst team members and began refactoring existing methods while making sure existing test cases still passed and new tests were added as needed.

= Implementation =
'''Refactor Team Model'''
* Methods involved:
** self.allowed_types
** self.team_operation
** self.responses
** author_names
** user?(user)
** add_member(user, _assignment_id = nil)
** self.size(team_id)
** copy_members(new_team)
** self.check_for_existing(parent, name, team_type)
** self.randomize_all_by_parent(parent, team_type, min_team_size)
** self.create_team_from_single_users(min_team_size, parent, team_type, users)
** self.assign_single_users_to_teams(min_team_size, parent, teams, users)
** self.generate_team_name(_team_name_prefix = “”)
** self.create_team_and_node(id)
** self.create_team_with_users(parent_id, user_ids)
** self.remove_user_from_previous_team(parent_id, user_id)
** self.find_team_users(assignment_id, user_id)

* Problems/Solutions:
** The refactoring efforts addressed several key issues in Expertiza's codebase, including redundancy, unclear naming, and inefficient implementations.
** Unnecessary methods and parameters were removed or consolidated, improving code clarity and maintainability.
** Naming conventions were refined to better reflect functionality, and certain methods were moved to more appropriate classes, such as CourseTeam and AssignmentTeam.
** The use of ActiveRecord's dependent destroy was implemented to ensure proper cleanup of associated records.
** Additionally, alternative implementations were suggested to simplify logic, such as replacing redundant methods with built-in Rails queries and using uniqueness validation instead of manual checks.
** Improvements were proposed for import/export methods.

* Changes:
** Moved parent_entity_type and self.find_parent_entity(id) from CourseTeam to Team.
[[File:2503-0.png]]
** Renamed author_names to member_names.
[[File:2503-1.png]]
** Removed unnecessary parameter from add_member; replaced size with instance method; CourseTeam’s add_participant method was removed, and CourseTeam inherits Team.add_member instead.
[[File:2503-2.png]]
** Renamed randomize_all_by_parent to create_random_teams.
[[File:2503-3.png]]
** Renamed create_team_from_single_users to team_from_users.
[[File:2503-4.png]]
** No changes to self.handle_duplicate.
[[File:2503-5.png]]
** Added optional user_ids parameter to facilitate removal of create_team_with_users method to avoid redundancy.

'''Refactor CourseTeam Model'''
* Changes:
** Refactored the code and now the method called copy_to_assignment()

'''Refactor AssignmentTeam Model'''
* Changes:
** assign_reviewer left as is [no change]
** get_reviewer() was renamed to reviewer()
** reviewed_by left() as is [no change]
** topic() renamed to topic_id()
** files() refactored to use an iterator-based approach
** For set.export_fields(), enabled fields to be an explicit return value to improve readability
** self.remove_team_by_id left as is, very concise; “unless nil” check ensures safety
** path() was refactored to avoid string concatenation
** set_team_directory_num() was refactored method name to match behavior
** Refactored method name to match behavior

'''Refactor MentoredTeam Model'''
* Changes:
** Refactored add_member to override Team.add_member to handle assigning a mentor

= Test Plan =
This project involves refactoring the Team hierarchy, ensuring that existing functionality remains unchanged while improving structure and maintainability. Since the refactor involves modifying class structures, consolidating redundant methods, and introducing better encapsulation, the following steps were taken to validate correctness:
* Refactored RSpec test files to reflect changes in class structure, method names, and logic updates.
* Ran the test suite after each major change to verify that functionality remained consistent across Team, CourseTeam, AssignmentTeam, and MentoredTeam.
* Ensured that core team operations (adding/removing members, copying teams, importing/exporting teams) worked as expected by validating test outputs against pre-refactor results.
* Ensured all refactored classes maintained high test coverage, targeting at least 90% coverage in Team, AssignmentTeam, and CourseTeam.
* Ensured that removed methods were either unnecessary or replaced with equivalent logic in the refactored structure.
* Validated UI functionality by testing that teams were correctly displayed, managed, and interacted with in the system.
[[File:I1.png]]

File:2503-5.png

2025-03-26T17:51:50Z

Mbenkar:

File:2503-4.png

2025-03-26T17:51:42Z

Mbenkar: