A structured AI interviewer web application built with Next.js, Gemini, and Supabase. The app conducts a technical interview through chat, enforces mandatory interview coverage, stores the full transcript, and generates a transcript-grounded hiring evaluation report.
This project is designed around the core assignment requirement: the important part is not just the chat interface, but the interview control logic, evidence tracking, and final evaluation quality.
- Starts a candidate interview session.
- Accepts job descriptions and resumes by paste,
.txt, or selectable-text PDF upload. - Opens with a consistent interview handshake.
- Conducts the rest of the interview through Gemini-generated interviewer turns.
- Maintains the conversation transcript and session state in Supabase.
- Covers required interview areas:
- candidate introduction
- academic background
- technical / coding background
- programming languages known
- 1-5 self-rating for each mentioned language
- logical follow-up questions grounded in prior answers
- Blocks final evaluation until mandatory coverage is complete.
- Generates a structured evaluation report with score, recommendation, strengths, weaknesses, technical assessment, communication assessment, cultural fit, sentiment, risks, missing evidence, and next-round focus.
The opening handshake is fixed by application code for consistency; all interview Q&A after the candidate's first reply is model-generated and transcript/context-driven. This avoids the model skipping the required introduction step while still keeping the actual interview dynamic.
- Next.js 16 App Router
- TypeScript
- React 19
- Tailwind CSS 4
- Google Gemini API via
@google/generative-ai - Supabase PostgreSQL
- Zod for response validation
Browser UI
-> /api/interview/start
-> /api/interview/message
-> /api/interview/end
-> /api/interview/[id]
Next.js API Routes
-> Supabase session/message storage
-> Gemini interviewer generation
-> coverage tracking
-> final evaluation generation
Supabase
-> interview_sessions
-> messages
-> evaluation_json
-> agent_state_jsonThe app does not rely only on a generic LLM prompt.
It uses three layers:
-
Structured interviewer prompt Guides the model to stay in interviewer role, ask one question at a time, and cover the mandatory interview areas.
-
Server-side coverage tracking
src/lib/coverage-state.tsanalyzes the transcript for required coverage. It tracks whether each mandatory area is missing, partial, or complete. -
Completion gating
/api/interview/endrefuses to generate the final report until required coverage is complete. If the candidate tries to end early, the API returns the missing areas and the next required question.
This makes the product more controlled than a simple chatbot wrapper.
The final evaluator receives:
- full transcript
- job description, if provided
- resume text, if provided
- per-turn rubric rollup
- verified coverage summary
The evaluator must return validated JSON matching the application schema.
Report fields include:
overallScoreconfidenceScorestrengthsweaknessesriskFlagshiringRecommendationtechnicalAssessmentcommunicationAssessmentculturalFitsentimentAnalysisperformanceSummarydetailedReasoningmissingEvidencenextRoundFocus
Voice interview mode extends the same structured interview engine used by typed chat.
Flow:
Candidate records answer
-> /api/stt
-> Deepgram speech-to-text
-> /api/interview/message
-> Gemini interviewer response
-> /api/tts
-> Deepgram Aura text-to-speech
-> browser plays interviewer audioThe voice path keeps transcript storage, coverage tracking, completion gating, and final evaluation identical to the text path.
Implementation details:
- Uses
MediaRecorderin the browser for answer capture. - Uses Deepgram STT through
/api/stt. - Uses Deepgram Aura TTS through
/api/tts. - Shows both the transcribed answer and interviewer response in the chat.
- Lets the candidate interrupt spoken interviewer audio by tapping the mic; current audio playback is cancelled before recording starts.
- Keeps typed answers available as a fallback during voice sessions.
This is a batch recording flow, not a full duplex LiveKit stream. src/lib/audio/streaming-audio-placeholder.ts is reserved for a future LiveKit + streaming STT/TTS implementation.
Supabase stores:
- interview session metadata
- chat transcript
- job description and resume text
- agent/rubric state
- final evaluation JSON
Schema:
supabase/schema.sqlRLS is enabled. The app uses the Supabase service role key only inside server routes.
npm installCreate a Supabase project and run:
supabase/schema.sqlIf updating an older local schema, also apply:
supabase/migration_add_jd_resume.sql
supabase/migration_agent_state.sqlCopy .env.example to .env.local and fill in:
GEMINI_API_KEY=
NEXT_PUBLIC_SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
GEMINI_MODEL=gemini-2.5-flashNotes:
SUPABASE_SERVICE_ROLE_KEYmust be a secret/service role key, not an anon or publishable key.GEMINI_MODELis optional. The default isgemini-2.5-flash.
npm run devOpen:
http://localhost:3000npm run dev
npm run build
npm run start
npm run lint| Method | Route | Purpose |
|---|---|---|
POST |
/api/interview/start |
Creates a session and stores the fixed opening message |
POST |
/api/interview/message |
Stores candidate answer, updates coverage, generates next interviewer turn |
POST |
/api/interview/end |
Generates final evaluation only if required coverage is complete |
GET |
/api/interview/[id] |
Returns session metadata, messages, and parsed evaluation |
POST |
/api/resume/parse |
Extracts resume text from PDF or .txt uploads |
POST |
/api/stt |
Transcribes recorded audio with Deepgram |
POST |
/api/tts |
Synthesizes interviewer speech with Deepgram Aura |
GET |
/api/dev/gemini-models |
Development helper for checking available Gemini models |
src/app/ Next.js routes and API handlers
src/components/ Chat, setup, voice, and report UI
src/lib/prompts.ts Interviewer and evaluator prompts
src/lib/gemini.ts Gemini calls and response parsing
src/lib/coverage-state.ts Mandatory coverage extraction and gating logic
src/lib/evaluation.ts Evaluation schema validation
src/lib/audio/ Deepgram STT/TTS service abstraction
src/lib/agent-state.ts Per-turn rubric rollup state
src/lib/rubric.ts Turn-level scoring schema
src/lib/supabase/admin.ts Server-side Supabase client
supabase/schema.sql Database schemaThe setup form supports manual resume paste, plain .txt upload, and selectable-text PDF upload. PDF parsing runs on the server through /api/resume/parse; scanned/image-only PDFs are not OCR processed and should be pasted manually.
- Gemini and Supabase secret keys are read only on the server.
- The browser never receives
GEMINI_API_KEYorSUPABASE_SERVICE_ROLE_KEY. - Supabase RLS is enabled. Direct browser access to tables is not used.
- This assignment version does not include candidate authentication; session IDs are used as access tokens for the interview/report pages.
- Coverage detection is deterministic and heuristic. It is intentionally server-side, but a production version should use a stronger semantic extractor and tests against real transcripts.
- Voice mode uses recorded audio chunks rather than full-duplex streaming; a future LiveKit version would reduce latency and support more natural overlapping speech.
- There is no reviewer/admin dashboard yet.
- There is no mock AI mode; reviewers need valid Gemini and Supabase credentials to run the full flow.
The project should pass:
npx tsc --noEmit
npm run lint
npm run buildOn some Windows/sandboxed environments, Next.js may need permission to spawn build workers. The application code itself builds cleanly once worker spawning is allowed.