TruthHire

AI-powered interview intelligence platform for hiring teams that want faster, fairer, and more evidence-backed decisions.

TruthHire runs a coordinated multi-agent pipeline over interview data to detect bluff patterns, surface resume contradictions, score job-fit, and generate actionable post-interview reports.

Table of Contents

1. Overview
2. Core Capabilities
3. Architecture
4. Agent Pipeline
5. Tech Stack
6. Repository Structure
7. Quick Start
8. Environment Variables
9. Database Setup and Migration
10. Running the System
11. API Reference
12. Real-Time and Audio Flow
13. Security and Privacy
14. Deployment Guide
15. Troubleshooting
16. Development Workflow
17. Roadmap
18. License

Overview

TruthHire is built for HR teams and interview panels that need structured signal, not guesswork.

What the platform does:

• Parses and normalizes candidate resume claims
• Matches resume strength versus job description requirements
• Processes interview answers through specialized AI evaluators
• Flags likely bluffing and claim contradictions
• Scores communication confidence indicators
• Produces candidate-facing and HR-facing report outputs

What it does not do:

• It does not replace human decision-making
• It does not use demographic attributes for scoring
• It does not persist raw audio streams as stored interview artifacts

Core Capabilities

• Multi-agent interview analysis pipeline
• Resume-to-answer contradiction detection
• Bluff probability scoring with follow-up trap suggestions
• Voice and linguistic confidence analysis
• Dynamic interview continuation questions
• Team analytics endpoint for hiring trend visibility
• Tiered plan enforcement and webhook-driven billing state updates

Architecture

TruthHire uses a split architecture:

• Frontend: Next.js 14 (App Router) for dashboard, interview setup, live flow, and reports
• Backend: Express + Socket.IO for API, orchestration, webhooks, and cron jobs
• Data: Supabase Postgres (plus Supabase Auth)
• Cache and rate limiting: Upstash Redis
• AI: Mistral models via centralized agent calling service

High-level runtime flow:

1. HR creates an interview
2. Resume is uploaded and parsed
3. JD is uploaded and matched
4. Interview starts
5. Each candidate answer is processed by agent orchestration
6. Finalize endpoint generates and stores reports
7. Optional notifications are sent through Brevo

Agent Pipeline

TruthHire includes seven specialized agents:

1. ResumeParser: Extracts structured claims from resume text
2. JDMatcher: Computes fit and interview focus areas versus JD
3. InterviewerAgent: Produces contextual follow-up questions
4. BluffDetector: Estimates bluff probability and bluff type
5. ContradictionEngine: Finds inconsistencies versus resume claims
6. VoiceAnalyzer: Scores linguistic and audio confidence indicators
7. ReportGenerator: Builds final HR and candidate report content

Pipeline sequencing:

• Setup phase: ResumeParser -> JDMatcher
• Per-answer phase:
  • Parallel: BluffDetector + ContradictionEngine + VoiceAnalyzer
  • Then: InterviewerAgent
• Finalization phase: Contradiction full-pass -> ReportGenerator -> status/report persistence

Tech Stack

Frontend

• Next.js 14
• React 18
• Supabase JS client

Backend

• Node.js + Express
• Socket.IO
• Supabase JS client
• Mistral SDK
• Upstash Redis + rate limiter
• node-cron
• multer + pdf/doc parser utilities
• Brevo transactional email SDK

Infra and Services

• Supabase (Auth + Postgres + optional storage)
• Upstash Redis
• Mistral API
• Lemon Squeezy and Razorpay webhooks

Repository Structure

interview/
  backend/
    agents/
    cron/
    db/
    middleware/
    orchestrator/
    routes/
    services/
    server.js
  frontend/
    app/
    components/
    lib/
  .env.example
  README.md
  SETUP.md
  package.json

Quick Start

Prerequisites

• Node.js 18+
• npm 9+
• Supabase project
• Mistral API key

Install

npm install
npm run install:all

Configure environment

cp .env.example .env

Populate required keys in .env. Full variable reference is in the Environment Variables section below.

Apply database schema

In Supabase SQL Editor:

1. Run backend/db/schema.sql
2. If you are upgrading an existing project, run backend/db/migration_fix_columns.sql

Run

npm run dev

Default local ports:

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Environment Variables

Copy from .env.example and fill values. Do not commit real values.

Required (core)

• MISTRAL_API_KEY
• SUPABASE_URL
• SUPABASE_ANON_KEY
• SUPABASE_SERVICE_ROLE_KEY
• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY

Required (runtime defaults)

• NEXT_PUBLIC_APP_URL (for links in report emails, defaults should be explicit)

Recommended

• UPSTASH_REDIS_REST_URL
• UPSTASH_REDIS_REST_TOKEN
• BREVO_API_KEY
• EMAIL_FROM
• EMAIL_FROM_NAME

Optional

• NEXT_PUBLIC_API_URL (frontend override, otherwise defaults to localhost backend)
• BACKEND_PORT (or PORT)

