AI Services Overview

The background-tasks service is the central AI/ML processing layer of the AIQLick platform. Built on FastAPI, it handles all compute-intensive workloads including CV parsing, job matching, meeting transcription analysis, and conversational AI agents.

Deployment

Environment	ECS service	Task sizing	Image	Reachable at
Production	bg-tasks-prod (cluster aiqlick, min 2 / max 8)	1 vCPU / 2 GB	842697652860.dkr.ecr.eu-north-1.amazonaws.com/background-tasks:<sha>	bg-prod.aiqlick.local:8000 (Cloud Map → internal ALB → ECS task)
Development	bg-tasks-dev (cluster aiqlick, min 1 / max 4)	0.5 vCPU / 1 GB	…/background-tasks:dev-<sha>	bg-dev.aiqlick.local:8000

Both services run on ECS Fargate in private subnets (no public IPs). Tasks are unreachable from the public internet — backend addresses them via Cloud Map private DNS routed by aiqlick-internal-alb. The frontend never calls bg-tasks directly; all AI ops flow through the NestJS AI gateway on api(.dev).aiqlick.com.

All concurrency is handled within the FastAPI event loop using native asyncio coroutines — there is no external task queue (no Celery, no Bull). Background workers are started via asyncio.create_task() at application startup and run continuously until shutdown.

Architecture

                    ┌─────────────────────────────────────┐
                    │         FastAPI Application          │
                    │                                      │
                    │  ┌──────────┐   ┌────────────────┐  │
  HTTP/WS ────────► │  │ Strawberry│   │ REST Endpoints │  │
                    │  │ GraphQL   │   │ /health        │  │
                    │  │ 12+ subs  │   │ /api/events    │  │
                    │  └──────────┘   └────────────────┘  │
                    │                                      │
                    │  ┌──────────────────────────────┐   │
                    │  │     Async Background Workers  │   │
                    │  │  Match Score Gen  (30s cycle) │   │
                    │  │  Inbound Email    (30s cycle) │   │
                    │  │  Inbound CV       (30s cycle) │   │
                    │  │  Document Worker  (30s cycle) │   │
                    │  └──────────────────────────────┘   │
                    │                                      │
                    │  ┌──────────────────────────────┐   │
                    │  │       AWS Service Clients     │   │
                    │  │  Bedrock  Rekognition         │   │
                    │  │  Transcribe  S3               │   │
                    │  └──────────────────────────────┘   │
                    └─────────────────────────────────────┘

Background Workers

Each worker runs as a long-lived async coroutine with built-in resilience patterns: circuit breakers to avoid cascading failures, exponential backoff on transient errors, and per-task timeout protection.

Worker	Cycle	Purpose
Match Score Generator	30 seconds	Processes up to 100 job-seeker/job pairs per cycle, computing compatibility scores
Inbound Email Worker	30 seconds	Polls IMAP for incoming emails, routes them to the appropriate pipeline
Inbound CV Worker	30 seconds	Picks up queued CV documents for AI extraction and face detection
Document Worker	30 seconds	Chunks, embeds, and indexes documents for RAG-powered AI agents

API Surface

GraphQL (Strawberry)

The service exposes a Strawberry GraphQL endpoint at /graphql supporting both HTTP (queries/mutations) and WebSocket (subscriptions). There are 12+ subscriptions that stream real-time progress updates to the frontend:

• cvExtraction -- CV parsing with structured data extraction
• faceExtraction -- Face detection from CV photos
• jobParsing -- Job description analysis
• addCandidate -- Full candidate onboarding pipeline
• userJobMatching / candidateJobMatching -- Real-time matching scores
• basicMatching -- Skill-only matching
• textRewrite -- AI-powered text rewriting
• meetingInsight -- Meeting transcript analysis
• agentChat -- Streaming agent conversations
• taskSubscription / metricsSubscription -- System monitoring

REST Endpoints

Endpoint	Method	Purpose
/health	GET	Liveness probe -- confirms the process is running
/health/ready	GET	Readiness probe -- confirms all dependencies (DB, AWS) are reachable
/docs	GET	Swagger/OpenAPI documentation
/api/events/room/destroyed	POST	Receives Prosody webhook events to trigger meeting insight generation

Key Processing Pipelines

Pipeline	Input	Output	Primary Model
CV Extraction	PDF/DOCX document	11 structured CV tables	Claude Sonnet 4.5
Job Parsing	Job description text	Structured job requirements and attributes	Claude Sonnet 4.5
Face Detection	CV document image	Detected face coordinates and cropped photo	AWS Rekognition
Matching	Job + talent pair	0-100 score with dimension breakdown	Internal scoring engine
Text Rewrite	Source text + instructions	Rewritten text	Claude Haiku 4.5
Meeting Insights	Transcription segments	Structured meeting analysis	Claude Haiku 4.5
Agent Chat	User message + context	Streamed response with tool calls	Amazon Nova Lite

AWS Service Dependencies

All heavy computation is offloaded to managed AWS services rather than running locally:

• AWS Bedrock (eu-north-1) -- LLM inference for all text generation and embedding tasks
• AWS Rekognition (eu-west-1) -- Face detection in CV photos
• AWS Transcribe (eu-west-1) -- Real-time speech-to-text for meeting transcription
• S3 (eu-north-1) -- Document storage and retrieval
• PostgreSQL (RDS) -- Shared database with the backend service via raw AsyncPG queries

Health and Lifecycle

The service implements graceful shutdown handling via SIGTERM and SIGINT signal handlers. On shutdown:

1. New requests are rejected
2. In-flight GraphQL subscriptions complete or are cancelled
3. Background workers finish their current cycle
4. Database connection pools are drained
5. The process exits cleanly

CI/CD includes automatic rollback: if the health check fails after deployment, the container is replaced with the :previous tagged image.