Skip to main content

Add Candidate Channel Implementation - Production Ready

Summary​

Successfully implemented the add_candidate WebSocket channel integration with robust authentication handling for both development and production environments.

Authentication Fixes Applied​

1. Production Authentication (/contexts/WebSocketContext.tsx)​

Fixed Issues:

  • ✅ Removed fallback to 'devtoken' in production
  • ✅ Added proper error handling when no token is found
  • ✅ Improved logging for production authentication
  • ✅ Added graceful handling of authentication errors during auto-connect

Key Changes:

// Production authentication now throws proper errors
if (!token) {
  console.error('[WebSocket] No authentication token found in storage');
  throw new Error('Authentication required: No token found. Please log in again.');
}

2. Add Candidate Page (/app/company/pipeline/addCandidate/page.tsx)​

Enhanced Error Handling:

  • ✅ Added authentication checks before save operations
  • ✅ Added user authentication status indicators
  • ✅ Disabled buttons when user is not authenticated
  • ✅ Added specific error messages for authentication failures
  • ✅ Added WebSocket connection status awareness

Key Changes:

// Authentication-aware button states
disabled={!cvExtraction.result || addCandidateChannel.isProcessing || !user || !addCandidateChannel.isConnected}

// Authentication error handling
if (error.message.includes('Authentication required')) {
  setSaveError("Authentication failed. Please log in again and try saving the candidate.");
}

3. Add Candidate Channel Hook (/lib/hooks/useAddCandidateChannel.ts)​

Properly Implemented:

  • ✅ Correct WebSocket message format matching existing patterns
  • ✅ Proper error handling for channel responses
  • ✅ Type-safe request/response handling
  • ✅ Timeout handling (60 seconds)
  • ✅ Connection state management

Complete Flow Implementation​

Step 1: Upload CV → AI Extraction​

  • ✅ Uses useCvExtractionWebSocket hook
  • ✅ Real-time progress tracking
  • ✅ Authentication aware (disabled when not logged in)
  • ✅ Error handling for connection/auth issues

Step 2: CV Builder → Dynamic Form Editing​

  • ✅ Converts extracted CV data to ProfileFormData format
  • ✅ Real-time form updates
  • ✅ Handles all CV data types (skills, experience, education)
  • ✅ Success/error state display

Step 3: Save via WebSocket add_candidate Channel​

  • ✅ Replaces GraphQL mutation completely
  • ✅ Uses WebSocket add_candidate channel
  • ✅ Returns candidate ID, match scores, and detailed match breakdown
  • ✅ Proper navigation with success parameters

Data Flow Verification​

Input: CV File Upload​

File → useCvExtractionWebSocket.extractCV() → CVExtractionResult

Transformation: CV Data → Form Data​

CVExtractionResult → convertCvDataToProfileForm() → ProfileFormData

Output: Add Candidate Channel​

ProfileFormData → useAddCandidateChannel.addCandidate() → AddCandidateChannelResponse

Response: Match Score & Navigation​

AddCandidateChannelResponse → Router.push with candidateId & matchScore

Authentication Token Flow​

Development Environment​

// Always uses 'devtoken' as server expects this
token = 'devtoken'

Production Environment​

// Gets JWT from localStorage (stored as 'token' by UserAuthProvider)
const token = localStorage.getItem('token') || sessionStorage.getItem('token');
if (!token) {
  throw new Error('Authentication required: No token found. Please log in again.');
}

Error Handling Matrix​

Error TypeHandlingUser Experience
No auth tokenThrow error, disable buttons"Please log in to continue"
WebSocket disconnectedShow connection status"Connection lost, please check internet"
Channel timeout60s timeout, clear state"Request timeout, please try again"
Server 403/AuthSpecific auth error message"Authentication failed, please log in again"
Invalid dataForm validation"Please fill required fields"
Processing errorDisplay server errorServer error message displayed

UI/UX Enhancements​

Authentication Status Indicators​

  • ✅ Red warning when user not authenticated
  • ✅ Authentication error messages for WebSocket issues
  • ✅ Disabled states for all action buttons when not authenticated

Connection Status​

  • ✅ WebSocket connection indicator
  • ✅ Add candidate channel status in debug tools
  • ✅ Real-time connection state updates

Success Flow​

  • ✅ Match score display in success message
  • ✅ Detailed match breakdown (skills, experience, education, overall)
  • ✅ Navigation includes candidateId and matchScore parameters

Production Deployment Checklist​

  • ✅ No 'devtoken' fallbacks in production
  • ✅ Proper error handling for missing authentication
  • ✅ JWT token correctly read from localStorage
  • ✅ WebSocket URL points to production pipeline server
  • ✅ All buttons disabled when authentication fails
  • ✅ Clear error messages for authentication issues
  • ✅ Graceful handling of connection failures

Testing Scenarios​

1. Authenticated User Flow​

  1. User uploads CV ✅
  2. AI extraction via WebSocket ✅
  3. CV Builder form populated ✅
  4. User edits form data ✅
  5. Save via add_candidate channel ✅
  6. Match score calculated and displayed ✅
  7. Navigation to pipeline with success ✅

2. Unauthenticated User Flow​

  1. User not logged in ✅
  2. Authentication warnings displayed ✅
  3. All action buttons disabled ✅
  4. Clear instructions to log in ✅

3. Authentication Failure Flow​

  1. User was logged in but token expired ✅
  2. WebSocket connection fails with auth error ✅
  3. Specific authentication error displayed ✅
  4. No automatic retries with invalid token ✅

4. Connection Failure Flow​

  1. WebSocket disconnection detected ✅
  2. Connection status updated ✅
  3. User informed of connection issue ✅
  4. Actions disabled until reconnection ✅

Architecture Compliance​

The implementation fully complies with the add_candidate channel documentation:

  • ✅ Uses correct message format: { pipeline_type: 'add_candidate', payload: {...} }
  • ✅ Handles response queue: add_candidate_results
  • ✅ Proper timeout handling (60 seconds)
  • ✅ Authentication via query parameter in WebSocket URL
  • ✅ Complete candidate data structure as specified
  • ✅ Match score calculation and detailed breakdown
  • ✅ Error handling for all documented error types

Performance Considerations​

  • ✅ Connection reuse (single WebSocket for all operations)
  • ✅ Proper cleanup of pending requests
  • ✅ Memory management with request timeouts
  • ✅ Efficient state updates (no unnecessary re-renders)
  • ✅ Background reconnection with auth error awareness

The implementation is now production-ready with robust authentication handling and complete add_candidate channel integration.

05/03/2026