CSC/ECE 517 Spring 2025 - E2515: Reimplement student teams controller.rb

E2515: Reimplement student_teams_controller.rb

Introduction

Expertiza is an open-source application developed on Ruby on Rails and maintained by the students and faculty of North Carolina State University. It allows the instructors to manage assignments and topics and enable efficient peer reviewing. A key part of Expertiza system’s modernization is its transition to a client-server architecture, where the frontend is built using React and backend is built using Rails APIs.

As a part of this modernization effort, the controllers in the legacy system are being re-implemented as RESTful APIs for ensuring better modularity, scalability and maintainability.

Project Description

The project E2515: Reimplement student_teams_controller.rb focuses on rewriting the StudentTeamsController from the legacy Expertiza system to a clean RESTful APSs which is in accordance with the modern object-oriented design principles. While the TeamsController manages instructor-level team operations (creation, deletion and randomization), the StudentTeamsController is student facing. It deals with operations like viewing team details, managing participation and handling team updates from the perspective of a student.

The main goal behind this reimplementation was to simplify the controller logic, eliminate tight coupling and offload business logic into models. Major emphasis was placed on enforcing RESTful practices, improving feedback, securing endpoints via strong parameters and ensuring throrough testing coverage.

Problem Statement

The existing implementation of Expertiza's StudentTeamsController presents significant architectural challenges that hinder long-term maintainability and scalability. Designed to handle student team operations - including formation, modification, and participant management - the controller currently exhibits several problematic patterns that complicate system evolution.

Key structural deficiencies include:

Overloaded Responsibilities: The controller improperly combines multiple functions including team administration, member management, and data validation within a single component, breaching fundamental modularity principles.
Duplicated Logic Patterns: Repetitive code segments for team retrieval, error management, and response generation appear throughout the implementation, creating unnecessary maintenance complexity.
Excessive Model Dependency: Tight integration with the AssignmentTeam model restricts flexibility, making future modifications to team behavior particularly challenging.
Unreliable Error Management: Inconsistent approaches to exception handling - using both global and local rescue blocks - coupled with hardcoded error messages, reduces reliability and debugging efficiency.
Inadequate Access Controls: Complete absence of permission verification creates potential security vulnerabilities in team modification operations.
Performance Bottlenecks: Likely inefficient data loading patterns in helper methods suggest scalability limitations as user numbers increase.

These architectural shortcomings collectively degrade the system's adaptability and operational stability. Proposed remediation focuses on several key improvements such as Responsibility Segregation, uniform error handling and response generation mechanisms, introduction of abstraction layers between controller and model operations (loose coupling), implementation of robust access control measures, and query optimization to enhance performance.

The restructured implementation will emphasize clean separation of concerns, predictable behavior patterns, and sustainable extensibility - ultimately delivering improved maintainability and more reliable operation.

Objective

The goal of this project is to reimplement the StudentTeamsController in the reimplementation-backend repository, transforming it into a well-structured, maintainable, and scalable RESTful API controller. Unlike other controllers, the StudentTeamsController is specifically designed for student-facing operations, enabling students to participate in teams by performing actions such as viewing team details and managing their participation. The following steps can be taken to achieve this:

Refactoring Controller Logic: Simplifying the controller by ensuring it only handles request orchestration and response delivery, while moving business logic to models or service objects.
Adopting RESTful Standards: Including standard RESTful actions (index, show, create, update, destroy) in the implementation, using strong parameters for security, and returning appropriate HTTP status codes and JSON responses.
Implementing Role-Based Access Control: Enforcing role-based authorization to restrict actions appropriately, and ensuring proper authorization and security.
Improving User Feedback: User feedback and error handling will be further enhanced to provide clearer, actionable messages for key operations like team creation or member removal, while structured error handling will ensure failures are managed gracefully.
Enhancing Code Quality: Adding detailed comments and using descriptive, action-oriented method names to improve readability and maintainability.
Ensuring Robust Testing: Writing comprehensive unit tests using RSpec to cover all controller actions and edge cases, ensuring reliability and scalability.

This reimplementation will result in a clean, scalable, and well-documented API controller that aligns with modern development practices.

Development Strategy

Our development methodology follows a test-driven approach to systematically rebuild the student team management components. We begin by constructing thorough test suites for the StudentTeamsController and related models, establishing clear behavioral expectations before refactoring. Each improvement iteration focuses on isolating responsibilities - separating team operations from participant management while eliminating duplicate logic. By progressively restructuring the codebase in small, test-validated increments, we ensure the redesigned system maintains all existing functionality while achieving superior architectural clarity. This disciplined modernization process emphasizes single-responsibility components, proper encapsulation, and clean separation between business logic and presentation layers. The resulting foundation will not only resolve current maintainability challenges but also establish patterns for future enhancements, delivering measurable gains in code quality, system performance, and long-term adaptability across the entire application.

