Expertiza_Wiki - User contributions [en]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:45:11Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:Joinrequest.png|thumb|center|850px|Join Request Form]]

''Figure 1: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:acceptrequest2.png|center|850px|Accept Request]]

[[File:acceptrequest1.png|center|850px|Accept Request Confirmation]]

''Figure 2: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:43:39Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:Joinrequest.png|thumb|center|850px|Join Request Form]]

''Figure 1: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:acceptrequest2.png|center|850px|Accept Request]]

[[File:acceptrequest1.png|center|850px|Accept Request Confirmation]]

''Figure 2: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:36:50Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:Joinrequest.png|thumb|center|850px|Join Request Form]]

''Figure 1: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:acceptrequest2.png|800px|Accept Request]]
| [[File:acceptrequest1.png|800px|Accept Request Confirmation]]
|}

''Figure 2: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

[[File:JoinTeamRequest_TestResults_Screenshot.png|700px|center|Test Results]]

''Figure 9: RSpec test output showing all tests passing. The documentation format displays each test case with its description, making it easy to understand what functionality is being verified.''

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

[[File:JoinTeamRequest_Frontend_Architecture.png|700px|center|Frontend Component Structure]]

''Figure 10: Frontend component hierarchy showing how the main JoinTeamRequests component composes smaller, focused components for list display, forms, and actions.''

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

[[File:JoinTeamRequest_UI_Overview.png|800px|center|UI Overview]]

''Figure 11: Complete UI overview showing the join team requests interface. The left panel shows the list of requests with filtering options, and the right panel shows the details of a selected request with action buttons for team members.''

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

File:Acceptrequest2.png

2025-12-03T01:35:36Z

Dshah24:

File:Acceptrequest1.png

2025-12-03T01:32:17Z

Dshah24:

File:Joinrequest.png

2025-12-03T01:27:34Z

Dshah24:

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:15:28Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:JoinTeamRequest_Create_Screenshot.png|700px|center|Create Request Form]]

''Figure 4: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:JoinTeamRequest_Accept_Screenshot.png|700px|center|Accept Request Confirmation]]

''Figure 5: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details and comments. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

[[File:JoinTeamRequest_TestResults_Screenshot.png|700px|center|Test Results]]

''Figure 9: RSpec test output showing all tests passing. The documentation format displays each test case with its description, making it easy to understand what functionality is being verified.''

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

[[File:JoinTeamRequest_Frontend_Architecture.png|700px|center|Frontend Component Structure]]

''Figure 10: Frontend component hierarchy showing how the main JoinTeamRequests component composes smaller, focused components for list display, forms, and actions.''

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

[[File:JoinTeamRequest_UI_Overview.png|800px|center|UI Overview]]

''Figure 11: Complete UI overview showing the join team requests interface. The left panel shows the list of requests with filtering options, and the right panel shows the details of a selected request with action buttons for team members.''

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:13:30Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Inconsistent API Responses:''' Without proper serialization, API responses varied in structure and content, making frontend integration difficult and error-prone. The lack of standardized response formats also complicated error handling on the client side.

'''Limited Query Capabilities:''' The original implementation only provided basic CRUD operations. There were no endpoints for filtering requests by team, by user, or by status, forcing the frontend to fetch all requests and filter client-side—an inefficient approach that doesn't scale well.

'''Missing Frontend Interface:''' While backend functionality existed, there was no dedicated user interface for managing join team requests, leaving users without a clear way to interact with this feature.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:JoinTeamRequest_Create_Screenshot.png|700px|center|Create Request Form]]

''Figure 4: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:JoinTeamRequest_Accept_Screenshot.png|700px|center|Accept Request Confirmation]]

''Figure 5: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details and comments. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

[[File:JoinTeamRequest_TestResults_Screenshot.png|700px|center|Test Results]]

''Figure 9: RSpec test output showing all tests passing. The documentation format displays each test case with its description, making it easy to understand what functionality is being verified.''

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

[[File:JoinTeamRequest_Frontend_Architecture.png|700px|center|Frontend Component Structure]]

''Figure 10: Frontend component hierarchy showing how the main JoinTeamRequests component composes smaller, focused components for list display, forms, and actions.''

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

[[File:JoinTeamRequest_UI_Overview.png|800px|center|UI Overview]]

''Figure 11: Complete UI overview showing the join team requests interface. The left panel shows the list of requests with filtering options, and the right panel shows the details of a selected request with action buttons for team members.''

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-03T01:06:56Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Inconsistent API Responses:''' Without proper serialization, API responses varied in structure and content, making frontend integration difficult and error-prone. The lack of standardized response formats also complicated error handling on the client side.

'''Limited Query Capabilities:''' The original implementation only provided basic CRUD operations. There were no endpoints for filtering requests by team, by user, or by status, forcing the frontend to fetch all requests and filter client-side—an inefficient approach that doesn't scale well.

'''Missing Frontend Interface:''' While backend functionality existed, there was no dedicated user interface for managing join team requests, leaving users without a clear way to interact with this feature.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 2. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:JoinTeamRequest_Create_Screenshot.png|700px|center|Create Request Form]]

''Figure 4: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 3. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 4. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 5. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:JoinTeamRequest_Accept_Screenshot.png|700px|center|Accept Request Confirmation]]

''Figure 5: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details and comments. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 6. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

[[File:JoinTeamRequest_TestResults_Screenshot.png|700px|center|Test Results]]

''Figure 9: RSpec test output showing all tests passing. The documentation format displays each test case with its description, making it easy to understand what functionality is being verified.''

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

[[File:JoinTeamRequest_Frontend_Architecture.png|700px|center|Frontend Component Structure]]

''Figure 10: Frontend component hierarchy showing how the main JoinTeamRequests component composes smaller, focused components for list display, forms, and actions.''

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

[[File:JoinTeamRequest_UI_Overview.png|800px|center|UI Overview]]

''Figure 11: Complete UI overview showing the join team requests interface. The left panel shows the list of requests with filtering options, and the right panel shows the details of a selected request with action buttons for team members.''

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

=== New Features ===

# '''Fine-grained authorization''' based on user roles (admin/student) and relationships (request creator/team member)
# '''Filtering endpoints''' (<code>for_team</code>, <code>by_user</code>, <code>pending</code>) for efficient data retrieval
# '''Accept/Decline workflow''' with team member validation and automatic team membership management
# '''Duplicate request prevention''' to avoid confusion from multiple pending requests to the same team
# '''Comprehensive error handling''' with user-friendly error messages suitable for display
# '''ActiveModel Serializer integration''' for consistent, predictable JSON responses
# '''Full test coverage''' for all endpoints and authorization scenarios

== Team Members ==

