AgentHR Developer Guide

Platform Overview

AgentHR is an AI-powered HR hiring SaaS platform built by Diploy (Bisht Technologies Private Limited). It enables organizations to create AI agents for automated phone interviews, manage hiring pipelines, bulk-screen CVs, and conduct AI voice interviews at scale.

Architecture Diagram

                    +-------------------+
                    |   React Frontend  |
                    |  (Vite + shadcn)  |
                    +--------+----------+
                             |
                    +--------v----------+
                    |  Express Backend  |
                    |   (TypeScript)    |
                    +--------+----------+
                             |
          +------------------+------------------+
          |                  |                  |
  +-------v------+  +-------v------+  +-------v------+
  |   Drizzle    |  |   Engines    |  |   Plugins    |
  |  PostgreSQL  |  | (Voice, Pay) |  | (REST, SIP,  |
  |              |  |              |  |  Team Mgmt)  |
  +--------------+  +------+-------+  +--------------+
                           |
            +--------------+--------------+
            |              |              |
     +------v---+  +------v---+  +------v---+
     | ElevenLabs|  |  Twilio  |  |  Plivo   |
     |  OpenAI   |  |          |  |          |
     +-----------+  +----------+  +----------+

Project Structure

AgentHR/
├── client/                  # React frontend (Vite)
│   ├── src/
│   │   ├── pages/           # Route-based page components
│   │   ├── components/      # Reusable UI components
│   │   │   ├── ui/          # shadcn/ui base components
│   │   │   ├── landing/     # Public landing page components
│   │   │   └── admin/       # Admin panel components
│   │   ├── contexts/        # React contexts (auth, plugins)
│   │   ├── hooks/           # Custom React hooks
│   │   ├── lib/             # Utilities (API client, formatters)
│   │   └── i18n/            # Internationalization config
│   └── public/              # Static assets
├── server/                  # Express backend
│   ├── routes/              # API route handlers
│   ├── services/            # Business logic layer
│   ├── engines/             # Specialized subsystems
│   │   ├── payment/         # Multi-gateway payment engine
│   │   ├── plivo/           # Plivo telephony engine
│   │   ├── twilio-openai/   # Twilio + OpenAI engine
│   │   ├── plivo-elevenlabs/# Plivo + ElevenLabs SIP engine
│   │   └── kyc/             # KYC verification engine
│   ├── infrastructure/      # DB pools, WebSocket, BullMQ
│   ├── middleware/          # Auth, rate limiting, logging
│   ├── storage/             # Data access layer (Drizzle)
│   ├── plugins/             # Plugin loader system
│   ├── demo-mode/           # Demo mode seeding & middleware
│   └── modules/             # Feature modules (widget, etc.)
├── shared/                  # Shared between client & server
│   └── schema.ts            # Drizzle ORM schema (source of truth)
├── plugins/                 # Installable plugins
│   ├── rest-api/            # REST API plugin
│   ├── sip-engine/          # SIP Engine plugin
│   └── team-management/     # Team Management plugin
├── packages/                # Internal libraries
│   └── diploy-core/         # Shared errors, logging, response utils
├── scripts/                 # Build, setup, deployment scripts
├── public/                  # Server-served static files
├── .env.example             # Environment variable template
├── drizzle.config.ts        # Drizzle ORM configuration
├── vite.config.ts           # Vite build configuration
├── tailwind.config.ts       # Tailwind CSS configuration
└── package.json             # Dependencies and scripts

Tech Stack

Database Schema

All tables are defined in shared/schema.ts using Drizzle ORM. The schema serves as the single source of truth for both backend queries and frontend types.

Core Tables

Key Relationships

Authentication & Authorization

Token Flow

Login Request (email + password)
       │
       ▼
   Validate credentials (bcrypt.compare)
       │
       ▼
   Generate Access Token (JWT, 15min expiry)
   Generate Refresh Token (random 64-char, 30-day expiry)
       │
       ├──► Access Token → Response body
       └──► Refresh Token → HttpOnly Secure Cookie (SHA-256 hashed in DB)
       
   On API Request:
       Authorization: Bearer <access_token>
       │
       ▼
   authenticateToken middleware → verify JWT → attach userId + userRole
       
   On Token Expiry:
       POST /api/auth/refresh (cookie-based)
       │
       ▼
   Validate refresh token hash → Issue new access token

Role Hierarchy

Middleware Chain

Request → Rate Limiter → authenticateToken → checkUserActive → requireRole / requireAdminPermission → Route Handler

API Reference

Authentication

Agents

Campaigns & Contacts

Phone Numbers

Calls & Analytics

Billing & Subscriptions

Admin Endpoints

AI Agent System

Agents are the core unit of the platform. Each agent is an AI persona configured with voice, personality, and instructions.

Agent Types

Voice Engines

Configuration Options

• Voice: ElevenLabs voice ID, stability, similarity boost, speed
• LLM: Model selection (gpt-4o-mini, gpt-realtime, etc.), temperature
• Behavior: System prompt, first message, language, max duration
• Transfer: Enable human transfer with phone number
• Knowledge Base: Attach documents for RAG context injection

