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

LayerComponents
UI (Next.js App Router)Client pages in src/app/(client) with React contexts (auth, interviews, interviewers, responses)
API/ServicesRoute handlers in src/app/api/*; business logic in src/services/*
Webhooks/Processingapi/response-webhook validates Retell signatures and triggers call retrieval and analysis
Data StoreMongoDB for interviews, interviewers, responses, users, and organizations
External ServicesRetell (LLM agents + events) and OpenAI (analytics generation)

​
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)

EntityKey Fields
Interviewername, agent_id, user { id, email }, companyId
Interviewid, name, objective, questions[], url, readable_slug, user, companyId
Responsecall_id, transcript, analytics { score, strengths, improvements, insights }, duration, is_analysed, candidate_status, timestamps
Organizationname, logo_url, companyId
User/Session_id, email, roleCode, companyId
Multi-tenancy:
All core entities are scoped by companyId for secure isolation between tenants.
  • Interview Creation
  • Calls & Analysis
  • API & Auth
  • App & Sessions
  • Performance & Cost
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

LayerTechnologiesPurpose
Frontend UINext.js 14 (App Router), React 18, Tailwind, Radix UI, shadcn/ui, framer-motionDashboard, modals, forms
State/FormsReact Context, React Hook FormClient state and validation
API/ServerNext.js Route Handlers, iron-sessionAPI endpoints and session management
Servicessrc/services/*Business logic and data access
DatabaseMongoDB (native driver)Data persistence
AI/MLOpenAI SDKTranscript analytics
Voice/TelephonyRetell SDKLLM agent creation and event handling
Utilitiesaxios, zod, uuid/nanoid, lucide-reactHTTP, validation, IDs, icons
Stylingtailwindcss-animate, clsx, class-variance-authorityStyling helpers
Build/ToolingTypeScript, ESLint, PostCSS, TailwindDeveloper tooling

​
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.
⌘I