{| class="wikitable"
|-
! Name !! Unity ID !! Contribution
|-
| [Team Member 1] || [unity_id] || Backend controller implementation, authorization logic
|-
| [Team Member 2] || [unity_id] || Model development, serializer implementation
|-
| [Team Member 3] || [unity_id] || Test coverage, documentation, code review
|-
| [Team Member 4] || [unity_id] || Frontend integration, UI components
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

The implementation follows Rails best practices and integrates seamlessly with the existing Expertiza codebase, providing a solid foundation for team formation workflows in the system.

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-12-02T23:08:47Z

Dshah24:

= CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests =

== Introduction ==

This project focuses on the integration and enhancement of the '''JoinTeamRequests''' functionality in the Expertiza reimplementation. The JoinTeamRequests feature allows students to request to join existing teams within assignments, providing a structured workflow for team formation and management.

The Expertiza system is a peer-review platform used extensively in academic settings, where students collaborate on assignments in teams. A critical component of this collaboration is the ability for students who are not yet part of a team to request membership in an existing team. This implementation delivers a complete backend API with proper authorization, serialization, and comprehensive test coverage, along with frontend components for managing join team requests.

The goal of this project is to create a seamless, secure, and user-friendly experience for both students requesting to join teams and team members who must review and respond to these requests.

== Problem Statement ==

In the Expertiza system, students need a mechanism to request membership in existing teams when they are not yet part of one. This process involves multiple stakeholders with different roles and permissions:

* '''Students without a team''' need to browse available teams and submit join requests
* '''Existing team members''' need to review incoming requests and decide whether to accept or decline them
* '''Administrators''' need oversight of all join team requests across the system for monitoring and troubleshooting purposes

The existing implementation in the Expertiza reimplementation had several limitations that this project addresses:

'''Authorization Gaps:''' The previous implementation lacked fine-grained access control. There was no proper distinction between who could view, create, modify, or act upon join team requests. This created potential security vulnerabilities where unauthorized users could access or manipulate requests.

'''Inconsistent API Responses:''' Without proper serialization, API responses varied in structure and content, making frontend integration difficult and error-prone. The lack of standardized response formats also complicated error handling on the client side.

'''Limited Query Capabilities:''' The original implementation only provided basic CRUD operations. There were no endpoints for filtering requests by team, by user, or by status, forcing the frontend to fetch all requests and filter client-side—an inefficient approach that doesn't scale well.

'''Missing Frontend Interface:''' While backend functionality existed, there was no dedicated user interface for managing join team requests, leaving users without a clear way to interact with this feature.

'''Insufficient Test Coverage:''' The existing tests did not cover edge cases or the full range of authorization scenarios, leaving potential bugs undiscovered.

== Design Goals ==

Our implementation focuses on five key design principles that guide all development decisions:

'''1. Robust Authorization:''' We implemented fine-grained access control based on user roles (administrator, student) and relationships (request creator, team member). Each API endpoint explicitly defines who can access it, and the authorization logic is centralized in a single method for consistency and maintainability. This ensures that users can only perform actions appropriate to their role and relationship to the request.

'''2. RESTful API Design:''' The API follows REST conventions with proper HTTP semantics. We use appropriate HTTP methods (GET for retrieval, POST for creation, PATCH for updates, DELETE for removal) and return meaningful HTTP status codes (200 for success, 201 for creation, 404 for not found, 422 for validation errors). This makes the API intuitive for developers and compatible with standard HTTP clients.

'''3. Consistent Serialization:''' All API responses pass through ActiveModel Serializers, ensuring consistent JSON structure across all endpoints. This includes nested representations of related objects (participant and team information) that the frontend needs to display meaningful information to users without making additional API calls.

'''4. Comprehensive Testing:''' Every endpoint and authorization scenario is covered by RSpec tests. We test both the "happy path" (expected behavior) and edge cases (error conditions, unauthorized access attempts). This gives us confidence that the implementation works correctly and will continue to work as the codebase evolves.

'''5. Frontend Integration:''' The backend is designed with frontend consumption in mind. Response formats include all necessary data for UI rendering, error messages are user-friendly, and filtering endpoints reduce the need for client-side data processing.

== Implementation ==

=== Backend Architecture Overview ===

The backend implementation follows the standard Rails MVC pattern with additional layers for serialization and authorization. The architecture consists of:

* '''Controller:''' Handles HTTP requests, enforces authorization, and coordinates between models and serializers
* '''Model:''' Defines data structure, relationships, and validations
* '''Serializer:''' Transforms model data into consistent JSON responses
* '''Routes:''' Maps URLs to controller actions

The following diagram illustrates the request flow through these components:

[[File:JoinTeamRequest_Architecture.png|800px|center|Architecture Overview]]

''Figure 1: Request flow architecture showing how HTTP requests are processed through the controller, which interacts with models and returns serialized responses.''

=== Controller: Api::V1::JoinTeamRequestsController ===

The controller is the heart of our implementation, located at <code>app/controllers/api/v1/join_team_requests_controller.rb</code>. It handles all join team request operations and enforces authorization rules.

==== Constants and Status Management ====

We define status constants at the class level to ensure consistency throughout the codebase and avoid magic strings. This approach makes the code more maintainable—if we ever need to change a status value, we only need to update it in one place.

<syntaxhighlight lang="ruby">
class Api::V1::JoinTeamRequestsController < ApplicationController
# Constants used to indicate status for the request
# Using constants prevents typos and enables easy refactoring
PENDING = 'PENDING'
DECLINED = 'DECLINED'
ACCEPTED = 'ACCEPTED'
</syntaxhighlight>

==== Before Actions ====

Rails before_action filters allow us to extract common logic that runs before specific controller actions. This follows the DRY (Don't Repeat Yourself) principle and ensures consistent behavior across related endpoints.

<syntaxhighlight lang="ruby">
# This filter runs before the create action, checking if the team is full
# Checking this early prevents unnecessary database operations if the request would fail anyway
before_action :check_team_status, only: [:create]

# This filter runs before the specified actions, finding the join team request
# Centralizing this lookup ensures consistent 404 handling and reduces code duplication
before_action :find_request, only: %i[show update destroy decline accept]
</syntaxhighlight>

==== Authorization Implementation ====

The <code>action_allowed?</code> method is the cornerstone of our authorization system. Unlike simple role-based checks, our implementation considers both the user's role AND their relationship to the specific resource being accessed. This provides security while maintaining usability.

The following table summarizes the authorization rules:

{| class="wikitable"
|-
! Action !! Authorization Rule !! Rationale
|-
| <code>index</code> || Only administrators || Viewing all requests system-wide is an administrative function
|-
| <code>create</code> || Any student || All students should be able to request to join teams
|-
| <code>show</code> || Request creator OR team member || Both parties need to see request details
|-
| <code>update</code>, <code>destroy</code> || Only the request creator || Only the requester should modify or withdraw their request
|-
| <code>accept</code>, <code>decline</code> || Only team members || Only existing team members can decide on membership
|-
| <code>for_team</code>, <code>by_user</code>, <code>pending</code> || Any student || Filtered views help students find relevant requests
|}

The implementation of this authorization logic demonstrates several important patterns:

<syntaxhighlight lang="ruby">
def action_allowed?
case params[:action]
when 'index'
# Only administrators can view all join team requests
# This prevents students from seeing requests for teams they're not part of
current_user_has_admin_privileges?

when 'create'
# Any student can create a join team request
# Additional validation (participant check, team membership) happens in the action itself
current_user_has_student_privileges?

when 'show'
# The participant who made the request OR any team member can view it
# This allows both parties to stay informed about the request status
return false unless current_user_has_student_privileges?

# Load the request for authorization check (memoized to avoid duplicate queries)
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request

# Check if user is either the creator or a team member
current_user_is_request_creator? || current_user_is_team_member?

when 'update', 'destroy'
# Only the participant who created the request can update or delete it
# This prevents team members from modifying requests they didn't create
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_request_creator?

when 'decline', 'accept'
# Only team members of the target team can accept/decline a request
# The requester themselves cannot accept their own request
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?

when 'for_team', 'by_user', 'pending'
# Students can view filtered lists
# These endpoints are scoped appropriately in their implementations
current_user_has_student_privileges?

else
# Default: deny access for any unrecognized actions
# This is a security best practice - fail closed
false
end
end
</syntaxhighlight>

==== API Endpoints ====

Each endpoint is designed to serve a specific use case. Below we detail each endpoint with its purpose, implementation, and usage examples.

===== 1. Index - List All Requests (Admin Only) =====

The index endpoint returns all join team requests in the system. This is intended for administrative oversight, allowing administrators to monitor team formation activity and troubleshoot issues.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests
# Returns all join team requests with eager-loaded associations
def index
# Using includes() prevents N+1 queries by eager loading participant and team data
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

[[File:JoinTeamRequest_Index_Screenshot.png|700px|center|Index Endpoint Result]]

''Figure 2: The admin view showing all join team requests in the system. Administrators can see requests across all teams, including their status and timestamps. Each row is clickable to view full request details.''

===== 2. Show - View Single Request =====

The show endpoint returns detailed information about a specific join team request. Both the requester and team members can access this endpoint to view the current status and any comments.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/1
# Returns a single join team request with full details
def show
# @join_team_request is set by the find_request before_action
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 3. For Team - Filter by Team =====

This filtering endpoint returns all join requests for a specific team. Team members use this to see who wants to join their team, making it easy to manage incoming requests.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/for_team/:team_id
# Get all join team requests for a specific team
def for_team
team = Team.find(params[:team_id])
# Access the requests through the team's association for cleaner code
join_team_requests = team.join_team_requests.includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
rescue ActiveRecord::RecordNotFound
# Provide a clear error message when the team doesn't exist
render json: { error: 'Team not found' }, status: :not_found
end
</syntaxhighlight>

[[File:JoinTeamRequest_ForTeam_Screenshot.png|700px|center|For Team Endpoint Result]]

''Figure 3: Team members can view all pending requests for their team. The interface shows requester information and allows team members to accept or decline each request. Hovering over a request reveals the requester's comments.''

===== 4. By User - Filter by User =====

This endpoint returns all join requests created by a specific user. Students use this to track the status of their outgoing requests.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/by_user/:user_id
# Get all join team requests created by a specific user
def by_user
# A user may have multiple participant records (one per assignment)
# We need to find all of them to get all their requests
participant_ids = Participant.where(user_id: params[:user_id]).pluck(:id)
join_team_requests = JoinTeamRequest.where(participant_id: participant_ids).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 5. Pending - Get Pending Requests =====

This convenience endpoint returns only pending requests, helping users focus on requests that require action.

<syntaxhighlight lang="ruby">
# GET api/v1/join_team_requests/pending
# Get all pending join team requests
def pending
join_team_requests = JoinTeamRequest.where(reply_status: PENDING).includes(:participant, :team)
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

===== 6. Create - Submit New Request =====

The create endpoint is the most complex, with multiple validation checks to ensure data integrity. It demonstrates defensive programming practices by validating inputs before creating records.

<syntaxhighlight lang="ruby">
# POST api/v1/join_team_requests
# Creates a new join team request with comprehensive validation
def create
# Step 1: Verify the user is a participant in the assignment
# This prevents users from creating requests for assignments they're not enrolled in
participant = AssignmentParticipant.find_by(user_id: @current_user.id, parent_id: params[:assignment_id])

unless participant
return render json: { error: 'You are not a participant in this assignment' }, status: :unprocessable_entity
end

# Step 2: Verify the target team exists
team = Team.find_by(id: params[:team_id])
unless team
return render json: { error: 'Team not found' }, status: :not_found
end

# Step 3: Check if user already belongs to the team
# This prevents unnecessary requests and potential confusion
if team.participants.include?(participant)
return render json: { error: 'You already belong to this team' }, status: :unprocessable_entity
end

# Step 4: Check for duplicate pending requests
# Allowing multiple pending requests to the same team would be confusing
existing_request = JoinTeamRequest.find_by(
participant_id: participant.id,
team_id: team.id,
reply_status: PENDING
)

if existing_request
return render json: { error: 'You already have a pending request for this team' }, status: :unprocessable_entity
end

# Step 5: Create the request with all validated data
join_team_request = JoinTeamRequest.new(
participant_id: participant.id,
team_id: team.id,
comments: params[:comments],
reply_status: PENDING # All new requests start as pending
)

if join_team_request.save
render json: join_team_request, serializer: JoinTeamRequestSerializer, status: :created
else
render json: { errors: join_team_request.errors.full_messages }, status: :unprocessable_entity
end
rescue ActiveRecord::RecordNotFound => e
render json: { error: e.message }, status: :not_found
end
</syntaxhighlight>

[[File:JoinTeamRequest_Create_Screenshot.png|700px|center|Create Request Form]]

''Figure 4: The join request form allows students to select a team and optionally add comments explaining why they want to join. The form validates that the student is not already on a team and that the target team is not full.''

===== 7. Update - Modify Request Comments =====

The update endpoint allows requesters to modify their request comments. We intentionally restrict updates to comments only—status changes must go through the accept/decline endpoints.

<syntaxhighlight lang="ruby">
# PATCH/PUT api/v1/join_team_requests/1
# Updates a join team request (comments only, not status)
def update
# Explicitly only allow updating comments
# This prevents requesters from accepting their own requests
if @join_team_request.update(comments: params[:comments])
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 8. Destroy - Delete Request =====

Students can withdraw their join requests at any time. This is useful if they've found another team or changed their mind.

<syntaxhighlight lang="ruby">
# DELETE api/v1/join_team_requests/1
# Deletes a join team request (withdraw the request)
def destroy
if @join_team_request.destroy
render json: { message: 'Join team request was successfully deleted' }, status: :ok
else
render json: { error: 'Failed to delete join team request' }, status: :unprocessable_entity
end
end
</syntaxhighlight>

===== 9. Accept - Approve and Add Member =====

The accept endpoint is critical—it not only updates the request status but also adds the requester to the team. This transactional operation ensures data consistency.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/accept
# Accept a join team request and add the participant to the team
def accept
# Validation 1: Ensure request hasn't already been processed
# This prevents race conditions and duplicate team membership
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

# Validation 2: Check team capacity before accepting
team = @join_team_request.team
if team.full?
return render json: { error: 'Team is full' }, status: :unprocessable_entity
end

# Attempt to add the participant to the team
begin
result = team.add_member(@join_team_request.participant)

if result[:success]
# Only update the request status after successfully adding the member
@join_team_request.reply_status = ACCEPTED
@join_team_request.save
render json: {
message: 'Join team request accepted successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
end
rescue StandardError => e
# Catch any unexpected errors during the add_member operation
render json: { error: e.message }, status: :unprocessable_entity
end
end
</syntaxhighlight>

[[File:JoinTeamRequest_Accept_Screenshot.png|700px|center|Accept Request Confirmation]]

''Figure 5: When a team member clicks the Accept button, a confirmation dialog appears showing the requester's details and comments. Upon confirmation, the requester is added to the team and notified of the acceptance.''

===== 10. Decline - Reject Request =====

The decline endpoint allows team members to reject join requests. Unlike delete, decline preserves the request record for audit purposes.

<syntaxhighlight lang="ruby">
# PATCH api/v1/join_team_requests/1/decline
# Decline a join team request
def decline
# Prevent re-processing of already handled requests
unless @join_team_request.reply_status == PENDING
return render json: { error: 'This request has already been processed' }, status: :unprocessable_entity
end

@join_team_request.reply_status = DECLINED
if @join_team_request.save
render json: {
message: 'Join team request declined successfully',
join_team_request: JoinTeamRequestSerializer.new(@join_team_request).as_json
}, status: :ok
else
render json: { errors: @join_team_request.errors.full_messages }, status: :unprocessable_entity
end
end
</syntaxhighlight>

==== Private Helper Methods ====

The private methods encapsulate reusable logic and keep the public action methods clean and focused.

<syntaxhighlight lang="ruby">
private

# Checks if the team is full before allowing request creation
# Running this as a before_action prevents unnecessary database operations
def check_team_status
team = Team.find(params[:team_id])
if team.full?
render json: { message: 'This team is full.' }, status: :unprocessable_entity
end
end

# Finds the join team request by ID
# Raises ActiveRecord::RecordNotFound if not found, which Rails converts to a 404 response
def find_request
@join_team_request = JoinTeamRequest.find(params[:id])
end

# Permits specified parameters for join team requests
# This is a security measure to prevent mass assignment vulnerabilities
def join_team_request_params
params.require(:join_team_request).permit(:comments, :reply_status)
end

# Helper method to check if current user is the creator of the request
# Uses safe navigation (&.) to handle nil cases gracefully
def current_user_is_request_creator?
return false unless @join_team_request && @current_user

participant = Participant.find_by(id: @join_team_request.participant_id)
participant&.user_id == @current_user.id
end

# Helper method to check if current user is a member of the target team
# This involves looking up the user's participant record for the relevant assignment
def current_user_is_team_member?
return false unless @join_team_request && @current_user

team = Team.find_by(id: @join_team_request.team_id)
return false unless team

# Find the participant record for the current user in the same assignment
if team.is_a?(AssignmentTeam)
participant = AssignmentParticipant.find_by(
user_id: @current_user.id,
parent_id: team.parent_id
)
return false unless participant

# Check if this participant is in the team's participants list
team.participants.include?(participant)
else
false
end
end
</syntaxhighlight>

=== Model: JoinTeamRequest ===

The model is intentionally simple, following the Rails principle of keeping models focused on data concerns. It defines relationships and validations, delegating business logic to the controller.

Located at <code>app/models/join_team_request.rb</code>:

<syntaxhighlight lang="ruby">
class JoinTeamRequest < ApplicationRecord
# Associations define the relationships with other models
belongs_to :team
belongs_to :participant

# Status validation ensures only valid statuses can be saved
# This is a database-level safeguard complementing the controller logic
ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }
end
</syntaxhighlight>

=== Serializer: JoinTeamRequestSerializer ===

The serializer transforms model data into a consistent JSON format suitable for frontend consumption. By including related data (participant and team details), we reduce the number of API calls the frontend needs to make.

<syntaxhighlight lang="ruby">
class JoinTeamRequestSerializer < ActiveModel::Serializer
# Top-level attributes from the JoinTeamRequest model
attributes :id, :reply_status, :comments, :created_at, :updated_at

# Declare associations (these methods below override default behavior)
belongs_to :participant
belongs_to :team

# Custom participant representation with user details
# This saves the frontend from making separate API calls for user information
def participant
{
id: object.participant.id,
user_id: object.participant.user_id,
user_name: object.participant.user&.name,
user_full_name: object.participant.user&.full_name
}
end

# Custom team representation with essential details
def team
{
id: object.team.id,
name: object.team.name,
parent_id: object.team.parent_id
}
end
end
</syntaxhighlight>

=== Routes Configuration ===

Our routes follow RESTful conventions with additional collection and member routes for specialized operations. The route structure makes the API intuitive and self-documenting.

Added to <code>config/routes.rb</code>:

<syntaxhighlight lang="ruby">
resources :join_team_requests do
collection do
# Filtering endpoints - operate on the collection, not a specific resource
get 'for_team/:team_id', action: :for_team
get 'by_user/:user_id', action: :by_user
get 'pending', action: :pending
end
member do
# Action endpoints - operate on a specific resource
patch 'accept', action: :accept
patch 'decline', action: :decline
end
end
</syntaxhighlight>

This configuration generates the following routes:

{| class="wikitable"
|-
! HTTP Method !! URL Pattern !! Controller Action !! Purpose
|-
| GET || /api/v1/join_team_requests || index || List all requests (admin)
|-
| GET || /api/v1/join_team_requests/:id || show || View single request
|-
| POST || /api/v1/join_team_requests || create || Submit new request
|-
| PATCH/PUT || /api/v1/join_team_requests/:id || update || Modify request
|-
| DELETE || /api/v1/join_team_requests/:id || destroy || Delete request
|-
| GET || /api/v1/join_team_requests/for_team/:team_id || for_team || Filter by team
|-
| GET || /api/v1/join_team_requests/by_user/:user_id || by_user || Filter by user
|-
| GET || /api/v1/join_team_requests/pending || pending || Get pending only
|-
| PATCH || /api/v1/join_team_requests/:id/accept || accept || Accept request
|-
| PATCH || /api/v1/join_team_requests/:id/decline || decline || Decline request
|}

=== Database Schema ===

The <code>join_team_requests</code> table stores all join request data. The schema is designed for efficient querying with indexed foreign keys.

From <code>db/schema.rb</code>:

<syntaxhighlight lang="ruby">
create_table "join_team_requests", charset: "utf8mb4", collation: "utf8mb4_0900_ai_ci", force: :cascade do |t|
t.datetime "created_at", null: false
t.datetime "updated_at", null: false
t.integer "participant_id" # Foreign key to participants table
t.integer "team_id" # Foreign key to teams table
t.text "comments" # Optional message from the requester
t.string "reply_status" # PENDING, ACCEPTED, or DECLINED
end
</syntaxhighlight>

=== API Response Format ===

Consistent response formats make frontend development more predictable. All successful responses follow the same structure, and error responses are clearly formatted.

==== Success Response Example (Single Request) ====

<syntaxhighlight lang="json">
{
"id": 1,
"reply_status": "PENDING",
"comments": "I would like to join your team for the project.",
"created_at": "2025-01-15T10:30:00.000Z",
"updated_at": "2025-01-15T10:30:00.000Z",
"participant": {
"id": 5,
"user_id": 12,
"user_name": "student1",
"user_full_name": "John Doe"
},
"team": {
"id": 3,
"name": "Team Alpha",
"parent_id": 1
}
}
</syntaxhighlight>

==== Error Response Examples ====

Validation errors return descriptive messages that can be displayed directly to users:

<syntaxhighlight lang="json">
{
"error": "You already belong to this team"
}
</syntaxhighlight>

<syntaxhighlight lang="json">
{
"error": "This request has already been processed"
}
</syntaxhighlight>

Model validation errors return an array format:

<syntaxhighlight lang="json">
{
"errors": ["Reply status is not included in the list"]
}
</syntaxhighlight>

== UML Diagrams ==

=== Class Diagram ===

The following class diagram illustrates the relationships between the main components of our implementation:

[[File:JoinTeamRequest_ClassDiagram.png|800px|center|Class Diagram]]

''Figure 6: Class diagram showing the JoinTeamRequestsController and its relationships with the JoinTeamRequest model, which belongs to both Participant and Team models. The controller methods are organized by visibility (public and private).''

<pre>
+----------------------------------+
| JoinTeamRequestsController |
+----------------------------------+
| - PENDING: String |
| - DECLINED: String |
| - ACCEPTED: String |
+----------------------------------+
| + action_allowed?(): Boolean |
| + index(): JSON |
| + show(): JSON |
| + for_team(): JSON |
| + by_user(): JSON |
| + pending(): JSON |
| + create(): JSON |
| + update(): JSON |
| + destroy(): JSON |
| + accept(): JSON |
| + decline(): JSON |
| - check_team_status(): void |
| - find_request(): void |
| - join_team_request_params() |
| - current_user_is_request_creator? |
| - current_user_is_team_member? |
+----------------------------------+
|
| uses
v
+----------------------------------+
| JoinTeamRequest |
+----------------------------------+
| + id: Integer |
| + participant_id: Integer |
| + team_id: Integer |
| + comments: Text |
| + reply_status: String |
| + created_at: DateTime |
| + updated_at: DateTime |
+----------------------------------+
| + participant: Participant |
| + team: Team |
+----------------------------------+
|
| belongs_to
v
+------------------+ +------------------+
| Participant | | Team |
+------------------+ +------------------+
| + id: Integer | | + id: Integer |
| + user_id: Int | | + name: String |
| + parent_id: Int | | + parent_id: Int |
+------------------+ | + full?(): Bool |
| + add_member() |
+------------------+
</pre>

=== Sequence Diagram - Create Join Team Request ===

This sequence diagram shows the flow of creating a new join team request, including all validation steps:

[[File:JoinTeamRequest_CreateSequence.png|900px|center|Create Sequence Diagram]]

''Figure 7: Sequence diagram for the create action. The controller performs multiple validation checks before creating the request, ensuring data integrity at each step.''

<pre>
Student Controller Participant Team JoinTeamRequest
| | | | |
| POST /join_team_requests | | |
|----------------->| | | |
| | | | |
| | check_team_status | | |
| |--------------------|-------------->| |
| | | full?() | |
| |<-------------------|---------------| |
| | | | |
| | find_by (user_id, parent_id) | |
| |------------------->| | |
| |<-------------------| | |
| | | | |
| | participants.include? (participant)| |
| |------------------------------------+ |
| |<-----------------------------------| |
| | | | |
| | find_by (participant_id, team_id, PENDING) |
| |-------------------------------------------------->|
| |<--------------------------------------------------|
| | | | |
| | new (participant_id, team_id, comments, PENDING) |
| |-------------------------------------------------->|
| | | | save |
| |<--------------------------------------------------|
| | | | |
| 201 Created | | | |
|<-----------------| | | |
</pre>

=== Sequence Diagram - Accept Join Team Request ===

This sequence diagram shows the flow of accepting a join team request:

[[File:JoinTeamRequest_AcceptSequence.png|900px|center|Accept Sequence Diagram]]

''Figure 8: Sequence diagram for the accept action. The controller verifies the request status and team capacity before adding the member and updating the request status.''

<pre>
TeamMember Controller JoinTeamRequest Team Participant
| | | | |
| PATCH /join_team_requests/:id/accept | |
|---------------->| | | |
| | | | |
| | find_request | | |
| |------------------->| | |
| |<-------------------| | |
| | | | |
| | action_allowed? | | |
| | (checks team membership) | |
| |------------------------------------+ |
| |<-----------------------------------| |
| | | | |
| | reply_status == PENDING? | |
| |------------------->| | |
| |<-------------------| | |
| | | | |
| | team.full?() | | |
| |------------------------------------+ |
| |<-----------------------------------| |
| | | | |
| | team.add_member (participant) | |
| |------------------------------------+--------------->|
| |<-----------------------------------|----------------|
| | | | |
| | reply_status = ACCEPTED | |
| |------------------->| | |
| | | save | |
| |<-------------------| | |
| | | | |
| 200 OK | | | |
|<----------------| | | |
</pre>

== Testing ==

=== Test Philosophy ===

Our testing approach follows the principle of testing behavior rather than implementation. Each test describes a user scenario and verifies that the system responds correctly. This makes tests resilient to refactoring and serves as executable documentation.

=== Test Coverage ===

Comprehensive RSpec tests are implemented in <code>spec/requests/api/v1/join_team_requests_spec.rb</code>. The tests cover all endpoints and authorization scenarios.

==== Test Categories ====

'''1. Index Tests'''

These tests verify that only administrators can access the full list of join team requests:

* Returns all join team requests for admin users with proper serialization
* Returns 403 Forbidden for non-admin users attempting to access the list

'''2. Show Tests'''

Show tests verify the authorization rules for viewing individual requests:

* Returns request details when accessed by the request creator
* Returns request details when accessed by a team member
* Returns 403 Forbidden when accessed by an unrelated user

'''3. Create Tests'''

Create tests cover both success cases and all validation scenarios:

* Creates request successfully with valid parameters and returns 201 Created
* Returns 422 when user tries to create a duplicate pending request
* Returns 422 when user already belongs to the target team
* Returns 422 when the target team is full
* Returns 422 when user is not a participant in the assignment

'''4. Update Tests'''

Update tests verify that only creators can modify their requests:

* Updates comments successfully for the request creator
* Returns 403 when a non-creator attempts to update

'''5. Destroy Tests'''

Destroy tests verify the deletion authorization:

* Deletes request successfully for the creator
* Returns 403 when a non-creator attempts to delete

'''6. Accept Tests'''

Accept tests cover the complex acceptance workflow:

* Accepts pending request, adds member to team, and updates status to ACCEPTED
* Returns 422 when attempting to accept an already-processed request
* Returns 422 when the target team is full
* Returns 403 when a non-team-member attempts to accept

'''7. Decline Tests'''

Decline tests mirror the accept tests for the decline workflow:

* Declines pending request and updates status to DECLINED
* Returns 422 when attempting to decline an already-processed request
* Returns 403 when a non-team-member attempts to decline

'''8. Filtering Endpoint Tests'''

These tests verify the query endpoints return correctly filtered results:

* <code>for_team</code> returns only requests for the specified team
* <code>by_user</code> returns only requests created by the specified user
* <code>pending</code> returns only requests with PENDING status

=== Running Tests ===

The following commands can be used to run the test suite:

<syntaxhighlight lang="bash">
# Run all join team request tests
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb

# Run with documentation format for readable output
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb --format documentation

# Run a specific test by line number
bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb:50

# Run tests with coverage report
COVERAGE=true bundle exec rspec spec/requests/api/v1/join_team_requests_spec.rb
</syntaxhighlight>

[[File:JoinTeamRequest_TestResults_Screenshot.png|700px|center|Test Results]]

''Figure 9: RSpec test output showing all tests passing. The documentation format displays each test case with its description, making it easy to understand what functionality is being verified.''

== Frontend Integration ==

=== Component Architecture ===

The frontend implementation uses React with TypeScript for type safety. Components are organized following a feature-based structure where all join team request related components are grouped together.

[[File:JoinTeamRequest_Frontend_Architecture.png|700px|center|Frontend Component Structure]]

''Figure 10: Frontend component hierarchy showing how the main JoinTeamRequests component composes smaller, focused components for list display, forms, and actions.''

=== React Components ===

The frontend implementation includes the following React components:

'''JoinTeamRequestList:''' Displays all join team requests with filtering capabilities. Users can filter by status (pending, accepted, declined) and search by team name or requester name. Each row in the list is clickable to expand and show the full request details including comments.

'''JoinTeamRequestForm:''' A form component for submitting new join requests. It includes team selection via a searchable dropdown and an optional comments field. The form performs client-side validation before submission.

'''JoinTeamRequestActions:''' A component containing Accept and Decline buttons for team members. These buttons are only rendered for users who are members of the target team. Clicking either button shows a confirmation modal before processing.

'''PendingRequestsBadge:''' A notification badge component that shows the count of pending requests. This appears in the navigation bar to alert team members of incoming requests that need attention.

=== API Integration ===

The frontend communicates with the backend using axios. All API calls are centralized in a service file for maintainability:

<syntaxhighlight lang="typescript">
// src/services/joinTeamRequestService.ts
import axiosClient from '../utils/axios_client';

interface JoinTeamRequestData {
team_id: number;
assignment_id: number;
comments?: string;
}

// Fetch all join team requests (admin only)
export const getJoinTeamRequests = () =>
axiosClient.get('/join_team_requests');

// Fetch requests for a specific team
export const getTeamRequests = (teamId: number) =>
axiosClient.get(`/join_team_requests/for_team/${teamId}`);

// Fetch requests by a specific user
export const getUserRequests = (userId: number) =>
axiosClient.get(`/join_team_requests/by_user/${userId}`);

// Fetch only pending requests
export const getPendingRequests = () =>
axiosClient.get('/join_team_requests/pending');

// Create a new join request
export const createJoinRequest = (data: JoinTeamRequestData) =>
axiosClient.post('/join_team_requests', data);

// Update request comments
export const updateJoinRequest = (id: number, comments: string) =>
axiosClient.patch(`/join_team_requests/${id}`, { comments });

// Delete a join request
export const deleteJoinRequest = (id: number) =>
axiosClient.delete(`/join_team_requests/${id}`);

// Accept a join request
export const acceptRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/accept`);

// Decline a join request
export const declineRequest = (id: number) =>
axiosClient.patch(`/join_team_requests/${id}/decline`);
</syntaxhighlight>

[[File:JoinTeamRequest_UI_Overview.png|800px|center|UI Overview]]

''Figure 11: Complete UI overview showing the join team requests interface. The left panel shows the list of requests with filtering options, and the right panel shows the details of a selected request with action buttons for team members.''

== Refactoring Improvements ==

This section highlights the key improvements made through refactoring, comparing the original implementation with our enhanced version.

=== Before: Scattered Authorization Logic ===

The original implementation had authorization checks scattered throughout each action method, leading to code duplication and inconsistency:

<syntaxhighlight lang="ruby">
# BEFORE: Authorization mixed with business logic
def accept
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... more logic
end

def decline
if current_user.role != 'student'
render json: { error: 'Unauthorized' }, status: :forbidden
return
end
# ... duplicate checks
end
</syntaxhighlight>

=== After: Centralized Authorization ===

Our refactored implementation centralizes all authorization in the <code>action_allowed?</code> method:

<syntaxhighlight lang="ruby">
# AFTER: Centralized authorization with clear rules
def action_allowed?
case params[:action]
when 'decline', 'accept'
return false unless current_user_has_student_privileges?
@join_team_request = JoinTeamRequest.find_by(id: params[:id]) unless @join_team_request
return false unless @join_team_request
current_user_is_team_member?
# ... other cases
end
end
</syntaxhighlight>

'''Benefits:'''
* Single source of truth for authorization rules
* Easier to audit and update security policies
* Reduced code duplication
* Consistent behavior across all endpoints

=== Before: Inconsistent Response Formats ===

The original implementation returned data in various formats, making frontend integration difficult:

<syntaxhighlight lang="ruby">
# BEFORE: Inconsistent response structure
def show
render json: @join_team_request.attributes
end

def index
render json: JoinTeamRequest.all.map { |r| { id: r.id, status: r.reply_status } }
end
</syntaxhighlight>

=== After: Serializer-Based Responses ===

Our implementation uses ActiveModel Serializers for consistent output:

<syntaxhighlight lang="ruby">
# AFTER: Consistent serialized responses
def show
render json: @join_team_request, serializer: JoinTeamRequestSerializer, status: :ok
end

def index
join_team_requests = JoinTeamRequest.includes(:participant, :team).all
render json: join_team_requests, each_serializer: JoinTeamRequestSerializer, status: :ok
end
</syntaxhighlight>

'''Benefits:'''
* Consistent JSON structure across all endpoints
* Easier frontend development with predictable data shapes
* Centralized control over what data is exposed
* Automatic handling of nested relationships

== Summary of Changes ==

=== Files Modified ===

{| class="wikitable"
|-
! File !! Changes !! Lines Modified
|-
| <code>app/controllers/api/v1/join_team_requests_controller.rb</code> || Complete rewrite with centralized authorization, new filtering endpoints, serializer integration, and comprehensive error handling || ~250
|-
| <code>app/models/join_team_request.rb</code> || Added status validation constants and updated association declarations || ~10
|-
| <code>app/serializers/join_team_request_serializer.rb</code> || New file - Custom serializer with nested participant and team data || ~25
|-
| <code>config/routes.rb</code> || Added collection routes for filtering and member routes for accept/decline actions || ~12
|-
| <code>spec/requests/api/v1/join_team_requests_spec.rb</code> || Comprehensive request specs covering all endpoints and authorization scenarios || ~400
|}

=== New Features ===

# '''Fine-grained authorization''' based on user roles (admin/student) and relationships (request creator/team member)
# '''Filtering endpoints''' (<code>for_team</code>, <code>by_user</code>, <code>pending</code>) for efficient data retrieval
# '''Accept/Decline workflow''' with team member validation and automatic team membership management
# '''Duplicate request prevention''' to avoid confusion from multiple pending requests to the same team
# '''Comprehensive error handling''' with user-friendly error messages suitable for display
# '''ActiveModel Serializer integration''' for consistent, predictable JSON responses
# '''Full test coverage''' for all endpoints and authorization scenarios

== Team Members ==

{| class="wikitable"
|-
! Name !! Unity ID !! Contribution
|-
| [Team Member 1] || [unity_id] || Backend controller implementation, authorization logic
|-
| [Team Member 2] || [unity_id] || Model development, serializer implementation
|-
| [Team Member 3] || [unity_id] || Test coverage, documentation, code review
|-
| [Team Member 4] || [unity_id] || Frontend integration, UI components
|}

== Conclusion ==

This project successfully delivers a complete, production-ready implementation of the JoinTeamRequests feature for the Expertiza reimplementation. The key achievements include:

* '''Security:''' Fine-grained authorization ensures users can only access and modify resources appropriate to their role
* '''Usability:''' Filtering endpoints and consistent response formats make the API easy to consume
* '''Maintainability:''' Centralized logic, comprehensive tests, and clear documentation facilitate future development
* '''Reliability:''' Thorough testing covers both happy paths and edge cases

The implementation follows Rails best practices and integrates seamlessly with the existing Expertiza codebase, providing a solid foundation for team formation workflows in the system.

== References ==

# [https://wiki.expertiza.ncsu.edu/ Expertiza Wiki] - Project documentation and guidelines
# [https://api.rubyonrails.org/ Rails API Documentation] - Ruby on Rails framework reference
# [https://rspec.info/documentation/ RSpec Documentation] - Testing framework documentation
# [https://github.com/rails-api/active_model_serializers ActiveModel Serializers] - JSON serialization library
# [https://github.com/expertiza/reimplementation-back-end Expertiza Reimplementation Backend] - Source repository
# [https://github.com/expertiza/reimplementation-front-end Expertiza Reimplementation Frontend] - Frontend repository

[[Category:CSC/ECE 517]]
[[Category:Fall 2025]]
[[Category:Expertiza]]

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-11-11T02:24:08Z

Dshah24:

= E2565. Integration of JoinTeamRequests =

== Overview ==

This document describes the design and implementation plan for integrating JoinTeamRequests functionality in Expertiza. The feature enables students to respond to teammate advertisements by creating join team requests, which topic holders can then approve or decline. This integration will complete the teammate advertisement workflow by connecting the advertisement creation (already implemented) with the join team request flow.

=== Problem Statement ===

Currently, Expertiza supports teammate advertisements for assignments with topics. Topic holders can create advertisements on the "Your Team" page. However, the complete flow for responding to advertisements and managing join team requests is not fully integrated. The following gaps exist:

# The join_team_requests_controller has action privilege checks scattered across methods instead of using a centralized `action_allowed?` method
# There is no frontend UI for viewing advertisements on the Signup Sheet page
# There is no UI for creating join team requests when responding to advertisements
# The "Received Requests" section is missing from the StudentTeamView page
# There is no method to accept join team requests (only decline exists)
# The controller needs better integration with the frontend

=== Goals ===

# Refactor the join_team_requests_controller to use a single `action_allowed?` method for privilege checking
# Add a trumpet icon on the Signup Sheet page to indicate when advertisements exist for topics
# Create a frontend UI for viewing advertisements and creating join team requests
# Add a "Received Requests" section to StudentTeamView.tsx for managing incoming join team requests
# Implement an accept method for join team requests
# Ensure proper validation that teams cannot accept requests when full
# Conduct comprehensive testing of the entire flow

== Design ==

=== Backend Design ===

==== Controller Refactoring ====

The `Api::V1::JoinTeamRequestsController` currently has privilege checks scattered across methods:

- `index` method checks for administrator role directly
- `action_allowed?` only checks if user is a student

'''Refactored Design:'''

The `action_allowed?` method will be enhanced to handle different actions based on the action being performed:

<source lang="ruby">
def action_allowed?
case action_name.to_sym
when :index
@current_user.administrator?
when :create, :show, :update, :destroy, :decline, :accept
@current_user.student?
else
false
end
end
</source>

All methods will rely on this centralized privilege check, removing individual checks from methods like `index`.

==== New Methods ====

'''1. Accept Method'''

Add a new `accept` method to handle accepting join team requests:

<source lang="ruby">
# PATCH/PUT api/v1/join_team_requests/:id/accept
# Accepts a join team request and adds the participant to the team
def accept
team = @join_team_request.team

# Check if team is full
if team.full?
return render json: { error: 'This team is full.' }, status: :unprocessable_entity
end

# Check if participant is already on the team
if team.participants.include?(@join_team_request.participant)
return render json: { error: 'Participant already belongs to the team' }, status: :unprocessable_entity
end

ActiveRecord::Base.transaction do
# Add participant to team
result = team.add_member(@join_team_request.participant)

if result[:success]
# Update request status
@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'JoinTeamRequest accepted successfully', join_team_request: @join_team_request }, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
raise ActiveRecord::Rollback
end
end
rescue => e
render json: { error: "Failed to accept request: #{e.message}" }, status: :unprocessable_entity
end
</source>

'''2. Get Join Team Requests for Team'''

Add a method to fetch all join team requests for a specific team (for the "Received Requests" section):

<source lang="ruby">
# GET api/v1/join_team_requests/team/:team_id
# Gets all join team requests for a specific team
def team_requests
team = Team.find(params[:team_id])

# Verify current user is a member of the team
unless team.participants.exists?(user_id: @current_user.id)
return render json: { error: 'Unauthorized' }, status: :unauthorized
end

join_team_requests = JoinTeamRequest.where(team_id: params[:team_id])
.includes(:participant => :user)
.order(created_at: :desc)

render json: join_team_requests, status: :ok
end
</source>

'''3. Get Advertisements for Assignment'''

Add a method to fetch all advertisements for an assignment (for the Signup Sheet page):

<source lang="ruby">
# GET api/v1/signed_up_teams/advertisements/:assignment_id
# Gets all advertisements for an assignment
def advertisements
assignment = Assignment.find(params[:assignment_id])
signed_up_teams = SignedUpTeam.joins(:team, :sign_up_topic)
.where(sign_up_topics: { assignment_id: params[:assignment_id] })
.where(advertise_for_partner: true)
.includes(:team, :sign_up_topic)

advertisements = signed_up_teams.map do |sut|
{
id: sut.id,
team_id: sut.team_id,
team_name: sut.team.name,
topic_id: sut.sign_up_topic_id,
topic_name: sut.sign_up_topic.topic_name,
comments_for_advertisement: sut.comments_for_advertisement,
created_at: sut.created_at
}
end

render json: advertisements, status: :ok
end
</source>

==== Model Updates ====

The `JoinTeamRequest` model needs to establish proper associations:

<source lang="ruby">
class JoinTeamRequest < ApplicationRecord
belongs_to :team
belongs_to :participant

ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }

scope :pending, -> { where(reply_status: 'PENDING') }
scope :for_team, ->(team_id) { where(team_id: team_id) }
end
</source>

==== Routes Updates ====

Add new routes for the additional endpoints:

<source lang="ruby">
resources :join_team_requests do
collection do
get 'team/:team_id', to: 'join_team_requests#team_requests'
post 'decline/:id', to: 'join_team_requests#decline'
post 'accept/:id', to: 'join_team_requests#accept'
end
end

resources :signed_up_teams do
collection do
get 'advertisements/:assignment_id', to: 'signed_up_teams#advertisements'
end
member do
post :create_advertisement
patch :update_advertisement
delete :remove_advertisement
end
end

</source>

=== Frontend Design ===

==== Signup Sheet Page Enhancement ====

Create a new component or enhance existing signup sheet to display advertisements:

'''Component: SignupSheet.tsx'''

This component will:

- Display all topics for an assignment
- Show a trumpet icon (🔔) next to topics that have advertisements
- Allow users to click on topics with advertisements to view details
- Provide a modal/dialog to view advertisement details and create a join team request

<source lang="typescript">
interface Advertisement {
id: number;
team_id: number;
team_name: string;
topic_id: number;
topic_name: string;
comments_for_advertisement: string;
created_at: string;
}

interface SignUpTopic {
id: number;
topic_name: string;
topic_identifier: string;
max_choosers: number;
description?: string;
has_advertisement?: boolean;
advertisement?: Advertisement;
}

</source>

The UI will show:

- A table/list of topics
- Trumpet icon indicator for topics with advertisements
- Click handler to open advertisement details modal

==== Join Team Request Modal ====

Create a modal component for creating join team requests:

'''Component: JoinTeamRequestModal.tsx'''

This modal will:

- Display advertisement details (team name, topic, desired qualifications)
- Provide a text area for comments (optional)
- Show a "Send Request" button
- Handle form submission and API calls

<source lang="typescript">
interface JoinTeamRequestModalProps {
show: boolean;
onHide: () => void;
advertisement: Advertisement;
assignmentId: number;
onSuccess: () => void;
}
</source>

==== StudentTeamView Enhancement ====

Add a "Received Requests" section to `StudentTeamView.tsx`:

'''Section: Received Join Team Requests'''

This section will:

- Display all pending join team requests for the current team
- Show request details: requester name, email, comments, date
- Provide "Approve" and "Decline" buttons for each request
- Disable approve button if team is full
- Show status for non-pending requests

<source lang="typescript">
interface JoinTeamRequest {
id: number;
participant_id: number;
team_id: number;
comments: string;
reply_status: 'PENDING' | 'ACCEPTED' | 'DECLINED';
created_at: string;
participant: {
id: number;
user: {
id: number;
name: string;
full_name: string;
email: string;
};
};
}
</source>

The UI structure will be similar to the existing "Received Invitations" section, with:

- Table displaying request information
- Action buttons (Approve/Decline) for pending requests
- Status display for processed requests

==== API Hooks ====

Create or extend hooks for join team requests:

'''File: hooks/useJoinTeamRequest.ts'''

<source lang="typescript">
export const useJoinTeamRequest = () => {
const createRequestAPI = useAPI();
const acceptRequestAPI = useAPI();
const declineRequestAPI = useAPI();
const fetchTeamRequestsAPI = useAPI();
const fetchAdvertisementsAPI = useAPI();

const createJoinTeamRequest = (teamId: number, assignmentId: number, comments?: string) =>
createRequestAPI.sendRequest({
url: `/join_team_requests`,
method: 'POST',
data: { team_id: teamId, assignment_id: assignmentId, comments }
});

const acceptJoinTeamRequest = (requestId: number) =>
acceptRequestAPI.sendRequest({
url: `/join_team_requests/accept/${requestId}`,
method: 'POST'
});

const declineJoinTeamRequest = (requestId: number) =>
declineRequestAPI.sendRequest({
url: `/join_team_requests/decline/${requestId}`,
method: 'POST'
});

const fetchTeamRequests = (teamId: number) =>
fetchTeamRequestsAPI.sendRequest({
url: `/join_team_requests/team/${teamId}`
});

const fetchAdvertisements = (assignmentId: number) =>
fetchAdvertisementsAPI.sendRequest({
url: `/signed_up_teams/advertisements/${assignmentId}`
});

return {
createJoinTeamRequest,
acceptJoinTeamRequest,
declineJoinTeamRequest,
fetchTeamRequests,
fetchAdvertisements,
createRequestAPI,
acceptRequestAPI,
declineRequestAPI,
fetchTeamRequestsAPI,
fetchAdvertisementsAPI
};
};

</source>

== Implementation Plan ==

=== Phase 1: Backend Refactoring ===

# '''Refactor action_allowed? method'''
## Update `Api::V1::JoinTeamRequestsController#action_allowed?` to handle all actions
## Remove individual privilege checks from `index` method
## Ensure all actions go through the centralized check
# '''Add accept method'''
## Implement `accept` method with team full validation
## Add transaction handling for atomic operations
## Update request status to ACCEPTED
## Add participant to team using `team.add_member`
# '''Add team_requests method'''
## Implement method to fetch requests for a team
## Add authorization check (user must be team member)
## Include participant and user data in response
# '''Add advertisements method to SignedUpTeamsController'''
## Implement method to fetch all advertisements for an assignment
## Join with teams and sign_up_topics
## Return formatted advertisement data
# '''Update JoinTeamRequest model'''
## Add `belongs_to :team` association
## Add scopes for filtering
## Update validations
# '''Update routes'''
## Add routes for new endpoints
## Ensure RESTful conventions

=== Phase 2: Frontend - Signup Sheet ===

# '''Create SignupSheet component (if not exists)'''
## Display topics for an assignment
## Fetch advertisements for the assignment
## Map advertisements to topics
## Display trumpet icon for topics with advertisements
# '''Create JoinTeamRequestModal component'''
## Design modal UI
## Implement form with comments field
## Add submit handler
## Handle success/error states
# '''Integrate modal with SignupSheet'''
## Add click handler for topics with advertisements
## Open modal with advertisement details
## Handle modal close

=== Phase 3: Frontend - StudentTeamView ===

# '''Add Received Requests section'''
## Create section similar to "Received Invitations"
## Fetch join team requests for current team
## Display requests in table format
# '''Implement approve/decline functionality'''
## Add approve button handler
## Add decline button handler
## Check team full status before allowing approve
## Update UI after actions
# '''Add useJoinTeamRequest hook'''
## Create hook file
## Implement all API methods
## Export hook for use in components

=== Phase 4: Integration and Testing ===

# '''End-to-end testing'''
## Test advertisement creation → request creation → approval flow
## Test decline flow
## Test team full validation
## Test authorization checks
# '''Unit testing'''
## Test controller methods
## Test model validations
## Test frontend components
# '''Integration testing'''
## Test API endpoints
## Test frontend-backend integration
## Test error handling

== Files Changed/Added ==

=== Backend Files ===

'''Modified:'''

- `app/controllers/api/v1/join_team_requests_controller.rb` - Refactor action_allowed?, add accept and team_requests methods
- `app/controllers/api/v1/signed_up_teams_controller.rb` - Add advertisements method
- `app/models/join_team_request.rb` - Add associations and scopes
- `config/routes.rb` - Add new routes

'''Added:'''

- `spec/requests/api/v1/join_team_requests_spec.rb` - Request specs for new methods
- `spec/models/join_team_request_spec.rb` - Model specs

=== Frontend Files ===

'''Modified:'''

- `src/pages/Student Teams/StudentTeamView.tsx` - Add Received Requests section
- `src/hooks/useStudentTeam.ts` - Add join team request methods (or create new hook)

'''Added:'''

- `src/pages/SignUpSheet/SignUpSheet.tsx` - Signup sheet component with advertisement indicators
- `src/pages/SignUpSheet/JoinTeamRequestModal.tsx` - Modal for creating join team requests
- `src/hooks/useJoinTeamRequest.ts` - Hook for join team request API calls
- `src/pages/SignUpSheet/SignUpSheet.module.css` - Styles for signup sheet
- `src/pages/SignUpSheet/JoinTeamRequestModal.module.css` - Styles for modal

== Testing Plan ==

=== Backend Testing ===

==== Unit Tests ====

# '''JoinTeamRequestsController Tests'''

## Test action_allowed? for different actions and user roles
## Test accept method with valid request
## Test accept method when team is full
## Test accept method when participant already on team
## Test team_requests method authorization
## Test team_requests method returns correct data
# '''SignedUpTeamsController Tests'''
## Test advertisements method returns correct data
## Test advertisements method filters correctly
# '''JoinTeamRequest Model Tests'''
## Test associations
## Test validations
## Test scopes

==== Integration Tests ====

# '''End-to-End Flow Tests'''
## Create advertisement → Create join request → Accept request
## Create advertisement → Create join request → Decline request
## Test team full validation prevents acceptance
## Test authorization prevents unauthorized access

=== Frontend Testing ===

==== Component Tests ====

# '''SignUpSheet Component'''
## Test advertisement indicators display correctly
## Test modal opens on click
## Test data fetching
# '''JoinTeamRequestModal Component'''
## Test form submission
## Test validation
## Test success/error handling
# '''StudentTeamView Component'''
## Test Received Requests section displays
## Test approve functionality
## Test decline functionality
## Test team full validation

==== Integration Tests ====

# '''API Integration'''
## Test all API calls work correctly
## Test error handling
## Test loading states

== Edge Cases and Error Handling ==

=== Backend Edge Cases ===

# '''Team Full Validation'''

- Check team capacity before accepting request
- Return appropriate error message
- Prevent race conditions with database transactions

# '''Authorization'''

- Verify user is team member before showing requests
- Verify user is student before creating requests
- Verify user is administrator before viewing all requests

# '''Duplicate Requests'''

- Prevent creating duplicate requests from same participant
- Handle case where participant already on team

# '''Concurrent Modifications'''

- Use transactions for atomic operations
- Handle race conditions in team membership updates

=== Frontend Edge Cases ===

# '''Network Errors'''

- Display appropriate error messages
- Handle timeout scenarios
- Provide retry mechanisms

# '''Empty States'''

- Show appropriate messages when no advertisements exist
- Show appropriate messages when no requests exist

# '''Loading States'''

- Display loading indicators during API calls
- Prevent multiple simultaneous requests

# '''Form Validation'''

- Validate required fields
- Provide user feedback for errors

== Security Considerations ==

# '''Authorization Checks'''

- All endpoints must verify user permissions
- Team members can only see requests for their team
- Students can only create requests for themselves

# '''Input Validation'''

- Sanitize all user inputs
- Validate team_id and assignment_id parameters
- Prevent SQL injection through parameterized queries

# '''Rate Limiting'''

- Consider rate limiting for request creation
- Prevent spam requests

== Future Enhancements ==

# Email notifications when join team requests are created

# Email notifications when requests are approved/declined

# Bulk approve/decline functionality

# Request history and audit trail

# Advanced filtering and search for requests

== References ==

- Expertiza Wiki: E2252. Refactor auth controller.rb & password retrieval controller.rb
- Rails API Documentation
- React Router Documentation
- Expertiza Codebase: Existing invitation and team management implementations

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-11-11T02:21:20Z

Dshah24:

= E2565. Integration of JoinTeamRequests =

== Overview ==

This document describes the design and implementation plan for integrating JoinTeamRequests functionality in Expertiza. The feature enables students to respond to teammate advertisements by creating join team requests, which topic holders can then approve or decline. This integration will complete the teammate advertisement workflow by connecting the advertisement creation (already implemented) with the join team request flow.

=== Problem Statement ===

Currently, Expertiza supports teammate advertisements for assignments with topics. Topic holders can create advertisements on the "Your Team" page. However, the complete flow for responding to advertisements and managing join team requests is not fully integrated. The following gaps exist:

# The join_team_requests_controller has action privilege checks scattered across methods instead of using a centralized `action_allowed?` method
# There is no frontend UI for viewing advertisements on the Signup Sheet page
# There is no UI for creating join team requests when responding to advertisements
# The "Received Requests" section is missing from the StudentTeamView page
# There is no method to accept join team requests (only decline exists)
# The controller needs better integration with the frontend

=== Goals ===

# Refactor the join_team_requests_controller to use a single `action_allowed?` method for privilege checking
# Add a trumpet icon on the Signup Sheet page to indicate when advertisements exist for topics
# Create a frontend UI for viewing advertisements and creating join team requests
# Add a "Received Requests" section to StudentTeamView.tsx for managing incoming join team requests
# Implement an accept method for join team requests
# Ensure proper validation that teams cannot accept requests when full
# Conduct comprehensive testing of the entire flow

== Design ==

=== Backend Design ===

==== Controller Refactoring ====

The `Api::V1::JoinTeamRequestsController` currently has privilege checks scattered across methods:

- `index` method checks for administrator role directly
- `action_allowed?` only checks if user is a student

'''Refactored Design:'''

The `action_allowed?` method will be enhanced to handle different actions based on the action being performed:

<source lang="ruby">
def action_allowed?
case action_name.to_sym
when :index
@current_user.administrator?
when :create, :show, :update, :destroy, :decline, :accept
@current_user.student?
else
false
end
end
</source>

All methods will rely on this centralized privilege check, removing individual checks from methods like `index`.

==== New Methods ====

'''1. Accept Method'''

Add a new `accept` method to handle accepting join team requests:

<source lang="ruby">
# PATCH/PUT api/v1/join_team_requests/:id/accept
# Accepts a join team request and adds the participant to the team
def accept
team = @join_team_request.team

# Check if team is full
if team.full?
return render json: { error: 'This team is full.' }, status: :unprocessable_entity
end

# Check if participant is already on the team
if team.participants.include?(@join_team_request.participant)
return render json: { error: 'Participant already belongs to the team' }, status: :unprocessable_entity
end

ActiveRecord::Base.transaction do
# Add participant to team
result = team.add_member(@join_team_request.participant)

if result[:success]
# Update request status
@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'JoinTeamRequest accepted successfully', join_team_request: @join_team_request }, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
raise ActiveRecord::Rollback
end
end
rescue => e
render json: { error: "Failed to accept request: #{e.message}" }, status: :unprocessable_entity
end
</source>

'''2. Get Join Team Requests for Team'''

Add a method to fetch all join team requests for a specific team (for the "Received Requests" section):

<source lang="ruby">
# GET api/v1/join_team_requests/team/:team_id
# Gets all join team requests for a specific team
def team_requests
team = Team.find(params[:team_id])

# Verify current user is a member of the team
unless team.participants.exists?(user_id: @current_user.id)
return render json: { error: 'Unauthorized' }, status: :unauthorized
end

join_team_requests = JoinTeamRequest.where(team_id: params[:team_id])
.includes(:participant => :user)
.order(created_at: :desc)

render json: join_team_requests, status: :ok
end
</source>

'''3. Get Advertisements for Assignment'''

Add a method to fetch all advertisements for an assignment (for the Signup Sheet page):

<source lang="ruby">
# GET api/v1/signed_up_teams/advertisements/:assignment_id
# Gets all advertisements for an assignment
def advertisements
assignment = Assignment.find(params[:assignment_id])
signed_up_teams = SignedUpTeam.joins(:team, :sign_up_topic)
.where(sign_up_topics: { assignment_id: params[:assignment_id] })
.where(advertise_for_partner: true)
.includes(:team, :sign_up_topic)

advertisements = signed_up_teams.map do |sut|
{
id: sut.id,
team_id: sut.team_id,
team_name: sut.team.name,
topic_id: sut.sign_up_topic_id,
topic_name: sut.sign_up_topic.topic_name,
comments_for_advertisement: sut.comments_for_advertisement,
created_at: sut.created_at
}
end

render json: advertisements, status: :ok
end
</source>

==== Model Updates ====

The `JoinTeamRequest` model needs to establish proper associations:

<source lang="ruby">
class JoinTeamRequest < ApplicationRecord
belongs_to :team
belongs_to :participant

ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }

