How foloup/foloup works
Purpose and Runtime
FoloUp is a Next.js/TypeScript platform for organizations to create AI-led voice hiring interviews, share candidate links, collect call results, and analyze responses. It runs as a Next.js application, deployable to Vercel or Docker. Primary runtime entry points are the routed UI under src/app/ and HTTP handlers under src/app/api/.
Identity, Tenancy, and Application Shell
Clerk provides authentication and organization tenancy. The app separates recruiter/admin-facing client routes from candidate-facing routes, with layouts supplying the relevant shell and providers.
• src/app/(client)/layout.tsx
• src/app/(user)/layout.tsx
• src/components/providers.tsx
• src/proxy.ts
Recruiter Dashboard and Interview Authoring
Recruiters manage interviewers and interviews from dashboard pages. The interview creation workflow captures role details, optionally accepts a PDF job description, generates or edits questions, and creates a shareable interview.
• src/app/(client)/dashboard/page.tsx
• src/components/dashboard/interview/createInterviewModal.tsx
• src/actions/parse-pdf.ts
• src/app/api/generate-interview-questions/route.ts
Domain State and Persistence Boundary
React contexts expose client-side collections for interviews, interviewers, candidates/clients, and responses. Service modules form the application’s persistence boundary and use Supabase; the schema and migration define the durable data model, including interviewer normalization.
• src/contexts/interviews.context.tsx
• src/services/interviews.service.ts
• src/services/responses.service.ts
• supabase_schema.sql
• supabase/migrations/20260520101000_normalize_interviewer_id.sql
Voice Interview Execution
Candidates enter through a unique interview route and interact with the call UI. Server APIs create/register calls and retrieve call state. Retell AI is the external voice-call runtime and owns call/recording management; webhook delivery returns asynchronous call events/results to the app.
• src/app/(user)/call/[interviewId]/page.tsx
• src/components/call/index.tsx
• src/app/api/create-interview/route.ts
• src/app/api/register-call/route.ts
• src/app/api/response-webhook/route.ts
AI Generation and Evaluation Pipeline
OpenAI-backed route handlers generate interview questions, analyze communication, and produce final insights. Prompt definitions isolate AI instructions from request orchestration; analytics and feedback services persist or aggregate the resulting assessments.
• src/app/api/analyze-communication/route.ts
• src/app/api/generate-insights/route.ts
• src/lib/prompts/generate-questions.ts
• src/lib/prompts/communication-analysis.ts
• src/services/analytics.service.ts
Results and Review Flow
After Retell call completion and webhook ingestion, response records feed recruiter review surfaces: per-question answers, summaries, feedback, and dashboard performance views. The interview detail route is the primary review entry point.
• src/app/(client)/interviews/[interviewId]/page.tsx
• src/components/dashboard/interview/questionAnswerCard.tsx
• src/components/dashboard/interview/summaryInfo.tsx
• src/services/feedback.service.ts
External Infrastructure
Required services are Clerk (auth/organizations), Supabase (database), Retell AI (voice calls and recordings), and OpenAI (question generation and analysis). Environment configuration begins at .env.example; containerized local/hosted execution is supported by Dockerfile and docker-compose.yml.
Main entry points: interviews.service.ts Domain services · analyze-communication/route.ts Evaluation APIs · page.tsx Interview review · generate-interview-questions/route.ts Question generation API
Components 20
Application UI
Next.js routed recruiter and candidate experiences.
- App shells & tenancy · Separates recruiter and candidate shells with shared providers.
src/app/(client)/layout.tsx - Auth proxy · Protects and routes authenticated application access.
src/proxy.ts - Recruiter dashboard · Recruiter entry point for interview management.
src/app/(client)/dashboard/page.tsx - Interview authoring · Captures role details, PDFs, questions, and shareable interviews.
src/components/dashboard/interview/createInterviewModal.tsx - Candidate call experience · Unique interview link and live call UI.
src/app/(user)/call/[interviewId]/page.tsx - Interview review · Shows answers, summaries, feedback, and performance.
src/app/(client)/interviews/[interviewId]/page.tsx - Question answers
src/components/dashboard/interview/questionAnswerCard.tsx
Server Workflows
Route handlers and AI orchestration.
- Question generation API · Generates interview questions from role inputs.
src/app/api/generate-interview-questions/route.ts - Call lifecycle APIs · Creates interviews and registers candidate calls.
src/app/api/create-interview/route.ts - Call results webhook · Ingests asynchronous Retell call events and results.
src/app/api/response-webhook/route.ts - Evaluation APIs · Analyzes communication and generates final insights.
src/app/api/analyze-communication/route.ts - AI prompts · Separates question and communication instructions from handlers.
src/lib/prompts/generate-questions.ts
Data & State
Client state and Supabase-backed domain services.
- Interview client state · Exposes interviews, interviewers, candidates, and responses to the UI.
src/contexts/interviews.context.tsx - Domain services · Persistence boundary for interviews and responses.
src/services/interviews.service.ts - Analytics & feedback · Persists and aggregates assessments for review.
src/services/analytics.service.ts - Interview data model · Durable model including normalized interviewer relationships.
supabase_schema.sql
External Services
Managed identity, voice, database, and AI providers.
- Clerk · Authentication and organization tenancy.
- Supabase · Application persistence store.
- Retell AI · Owns voice calls, recordings, and completion events.
- OpenAI · Generates questions and candidate assessments.
Connections 21
- Auth proxy → Clerk: authenticates
- App shells & tenancy → Clerk: organization context
- Recruiter dashboard → Interview client state: reads and updates
- Interview authoring → Question generation API: requests questions
- Interview authoring → Domain services: creates interview
- Question generation API → AI prompts: uses
- Question generation API → OpenAI: generates with
- Interview client state → Domain services: loads domain data
- Domain services → Supabase: persists
- Interview data model → Supabase: defines schema
- Candidate call experience → Call lifecycle APIs: starts and registers call
- Call lifecycle APIs → Retell AI: creates voice call
- Retell AI → Call results webhook: completion events
- Call results webhook → Domain services: stores responses
- Call results webhook → Evaluation APIs: triggers assessment
- Evaluation APIs → AI prompts: uses
- Evaluation APIs → OpenAI: analyzes with
- Evaluation APIs → Analytics & feedback: persists assessments
- Interview review → Domain services: loads responses
- Interview review → Analytics & feedback: loads insights
- Interview review → Question answers: renders