# foloup/foloup architecture

> Architecture diagram of the GitHub repository foloup/foloup, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/foloup/foloup
- Repository: https://github.com/foloup/foloup

## Overview

#### 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: [`src/services/interviews.service.ts`](https://github.com/foloup/foloup/blob/main/src/services/interviews.service.ts) (Domain services), [`src/app/api/analyze-communication/route.ts`](https://github.com/foloup/foloup/blob/main/src/app/api/analyze-communication/route.ts) (Evaluation APIs), [`src/app/(client)/interviews/[interviewId]/page.tsx`](https://github.com/foloup/foloup/blob/main/src/app/(client)/interviews/%5BinterviewId%5D/page.tsx) (Interview review), [`src/app/api/generate-interview-questions/route.ts`](https://github.com/foloup/foloup/blob/main/src/app/api/generate-interview-questions/route.ts) (Question generation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Application UI"]
  node_shell["App shells &amp; tenancy<br/>Next.js layouts<br/>[layout.tsx]"]
  node_proxy["Auth proxy<br/>Next.js proxy<br/>[proxy.ts]"]
  node_dashboard["Recruiter dashboard<br/>dashboard route<br/>[page.tsx]"]
  node_authoring["Interview authoring<br/>creation modal"]
  node_candidate_call["Candidate call experience<br/>candidate route<br/>[page.tsx]"]
  node_review["Interview review<br/>detail route<br/>[page.tsx]"]
  node_question_answers["Question answers<br/>review component"]
end

subgraph group_api["Server Workflows"]
  node_question_api["Question generation API<br/>route handler<br/>[route.ts]"]
  node_call_api["Call lifecycle APIs<br/>route handlers<br/>[route.ts]"]
  node_webhook["Call results webhook<br/>route handler<br/>[route.ts]"]
  node_evaluation_api["Evaluation APIs<br/>route handlers<br/>[route.ts]"]
  node_prompts["AI prompts<br/>prompt definitions"]
end

subgraph group_data["Data &amp; State"]
  node_client_state["Interview client state<br/>React context"]
  node_domain_services["Domain services<br/>service layer"]
  node_analytics["Analytics &amp; feedback<br/>service layer"]
  node_schema["Interview data model<br/>SQL schema"]
end

subgraph group_external["External Services"]
  node_clerk{{"Clerk<br/>identity provider"}}
  node_supabase[("Supabase<br/>database")]
  node_retell{{"Retell AI<br/>voice platform"}}
  node_openai{{"OpenAI<br/>AI provider"}}
end

node_proxy -->|"authenticates"| node_clerk
node_shell -->|"organization context"| node_clerk
node_dashboard -->|"reads and updates"| node_client_state
node_authoring -->|"requests questions"| node_question_api
node_authoring -->|"creates interview"| node_domain_services
node_question_api -->|"uses"| node_prompts
node_question_api -->|"generates with"| node_openai
node_client_state -->|"loads domain data"| node_domain_services
node_domain_services -->|"persists"| node_supabase
node_schema -->|"defines schema"| node_supabase
node_candidate_call -->|"starts and registers call"| node_call_api
node_call_api -->|"creates voice call"| node_retell
node_retell -.->|"completion events"| node_webhook
node_webhook -->|"stores responses"| node_domain_services
node_webhook -->|"triggers assessment"| node_evaluation_api
node_evaluation_api -->|"uses"| node_prompts
node_evaluation_api -->|"analyzes with"| node_openai
node_evaluation_api -->|"persists assessments"| node_analytics
node_review -->|"loads responses"| node_domain_services
node_review -->|"loads insights"| node_analytics
node_review -->|"renders"| node_question_answers

