GraphQL Operations

GraphQL operations are organized in graphql/operations/ with 34+ feature-specific directories. The Apollo Client setup lives in graphql/apollo/.

Operation Directories

graphql/operations/
  admin/                aiAgent/             badge/
  ai/                   billingConfig/       buzzfeed/
  candidate/            collaboratingPartners/
  companies/            contacts/            credit/
  cv/                   dashboard/           interview/
  job/                  jobSeekerInvitations/
  meetingInsights/      messaging/           notification/
  payment/              pipeline/            promo-code/
  role/                 schema/              sharelist/
  skills/               talentPool/          talents/
  types/                user/

Each directory contains queries, mutations, and subscriptions for that feature domain.

Fragment Conventions

Reusable fragments are centralized in graphql/operations/schema/ by entity:

Fragment	Entity
USER_FIELDS	User profile fields
COMPANY_FIELDS	Company details
JOB_FIELDS	Job listing fields
TALENT_FIELDS	Talent profile fields
CANDIDATE_FIELDS	Candidate fields
CV_FIELDS	CV document fields
PARSED_CV_FIELDS	Legacy parsed CV data

Fragments ensure consistent field selection when the same entity appears in different operations.

Structured CV Fragments

The structured CV migration introduced additional fragments in graphql/operations/schema/cv/fragments.ts:

• CV_PROFILE_FIELDS -- Profile data (CvProfile)
• CV_JOB_PREFERENCE_FIELDS -- Job preferences (CvJobPreference)
• CV_WORK_EXPERIENCE_FIELDS -- Work history (CvWorkExperience)
• CV_EDUCATION_FIELDS -- Education (CvEducation)
• CV_CERTIFICATION_FIELDS -- Certifications (CvCertification)
• CV_LANGUAGE_FIELDS -- Languages (CvLanguage)
• CV_PROJECT_FIELDS -- Projects (CvProject)
• CV_METADATA_FIELDS -- Parsing metadata (CvMetadata)

See Structured CV Migration for details.

Single Apollo Client

The frontend uses one Apollo Client instance pointed at the backend (NEXT_PUBLIC_API_URL over HTTP, NEXT_PUBLIC_GRAPHQL_WS_URL over WS). All AI operations — CV extraction, job parsing, agent chat, voice, document processing — go through the NestJS gateway via the subscribeAi / queryAi / mutateAi GraphQL roots and reuse the same client.

The dual-client setup that previously routed AI traffic via NEXT_PUBLIC_AI_GRAPHQL_URL was retired in the Phase 3.7 cutover. See lib/ai/aiGateway.ts for the typed wrappers (subscribeAiOp, aiGatewayRequest) every AI hook now uses.

Subscription Patterns

CV Extraction

subscription CvExtraction($input: CVExtractionInput!) {
  cvExtraction(input: $input) {
    status
    progress
    data { ... }
  }
}

Streams through the background-tasks WebSocket.

Agent Chat

subscription AgentChat($input: AgentChatInput!) {
  agentChat(input: $input) {
    type    # ChatProcessing | ChatChunk | ChatToolCall | ChatComplete | ChatError
    data
  }
}

Streams through the background-tasks WebSocket.

Log Streaming (Admin)

subscription LogStream {
  logStream {
    level
    message
    timestamp
  }
}

Streams through the main backend WebSocket. Super admin only.

Notifications

Notifications use polling instead of subscriptions:

useQuery(UNREAD_NOTIFICATION_COUNT, { pollInterval: 30000 });

Messages

subscription MessageSent($conversationId: ID!) {
  messageSent(conversationId: $conversationId) { ... }
}

Streams through the main backend WebSocket.

File Upload Pattern

The Apollo Client uses a custom uploadLink for file uploads:

• Detects operations with File variables
• Sends as multipart/form-data instead of JSON
• Bypasses retry to avoid timeout on large files
• Defined in graphql/apollo/customUploadLink.ts

Apollo Client Files

File	Purpose
graphql/apollo/apolloClient.ts	Main Apollo Client configuration
graphql/apollo/authLink.ts	JWT authentication link
graphql/apollo/authRoutes.ts	Routes that skip authentication
graphql/apollo/customUploadLink.ts	Multipart file upload link