scope :pending, -> { where(reply_status: 'PENDING') }
scope :for_team, ->(team_id) { where(team_id: team_id) }
end
</source>

==== Routes Updates ====

Add new routes for the additional endpoints:

<source lang="ruby">
resources :join_team_requests do
collection do
get 'team/:team_id', to: 'join_team_requests#team_requests'
post 'decline/:id', to: 'join_team_requests#decline'
post 'accept/:id', to: 'join_team_requests#accept'
end
end

resources :signed_up_teams do
collection do
get 'advertisements/:assignment_id', to: 'signed_up_teams#advertisements'
end
member do
post :create_advertisement
patch :update_advertisement
delete :remove_advertisement
end
end

</source>

=== Frontend Design ===

==== Signup Sheet Page Enhancement ====

Create a new component or enhance existing signup sheet to display advertisements:

'''Component: SignupSheet.tsx'''

This component will:

- Display all topics for an assignment
- Show a trumpet icon (🔔) next to topics that have advertisements
- Allow users to click on topics with advertisements to view details
- Provide a modal/dialog to view advertisement details and create a join team request

<source lang="typescript">
interface Advertisement {
id: number;
team_id: number;
team_name: string;
topic_id: number;
topic_name: string;
comments_for_advertisement: string;
created_at: string;
}

