Domain Model

This page defines the core entities and relationships that make up the AIQLick recruitment platform. Understanding these concepts is essential for working with any part of the codebase.

Visual Diagrams

For visual ER diagrams of every model and relationship, see Entity Relationships.

Identity and Access

User

The central identity entity representing both job seekers and employers. A single user account can operate in either mode.

• selectedCompanyId determines the user's currently active company context. When set, the user operates in employer mode within that company. When null, the user is in job seeker mode.
• Users can belong to multiple companies simultaneously, each with different roles and permissions.
• Authentication produces a JWT token that encodes the user identity and is validated across all services.

Company

The organizational entity that owns most multi-tenant resources (jobs, pipelines, talent pools, candidates).

• Companies are the primary unit of access control. Most queries are scoped to the user's active company.
• Billing (subscriptions, credit balances) is attached at the company level for employer operations.
• A company can have multiple members with different roles from the platform's 8-role system.

UserCompanyRole

The RBAC (Role-Based Access Control) bridge between users and companies.

• Each record associates a user with a company and assigns one of the platform's 8 roles.
• Roles are organized into tiers: Admin (Super Admin, Company Admin), Member (Internal Sales, Recruiter/HR), Viewer (External Sales, Economy, Auditor/Viewer), and Special (support).
• A user may hold different roles in different companies.
• Authorization is enforced via role name checks (@HasRole decorator, roles.ts tier functions), not via the permission join table. See Security & Authentication for the full role matrix.

ViewMode

The ViewMode enum (EMPLOYER / JOB_SEEKER) is a fundamental concept that affects multiple system behaviors:

Aspect	EMPLOYER mode	JOB_SEEKER mode
Company context	selectedCompanyId is set	selectedCompanyId is null
Credit routing	AI costs deducted from company balance	AI costs deducted from personal balance
UI layout	Company dashboard, job management, pipelines	Personal profile, job search, applications
Data access	Scoped to the active company's resources	Scoped to the user's personal resources

Recruitment

Talent

A candidate profile stored in the system, independent of any specific job application.

• Talents live within talent pools, which are owned by companies or shared across organizations.
• Unique constraint: @@unique([userId, talentPoolId]) -- a person can appear once per pool.
• Each talent tracks an active CV and maintains parsed profile data (skills, experience, education).
• Talents become candidates when they are linked to a specific job.

TalentNote

An internal note attached directly to a talent profile, independent of any job candidacy.

• Notes allow recruiters to capture observations and context before a talent is linked to any job.
• Only the author can edit or delete their own notes; all team members with access to the talent can view them.
• Notes are never visible to the talent themselves (the job seeker).

Candidate

A talent that has been applied or added to a specific job, tracked through a recruitment pipeline.

• Status progression: NEW -> IN_REVIEW -> INTERVIEW -> APPROVED or REJECTED
• Each candidate is associated with exactly one job and one pipeline position.
• The candidate record tracks the full history of status changes, reviewer notes, and interview outcomes.

Pipeline

A configurable Kanban-style workflow that defines the stages candidates move through during recruitment.

• Pipelines are linked to jobs via PipelineItem records.
• Stages are customizable per company and can be reordered.
• Candidates progress through pipeline stages, providing a visual overview of recruitment progress.

Job

A job posting created by a company, representing an open position.

• Status values: NEW, IN_PROGRESS, PENDING_FEEDBACK, CLOSED, FUTURE_REQUESTS, DRAFT
• Each job references three company roles:
  • Owner -- the hiring company
  • Hiring manager -- the responsible team
  • Supplier -- external recruiter, if applicable
• Jobs are the anchor point for candidates, matching scores, and pipeline tracking.

Documents

CV

A resume document uploaded to S3 and processed by the AI pipeline.

• The raw file is stored in S3 (aiqlick-uploads bucket).
• AI extraction writes parsed data into 11 structured tables: CvProfile, CvJobPreference, CvWorkExperience, CvEducation, CvCertification, CvLanguage, CvProject, CvPublication, CvAward, CvVolunteer, and CvMetadata.
• Extraction runs as a streaming subscription (cvExtraction), providing real-time progress to the frontend.

Communication

Meeting

A video conference room hosted on the Jitsi Meet infrastructure.

• The roomName field correlates with Transcription.meetingId for linking audio transcription data.
• Meetings can be scheduled in advance with calendar invitations (RSVP links) or created on demand.
• Reminders are sent at 24h, 6h, and 1h before the scheduled time.

Transcription

Speech-to-text segments generated during a meeting.

• Written by background-tasks as audio is processed through the Jigasi transcription gateway and AWS Transcribe.
• Each segment includes the speaker identifier, timestamp, and transcribed text.
• Transcription data feeds into the meeting insight generation pipeline.

MeetingInsight

AI-generated analysis of a meeting based on its transcription data.

• Insights include summaries, action items, key topics, and sentiment analysis.
• Supports versioning for live updates: insights are regenerated as new transcription data arrives during an active meeting.
• Generated automatically when a meeting ends (triggered by Prosody webhook) or on demand.

AI

Agent

An AI assistant configuration that powers the conversational agent feature.

• Defines the LLM model, RAG (Retrieval-Augmented Generation) settings, and available tools.
• Has 11 child tables covering conversations, messages, documents, document chunks, embeddings, tool definitions, and execution logs.
• Documents are chunked, embedded using Titan Embed v2 (1024 dimensions), and indexed for hybrid search (0.7x vector + 0.3x text score).
• The document worker polls every 30 seconds for new documents to process.

Entity Relationship Summary

Key Enums

Enum	Values
CandidateStatus	NEW, IN_REVIEW, INTERVIEW, APPROVED, REJECTED, WITHDRAWN
JobStatus	NEW, IN_PROGRESS, PENDING_FEEDBACK, CLOSED, FUTURE_REQUESTS, DRAFT
InterviewStatus	Tracks interview lifecycle
ViewMode	EMPLOYER, JOB_SEEKER
AIOperationType	CV_EXTRACTION, JOB_PARSING, MEETING_INSIGHT, MATCHING, TEXT_REWRITE, AGENT_CHAT
CreditTransactionType	PLAN_ALLOCATION, PACK_PURCHASE, CONSUMPTION, INITIAL_GRANT, REFUND, MANUAL_ADJUSTMENT, TRANSFER
BillingMode	PREPAID (standard credits), POSTPAID (enterprise usage-based invoicing)
SubscriptionStatus	Tracks subscription lifecycle synced with Stripe; includes PENDING_APPROVAL and UNPAID for enterprise flows