Implement group management system

[Raafay-Qureshi]

Summary

Implements comprehensive Group Management System for organizing interviewers and candidates into efficient scheduling groups. Includes full CRUD operations, role-based member assignment, bidirectional user-group synchronization, and advanced filtering with search and pagination.

Features Added

1. Enhanced Group Model

Modified backend/src/models/group.ts with new fields per requirements:

• description: String (optional) - Group description for better organization
• type: Enum ('interviewer' | 'candidate' | 'both') - Classifies group purpose
• candidates: Array of User ObjectIds - Separate from members for candidate users
• settings: Embedded object with availabilityOverride (boolean) and priority (number)
• Compound Unique Index: Ensures group names are unique within each team

2. Group API Endpoints

POST /api/groups

• Access: Admin only
• Behavior: Creates new group with validation, assigns to admin's team
• Validation: Zod schema for name, description, type, members, candidates, teamId, settings
• Features:
  • Validates all members/candidates belong to the same team
  • Bidirectional sync: Updates User.groupIds for all added members
  • Returns populated group with members, candidates, and creator

GET /api/groups

• Access: All authenticated users (team-scoped)
• Filtering: Supports filtering by:
  • type - Filter by 'interviewer', 'candidate', or 'both'
  • search - Case-insensitive partial name matching
  • page - Pagination page number (default: 1)
  • limit - Results per page (default: 20, max: 100)
• Returns: Paginated response with items, page, limit, total count

GET /api/groups/:id

• Access: Team members
• Returns: Single group with populated members, candidates, and creator

PUT /api/groups/:id

• Access: Admin (team members)
• Behavior: Updates group properties (name, description, type, settings)
• Protection: Cannot modify teamId, members, or candidates (use member endpoints)
• Returns: Updated group with populated fields

DELETE /api/groups/:id

• Access: Admin only
• Behavior: Deletes group and cleans up User.groupIds references
• Features: Bidirectional sync - removes group from all users' groupIds

POST /api/groups/:id/members

• Access: Admin only
• Behavior: Adds user to group with role-based assignment
• Features:
  • Automatically routes to members array (interviewers/admins) or candidates array based on user.role
  • Bidirectional sync: Updates User.groupIds
  • Idempotent: Duplicate additions are no-ops

DELETE /api/groups/:id/members/:userId

• Access: Admin only
• Behavior: Removes user from group
• Features:
  • Removes from both members and candidates arrays (idempotent)
  • Bidirectional sync: Removes group from User.groupIds
  • Validates userId format before processing

GET /api/groups/:id/members

• Access: Team members
• Returns: Array of group members (interviewers only)

3. Validation & Error Handling

• Zod Schemas: Comprehensive validation for all request bodies
  • createGroupSchema: Validates all creation fields with proper types
  • updateGroupSchema: Validates update fields (teamId not allowed)
  • addMemberSchema: Validates userId format
  • groupFilterSchema: Validates query parameters
• Error Middleware: Centralized handling for Zod, Mongoose, and auth errors
  • Zod validation errors return 400 with detailed issues array
  • Mongoose validation errors return 400 with field-level details
  • Authorization errors return 403 with descriptive messages

Security & Permissions

• JWT authentication required on all endpoints
• Role-based authorization (admin-only for write operations)
• Team-based access control using PermissionChecker.requireTeamAccess()
• Users can only access groups within their assigned team
• Input validation prevents invalid ObjectIds and malformed data

Data Consistency

All group membership changes maintain data consistency:

• Adding Members: Updates both Group.members/candidates AND User.groupIds
• Removing Members: Cleans up both Group arrays AND User.groupIds
• Deleting Groups: Removes group reference from all affected users
• Idempotent Operations: Duplicate operations succeed gracefully

Acceptance Criteria Met

• Groups can be created, retrieved, updated, and deleted
• Group data is properly validated (Zod schemas)
• Users can be assigned to and removed from groups
• Groups can be filtered and searched (type, name search, pagination)
• API endpoints follow RESTful conventions
• Proper authorization controls are in place (team-admin access)
• Group-based organization supports the scheduling workflow

Files Changed

• Modified: backend/src/models/group.ts - Enhanced model with type, description, candidates, settings, compound index
• Modified: backend/src/routes/groupRoutes.ts - Complete CRUD implementation with validation, filtering, error handling

Closes #108

[Flapjacck]

LGTM