interface SignUpTopic {
id: number;
topic_name: string;
topic_identifier: string;
max_choosers: number;
description?: string;
has_advertisement?: boolean;
advertisement?: Advertisement;
}

</source>

The UI will show:

- A table/list of topics
- Trumpet icon indicator for topics with advertisements
- Click handler to open advertisement details modal

==== Join Team Request Modal ====

Create a modal component for creating join team requests:

'''Component: JoinTeamRequestModal.tsx'''

This modal will:

- Display advertisement details (team name, topic, desired qualifications)
- Provide a text area for comments (optional)
- Show a "Send Request" button
- Handle form submission and API calls

<source lang="typescript">
interface JoinTeamRequestModalProps {
show: boolean;
onHide: () => void;
advertisement: Advertisement;
assignmentId: number;
onSuccess: () => void;
}
</source>

==== StudentTeamView Enhancement ====

Add a "Received Requests" section to `StudentTeamView.tsx`:

'''Section: Received Join Team Requests'''

This section will:

- Display all pending join team requests for the current team
- Show request details: requester name, email, comments, date
- Provide "Approve" and "Decline" buttons for each request
- Disable approve button if team is full
- Show status for non-pending requests

<source lang="typescript">
interface JoinTeamRequest {
id: number;
participant_id: number;
team_id: number;
comments: string;
reply_status: 'PENDING' | 'ACCEPTED' | 'DECLINED';
created_at: string;
participant: {
id: number;
user: {
id: number;
name: string;
full_name: string;
email: string;
};
};
}
</source>