Campaign Execution Engine

Execution Flow

Create Campaign → Upload CSV Contacts → Start Campaign
       │
       ▼
   CampaignExecutor validates:
   - Agent exists and is configured
   - Phone number assigned
   - Contacts have valid phone numbers
   - User has sufficient credits
       │
       ▼
   Route to engine based on telephonyProvider:
   ├── ElevenLabs → BatchCallingService (ElevenLabs Batch API)
   ├── Plivo → PlivoBatchCallingService (local concurrency)
   └── Twilio → TwilioOpenAIBatchCallingService (local concurrency)
       │
       ▼
   Pre-create call records in DB (batch insert)
       │
       ▼
   Execute calls with concurrency control
       │
       ▼
   Webhooks update call status, transcript, duration
       │
       ▼
   Campaign marked "completed" when all contacts processed

Key Features

• Timezone Awareness: scheduleTimezone field ensures calls happen within allowed hours
• Batch Processing: Contacts loaded in chunks of 500 to prevent memory exhaustion
• Concurrency Control: Global campaign_batch_concurrency setting limits parallel calls
• Auto-Pause/Resume: Scheduler (30s interval) pauses campaigns outside allowed hours
• Retry Logic: Failed calls retry up to 24 times (hourly) via ElevenLabs migration engine
• BullMQ (Optional): Set ENABLE_BULLMQ=true + REDIS_URL for distributed queue processing

Key Files

Flow Builder System

A visual conversation designer built on React Flow. Users create branching conversational logic using drag-and-drop nodes.

Node Types

• Start Node: Entry point with initial greeting
• Message Node: AI speaks a message
• Question Node: Ask a question and branch on response
• Condition Node: Logic branching (if/else)
• Transfer Node: Hand off to human agent
• End Node: Conversation termination

Flow Compilation

When saved, flows are compiled into executable state machines stored in compiledStates, compiledSystemPrompt, and compiledTools fields. The flow compilation is handled by server/services/elevenlabs-flow-compiler.ts (for ElevenLabs agents) and the flow agent service (server/services/flow-agent.ts), which convert visual nodes into LLM-compatible instructions.

Payment Infrastructure

Supported Gateways

Credit System

• Credits are the platform's internal currency for telephony usage
• Purchases via any gateway award credits atomically using PostgreSQL advisory locks
• Deductions happen per-call with unique reference IDs to prevent double-charging
• Refunds automatically reverse credit awards if unspent

Invoice Generation

Uses pdfkit to generate branded PDF invoices after completed transactions. Stored in ./data/invoices/ and linked in the invoices table.

HR / Hiring Module

Workflow

Create Job Posting → Upload CVs / Receive Widget Applications
       │
       ▼
   AI CV Screening (score + evaluation)
       │
       ▼
   Candidates enter Pipeline (stages: Applied → Screening → Interview → Offer → Hired)
       │
       ▼
   Schedule AI Phone Interview (via campaign executor or widget callback)
       │
       ▼
   Interview Session recorded with scoring, evaluation, recommendation
       │
       ▼
   Move through pipeline stages → Hire or Reject

Key Features

• AI CV Screening: Automatic scoring of uploaded resumes against job requirements
• Pipeline Management: Kanban-style candidate tracking through hiring stages
• AI Interviews: Automated phone interviews with scoring and recommendations
• Hiring Widget: Embeddable 6-step application wizard with instant AI voice interviews
• Analytics: Hiring funnel metrics and conversion rates

Webhook System

Users can subscribe to platform events and receive real-time HTTP notifications.

• HMAC-SHA256 Verification: Every delivery is signed with the subscription's secret
• Automatic Retries: Failed deliveries retry with exponential backoff (up to 5 attempts)
• Events: call.completed, campaign.completed, candidate.applied, etc.
• Delivery Logging: Every attempt is recorded in webhook_deliveries

Knowledge Base (RAG)

Users upload documents that get processed into chunks, embedded, and injected as context into AI agent conversations.

• Document Types: Text, URL, File upload (PDF, DOCX, TXT)
• Processing: Documents are sent to ElevenLabs Knowledge Base API for indexing
• Agent Linking: Multiple KB documents can be attached to a single agent via knowledgeBaseIds

Client-Side Architecture

Component Structure

client/src/
├── App.tsx                  # Root component with routing and guards
├── pages/                   # Route-based page components
│   ├── LandingPage.tsx      # Public landing page
│   ├── LoginPage.tsx        # Auth (login + register)
│   ├── Dashboard.tsx        # User dashboard
│   ├── Agents.tsx           # Agent management
│   ├── JobsPage.tsx         # HR job listings
│   ├── CandidatesPage.tsx   # Candidate management
│   ├── PipelinePage.tsx     # Hiring pipeline
│   ├── FlowBuilderPage.tsx  # Visual flow editor
│   ├── FlowsPage.tsx        # Flow listing
│   ├── Billing.tsx          # Subscription & credits
│   ├── Settings.tsx         # User profile
│   ├── AdminDashboard.tsx   # Admin panel
│   ├── AdminCampaignDetail.tsx
│   ├── InstallWizard.tsx    # First-time setup
│   └── policies/            # Privacy, Terms, Cookies
├── components/
│   ├── ui/                  # shadcn/ui primitives
│   ├── landing/             # Landing page sections
│   └── admin/               # Admin-specific components
├── contexts/
│   ├── plugin-registry.tsx  # Runtime plugin UI injection
│   └── dynamic-languages.tsx # i18n dynamic loading
├── hooks/                   # useToast, useAuth, etc.
├── lib/
│   ├── queryClient.ts       # TanStack Query config
│   ├── auth-storage.ts      # Token persistence
│   └── formatters.ts        # Date, currency formatters
└── i18n/                    # Translation files (11 languages)