Payment/Webhook optional variables

• LEMON_SQUEEZY_API_KEY
• LEMON_SQUEEZY_WEBHOOK_SECRET
• NEXT_PUBLIC_LEMON_SQUEEZY_STORE_ID
• RAZORPAY_KEY_ID
• RAZORPAY_KEY_SECRET
• RAZORPAY_WEBHOOK_SECRET

Database Setup and Migration

Fresh project

Use backend/db/schema.sql only.

Existing project migration

Use backend/db/migration_fix_columns.sql after schema alignment to:

• Backfill/rename legacy columns
• Repair report and contradiction field naming
• Recreate increment_interviews_used function
• Repair auth signup profile trigger behavior

If signup failures occurred with "Database error creating new user", run the migration script to repair trigger/profile compatibility.

Running the System

Monorepo command

npm run dev

Separate processes

# Terminal 1
cd backend
npm run dev

# Terminal 2
cd frontend
npm run dev

Production build check

cd frontend
npm run build

API Reference

Base URL (local):

• Backend API: http://localhost:3001

Authentication:

• All protected endpoints require Authorization: Bearer <supabase_access_token>
• Public endpoints:
  • GET /api/health
  • POST /api/webhook/*

Health

• GET /api/health

Auth (protected)

• GET /api/auth/profile
• PUT /api/auth/profile

Interviews (protected)

• POST /api/interviews
• GET /api/interviews
• GET /api/interviews/:id
• POST /api/interviews/:id/resume
• POST /api/interviews/:id/jd
• POST /api/interviews/:id/start
• POST /api/interviews/:id/answer
• POST /api/interviews/:id/complete
• GET /api/interviews/:id/turns
• DELETE /api/interviews/:id

Reports (protected)

• GET /api/reports/:interviewId
• GET /api/reports/analytics/team

Webhooks (public)

• POST /api/webhook/lemon-squeezy
• POST /api/webhook/stripe (deprecated response)
• POST /api/webhook/razorpay

Real-Time and Audio Flow

Backend Socket.IO handlers support:

• join_interview
• leave_interview
• audio_chunk

The backend processes finalized candidate utterances through the orchestrator and emits structured analysis events.

Current frontend flow is API-first and can be extended to consume more live socket events as needed.

Security and Privacy

• Row-level ownership checks enforced at route level with Supabase identity
• Rate limiting middleware with graceful fallback if Redis is unavailable
• Webhook signature verification for Lemon Squeezy and Razorpay
• .env files are ignored via .gitignore patterns
• No hardcoded credentials should exist in code or docs
• Audio streams are processed in-session and not persisted as raw streams

Deployment Guide

Frontend

Deploy frontend Next.js app to Vercel or equivalent.

Backend

Deploy Express backend to Render, Railway, VPS, or container platform.

Production checklist:

1. Set backend CORS origins to your frontend domain
2. Set NEXT_PUBLIC_APP_URL to deployed frontend URL
3. Configure webhook URLs to deployed backend
4. Ensure Supabase keys and Mistral key are present in backend environment
5. Confirm Redis credentials for rate limiting and cache

Webhook endpoints

• https://your-api-domain/api/webhook/lemon-squeezy
• https://your-api-domain/api/webhook/razorpay

Troubleshooting

Signup/login succeeds but API returns 401

• Confirm frontend uses correct NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
• Confirm bearer token is attached to API calls
• Confirm backend can validate token against same Supabase project

"Database error creating new user"

• Run backend/db/migration_fix_columns.sql in Supabase
• Ensure profiles table includes fields expected by trigger

Interview setup fails during resume/JD analysis

• Verify MISTRAL_API_KEY is set in backend environment
• Check backend logs for agent-call validation errors

Rate limit behavior seems inconsistent

• Verify Upstash credentials
• If Redis unavailable, middleware falls back to permissive mode by design

Email sending not occurring

• Set BREVO_API_KEY
• Without key, service degrades to console-only mode

Development Workflow

Typical local workflow

1. Create interview from dashboard
2. Upload/paste resume
3. Upload/paste JD
4. Start interview
5. Submit manual or captured answers
6. Complete interview and inspect report endpoint

Useful scripts

Root:

• npm run dev
• npm run install:all

Backend:

• npm run dev
• npm start

Frontend:

• npm run dev
• npm run build
• npm run start

Roadmap

• Rich real-time event visualizations in live interview UI
• Expanded analytics and cohort benchmarking
• Team workspaces and multi-role access controls
• Deeper observability and audit logging
• Additional language and domain-specific interview packs

License

MIT

Contributing

PRs are welcome.

Recommended process:

1. Fork and create a feature branch
2. Keep changes scoped and tested
3. Update docs for behavior/API changes
4. Open a pull request with context and validation notes

---

If you are setting this up for the first time, start with SETUP.md and then return here for advanced architecture, API, and deployment details.