The UI structure will be similar to the existing "Received Invitations" section, with:

- Table displaying request information
- Action buttons (Approve/Decline) for pending requests
- Status display for processed requests

==== API Hooks ====

Create or extend hooks for join team requests:

'''File: hooks/useJoinTeamRequest.ts'''

<source lang="typescript">
export const useJoinTeamRequest = () => {
const createRequestAPI = useAPI();
const acceptRequestAPI = useAPI();
const declineRequestAPI = useAPI();
const fetchTeamRequestsAPI = useAPI();
const fetchAdvertisementsAPI = useAPI();

const createJoinTeamRequest = (teamId: number, assignmentId: number, comments?: string) =>
createRequestAPI.sendRequest({
url: `/join_team_requests`,
method: 'POST',
data: { team_id: teamId, assignment_id: assignmentId, comments }
});

const acceptJoinTeamRequest = (requestId: number) =>
acceptRequestAPI.sendRequest({
url: `/join_team_requests/accept/${requestId}`,
method: 'POST'
});

const declineJoinTeamRequest = (requestId: number) =>
declineRequestAPI.sendRequest({
url: `/join_team_requests/decline/${requestId}`,
method: 'POST'
});

const fetchTeamRequests = (teamId: number) =>
fetchTeamRequestsAPI.sendRequest({
url: `/join_team_requests/team/${teamId}`
});

const fetchAdvertisements = (assignmentId: number) =>
fetchAdvertisementsAPI.sendRequest({
url: `/signed_up_teams/advertisements/${assignmentId}`
});

return {
createJoinTeamRequest,
acceptJoinTeamRequest,
declineJoinTeamRequest,
fetchTeamRequests,
fetchAdvertisements,
createRequestAPI,
acceptRequestAPI,
declineRequestAPI,
fetchTeamRequestsAPI,
fetchAdvertisementsAPI
};
};

