> ## Documentation Index
> Fetch the complete documentation index at: https://opensource.weam.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Recruiter

## 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.

> [!NOTE]
>
> 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

| Layer | Components |
| - | - |
| **UI (Next.js App Router)** | Client pages in `src/app/(client)` with React contexts (`auth`, `interviews`, `interviewers`, `responses`) |
| **API/Services** | Route handlers in `src/app/api/*`; business logic in `src/services/*` |
| **Webhooks/Processing** | `api/response-webhook` validates Retell signatures and triggers call retrieval and analysis |
| **Data Store** | MongoDB for interviews, interviewers, responses, users, and organizations |
| **External Services** | Retell (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)

| Entity | Key Fields |
| - | - |
| **Interviewer** | `name`, `agent_id`, `user { id, email }`, `companyId` |
| **Interview** | `id`, `name`, `objective`, `questions[]`, `url`, `readable_slug`, `user`, `companyId` |
| **Response** | `call_id`, `transcript`, `analytics { score, strengths, improvements, insights }`, `duration`, `is_analysed`, `candidate_status`, timestamps |
| **Organization** | `name`, `logo_url`, `companyId` |
| **User/Session** | `_id`, `email`, `roleCode`, `companyId` |

## TroubleShooting

> [tab] Interview Creation
>
> > [accordion] Failed to create interview
> >
> > **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

> [tab] Calls & Analysis
>
> > [accordion] Invalid signature or missing analysis
> >
> > **Symptoms**
> >
> > * Webhook returns 401 “Invalid signature”
> > * Analytics not generated; `is_analysed` remains false
> > * Public `get-call` fails and fallback also fails
> >
> > **Common causes**
> >
> > * Incorrect/missing `RETELL_API_KEY`
> > * Transcript missing from call response
> > * Misconfigured `NEXT_PUBLIC_LIVE_URL`/base path; call ID not ready
> >
> > **Solutions**
> >
> > * Verify Retell signature and API key
> > * Check transcript existence; set `OPENAI_API_KEY`
> > * Fix base URL/path; retry after analysis event

> [tab] API & Auth
>
> > [accordion] Protected endpoints failing
> >
> > **Symptoms**
> >
> > * 401 from protected endpoints; redirect to `/login`
> > * Public endpoints return 4xx/5xx
> >
> > **Common causes**
> >
> > * Expired/missing session; `check-access` denies
> > * Invalid request body; entity not found
> >
> > **Solutions**
> >
> > * Ensure session is set; verify role and `_id`
> > * Validate payload fields; ensure entities exist

> [tab] App & Sessions
>
> > [accordion] Session issues
> >
> > **Symptoms**
> >
> > * Client shows no user; `/api/auth/session` returns 401
> > * Stale cookies break auth consistency
> >
> > **Common causes**
> >
> > * Cookie name/password mismatch; iron-session misconfig
> > * Legacy cookies (`foloup_auth_session`, `iron-session`)
> >
> > **Solutions**
> >
> > * Set `NEXT_PUBLIC_COOKIE_NAME` and `NEXT_PUBLIC_COOKIE_PASSWORD`
> > * Clear old cookies; re-fetch session

> [tab] Performance & Cost
>
> > [accordion] Slow analytics or high costs
> >
> > **Symptoms**
> >
> > * Slow analytics
> > * High OpenAI usage
> > * Dashboard slow due to data fetching
> >
> > **Common causes**
> >
> > * Large transcripts; repeated re-analysis
> > * Unscoped queries; no pagination
> >
> > **Solutions**
> >
> > * Generate analytics once; cache/store results
> > * Scope by `companyId`, paginate, reuse context state

## Tech Stack

| Layer | Technologies | Purpose |
| - | - | - |
| **Frontend UI** | Next.js 14 (App Router), React 18, Tailwind, Radix UI, shadcn/ui, framer-motion | Dashboard, modals, forms |
| **State/Forms** | React Context, React Hook Form | Client state and validation |
| **API/Server** | Next.js Route Handlers, iron-session | API endpoints and session management |
| **Services** | `src/services/*` | Business logic and data access |
| **Database** | MongoDB (native driver) | Data persistence |
| **AI/ML** | OpenAI SDK | Transcript analytics |
| **Voice/Telephony** | Retell SDK | LLM agent creation and event handling |
| **Utilities** | axios, zod, uuid/nanoid, lucide-react | HTTP, validation, IDs, icons |
| **Styling** | tailwindcss-animate, clsx, class-variance-authority | Styling helpers |
| **Build/Tooling** | TypeScript, ESLint, PostCSS, Tailwind | Developer 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.