click node_shell "https://github.com/foloup/foloup/blob/main/src/app/(client)/layout.tsx"
click node_proxy "https://github.com/foloup/foloup/blob/main/src/proxy.ts"
click node_dashboard "https://github.com/foloup/foloup/blob/main/src/app/(client)/dashboard/page.tsx"
click node_authoring "https://github.com/foloup/foloup/blob/main/src/components/dashboard/interview/createInterviewModal.tsx"
click node_candidate_call "https://github.com/foloup/foloup/blob/main/src/app/(user)/call/%5BinterviewId%5D/page.tsx"
click node_review "https://github.com/foloup/foloup/blob/main/src/app/(client)/interviews/%5BinterviewId%5D/page.tsx"
click node_question_answers "https://github.com/foloup/foloup/blob/main/src/components/dashboard/interview/questionAnswerCard.tsx"
click node_client_state "https://github.com/foloup/foloup/blob/main/src/contexts/interviews.context.tsx"
click node_domain_services "https://github.com/foloup/foloup/blob/main/src/services/interviews.service.ts"
click node_analytics "https://github.com/foloup/foloup/blob/main/src/services/analytics.service.ts"
click node_schema "https://github.com/foloup/foloup/blob/main/supabase_schema.sql"
click node_question_api "https://github.com/foloup/foloup/blob/main/src/app/api/generate-interview-questions/route.ts"
click node_call_api "https://github.com/foloup/foloup/blob/main/src/app/api/create-interview/route.ts"
click node_webhook "https://github.com/foloup/foloup/blob/main/src/app/api/response-webhook/route.ts"
click node_evaluation_api "https://github.com/foloup/foloup/blob/main/src/app/api/analyze-communication/route.ts"
click node_prompts "https://github.com/foloup/foloup/blob/main/src/lib/prompts/generate-questions.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_shell,node_proxy,node_dashboard,node_authoring,node_candidate_call,node_review,node_question_answers toneBlue
class node_question_api,node_call_api,node_webhook,node_evaluation_api,node_prompts toneAmber
class node_client_state,node_domain_services,node_analytics,node_schema toneMint
class node_clerk,node_supabase,node_retell,node_openai toneRose
```

## Components

### Application UI

Next.js routed recruiter and candidate experiences.

- [App shells & tenancy](https://github.com/foloup/foloup/blob/main/src/app/(client)/layout.tsx): Next.js layouts · Separates recruiter and candidate shells with shared providers. · `src/app/(client)/layout.tsx`
- [Auth proxy](https://github.com/foloup/foloup/blob/main/src/proxy.ts): Next.js proxy · Protects and routes authenticated application access. · `src/proxy.ts`
- [Recruiter dashboard](https://github.com/foloup/foloup/blob/main/src/app/(client)/dashboard/page.tsx): dashboard route · Recruiter entry point for interview management. · `src/app/(client)/dashboard/page.tsx`
- [Interview authoring](https://github.com/foloup/foloup/blob/main/src/components/dashboard/interview/createInterviewModal.tsx): creation modal · Captures role details, PDFs, questions, and shareable interviews. · `src/components/dashboard/interview/createInterviewModal.tsx`
- [Candidate call experience](https://github.com/foloup/foloup/blob/main/src/app/(user)/call/%5BinterviewId%5D/page.tsx): candidate route · Unique interview link and live call UI. · `src/app/(user)/call/[interviewId]/page.tsx`
- [Interview review](https://github.com/foloup/foloup/blob/main/src/app/(client)/interviews/%5BinterviewId%5D/page.tsx): detail route · Shows answers, summaries, feedback, and performance. · `src/app/(client)/interviews/[interviewId]/page.tsx`
- [Question answers](https://github.com/foloup/foloup/blob/main/src/components/dashboard/interview/questionAnswerCard.tsx): review component · `src/components/dashboard/interview/questionAnswerCard.tsx`

### Server Workflows

Route handlers and AI orchestration.

- [Question generation API](https://github.com/foloup/foloup/blob/main/src/app/api/generate-interview-questions/route.ts): route handler · Generates interview questions from role inputs. · `src/app/api/generate-interview-questions/route.ts`
- [Call lifecycle APIs](https://github.com/foloup/foloup/blob/main/src/app/api/create-interview/route.ts): route handlers · Creates interviews and registers candidate calls. · `src/app/api/create-interview/route.ts`
- [Call results webhook](https://github.com/foloup/foloup/blob/main/src/app/api/response-webhook/route.ts): route handler · Ingests asynchronous Retell call events and results. · `src/app/api/response-webhook/route.ts`
- [Evaluation APIs](https://github.com/foloup/foloup/blob/main/src/app/api/analyze-communication/route.ts): route handlers · Analyzes communication and generates final insights. · `src/app/api/analyze-communication/route.ts`
- [AI prompts](https://github.com/foloup/foloup/blob/main/src/lib/prompts/generate-questions.ts): prompt definitions · 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](https://github.com/foloup/foloup/blob/main/src/contexts/interviews.context.tsx): React context · Exposes interviews, interviewers, candidates, and responses to the UI. · `src/contexts/interviews.context.tsx`
- [Domain services](https://github.com/foloup/foloup/blob/main/src/services/interviews.service.ts): service layer · Persistence boundary for interviews and responses. · `src/services/interviews.service.ts`
- [Analytics & feedback](https://github.com/foloup/foloup/blob/main/src/services/analytics.service.ts): service layer · Persists and aggregates assessments for review. · `src/services/analytics.service.ts`
- [Interview data model](https://github.com/foloup/foloup/blob/main/supabase_schema.sql): SQL schema · Durable model including normalized interviewer relationships. · `supabase_schema.sql`

### External Services

Managed identity, voice, database, and AI providers.

- **Clerk**: identity provider · Authentication and organization tenancy.
- **Supabase**: database · Application persistence store.
- **Retell AI**: voice platform · Owns voice calls, recordings, and completion events.
- **OpenAI**: AI provider · Generates questions and candidate assessments.

## Connections

- 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