</source>

== Implementation Plan ==

=== Phase 1: Backend Refactoring ===

# '''Refactor action_allowed? method'''
## Update `Api::V1::JoinTeamRequestsController#action_allowed?` to handle all actions
## Remove individual privilege checks from `index` method
## Ensure all actions go through the centralized check
# '''Add accept method'''
## Implement `accept` method with team full validation
## Add transaction handling for atomic operations
## Update request status to ACCEPTED
## Add participant to team using `team.add_member`
# '''Add team_requests method'''
## Implement method to fetch requests for a team
## Add authorization check (user must be team member)
## Include participant and user data in response
# '''Add advertisements method to SignedUpTeamsController'''
## Implement method to fetch all advertisements for an assignment
## Join with teams and sign_up_topics
## Return formatted advertisement data
# '''Update JoinTeamRequest model'''
## Add `belongs_to :team` association
## Add scopes for filtering
## Update validations
# '''Update routes'''
## Add routes for new endpoints
## Ensure RESTful conventions

=== Phase 2: Frontend - Signup Sheet ===

# '''Create SignupSheet component (if not exists)'''

## Display topics for an assignment

## Fetch advertisements for the assignment

## Map advertisements to topics

## Display trumpet icon for topics with advertisements

# '''Create JoinTeamRequestModal component'''

## Design modal UI

## Implement form with comments field

## Add submit handler

## Handle success/error states

# '''Integrate modal with SignupSheet'''

## Add click handler for topics with advertisements

## Open modal with advertisement details

## Handle modal close

=== Phase 3: Frontend - StudentTeamView ===

# '''Add Received Requests section'''

## Create section similar to "Received Invitations"

## Fetch join team requests for current team

## Display requests in table format

# '''Implement approve/decline functionality'''

## Add approve button handler

## Add decline button handler

## Check team full status before allowing approve

## Update UI after actions

# '''Add useJoinTeamRequest hook'''

## Create hook file

## Implement all API methods

## Export hook for use in components

=== Phase 4: Integration and Testing ===

# '''End-to-end testing'''

## Test advertisement creation → request creation → approval flow

## Test decline flow

## Test team full validation

## Test authorization checks

# '''Unit testing'''

## Test controller methods

## Test model validations

## Test frontend components

# '''Integration testing'''

## Test API endpoints

## Test frontend-backend integration

## Test error handling

== Files Changed/Added ==

=== Backend Files ===

'''Modified:'''

- `app/controllers/api/v1/join_team_requests_controller.rb` - Refactor action_allowed?, add accept and team_requests methods
- `app/controllers/api/v1/signed_up_teams_controller.rb` - Add advertisements method
- `app/models/join_team_request.rb` - Add associations and scopes
- `config/routes.rb` - Add new routes

'''Added:'''

- `spec/requests/api/v1/join_team_requests_spec.rb` - Request specs for new methods
- `spec/models/join_team_request_spec.rb` - Model specs

=== Frontend Files ===

'''Modified:'''

- `src/pages/Student Teams/StudentTeamView.tsx` - Add Received Requests section
- `src/hooks/useStudentTeam.ts` - Add join team request methods (or create new hook)

'''Added:'''

- `src/pages/SignUpSheet/SignUpSheet.tsx` - Signup sheet component with advertisement indicators
- `src/pages/SignUpSheet/JoinTeamRequestModal.tsx` - Modal for creating join team requests
- `src/hooks/useJoinTeamRequest.ts` - Hook for join team request API calls
- `src/pages/SignUpSheet/SignUpSheet.module.css` - Styles for signup sheet
- `src/pages/SignUpSheet/JoinTeamRequestModal.module.css` - Styles for modal

== Testing Plan ==

=== Backend Testing ===

==== Unit Tests ====

# '''JoinTeamRequestsController Tests'''

## Test action_allowed? for different actions and user roles

## Test accept method with valid request

## Test accept method when team is full

## Test accept method when participant already on team

## Test team_requests method authorization

## Test team_requests method returns correct data

# '''SignedUpTeamsController Tests'''

## Test advertisements method returns correct data

## Test advertisements method filters correctly

# '''JoinTeamRequest Model Tests'''

## Test associations

## Test validations

## Test scopes

==== Integration Tests ====

# '''End-to-End Flow Tests'''

## Create advertisement → Create join request → Accept request

## Create advertisement → Create join request → Decline request

## Test team full validation prevents acceptance

## Test authorization prevents unauthorized access

=== Frontend Testing ===

==== Component Tests ====

# '''SignUpSheet Component'''

## Test advertisement indicators display correctly

## Test modal opens on click

## Test data fetching

# '''JoinTeamRequestModal Component'''

## Test form submission

## Test validation

## Test success/error handling

# '''StudentTeamView Component'''

## Test Received Requests section displays

## Test approve functionality

## Test decline functionality

## Test team full validation

==== Integration Tests ====

# '''API Integration'''

## Test all API calls work correctly

## Test error handling

## Test loading states

== Edge Cases and Error Handling ==

=== Backend Edge Cases ===

# '''Team Full Validation'''

- Check team capacity before accepting request
- Return appropriate error message
- Prevent race conditions with database transactions

# '''Authorization'''

- Verify user is team member before showing requests
- Verify user is student before creating requests
- Verify user is administrator before viewing all requests

# '''Duplicate Requests'''

- Prevent creating duplicate requests from same participant
- Handle case where participant already on team

# '''Concurrent Modifications'''

- Use transactions for atomic operations
- Handle race conditions in team membership updates

=== Frontend Edge Cases ===

# '''Network Errors'''

- Display appropriate error messages
- Handle timeout scenarios
- Provide retry mechanisms

# '''Empty States'''

- Show appropriate messages when no advertisements exist
- Show appropriate messages when no requests exist

# '''Loading States'''

- Display loading indicators during API calls
- Prevent multiple simultaneous requests

# '''Form Validation'''

- Validate required fields
- Provide user feedback for errors

== Security Considerations ==

# '''Authorization Checks'''

- All endpoints must verify user permissions
- Team members can only see requests for their team
- Students can only create requests for themselves

# '''Input Validation'''

- Sanitize all user inputs
- Validate team_id and assignment_id parameters
- Prevent SQL injection through parameterized queries

# '''Rate Limiting'''

- Consider rate limiting for request creation
- Prevent spam requests

== Future Enhancements ==

# Email notifications when join team requests are created

# Email notifications when requests are approved/declined

# Bulk approve/decline functionality

# Request history and audit trail

# Advanced filtering and search for requests

== References ==

- Expertiza Wiki: E2252. Refactor auth controller.rb & password retrieval controller.rb
- Rails API Documentation
- React Router Documentation
- Expertiza Codebase: Existing invitation and team management implementations

CSC/ECE 517 Fall 2025 - E2565. Integration of JoinTeamRequests

2025-11-11T02:19:21Z

Dshah24:

= E2565. Integration of JoinTeamRequests =

== Overview ==

This document describes the design and implementation plan for integrating JoinTeamRequests functionality in Expertiza. The feature enables students to respond to teammate advertisements by creating join team requests, which topic holders can then approve or decline. This integration will complete the teammate advertisement workflow by connecting the advertisement creation (already implemented) with the join team request flow.

=== Problem Statement ===

Currently, Expertiza supports teammate advertisements for assignments with topics. Topic holders can create advertisements on the "Your Team" page. However, the complete flow for responding to advertisements and managing join team requests is not fully integrated. The following gaps exist:

# The join_team_requests_controller has action privilege checks scattered across methods instead of using a centralized `action_allowed?` method
# There is no frontend UI for viewing advertisements on the Signup Sheet page
# There is no UI for creating join team requests when responding to advertisements
# The "Received Requests" section is missing from the StudentTeamView page
# There is no method to accept join team requests (only decline exists)
# The controller needs better integration with the frontend

=== Goals ===

# Refactor the join_team_requests_controller to use a single `action_allowed?` method for privilege checking
# Add a trumpet icon on the Signup Sheet page to indicate when advertisements exist for topics
# Create a frontend UI for viewing advertisements and creating join team requests
# Add a "Received Requests" section to StudentTeamView.tsx for managing incoming join team requests
# Implement an accept method for join team requests
# Ensure proper validation that teams cannot accept requests when full
# Conduct comprehensive testing of the entire flow

== Design ==

=== Backend Design ===

==== Controller Refactoring ====

The `Api::V1::JoinTeamRequestsController` currently has privilege checks scattered across methods:

- `index` method checks for administrator role directly
- `action_allowed?` only checks if user is a student

'''Refactored Design:'''

The `action_allowed?` method will be enhanced to handle different actions based on the action being performed:

<source lang="ruby">
def action_allowed?
case action_name.to_sym
when :index
@current_user.administrator?
when :create, :show, :update, :destroy, :decline, :accept
@current_user.student?
else
false
end
end
</source>

All methods will rely on this centralized privilege check, removing individual checks from methods like `index`.

==== New Methods ====

'''1. Accept Method'''

Add a new `accept` method to handle accepting join team requests:

<source lang="ruby">
# PATCH/PUT api/v1/join_team_requests/:id/accept
# Accepts a join team request and adds the participant to the team
def accept
team = @join_team_request.team

# Check if team is full
if team.full?
return render json: { error: 'This team is full.' }, status: :unprocessable_entity
end

# Check if participant is already on the team
if team.participants.include?(@join_team_request.participant)
return render json: { error: 'Participant already belongs to the team' }, status: :unprocessable_entity
end

ActiveRecord::Base.transaction do
# Add participant to team
result = team.add_member(@join_team_request.participant)

if result[:success]
# Update request status
@join_team_request.update!(reply_status: ACCEPTED)
render json: { message: 'JoinTeamRequest accepted successfully', join_team_request: @join_team_request }, status: :ok
else
render json: { error: result[:error] }, status: :unprocessable_entity
raise ActiveRecord::Rollback
end
end
rescue => e
render json: { error: "Failed to accept request: #{e.message}" }, status: :unprocessable_entity
end
</source>

'''2. Get Join Team Requests for Team'''

Add a method to fetch all join team requests for a specific team (for the "Received Requests" section):

<source lang="ruby">
# GET api/v1/join_team_requests/team/:team_id
# Gets all join team requests for a specific team
def team_requests
team = Team.find(params[:team_id])

# Verify current user is a member of the team
unless team.participants.exists?(user_id: @current_user.id)
return render json: { error: 'Unauthorized' }, status: :unauthorized
end

join_team_requests = JoinTeamRequest.where(team_id: params[:team_id])
.includes(:participant => :user)
.order(created_at: :desc)

render json: join_team_requests, status: :ok
end
</source>

'''3. Get Advertisements for Assignment'''

Add a method to fetch all advertisements for an assignment (for the Signup Sheet page):

<source lang="ruby">
# GET api/v1/signed_up_teams/advertisements/:assignment_id
# Gets all advertisements for an assignment
def advertisements
assignment = Assignment.find(params[:assignment_id])
signed_up_teams = SignedUpTeam.joins(:team, :sign_up_topic)
.where(sign_up_topics: { assignment_id: params[:assignment_id] })
.where(advertise_for_partner: true)
.includes(:team, :sign_up_topic)

advertisements = signed_up_teams.map do |sut|
{
id: sut.id,
team_id: sut.team_id,
team_name: sut.team.name,
topic_id: sut.sign_up_topic_id,
topic_name: sut.sign_up_topic.topic_name,
comments_for_advertisement: sut.comments_for_advertisement,
created_at: sut.created_at
}
end

render json: advertisements, status: :ok
end
</source>

==== Model Updates ====

The `JoinTeamRequest` model needs to establish proper associations:

<source lang="ruby">
class JoinTeamRequest < ApplicationRecord
belongs_to :team
belongs_to :participant

ACCEPTED_STATUSES = %w[ACCEPTED DECLINED PENDING]
validates :reply_status, inclusion: { in: ACCEPTED_STATUSES }

scope :pending, -> { where(reply_status: 'PENDING') }
scope :for_team, ->(team_id) { where(team_id: team_id) }
end
</source>

==== Routes Updates ====

Add new routes for the additional endpoints:

<source lang="ruby">
resources :join_team_requests do
collection do
get 'team/:team_id', to: 'join_team_requests#team_requests'
post 'decline/:id', to: 'join_team_requests#decline'
post 'accept/:id', to: 'join_team_requests#accept'
end
end

resources :signed_up_teams do
collection do
get 'advertisements/:assignment_id', to: 'signed_up_teams#advertisements'
end
member do
post :create_advertisement
patch :update_advertisement
delete :remove_advertisement
end
end

</source>

=== Frontend Design ===

==== Signup Sheet Page Enhancement ====

Create a new component or enhance existing signup sheet to display advertisements:

'''Component: SignupSheet.tsx'''

This component will:

- Display all topics for an assignment
- Show a trumpet icon (🔔) next to topics that have advertisements
- Allow users to click on topics with advertisements to view details
- Provide a modal/dialog to view advertisement details and create a join team request

<source lang="typescript">
interface Advertisement {
id: number;
team_id: number;
team_name: string;
topic_id: number;
topic_name: string;
comments_for_advertisement: string;
created_at: string;
}

interface SignUpTopic {
id: number;
topic_name: string;
topic_identifier: string;
max_choosers: number;
description?: string;
has_advertisement?: boolean;
advertisement?: Advertisement;
}

</source>

The UI will show:

- A table/list of topics
- Trumpet icon indicator for topics with advertisements
- Click handler to open advertisement details modal

==== Join Team Request Modal ====

Create a modal component for creating join team requests:

'''Component: JoinTeamRequestModal.tsx'''

This modal will:

- Display advertisement details (team name, topic, desired qualifications)
- Provide a text area for comments (optional)
- Show a "Send Request" button
- Handle form submission and API calls

<source lang="typescript">
interface JoinTeamRequestModalProps {
show: boolean;
onHide: () => void;
advertisement: Advertisement;
assignmentId: number;
onSuccess: () => void;
}
</source>

==== StudentTeamView Enhancement ====

Add a "Received Requests" section to `StudentTeamView.tsx`:

'''Section: Received Join Team Requests'''

This section will:

- Display all pending join team requests for the current team
- Show request details: requester name, email, comments, date
- Provide "Approve" and "Decline" buttons for each request
- Disable approve button if team is full
- Show status for non-pending requests

<source lang="typescript">
interface JoinTeamRequest {
id: number;
participant_id: number;
team_id: number;
comments: string;
reply_status: 'PENDING' | 'ACCEPTED' | 'DECLINED';
created_at: string;
participant: {
id: number;
user: {
id: number;
name: string;
full_name: string;
email: string;
};
};
}
</source>

The UI structure will be similar to the existing "Received Invitations" section, with:

- Table displaying request information
- Action buttons (Approve/Decline) for pending requests
- Status display for processed requests

==== API Hooks ====

Create or extend hooks for join team requests:

'''File: hooks/useJoinTeamRequest.ts'''

<source lang="typescript">
export const useJoinTeamRequest = () => {
const createRequestAPI = useAPI();
const acceptRequestAPI = useAPI();
const declineRequestAPI = useAPI();
const fetchTeamRequestsAPI = useAPI();
const fetchAdvertisementsAPI = useAPI();

const createJoinTeamRequest = (teamId: number, assignmentId: number, comments?: string) =>
createRequestAPI.sendRequest({
url: `/join_team_requests`,
method: 'POST',
data: { team_id: teamId, assignment_id: assignmentId, comments }
});

const acceptJoinTeamRequest = (requestId: number) =>
acceptRequestAPI.sendRequest({
url: `/join_team_requests/accept/${requestId}`,
method: 'POST'
});

const declineJoinTeamRequest = (requestId: number) =>
declineRequestAPI.sendRequest({
url: `/join_team_requests/decline/${requestId}`,
method: 'POST'
});

const fetchTeamRequests = (teamId: number) =>
fetchTeamRequestsAPI.sendRequest({
url: `/join_team_requests/team/${teamId}`
});

const fetchAdvertisements = (assignmentId: number) =>
fetchAdvertisementsAPI.sendRequest({
url: `/signed_up_teams/advertisements/${assignmentId}`
});

return {
createJoinTeamRequest,
acceptJoinTeamRequest,
declineJoinTeamRequest,
fetchTeamRequests,
fetchAdvertisements,
createRequestAPI,
acceptRequestAPI,
declineRequestAPI,
fetchTeamRequestsAPI,
fetchAdvertisementsAPI
};
};

</source>

== Implementation Plan ==

=== Phase 1: Backend Refactoring ===

# '''Refactor action_allowed? method'''

## Update `Api::V1::JoinTeamRequestsController#action_allowed?` to handle all actions

## Remove individual privilege checks from `index` method

## Ensure all actions go through the centralized check

# '''Add accept method'''

## Implement `accept` method with team full validation

## Add transaction handling for atomic operations

## Update request status to ACCEPTED

## Add participant to team using `team.add_member`

# '''Add team_requests method'''

## Implement method to fetch requests for a team

## Add authorization check (user must be team member)

## Include participant and user data in response

# '''Add advertisements method to SignedUpTeamsController'''

## Implement method to fetch all advertisements for an assignment

## Join with teams and sign_up_topics

## Return formatted advertisement data

# '''Update JoinTeamRequest model'''

## Add `belongs_to :team` association

## Add scopes for filtering

## Update validations

# '''Update routes'''

## Add routes for new endpoints

## Ensure RESTful conventions

=== Phase 2: Frontend - Signup Sheet ===

# '''Create SignupSheet component (if not exists)'''

## Display topics for an assignment

## Fetch advertisements for the assignment

## Map advertisements to topics

## Display trumpet icon for topics with advertisements

# '''Create JoinTeamRequestModal component'''

## Design modal UI

## Implement form with comments field

## Add submit handler

## Handle success/error states

# '''Integrate modal with SignupSheet'''

## Add click handler for topics with advertisements

## Open modal with advertisement details

## Handle modal close

=== Phase 3: Frontend - StudentTeamView ===

# '''Add Received Requests section'''

## Create section similar to "Received Invitations"

## Fetch join team requests for current team

## Display requests in table format

# '''Implement approve/decline functionality'''

## Add approve button handler

## Add decline button handler

## Check team full status before allowing approve

## Update UI after actions

# '''Add useJoinTeamRequest hook'''

## Create hook file

## Implement all API methods

## Export hook for use in components

=== Phase 4: Integration and Testing ===

# '''End-to-end testing'''

## Test advertisement creation → request creation → approval flow

## Test decline flow

## Test team full validation

## Test authorization checks

# '''Unit testing'''

## Test controller methods

## Test model validations

## Test frontend components

# '''Integration testing'''

## Test API endpoints

## Test frontend-backend integration

## Test error handling

== Files Changed/Added ==

=== Backend Files ===

'''Modified:'''

- `app/controllers/api/v1/join_team_requests_controller.rb` - Refactor action_allowed?, add accept and team_requests methods
- `app/controllers/api/v1/signed_up_teams_controller.rb` - Add advertisements method
- `app/models/join_team_request.rb` - Add associations and scopes
- `config/routes.rb` - Add new routes

'''Added:'''

- `spec/requests/api/v1/join_team_requests_spec.rb` - Request specs for new methods
- `spec/models/join_team_request_spec.rb` - Model specs

=== Frontend Files ===

'''Modified:'''

- `src/pages/Student Teams/StudentTeamView.tsx` - Add Received Requests section
- `src/hooks/useStudentTeam.ts` - Add join team request methods (or create new hook)

'''Added:'''

- `src/pages/SignUpSheet/SignUpSheet.tsx` - Signup sheet component with advertisement indicators
- `src/pages/SignUpSheet/JoinTeamRequestModal.tsx` - Modal for creating join team requests
- `src/hooks/useJoinTeamRequest.ts` - Hook for join team request API calls
- `src/pages/SignUpSheet/SignUpSheet.module.css` - Styles for signup sheet
- `src/pages/SignUpSheet/JoinTeamRequestModal.module.css` - Styles for modal

== Testing Plan ==

=== Backend Testing ===

==== Unit Tests ====

# '''JoinTeamRequestsController Tests'''

## Test action_allowed? for different actions and user roles

## Test accept method with valid request

## Test accept method when team is full

## Test accept method when participant already on team

## Test team_requests method authorization

## Test team_requests method returns correct data

# '''SignedUpTeamsController Tests'''

## Test advertisements method returns correct data

## Test advertisements method filters correctly

# '''JoinTeamRequest Model Tests'''

## Test associations

## Test validations

## Test scopes

==== Integration Tests ====

# '''End-to-End Flow Tests'''

## Create advertisement → Create join request → Accept request

## Create advertisement → Create join request → Decline request