Files Modified:

Created ==>
- app/controllers/api/v1/student_teams_controller.rb
- app/helpers/student_teams_helper.rb
- app/models/assignment_team.rb
- spec/controllers/student_teams/assignment_team_spec.rb
- spec/controllers/student_teams/student_team_helper_spec.rb
- spec/controllers/student_teams/student_team_controller_spec.rb
- spec/factories/assignment_teams.rb

Updated ==>
- app/controllers/application_controller.rb
- app/models/team.rb
- app/models/role.rb
- config/routes.rb
- db/schema.rb
- db/seeds.rb
- spec/rails_helper.rb

Project Design and Implementation

The re design approach for the project was driven by the following goals:

Separation of concerns – The business logic was extracted from the controller and moved to model classes (AssignmentTeam and AsssignmentParticipant), allowing the controller to strictly handle all HTTP responsibilities.
RESTful conventions – Implemented the index, show, create, destroy, add_participant and remove_participant as clearly defined API actions.
Improved Error Handling – Used rescue_from to catch common expectatiobs and return structured and meaningful error messages.
Enhanced user feedback – Success and failures states are now clearly communicated to the clients with proper HTTP status code and descriptive messages.
Scalability – The new design accommodates growing features such as mentor assignment, checking team capacity and topic integrations without bloating the controller.
Comprehensive Testing – The RSpec tests were written for all controller actions and model logic for ensuring correctness and edge-case handling.

In addition to this, Swagger documentation was generated for providing API consumers with a clear understanding of the endpoints and expected behavior.

Functionality

The following key features and improvements were implemented:

Controller Features:
- index – Lists all the teams associated with the particular student.
- Show – Fetches specific team and its members.
- Create – Creates a new team with the student as its first member.
- Update – Updates the team’s name while ensuring uniqueness.
- Destroy – Deletes a team based on its ID.
- add_participant – Adds a participant to the team after validating conditions like duplication, maximum size and more.
- remove_participant – Removes the participant and deletes the team if it is unused and empty.
AssignmentTeam model Enhancements:
- add_member – Adds a participant to a team with transaction safety and validations.
- remove_member – Removes a participant and handles cleanup if necessary.
- members – Returns detailed information about the team members.
- member?, full?, size – These are the utility methods for managing and validating team constraints.
AssignmentParticpant Model Additions:
- teams – Fetches all the teams the participant is a part of.
- set_handle – Ensures unique and meaningful participant handles.
Testing and Documentation:
- Rspec for all the API endpoints and model logics.
- Swagge-based API documentation for clarity and usability.

Tasks Completed

All the methods return appropriate JSON and status codes.

Methods:

AssignmentTeam Model:
- members: Method was added to view all the details of all members in an assignment team.
- full?: Method added to check if the team is at capacity
- member?: Method checks if a participant is a member of the team.
- size: Checking team size.
- validate_team_size: Validating the team size before saving team details.
- add_paticipant: For adding a member to the team.
- remove_participant: For removing a member from the team.

StudentTeamsController:
- index: Implemented for retrieving all teams associated with a student.
- show: For fetching details of a specific team and its members.
- create: Creates a new team with the current student as first member.
- update: Implemented for the sake of updating team name, while also checking if the new name is unique or already in use.
- destroy: To delete a team.
- add_participant: Adds a participant to a team.
- remove_participant: Removes a participant from their currently assigned team.

StudentTeamsHelper:
- fetch_student_teams: used in the index method of the StudentTeamsController to fetch all teams associated with a student.
- fetch_team_details: used in the show method of the StudentTeamsController, and contains the main logic.
- create_student_team: used in the create method of the StudentTeamsController and contains the logic of creating a team after validating the team name is unique.
- add_team_participant: used in the add_participant method of the StudentTeamsController which checks if the member to be added is already a part of a team, and if not then the member gets added.
- remove_team_participant: used in the remove_participant method of the StudentTeamsController for removing a participant from the team.
- set_student: sets the current student based on id. Private method.
- set_team: sets the current team using team ID. Private method.

Additional: Endpoints added to swagger

Testing Plan

To successfully run the test, the user needs to be logged in and should be authorized to run the tests.
The command for running the tests: bundle exec rspec spec/controllers/student_teams/student_teams_controller_spec.rb

index endpoint: