# WaMax HR & ATS — Full System Architecture & LLM Comprehensive Reference

## 1. Executive Overview
WaMax HR & ATS is an enterprise-grade, multi-tenant recruitment and talent acquisition automation suite developed by WhatYouWantKerala (WYWK). It uniquely unifies WhatsApp communication, local AI computer vision, telephonic voice interviews, and multi-channel CRM into a single high-performance system.

## 2. Technical Stack & Operating Environment
- Backend Runtime: Node.js (v20+ LTS), Express.js
- Real-Time Communication: WebSockets (ws), Baileys WhatsApp Web API (sockets engine)
- Artificial Intelligence: Google Gemini 2.5 Flash / Pro, Deepgram Aura 2, voxCPM, pocket-tts, Tesseract.js OCR, Brain.js local NLP fallback
- Databases: Split LowDB architecture with atomic file-segmented persistence (candidates.json, sessions.json, settings.json, jobs.json, system.json, crm.json), plus MySQL for high-volume interview state synchronization
- Process Manager: PM2 cluster mode (hr_chatbot)
- Frontend Framework: Modern Vanilla JavaScript (ES6+), Tailwind CSS, GSAP 3, Lenis Smooth Scrolling, Chart.js

## 3. Detailed Engine Breakdown

### Engine 01: Multi-SIM WhatsApp Hub (5-Slot Architecture)
- Runs up to 5 concurrent WhatsApp business numbers from a single server instance.
- Dedicated session isolation (`session/conn_1` through `session/conn_5`).
- Live QR pairing and automated heartbeat watchdog recovery (`startHeartbeatWatchdog`).
- Eliminates per-conversation Meta Cloud API billing, saving agencies thousands of dollars monthly.

### Engine 02: Conversational Multilingual Screening
- Supports dynamic candidate qualification in Malayalam, Arabic, English, Hindi, Tamil, Kannada, Urdu, Nepali, and Bengali.
- Automatic intent recognition with Systematic Intent Recognition & Matching (SIRM).
- Graceful dead-end filtering (e.g. ignoring solitary 👍 thumbs-up reactions to keep pipelines clean).

### Engine 03: Asynchronous & Synchronous Audio Interviews
- Asynchronous WhatsApp Audio: Candidates submit voice notes describing their experience; WaMax performs audio transcription and acoustic analysis to extract candidate responses.
- Synchronous Web Voice Call Lobby (`/interview/lobby`): Real-time telephonic interview simulation evaluating speech fluency, pace, confidence, and filler word frequency. Generates an objective 1-10 scorecard.

### Engine 04: Edge-Level MRZ Passport Scanner
- Uses Tesseract.js locally to scan uploaded passport images and PDFs.
- Parses 2-line ICAO Doc 9303 Machine Readable Zone (MRZ).
- Automatically populates: Full Name, Passport Number, Nationality, Date of Birth, Gender, and Document Expiry.
- Fraudulent or expired passports trigger an automatic warning flag.

### Engine 05: Smart CV Parsing & Question Skipping
- Automatically parses PDF, DOCX, and text resumes.
- Maps extracted biographical details to candidate session variables.
- Dynamically skips funnel steps that have already been answered via CV.

### Engine 06: Recruiter Live Omnichannel Inbox (`/admin/inbox.html`)
- Omnichannel message aggregation across WhatsApp, Instagram Direct, and Telegram.
- Recruiter collision prevention: locks active conversations to assigned staff members.
- Internal staff-only notes (`isInternal: true`) visible only to team members.
- Auto-assignment modes: Least-Busy and Round-Robin routing with configurable max chat thresholds.
- 1-Click "Mark Handled / Resolved" returns conversation to automated bot flow.

### Engine 07: Client Review Portals & Anti-Poaching System (`/client-portal`)
- Segregated employer review portals with enterprise branding.
- Sensitive candidate contact details (phone number, email address) are masked to prevent unauthorized direct poaching.
- Employers can 1-click Approve, Reject, or Request Second Rounds with custom notes.
- Generates verified, branded PDF candidate dossiers with secure QR verification codes.

### Engine 08: Visual Recruitment Funnel Designer
- Node-based visual flow designer to create custom qualification trees.
- Supports buttons, lists, text inputs, file uploads, and conditional logic branching.

### Engine 09: WayConnect CRM & Ticketing
- Enterprise ticketing module with automated SLA timers and manager escalations.
- Deal pipelines, contact profiles, and multi-tenant SaaS workspace management.

### Engine 10: Anti-Ban Bulk Broadcast Engine
- Automated candidate notifications and job alerts.
- Adheres to WhatsApp anti-spam best practices using randomized delays (8-15s), human typing emulations, and daily volume caps.

## 4. API Endpoints
- GET `/api/health`: Health status check
- POST `/api/login`: Staff and Admin authentication
- GET `/api/inbox/chats`: Fetch omnichannel candidate conversation stream
- POST `/api/inbox/takeover`: Recruiter exclusive session lock
- POST `/api/inbox/resolve`: Release conversation back to AI automation
- GET `/api/whatsapp/slots`: Monitor all 5 WhatsApp connection slots
- GET `/api/whatsapp/status`: Check primary connection health
- POST `/api/interview/validate`: Validate candidate interview token
- GET `/api/talent-match`: AI-powered candidate to job requirement scoring