Routing & Guards

Route Groups

Guard Logic

• UserGuard: Validates user JWT or team member session. Redirects to /login if invalid.
• AdminGuard: Validates user has role: "admin". Redirects to /app if not admin.
• AdminTeamGuard: Validates admin team session token. Redirects to /admin/team/login if invalid.

Pages Reference

Public Pages

User Dashboard Pages (/app/*)

Plugin System

Architecture

Plugins are self-contained extensions with their own backend routes, frontend UI, and database migrations.

plugins/
├── my-plugin/
│   ├── plugin.json          # Manifest: metadata, entry points, DB requirements
│   ├── index.ts              # Backend: Express route registration
│   ├── frontend/
│   │   └── index.tsx         # Frontend: UI component registration
│   ├── dist/
│   │   └── bundle.js         # Built frontend bundle
│   └── migrations/
│       └── 001_create_tables.sql

Lifecycle

1. Discovery: server/plugins/loader.ts scans /plugins for directories with plugin.json
2. Enable Check: Reads global_settings table for plugin_[name]_enabled = true
3. Backend Registration: Imports and calls the registerFunction from the manifest
4. Frontend Loading: PluginBootstrapper fetches /api/plugins/capabilities, downloads bundles
5. UI Injection: Bundles call window.__AGENTHR_PLUGIN_REGISTRY__ to register tabs and menu items

Plugin Management API

REST API Plugin

Exposes platform data via authenticated REST endpoints with API key management and professional documentation.

SIP Engine Plugin

Enables custom SIP trunk integration for voice calls, allowing users to bring their own telephony infrastructure.

Team Management Plugin

Adds RBAC (Role-Based Access Control) and multi-user sub-accounts for organizations.

Development Setup

Prerequisites

• Node.js 18.x or 20.x
• PostgreSQL 14+
• npm 8+
• Redis (optional, for BullMQ)

Installation Steps

# 1. Extract the package
unzip AgentHR-v1.0.0-complete.zip
cd AgentHR-v1.0.0

# 2. Copy environment template
cp .env.example .env

# 3. Run setup (auto-generates SESSION_SECRET and JWT_SECRET)
npm run setup

# 4. Edit .env with your configuration
#    - Database credentials
#    - Twilio / ElevenLabs API keys
#    - SMTP settings
#    - Payment gateway keys (optional)

# 5. Install dependencies
npm install

# 6. Push database schema
npm run db:push

# 7. Seed system data (plans, models, templates, etc.)
npm run db:seed

# 8. Build plugins (if modifying plugin source)
npm run build:plugins

# 9. Build for production
npm run build

# 10. Start the application
bash scripts/production.sh start

Development Mode

# Start dev server with hot reload
npm run dev
# Server runs on http://localhost:5000

npm Scripts

Environment Variables

Required

Integrations

Optional

Demo Mode

Demo mode creates a pre-populated demo account for showcasing the platform to visitors.

Activation

# In .env file
DEMO_MODE=true

What Gets Created

Behavior

• Seeding is idempotent — checks existing data count, skips if complete, cleans and re-seeds if partial
• Admin routes (/api/admin/*) are blocked with 403 for security
• User-side write operations are allowed so visitors can test features
• Response data is masked (emails, phone numbers, names) for privacy
• Configurable credentials via DEMO_EMAIL, DEMO_PASSWORD, DEMO_NAME env vars

Key Files

Production Deployment

Using Production Script

# Start
bash scripts/production.sh start

# Stop
bash scripts/production.sh stop

# Restart
bash scripts/production.sh restart

# View status
bash scripts/production.sh status

# View logs
bash scripts/production.sh logs

Using deploy.sh

# Full deployment (install, build, restart)
bash deploy.sh

Production Checklist

• Set NODE_ENV=production
• Use strong, unique SESSION_SECRET and JWT_SECRET (auto-generated by setup)
• Configure proper APP_URL and APP_DOMAIN
• Set up SMTP for email OTP verification
• Configure at least one telephony provider (Twilio or Plivo)
• Configure at least one voice AI provider (ElevenLabs or OpenAI)
• Configure at least one payment gateway
• Set up SSL/TLS (required for webhooks and cookie security)
• Enable STRIPE_WEBHOOK_SECRET for production webhook verification
• Run npm run db:push && npm run db:seed to initialize database
• Run npm run build before starting production server