# anujsharma8d/mockspire architecture

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

- Interactive diagram: https://gitdiagram.com/anujsharma8d/mockspire
- Repository: https://github.com/anujsharma8d/mockspire

## Overview

Mockspire is an AI-powered mock-interview platform. The main workflow is: a candidate configures an interview, answers generated questions (optionally by speech), receives adaptive follow-ups, and views scored feedback and progress. The graph separates the React experience, API/auth boundary, interview and analysis logic, and persistence/integrations. The excerpts show key interview and result calls; some client API wiring and unsampled controllers are represented only at subsystem level, so their links rely on README architecture and workflow descriptions.

Main entry points: [`client/src/App.jsx`](https://github.com/anujsharma8d/mockspire/blob/main/client/src/App.jsx) (React routes), [`client/src/api`](https://github.com/anujsharma8d/mockspire/tree/main/client/src/api) (API clients), [`server/controllers/InterviewController.js`](https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/InterviewController.js) (Session and question setup), [`server/models`](https://github.com/anujsharma8d/mockspire/tree/main/server/models) (MongoDB models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Candidate experience"]
  node_webapp["React routes<br/>[App.jsx]"]
  node_setup["Interview setup<br/>[Setup.jsx]"]
  node_practice["Live interview<br/>[Interview.jsx]"]
  node_speech["Speech input"]
  node_resultsui["Results view<br/>[Result.jsx]"]
  node_progressui["Dashboard and history<br/>[Dashboard.jsx]"]
end

subgraph group_api["API and access"]
  node_clientapi["API clients"]
  node_server["Express API<br/>[server.js]"]
  node_authroutes["Authentication routes<br/>[authRoutes.js]"]
  node_auth["JWT verification<br/>[auth.js]"]
  node_interviewroutes["Interview routes<br/>[interviewRoutes.js]"]
end

subgraph group_interview["Interview workflow"]
  node_interviewctl["Session and question setup"]
  node_answerctl["Answer handling"]
  node_adaptive["Adaptive evaluation"]
  node_questionselect["Question selection"]
  node_fallback["Fallback question bank"]
  node_gemini{{"Gemini AI"}}
end

subgraph group_insights["Analysis and persistence"]
  node_resultctl["Result generation"]
  node_insightctl["Performance insights"]
  node_database[("MongoDB models")]
end

node_candidate(("Candidate"))
node_speechapi{{"Browser Speech API"}}

node_candidate -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_setup
node_webapp -->|"routes to"| node_practice
node_webapp -->|"routes to"| node_resultsui
node_webapp -->|"routes to"| node_progressui
node_practice -.->|"uses"| node_speech
node_speech -->|"recognizes speech"| node_speechapi
node_setup -->|"requests interview"| node_clientapi
node_practice -->|"submits answers"| node_clientapi
node_resultsui -->|"requests results"| node_clientapi
node_progressui -->|"requests history"| node_clientapi
node_clientapi -->|"REST requests"| node_server
node_server -->|"mounts"| node_authroutes
node_server -->|"mounts"| node_interviewroutes
node_authroutes -->|"verifies protected requests"| node_auth
node_interviewroutes -->|"verifies requests"| node_auth
node_interviewroutes -->|"dispatches"| node_interviewctl
node_interviewctl -->|"generates questions"| node_gemini
node_interviewctl -->|"falls back to"| node_fallback
node_interviewctl -->|"stores sessions and questions"| node_database
node_answerctl -->|"evaluates and follows up"| node_adaptive
node_answerctl -->|"builds context and questions"| node_questionselect
node_answerctl -->|"reads and saves answers"| node_database
node_adaptive -->|"evaluates responses"| node_gemini
node_resultctl -->|"loads and stores results"| node_database
node_resultctl -->|"generates feedback"| node_gemini
node_insightctl -->|"reads insights"| node_database
node_insightctl -->|"generates insights"| node_gemini

click node_webapp "https://github.com/anujsharma8d/mockspire/blob/main/client/src/App.jsx"
click node_setup "https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Setup.jsx"
click node_practice "https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Interview.jsx"
click node_speech "https://github.com/anujsharma8d/mockspire/blob/main/client/src/hooks/useSpeechRecognition.js"
click node_resultsui "https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Result.jsx"
click node_progressui "https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Dashboard.jsx"
click node_clientapi "https://github.com/anujsharma8d/mockspire/tree/main/client/src/api"
click node_server "https://github.com/anujsharma8d/mockspire/blob/main/server/server.js"
click node_authroutes "https://github.com/anujsharma8d/mockspire/blob/main/server/routes/authRoutes.js"
click node_auth "https://github.com/anujsharma8d/mockspire/blob/main/server/middleware/auth.js"
click node_interviewroutes "https://github.com/anujsharma8d/mockspire/blob/main/server/routes/interviewRoutes.js"
click node_interviewctl "https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/InterviewController.js"
click node_answerctl "https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/AnswerController.js"
click node_adaptive "https://github.com/anujsharma8d/mockspire/blob/main/server/services/adaptiveInterviewService.js"
click node_questionselect "https://github.com/anujsharma8d/mockspire/blob/main/server/services/questionSelectionService.js"
click node_fallback "https://github.com/anujsharma8d/mockspire/blob/main/server/services/fallbackQuestionBank.js"
click node_resultctl "https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/ResultController.js"
click node_insightctl "https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/InsightController.js"
click node_database "https://github.com/anujsharma8d/mockspire/tree/main/server/models"

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_webapp,node_setup,node_practice,node_speech,node_resultsui,node_progressui,node_speechapi toneBlue
class node_clientapi,node_server,node_authroutes,node_auth,node_interviewroutes toneAmber
class node_interviewctl,node_answerctl,node_adaptive,node_questionselect,node_fallback,node_gemini toneMint
class node_resultctl,node_insightctl,node_database toneRose
class node_candidate toneIndigo
```

## Components

### Candidate experience

- [React routes](https://github.com/anujsharma8d/mockspire/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Interview setup](https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Setup.jsx): `client/src/pages/Setup.jsx`
- [Live interview](https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Interview.jsx): `client/src/pages/Interview.jsx`
- [Speech input](https://github.com/anujsharma8d/mockspire/blob/main/client/src/hooks/useSpeechRecognition.js): `client/src/hooks/useSpeechRecognition.js`
- [Results view](https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Result.jsx): `client/src/pages/Result.jsx`
- [Dashboard and history](https://github.com/anujsharma8d/mockspire/blob/main/client/src/pages/Dashboard.jsx): `client/src/pages/Dashboard.jsx`

### API and access

- [API clients](https://github.com/anujsharma8d/mockspire/tree/main/client/src/api): `client/src/api`
- [Express API](https://github.com/anujsharma8d/mockspire/blob/main/server/server.js): `server/server.js`
- [Authentication routes](https://github.com/anujsharma8d/mockspire/blob/main/server/routes/authRoutes.js): `server/routes/authRoutes.js`
- [JWT verification](https://github.com/anujsharma8d/mockspire/blob/main/server/middleware/auth.js): `server/middleware/auth.js`
- [Interview routes](https://github.com/anujsharma8d/mockspire/blob/main/server/routes/interviewRoutes.js): `server/routes/interviewRoutes.js`

### Interview workflow

- [Session and question setup](https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/InterviewController.js): `server/controllers/InterviewController.js`
- [Answer handling](https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/AnswerController.js): `server/controllers/AnswerController.js`
- [Adaptive evaluation](https://github.com/anujsharma8d/mockspire/blob/main/server/services/adaptiveInterviewService.js): `server/services/adaptiveInterviewService.js`
- [Question selection](https://github.com/anujsharma8d/mockspire/blob/main/server/services/questionSelectionService.js): `server/services/questionSelectionService.js`
- [Fallback question bank](https://github.com/anujsharma8d/mockspire/blob/main/server/services/fallbackQuestionBank.js): `server/services/fallbackQuestionBank.js`
- **Gemini AI**

### Analysis and persistence

- [Result generation](https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/ResultController.js): `server/controllers/ResultController.js`
- [Performance insights](https://github.com/anujsharma8d/mockspire/blob/main/server/controllers/InsightController.js): `server/controllers/InsightController.js`
- [MongoDB models](https://github.com/anujsharma8d/mockspire/tree/main/server/models): `server/models`

### Other components

- **Candidate**
- **Browser Speech API**

## Connections

- Candidate → React routes: uses (evidence: `README.md`)
- React routes → Interview setup: routes to (evidence: `client/src/App.jsx`)
- React routes → Live interview: routes to (evidence: `client/src/App.jsx`)
- React routes → Results view: routes to (evidence: `client/src/App.jsx`)
- React routes → Dashboard and history: routes to (evidence: `client/src/App.jsx`)
- Live interview → Speech input: uses
- Speech input → Browser Speech API: recognizes speech (evidence: `README.md`)
- Interview setup → API clients: requests interview (evidence: `README.md`)
- Live interview → API clients: submits answers (evidence: `README.md`)
- Results view → API clients: requests results (evidence: `README.md`)
- Dashboard and history → API clients: requests history (evidence: `client/src/pages/Dashboard.jsx`)
- API clients → Express API: REST requests (evidence: `README.md`)
- Express API → Authentication routes: mounts (evidence: `server/server.js`)
- Express API → Interview routes: mounts (evidence: `server/server.js`)
- Authentication routes → JWT verification: verifies protected requests (evidence: `server/routes/authRoutes.js`)
- Interview routes → JWT verification: verifies requests (evidence: `server/routes/interviewRoutes.js`)
- Interview routes → Session and question setup: dispatches (evidence: `server/routes/interviewRoutes.js`)
- Session and question setup → Gemini AI: generates questions (evidence: `server/controllers/InterviewController.js`)
- Session and question setup → Fallback question bank: falls back to (evidence: `server/controllers/InterviewController.js`)
- Session and question setup → MongoDB models: stores sessions and questions (evidence: `server/controllers/InterviewController.js`)
- Answer handling → Adaptive evaluation: evaluates and follows up (evidence: `server/controllers/AnswerController.js`)
- Answer handling → Question selection: builds context and questions (evidence: `server/controllers/AnswerController.js`)
- Answer handling → MongoDB models: reads and saves answers (evidence: `server/controllers/AnswerController.js`)
- Adaptive evaluation → Gemini AI: evaluates responses (evidence: `server/services/adaptiveInterviewService.js`)
- Result generation → MongoDB models: loads and stores results (evidence: `server/controllers/ResultController.js`)
- Result generation → Gemini AI: generates feedback (evidence: `server/controllers/ResultController.js`)
- Performance insights → MongoDB models: reads insights (evidence: `server/controllers/InsightController.js`)
- Performance insights → Gemini AI: generates insights (evidence: `server/controllers/InsightController.js`)
