# vishesh233/interviewpilot architecture

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

- Interactive diagram: https://gitdiagram.com/vishesh233/interviewpilot
- Repository: https://github.com/vishesh233/interviewpilot

## Overview

InterviewPilot turns a job description into a saved, editable interview-preparation kit, then supports studying and practicing from it. The principal workflow runs through authenticated browser requests, background generation jobs, staged preparation, and MongoDB persistence; the frontend polls jobs and presents the resulting kit. Distinct stages include requirement extraction, company research, question generation, coverage and gap filling, and schedule creation. The README also documents optional resume matching, answer feedback, and mock interviews. Some subsystem paths are present in the tree but their implementation was not sampled, so those capabilities are shown without inferred internal call edges.

Main entry points: [`backend/src/server.js`](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/server.js) (Express API), [`backend/src/services/interviewPrepPipelineService.js`](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/interviewPrepPipelineService.js) (Prep pipeline), [`backend/src/models/InterviewPrepKit.js`](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/models/InterviewPrepKit.js) (Interview kits), [`frontend/app/layout.js`](https://github.com/vishesh233/interviewpilot/blob/main/frontend/app/layout.js) (InterviewPilot UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web app"]
  node_browser["InterviewPilot UI<br/>[layout.js]"]
  node_newkit["New kit form<br/>[NewKitForm.js]"]
  node_jobpoll["Job polling<br/>[useJobPolling.js]"]
  node_workspace["Kit workspace<br/>[KitWorkspace.js]"]
  node_study["Study views<br/>[QuestionsPanel.js]"]
  node_practiceui["Practice modes<br/>[PracticeMode.js]"]
end

subgraph group_api["API and jobs"]
  node_server["Express API<br/>[server.js]"]
  node_kitroutes["Kit routes"]
  node_jobroutes["Job routes"]
  node_kitcontroller["Kit controllers"]
  node_buildercontroller["Builder controller"]
  node_jobcontroller["Job controller"]
  node_jobs["Generation job runner"]
end

subgraph group_generation["Kit generation"]
  node_pipeline["Prep pipeline"]
  node_requirements["Requirement extraction"]
  node_research["Company research"]
  node_companybrief["Company brief"]
  node_questions["Question generation"]
  node_coverage["Coverage and gap fill<br/>[coverageService.js]"]
  node_gapfill["Gap filling<br/>[gapFillService.js]"]
  node_schedule["Study schedule<br/>[scheduleService.js]"]
  node_resume["Resume matching"]
end

subgraph group_kit["Kit and practice"]
  node_kitbuilder["Kit shaping and validation"]
  node_feedback["Answer feedback"]
  node_mock["Mock interviews"]
end

subgraph group_persistence["Persistence and AI"]
  node_kitstore[("Interview kits")]
  node_jobstore[("Generation jobs<br/>[GenerationJob.js]")]
  node_gemini["Gemini model adapter<br/>[geminiClient.js]"]
end

node_user(("Job seeker"))
node_mongodb[("MongoDB")]

node_user -->|"uses"| node_browser
node_browser -->|"starts kit"| node_newkit
node_newkit -->|"submits request"| node_server
node_browser -->|"calls API"| node_server
node_server -->|"mounts routes"| node_kitroutes
node_server -->|"mounts routes"| node_jobroutes
node_kitroutes -->|"routes requests"| node_kitcontroller
node_kitroutes -->|"routes edits"| node_buildercontroller
node_jobroutes -->|"routes polling"| node_jobcontroller
node_jobcontroller -->|"starts and reads jobs"| node_jobs
node_jobs -.->|"runs pipeline"| node_pipeline
node_pipeline -->|"extracts"| node_requirements
node_pipeline -->|"researches company"| node_research
node_research -.->|"builds brief"| node_companybrief
node_pipeline -->|"generates questions"| node_questions
node_pipeline -->|"checks coverage"| node_coverage
node_pipeline -->|"fills gaps"| node_gapfill
node_pipeline -.->|"creates schedule"| node_schedule
node_pipeline -->|"matches resume"| node_resume
node_pipeline -.->|"uses model"| node_gemini
node_jobpoll -->|"polls job"| node_server
node_jobs -.->|"persists checkpoints"| node_jobstore
node_kitcontroller -->|"reads and writes kits"| node_kitstore
node_kitcontroller -->|"prepares kit"| node_kitbuilder
node_kitbuilder -->|"checks coverage"| node_coverage
node_buildercontroller -->|"loads and saves"| node_kitstore
node_buildercontroller -->|"requests grading"| node_feedback
node_workspace -.->|"loads kit"| node_server
node_workspace -.->|"shows kit content"| node_study
node_study -.->|"edits questions"| node_server
node_practiceui -.->|"saves practice"| node_server
node_feedback -->|"grades answer"| node_gemini
node_server -.->|"serves mock interviews"| node_mock
node_kitstore -->|"stored in"| node_mongodb
node_jobstore -.->|"stored in"| node_mongodb
node_companybrief -.-> node_server
node_mock -.->|"uses kit"| node_kitstore

click node_browser "https://github.com/vishesh233/interviewpilot/blob/main/frontend/app/layout.js"
click node_newkit "https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/kit/NewKitForm.js"
click node_jobpoll "https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/jobs/useJobPolling.js"
click node_workspace "https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/kit/KitWorkspace.js"
click node_study "https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/questions/QuestionsPanel.js"
click node_practiceui "https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/practice/PracticeMode.js"
click node_server "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/server.js"
click node_kitroutes "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/routes/interviewPrepKitsRoutes.js"
click node_jobroutes "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/routes/generationJobRoutes.js"
click node_kitcontroller "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/interviewPrepKitsController.js"
click node_buildercontroller "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/interviewPrepKitBuilderController.js"
click node_jobcontroller "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/generationJobsController.js"
click node_jobs "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/generationJobService.js"
click node_pipeline "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/interviewPrepPipelineService.js"
click node_requirements "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/requirementExtractionService.js"
click node_research "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/companyResearchPipelineService.js"
click node_companybrief "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/companyBriefService.js"
click node_questions "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/questionGenerationService.js"
click node_coverage "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/coverageService.js"
click node_gapfill "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/gapFillService.js"
click node_schedule "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/scheduleService.js"
click node_resume "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/resumeMatchService.js"
click node_kitbuilder "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/kitBuilderService.js"
click node_feedback "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/answerFeedbackService.js"
click node_mock "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/mockInterviewService.js"
click node_kitstore "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/models/InterviewPrepKit.js"
click node_jobstore "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/models/GenerationJob.js"
click node_gemini "https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/geminiClient.js"

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_browser,node_newkit,node_jobpoll,node_workspace,node_study,node_practiceui toneBlue
class node_server,node_kitroutes,node_jobroutes,node_kitcontroller,node_buildercontroller,node_jobcontroller,node_jobs,node_mongodb toneAmber
class node_pipeline,node_requirements,node_research,node_companybrief,node_questions,node_coverage,node_gapfill,node_schedule,node_resume toneMint
class node_kitbuilder,node_feedback,node_mock toneRose
class node_kitstore,node_jobstore,node_gemini,node_user toneIndigo
```

## Components

### Web app

- [InterviewPilot UI](https://github.com/vishesh233/interviewpilot/blob/main/frontend/app/layout.js): `frontend/app/layout.js`
- [New kit form](https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/kit/NewKitForm.js): `frontend/components/kit/NewKitForm.js`
- [Job polling](https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/jobs/useJobPolling.js): `frontend/components/jobs/useJobPolling.js`
- [Kit workspace](https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/kit/KitWorkspace.js): `frontend/components/kit/KitWorkspace.js`
- [Study views](https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/questions/QuestionsPanel.js): `frontend/components/questions/QuestionsPanel.js`
- [Practice modes](https://github.com/vishesh233/interviewpilot/blob/main/frontend/components/practice/PracticeMode.js): `frontend/components/practice/PracticeMode.js`

### API and jobs

- [Express API](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/server.js): `backend/src/server.js`
- [Kit routes](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/routes/interviewPrepKitsRoutes.js): `backend/src/routes/interviewPrepKitsRoutes.js`
- [Job routes](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/routes/generationJobRoutes.js): `backend/src/routes/generationJobRoutes.js`
- [Kit controllers](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/interviewPrepKitsController.js): `backend/src/controllers/interviewPrepKitsController.js`
- [Builder controller](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/interviewPrepKitBuilderController.js): `backend/src/controllers/interviewPrepKitBuilderController.js`
- [Job controller](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/controllers/generationJobsController.js): `backend/src/controllers/generationJobsController.js`
- [Generation job runner](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/generationJobService.js): `backend/src/services/generationJobService.js`

### Kit generation

- [Prep pipeline](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/interviewPrepPipelineService.js): `backend/src/services/interviewPrepPipelineService.js`
- [Requirement extraction](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/requirementExtractionService.js): `backend/src/services/requirementExtractionService.js`
- [Company research](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/companyResearchPipelineService.js): `backend/src/services/companyResearchPipelineService.js`
- [Company brief](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/companyBriefService.js): `backend/src/services/companyBriefService.js`
- [Question generation](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/questionGenerationService.js): `backend/src/services/questionGenerationService.js`
- [Coverage and gap fill](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/coverageService.js): `backend/src/services/coverageService.js`
- [Gap filling](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/gapFillService.js): `backend/src/services/gapFillService.js`
- [Study schedule](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/scheduleService.js): `backend/src/services/scheduleService.js`
- [Resume matching](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/resumeMatchService.js): `backend/src/services/resumeMatchService.js`

### Kit and practice

- [Kit shaping and validation](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/kitBuilderService.js): `backend/src/services/kitBuilderService.js`
- [Answer feedback](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/answerFeedbackService.js): `backend/src/services/answerFeedbackService.js`
- [Mock interviews](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/mockInterviewService.js): `backend/src/services/mockInterviewService.js`

### Persistence and AI

- [Interview kits](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/models/InterviewPrepKit.js): `backend/src/models/InterviewPrepKit.js`
- [Generation jobs](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/models/GenerationJob.js): `backend/src/models/GenerationJob.js`
- [Gemini model adapter](https://github.com/vishesh233/interviewpilot/blob/main/backend/src/services/geminiClient.js): `backend/src/services/geminiClient.js`

### Other components

- **Job seeker**
- **MongoDB**

## Connections

- Job seeker → InterviewPilot UI: uses (evidence: `README.md`)
- InterviewPilot UI → New kit form: starts kit (evidence: `README.md`)
- New kit form → Express API: submits request (evidence: `README.md`)
- InterviewPilot UI → Express API: calls API (evidence: `README.md`)
- Express API → Kit routes: mounts routes (evidence: `backend/src/server.js`)
- Express API → Job routes: mounts routes (evidence: `backend/src/server.js`)
- Kit routes → Kit controllers: routes requests (evidence: `backend/src/routes/interviewPrepKitsRoutes.js`)
- Kit routes → Builder controller: routes edits (evidence: `backend/src/routes/interviewPrepKitsRoutes.js`)
- Job routes → Job controller: routes polling (evidence: `backend/src/routes/generationJobRoutes.js`)
- Job controller → Generation job runner: starts and reads jobs (evidence: `backend/src/controllers/generationJobsController.js`)
- Generation job runner → Prep pipeline: runs pipeline
- Prep pipeline → Requirement extraction: extracts (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Company research: researches company (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Company research → Company brief: builds brief
- Prep pipeline → Question generation: generates questions (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Coverage and gap fill: checks coverage (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Gap filling: fills gaps (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Study schedule: creates schedule (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Resume matching: matches resume (evidence: `backend/src/services/interviewPrepPipelineService.js`)
- Prep pipeline → Gemini model adapter: uses model
- Job polling → Express API: polls job (evidence: `README.md`)
- Generation job runner → Generation jobs: persists checkpoints
- Kit controllers → Interview kits: reads and writes kits (evidence: `backend/src/controllers/interviewPrepKitsController.js`)
- Kit controllers → Kit shaping and validation: prepares kit (evidence: `backend/src/controllers/interviewPrepKitsController.js`)
- Kit shaping and validation → Coverage and gap fill: checks coverage (evidence: `backend/src/services/kitBuilderService.js`)
- Builder controller → Interview kits: loads and saves (evidence: `backend/src/controllers/interviewPrepKitBuilderController.js`)
- Builder controller → Answer feedback: requests grading (evidence: `backend/src/controllers/interviewPrepKitBuilderController.js`)
- Kit workspace → Express API: loads kit
- Kit workspace → Study views: shows kit content
- Study views → Express API: edits questions
- Practice modes → Express API: saves practice
- Answer feedback → Gemini model adapter: grades answer (evidence: `backend/src/services/answerFeedbackService.js`)
- Express API → Mock interviews: serves mock interviews
- Interview kits → MongoDB: stored in (evidence: `backend/src/models/InterviewPrepKit.js`)
- Generation jobs → MongoDB: stored in
- Company brief → Express API
- Mock interviews → Interview kits: uses kit
