Skip to main content

​
Overview

This Next.js 14 app manages AI-driven interview workflows: create interviewers (Retell agents), create interviews with shareable call links, register and analyze calls, and store transcripts and insights in MongoDB with session-based access.
This AI Recruiter is part of Weam. Configuration, usage, and access happen within Weam.

​
What It Does (Capabilities)

  • Create Retell-backed interviewers and LLM agents
  • Create interviews with questions/objectives and shareable call URLs
  • Register calls and receive webhook events from Retell
  • Fetch call details/transcripts and generate OpenAI analytics
  • Manage interviews and responses via dashboard and APIs
  • Session-based access control with iron-session and middleware

​
User Flows

  • Configure interviewer: Provision a Retell-backed agent.
  • Create interview: Set name, objective, and questions; generate a shareable call URL.
  • Conduct call: Candidate joins via the link; system registers and receives Retell events.
  • Analyze & review: Transcript is processed, insights are generated via OpenAI, and data is stored for dashboard review.

​
Architecture

​
Technical Design

  • Interviewers: Create Retell LLM and agent, store agent_id with user and company context.
  • Interviews: Generate shareable call URL using NEXT_PUBLIC_LIVE_URL and optional slug; store questions and metadata.
  • Responses: Register calls and persist transcript, analytics, duration, and status flags.
  • Analytics: Build prompt from transcript and interview questions, generate structured insights with OpenAI.
  • Session/State: iron-session with /api/auth/session; middleware checks public/protected routes via check-access for role USER.
  • Security/Validation: Retell webhook signature verification; API key validation; session-based access control; selective public routes for integration flows.

​
API Reference (High Level)

​
Auth / Session

  • GET /api/auth/session - Returns current session user and companyId (401 if none).
  • POST /api/auth/logout - Ends session.
  • POST /api/auth/check-access - Used by middleware for authorization decisions.

​
Interviewers

  • GET /api/interviewers - List interviewers.
  • POST /api/interviewers - Create interviewer (provisions Retell agent).

​
Interviews

  • GET /api/interviews - List interviews (scoped by user/company).
  • POST /api/interviews - Create new interview.
  • POST /api/create-interview - Alternate creation path with call URL generation.
  • POST /api/interviews/[id]/generate-token - Generates secure token.

​
Calls and Responses

  • Public:
    • POST /api/public/register-call
    • POST /api/public/get-call
    • POST /api/public/responses
  • Authenticated:
    • POST /api/register-call
    • POST /api/get-call
    • GET /api/responses/call/[callId]
    • CRUD under /api/responses

​
Webhooks

  • POST /api/response-webhook - Validates Retell signature and triggers call retrieval/analysis.
Auth Scoping:
  • Public endpoints are available for integrations (no session).
  • Protected endpoints require iron-session; middleware enforces USER role access.

​
Data and Schemas (Conceptual)

​
TroubleShooting

Symptoms
  • 500 errors; toast shows “Failed to create interview”
  • Missing API keys; no new records
Common causes
  • Missing OPENAI_API_KEY, RETELL_API_KEY, NEXT_PUBLIC_*, DB vars
  • No user session (401)
  • Invalid payload types (e.g., BigInts)
Solutions
  • Set required env vars; retry
  • Ensure valid session before calling API
  • Sanitize payload on client

​
Tech Stack

​
Best Practices

  • Validate env vars before sensitive operations.
  • Preserve HTTP status codes for clarity.
  • Use authenticated endpoints wherever possible.
  • Cache analytics results to avoid recomputation.
  • Enforce tenant scoping via companyId.
  • Clear cookies on inconsistent auth state.
  • Log and handle Retell/OpenAI errors gracefully.
  • Avoid re-analyzing the same transcript multiple times.
  • Keep prompts deterministic and lightweight for stable OpenAI costs.