## Test team full validation prevents acceptance

## Test authorization prevents unauthorized access

=== Frontend Testing ===

==== Component Tests ====

# '''SignUpSheet Component'''

## Test advertisement indicators display correctly

## Test modal opens on click

## Test data fetching

# '''JoinTeamRequestModal Component'''

## Test form submission

## Test validation

## Test success/error handling

# '''StudentTeamView Component'''

## Test Received Requests section displays

## Test approve functionality

## Test decline functionality

## Test team full validation

==== Integration Tests ====

# '''API Integration'''

## Test all API calls work correctly

## Test error handling

## Test loading states

== Edge Cases and Error Handling ==

=== Backend Edge Cases ===

# '''Team Full Validation'''

- Check team capacity before accepting request
- Return appropriate error message
- Prevent race conditions with database transactions

# '''Authorization'''

- Verify user is team member before showing requests
- Verify user is student before creating requests
- Verify user is administrator before viewing all requests

# '''Duplicate Requests'''

- Prevent creating duplicate requests from same participant
- Handle case where participant already on team

# '''Concurrent Modifications'''

- Use transactions for atomic operations
- Handle race conditions in team membership updates

=== Frontend Edge Cases ===

# '''Network Errors'''

- Display appropriate error messages
- Handle timeout scenarios
- Provide retry mechanisms

# '''Empty States'''

- Show appropriate messages when no advertisements exist
- Show appropriate messages when no requests exist

# '''Loading States'''

- Display loading indicators during API calls
- Prevent multiple simultaneous requests

# '''Form Validation'''

- Validate required fields
- Provide user feedback for errors

== Security Considerations ==

# '''Authorization Checks'''

- All endpoints must verify user permissions
- Team members can only see requests for their team
- Students can only create requests for themselves

# '''Input Validation'''

- Sanitize all user inputs
- Validate team_id and assignment_id parameters
- Prevent SQL injection through parameterized queries

# '''Rate Limiting'''

- Consider rate limiting for request creation
- Prevent spam requests

== Future Enhancements ==

# Email notifications when join team requests are created

# Email notifications when requests are approved/declined

# Bulk approve/decline functionality

# Request history and audit trail

# Advanced filtering and search for requests

== References ==

- Expertiza Wiki: E2252. Refactor auth controller.rb & password retrieval controller.rb
- Rails API Documentation
- React Router Documentation
- Expertiza Codebase: Existing invitation and team management implementations

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:24:35Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah, Vatsalkumar Patel, Smit Raval '''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}
[[File:Heatgrid_3.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_toggle.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_showallreviews.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

== Future Work(Suggested) ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|}

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:23:52Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah, Vatsalkumar Patel, Smit Raval '''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}
[[File:Heatgrid_3.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_toggle.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_showallreviews.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|}

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:19:22Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah, Vatsalkumar Patel, Smit Raval '''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}
[[File:Heatgrid_3.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_toggle.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_showallreviews.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

[[File:Heatgrid_tooltip.png|thumb|center|500px|Tooltip shown when hovering over item weight label.]]

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|-
| Heatgrid_tooltip.png || Tooltip on item weight || Testing and Validation
|}

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:19:02Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah, Vatsalkumar Patel, Smit Raval '''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails (Api::V1::GradesController)

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}
[[File:Heatgrid_3.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_toggle.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_showallreviews.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

[[File:Heatgrid_tooltip.png|thumb|center|500px|Tooltip shown when hovering over item weight label.]]

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|-
| Heatgrid_tooltip.png || Tooltip on item weight || Testing and Validation
|}

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:16:21Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah ''(and team, if applicable)''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails (Api::V1::GradesController)

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}
[[File:Heatgrid_3.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_toggle.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_showallreviews.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

[[File:Heatgrid_tooltip.png|thumb|center|500px|Tooltip shown when hovering over item weight label.]]

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|-
| Heatgrid_tooltip.png || Tooltip on item weight || Testing and Validation
|}

File:Heatgrid 3.png

2025-10-29T03:16:02Z

Dshah24:

File:Heatgrid showallreviews.png

2025-10-29T03:14:13Z

Dshah24:

File:Heatgrid toggle.png

2025-10-29T03:12:39Z

Dshah24:

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-29T03:11:20Z

Dshah24:

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah ''(and team, if applicable)''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails (Api::V1::GradesController)

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

{| style="border: none; margin: 0 auto; text-align: center;"
|-
| [[File:Heatgrid_1.png|800px|Current Heatgrid View (Before Redesign)]]
| [[File:Heatgrid_2.png|800px|Updated Heatgrid Rendering Real Data (After Integration)]]
|}

== Technical Background ==

=== Frontend Implementation ===
* '''Framework:''' React + TypeScript (TSX components under 'src/')
* '''Styling:''' 'grades.scss' (defines colors, table layout, and heat intensity mapping)
* '''Components:'''
** 'ReviewTable.tsx' — main heatgrid rendering component
** 'ReviewTableRow.tsx' — row logic and item expansion
** 'RoundSelector.tsx' — UI for selecting review rounds
** 'Statistics.tsx' — displays score summaries and analytics
* '''Data Flow:''' Previously used 'heatMapData.json' (dummy). Now retrieves real data from backend API via 'gradesService.ts'.

=== Backend Implementation ===
* '''Framework:''' Ruby on Rails ('Api::V1' namespace)
* '''Controller:''' 'grades_controller.rb'
* '''Purpose:''' Exposes JSON endpoints for fetching review and grade data
* '''Data Source:''' Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_goals.png|thumb|center|750px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
** “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

[[File:Heatgrid_itemlist.png|thumb|center|500px|“Show item prompts” toggle with item list displayed above table.]]
[[File:Heatgrid_expand_review.png|thumb|center|500px|Expanded review view using “+” button or “Show all reviews”.]]

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

[[File:Heatgrid_tooltip.png|thumb|center|500px|Tooltip shown when hovering over item weight label.]]

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* 'app/controllers/api/v1/grades_controller.rb'
* 'frontend/src/pages/ViewTeamGrades/'
* 'frontend/src/services/gradesService.ts'
* 'frontend/src/styles/grades.scss'

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|-
| Heatgrid_tooltip.png || Tooltip on item weight || Testing and Validation
|}

File:Heatgrid goals.png

2025-10-29T03:10:51Z

Dshah24:

File:Heatgrid 2.png

2025-10-29T00:02:03Z

Dshah24:

File:Heatgrid 1.png

2025-10-29T00:00:37Z

Dshah24:

CSC/ECE 517 Fall 2025 - E2553. Heatgrid and Grades Controller (Frontend + Backend)

2025-10-28T22:56:41Z

Dshah24: Created page with "= E2553: Heatgrid and Grades Controller (Frontend + Backend) = '''Mentor:''' Vihar Manojkumar Shah '''Contributors:''' Devyash Shah ''(and team, if applicable)'' '''Frontend Framework:''' React + TypeScript '''Backend Framework:''' Ruby on Rails (Api::V1::GradesController) == Overview == The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and in..."

= E2553: Heatgrid and Grades Controller (Frontend + Backend) =

'''Mentor:''' Vihar Manojkumar Shah
'''Contributors:''' Devyash Shah ''(and team, if applicable)''
'''Frontend Framework:''' React + TypeScript
'''Backend Framework:''' Ruby on Rails (Api::V1::GradesController)

== Overview ==
The '''Heatgrid''' is a key component of the ''View Team Grades'' page in Expertiza. It visualizes a matrix of peer review scores for each rubric item, enabling students and instructors to understand feedback and performance across multiple review rounds.

Originally, this view rendered dummy data and did not conform to the system’s visual design guidelines. The purpose of this project is to redesign the interface for improved usability and integrate it fully with the backend so that it displays real grading data dynamically.

[[File:Heatgrid_before.png|thumb|center|500px|Current Heatgrid View (Before Redesign)]]

== Technical Background ==

=== Frontend Implementation ===
* **Framework:** React + TypeScript (TSX components under `src/`)
* **Styling:** `grades.scss` (defines colors, table layout, and heat intensity mapping)
* **Components:**
** `ReviewTable.tsx` — main heatgrid rendering component
** `ReviewTableRow.tsx` — row logic and item expansion
** `RoundSelector.tsx` — UI for selecting review rounds
** `Statistics.tsx` — displays score summaries and analytics
* **Data Flow:** Previously used `heatMapData.json` (dummy). Now retrieves real data from backend API via `gradesService.ts`.

=== Backend Implementation ===
* **Framework:** Ruby on Rails (`Api::V1` namespace)
* **Controller:** `grades_controller.rb`
* **Purpose:** Exposes JSON endpoints for fetching review and grade data
* **Data Source:** Database models for Assignments, Participants, Reviews, and Scores

=== Example Endpoint ===
<syntaxhighlight lang="json">
GET /api/v1/grades/:assignment_id/view_our_scores
{
"Review-Round-1": [
[
{
"id": 42,
"item_id": 7,
"txt": "Clarity of explanation",
"answer": 4,
"comments": "Well-structured response",
"reviewer_name": "Alice Johnson",
"reviewee_name": "Team Alpha"
}
]
]
}
</syntaxhighlight>

== Project Goals ==
{| class="wikitable"
! Goal !! Description
|-
| UI Consistency || Ensure all fonts, buttons, and table elements match Expertiza’s design language.
|-
| Dynamic Data Integration || Replace dummy JSON with backend-driven API calls.
|-
| Readability Improvements || Adjust font size, reduce whitespace, and improve table density.
|-
| Interactivity || Add toggles, tooltips, and expandable reviews.
|-
| Compatibility || Ensure proper rendering across all 10 rubric item types.
|}

[[File:Heatgrid_after.png|thumb|center|500px|Updated Heatgrid Rendering Real Data (After Integration)]]

== Backend API Endpoints ==
{| class="wikitable"
! Endpoint !! Method !! Description
|-
| /api/v1/grades/:assignment_id/view_all_scores || GET || Returns all team review scores (for instructors/admins)
|-
| /api/v1/grades/:assignment_id/view_our_scores || GET || Returns team-scoped scores for current participant
|-
| /api/v1/grades/:assignment_id/view_my_scores || GET || Returns data for reviews received, given, and feedback
|-
| /api/v1/grades/:participant_id/edit || GET || Retrieves participant and item data for grade editing
|-
| /api/v1/grades/:participant_id/update || PATCH || Updates grade and submission comment
|}

== Key Features Implemented ==
* Use the term '''items''' instead of “questions”.
* Increased font size and reduced blank space in table cells.
* Left-aligned prompts in the rubric display.
* Added the option to display an item list above the table.
* Ensured consistent font and button styling.
* Display reviewer names instead of placeholders (e.g., “Reviewer 1”).
* Enabled clicking on review numbers or reviewer names to open that review.
* Added “Show all reviews” and per-review “+” expand buttons.
* Added hover tooltip on item weight (e.g., “This is the weight of this item”).
* Centered item numbers.
* Verified rendering for all 10 item types (criterion, text field, checkbox, etc.).
* For text-field items: Displayed preview with “...” to expand full text.
* Adjusted column widths to match longest responses.
* Renamed toggle button:
* “Toggle question list” → “Show item prompts” / “Hide item prompts”
* Displayed both team member names and usernames.

[[File:Heatgrid_itemlist.png|thumb|center|500px|“Show item prompts” toggle with item list displayed above table.]]
[[File:Heatgrid_expand_review.png|thumb|center|500px|Expanded review view using “+” button or “Show all reviews”.]]

== Testing and Validation ==
=== Frontend ===
* Verified across multiple item types, review rounds, and team configurations.
* Confirmed responsive layout and tooltip functionality.
* Tested with Chrome, Firefox, and Safari for UI consistency.

=== Backend ===
* Confirmed endpoint connectivity and response structures.
* Verified role-based access: anonymized reviewer names for non-staff users.
* Validated data across multiple assignments and rounds.

[[File:Heatgrid_tooltip.png|thumb|center|500px|Tooltip shown when hovering over item weight label.]]

== Future Work ==
* Enable sorting by reviewer or average score.
* Add export functionality (CSV or Excel format).
* Integrate instructor-level analytics and visualization.

== References ==
* [https://github.com/expertiza/expertiza Expertiza GitHub Repository]
* `app/controllers/api/v1/grades_controller.rb`
* `frontend/src/pages/ViewTeamGrades/`
* `frontend/src/services/gradesService.ts`
* `frontend/src/styles/grades.scss`

== Screenshot Summary ==
{| class="wikitable"
! Screenshot !! Description !! Section
|-
| Heatgrid_before.png || Old dummy-data Heatgrid || Overview
|-
| Heatgrid_after.png || Backend-connected Heatgrid || Technical Background
|-
| Heatgrid_itemlist.png || “Show item prompts” toggle view || Key Features
|-
| Heatgrid_expand_review.png || Expanded review example || Key Features
|-
| Heatgrid_tooltip.png || Tooltip on item weight || Testing and Validation
|}