Skip to main content

CV Extraction WebSocket Implementation

This document explains the implementation of CV extraction using WebSocket communication in the Add Candidate page.

Files Created/Modified​

1. New Hook: lib/hooks/useCvExtractionWebSocket.ts​

A custom React hook that handles CV extraction via WebSocket:

  • Purpose: Parse-only CV processing without database persistence
  • WebSocket Message Format: Follows the CV extraction guide specifications
  • Features:
    • File upload with progress tracking
    • WebSocket-based CV extraction
    • Real-time processing status updates
    • Error handling and timeouts
    • TypeScript interfaces for type safety

Key Functions:​

  • extractCV(file: File): Upload file and extract CV data
  • reset(): Reset extraction state
  • Real-time status updates via WebSocket messages

2. Updated Page: app/company/pipeline/addCandidate/page.tsx​

Enhanced the Add Candidate page to use the new WebSocket-based extraction:

New Features:​

  • File Upload UI: Visual file selection with status
  • Processing Indicators: Real-time upload and processing progress
  • Success/Error States: Clear feedback to users
  • Debug Tools: WebSocket connection status (development only)
  • Auto-navigation: Automatically advance to review step after successful extraction

UI Components:​

  • File upload dropzone
  • Selected file preview with remove option
  • AI Extract button with loading states
  • Processing progress bars
  • Error/success notifications
  • Review section with extracted data display

3. Upload API: app/api/upload/route.ts​

Simple file upload endpoint for demo purposes:

  • Validation: File type and size checking
  • Mock MinIO URLs: Simulates file storage for development
  • Error Handling: Proper HTTP status codes and error messages
  • Security: File type validation and size limits

WebSocket Message Flow​

1. File Upload​

// User selects file → Upload to API → Get MinIO URL
const fileUrl = await uploadFile(file)

2. CV Extraction Request​

// Send extraction request via WebSocket
const message = {
  type: 'cv_extraction_request',
  pipeline_type: 'cv_extraction',
  payload: {
    id: requestId,
    file_url: fileUrl
  }
}

3. WebSocket Responses​

// Processing started
{ type: 'processing_started', id: requestId, status: 'processing' }

// Success response
{ 
  type: 'pipeline_result', 
  data: { 
    data: { 
      first_name: 'John', 
      last_name: 'Doe',
      skills: [...],
      experiences: [...],
      // ... other extracted data
    } 
  } 
}

// Error response
{ type: 'pipeline_error', id: requestId, error: 'Error message' }

Data Transformation​

The hook transforms server response fields to match frontend interfaces:

// Server → Frontend mapping
first_name → firstName
last_name → lastName
job_title → jobTitle
years_experience → yearsExperience
// etc.

Development Features​

Debug Tools​

  • WebSocket connection status
  • Raw extracted data preview
  • Error logging and diagnostics

Progress Tracking​

  • Upload progress bar
  • Processing status indicators
  • Real-time feedback

Usage Example​

const cvExtraction = useCvExtractionWebSocket()

// Extract CV data
const result = await cvExtraction.extractCV(file)

// Check status
if (cvExtraction.isProcessing) {
  // Show loading state
}

if (cvExtraction.result) {
  // Display extracted data
}

if (cvExtraction.error) {
  // Handle error
}

Key Benefits​

  1. Real-time Processing: Live updates via WebSocket
  2. Parse-only: No database persistence for preview functionality
  3. Type Safety: Full TypeScript interfaces
  4. Error Handling: Comprehensive error states
  5. User Experience: Clear progress indicators and feedback
  6. Development Tools: Debug tools for troubleshooting

Integration with Existing System​

  • Uses existing WebSocketContext for connection management
  • Compatible with current pipeline architecture
  • Follows established patterns for hooks and components
  • Integrates with existing UI components (Button, Input, etc.)

Future Enhancements​

  1. Real MinIO Integration: Replace mock upload with actual MinIO
  2. Drag & Drop: Enhanced file upload UX
  3. Multiple Files: Batch CV processing
  4. Preview: PDF/document preview before extraction
  5. Retry Logic: Automatic retry for failed extractions