# himavarshithreddy/interviewos architecture

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

- Interactive diagram: https://gitdiagram.com/himavarshithreddy/interviewos
- Repository: https://github.com/himavarshithreddy/interviewos

## Overview

1. **Overall shape**
   - InterviewOS is a two-process application: a **React/Vite frontend** in the repo root and a **Node.js backend** under `server/`.
   - The app is centered on one workflow: **upload resume → configure panelists → run a live interview → analyze performance → render a report/dashboard**.

2. **Frontend composition**
   - The main UI is split into feature components in `components/`: `ResumeUploader`, `PanelConfiguration`, `LiveInterview`, and `Dashboard`.
   - `App.tsx` is the top-level composition point, while `index.tsx` and `index.html` bootstrap the browser app.
   - Supporting UI robustness comes from `src/components/ErrorBoundary.tsx`.

3. **Client-side state and interaction layer**
   - `src/services/apiClient.ts` is the browser-to-server boundary for REST calls.
   - `src/hooks/useVAD.ts` and `src/hooks/useVideoAnalysis.ts` handle real-time client behavior: voice activity detection and periodic video capture/upload for analysis.
   - `src/utils/sessionStorage.ts` suggests session persistence for interview state, while `src/utils/reportDownload.ts` supports exporting the final report.

4. **Live interview data path**
   - The live interview is not just request/response; it is a **streaming browser session**.
   - Browser audio is processed with `public/worklets/audio-processor.js` and utilities in `utils/audioUtils.ts`, then used for low-latency voice interaction.
   - The browser connects directly to Gemini Live for conversational audio, while also sending transcript/session signals to the backend orchestration channel.

5. **Backend entrypoint and boundaries**
   - `server/src/index.ts` is the backend bootstrap for the HTTP API and WebSocket server.
   - The backend is responsible for **resume parsing, panelist generation, analysis, and final reporting**.
   - It is intentionally not in the media path for the live audio stream; that path stays mostly browser-to-Gemini for latency reasons.

6. **Backend service layer**
   - `server/src/services/geminiService.ts` is the core Gemini integration used for structured generation and evaluation.
   - `interviewOrchestrator.ts` maintains interview state, topic coverage, depth progression, and panel flow.
   - `emotionAnalyzer.ts`, `presentationCoach.ts`, and `industrySpecialist.ts` provide specialized analysis and domain-specific question/evaluation logic.

7. **WebSocket orchestration**
   - `server/src/websocket/liveInterviewHandler.ts` hosts the live interview WebSocket channel.
   - This socket is for **orchestration metadata**, not audio transport: transcript snapshots, next-question hints, and interview coordination.
   - That separation is important architecturally because it keeps the low-latency media stream independent from the control plane.

8. **Evaluation and reporting flow**
   - The final assessment is generated server-side from interview transcript/session data, with Gemini used for deep reasoning and scoring.
   - The report aggregates technical, communication, culture-fit, and panel feedback signals, then the dashboard renders the outcome.
   - The repository’s `README` indicates body-language and some temporal/voice analytics are partially sample-driven when API limits apply.

9. **Shared types and constants**
   - `types.ts` defines shared domain shapes used across UI and server-facing data.
   - `src/constants/index.ts` centralizes fixed values such as categories, labels, and likely scoring or config defaults.
   - This shared model is key for keeping resume parsing, panel generation, and report rendering aligned.

10. **Deployment and runtime**
   - The app is built for a browser frontend plus a long-running Node backend.
   - `deploy/nginx.conf`, `deploy/deploy.sh`, and `deploy/oracle-setup.sh` show that production deployment is expected to be reverse-proxied and hosted on a Linux VM or similar environment.
   - `server/.env.example` indicates external API keys/configuration are injected at runtime, especially for Gemini access.

11. **What to draw as the main boundaries**
   - Draw three primary boxes: **Browser UI**, **Backend API/WebSocket orchestration**, and **Gemini external services**.
   - Inside the browser, separate **static UI**, **live media processing**, and **analysis/report UI**.
   - Inside the backend, separate **HTTP analysis/report endpoints** from the **WebSocket orchestration service** and the **Gemini-powered service layer**.

12. **Most important architectural idea**
   - The repo combines two very different interaction modes:  
     - a **real-time conversational path** optimized for latency and user experience, and  
     - a **server-mediated evaluation path** optimized for structured analysis and reporting.
   - That split is the core architectural decision behind the project.

Main entry points: [`App.tsx`](https://github.com/himavarshithreddy/interviewos/blob/main/App.tsx) (App shell), [`components/LiveInterview.tsx`](https://github.com/himavarshithreddy/interviewos/blob/main/components/LiveInterview.tsx) (Live interview), [`server/src/services/interviewOrchestrator.ts`](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/interviewOrchestrator.ts) (Interview flow), [`server/src/index.ts`](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/index.ts) (Server entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser UI"]
  node_app["App shell<br/>React root<br/>[App.tsx]"]
  node_boot["Browser entry<br/>Vite bootstrap<br/>[index.tsx]"]
  node_ui_resume["Resume upload<br/>feature UI<br/>[ResumeUploader.tsx]"]
  node_ui_panel["Panel setup<br/>feature UI"]
  node_ui_live["Live interview<br/>feature UI<br/>[LiveInterview.tsx]"]
  node_ui_dash["Dashboard<br/>report UI<br/>[Dashboard.tsx]"]
  node_ui_error["Error boundary<br/>ui guard<br/>[ErrorBoundary.tsx]"]
  node_client_api["API client<br/>REST boundary<br/>[apiClient.ts]"]
  node_vad(("Voice activity<br/>hook<br/>[useVAD.ts]"))
  node_video(("Video analysis<br/>hook"))
  node_session["Session state<br/>persistence util<br/>[sessionStorage.ts]"]
  node_reportdl["Report export<br/>download util<br/>[reportDownload.ts]"]
  node_audio{{"Audio worklet<br/>media processor<br/>[audio-processor.js]"}}
  node_audutil["Audio utils<br/>media util<br/>[audioUtils.ts]"]
end

subgraph group_backend["Backend Orchestration"]
  node_server_boot["Server entry<br/>Node bootstrap<br/>[index.ts]"]
  node_ws["Live socket<br/>WebSocket control"]
  node_orchestrator["Interview flow<br/>state orchestrator"]
  node_gemini["Gemini service<br/>LLM integration<br/>[geminiService.ts]"]
  node_emotion["Emotion analysis<br/>analysis service<br/>[emotionAnalyzer.ts]"]
  node_coach["Presentation coach<br/>analysis service"]
  node_specialist["Industry specialist<br/>domain service"]
end

subgraph group_infra["Deploy"]
  node_nginx["Nginx config<br/>reverse proxy<br/>[nginx.conf]"]
  node_deploysh["Deploy script<br/>ops script<br/>[deploy.sh]"]
  node_oracle["Oracle setup<br/>ops script<br/>[oracle-setup.sh]"]
end

node_boot -->|"mounts"| node_app
node_app -->|"renders"| node_ui_resume
node_app -->|"renders"| node_ui_panel
node_app -->|"renders"| node_ui_live
node_app -->|"renders"| node_ui_dash
node_app -->|"wraps"| node_ui_error
node_ui_resume -->|"uploads"| node_client_api
node_ui_panel -->|"configures"| node_client_api
node_ui_live -->|"detects speech"| node_vad
node_ui_live -->|"captures video"| node_video
node_ui_live -->|"persists"| node_session
node_ui_live -->|"processes audio"| node_audio
node_audio -->|"uses"| node_audutil
node_ui_live -->|"orchestrates"| node_ws
node_ui_dash -->|"exports"| node_reportdl
node_client_api -->|"calls"| node_server_boot
node_server_boot -->|"hosts"| node_ws
node_server_boot -->|"routes"| node_orchestrator
node_orchestrator -->|"invokes"| node_gemini
node_orchestrator -->|"evaluates"| node_emotion
node_orchestrator -->|"evaluates"| node_coach
node_orchestrator -->|"specializes"| node_specialist
node_ws -->|"syncs state"| node_orchestrator
node_ui_dash -->|"fetches report"| node_client_api
node_deploysh -.->|"configures"| node_nginx
node_deploysh -.->|"prepares"| node_oracle
node_server_boot -.->|"uses"| node_gemini

click node_app "https://github.com/himavarshithreddy/interviewos/blob/main/App.tsx"
click node_boot "https://github.com/himavarshithreddy/interviewos/blob/main/index.tsx"
click node_ui_resume "https://github.com/himavarshithreddy/interviewos/blob/main/components/ResumeUploader.tsx"
click node_ui_panel "https://github.com/himavarshithreddy/interviewos/blob/main/components/PanelConfiguration.tsx"
click node_ui_live "https://github.com/himavarshithreddy/interviewos/blob/main/components/LiveInterview.tsx"
click node_ui_dash "https://github.com/himavarshithreddy/interviewos/blob/main/components/Dashboard.tsx"
click node_ui_error "https://github.com/himavarshithreddy/interviewos/blob/main/src/components/ErrorBoundary.tsx"
click node_client_api "https://github.com/himavarshithreddy/interviewos/blob/main/src/services/apiClient.ts"
click node_vad "https://github.com/himavarshithreddy/interviewos/blob/main/src/hooks/useVAD.ts"
click node_video "https://github.com/himavarshithreddy/interviewos/blob/main/src/hooks/useVideoAnalysis.ts"
click node_session "https://github.com/himavarshithreddy/interviewos/blob/main/src/utils/sessionStorage.ts"
click node_reportdl "https://github.com/himavarshithreddy/interviewos/blob/main/src/utils/reportDownload.ts"
click node_audio "https://github.com/himavarshithreddy/interviewos/blob/main/public/worklets/audio-processor.js"
click node_audutil "https://github.com/himavarshithreddy/interviewos/blob/main/utils/audioUtils.ts"
click node_server_boot "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/index.ts"
click node_ws "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/websocket/liveInterviewHandler.ts"
click node_orchestrator "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/interviewOrchestrator.ts"
click node_gemini "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/geminiService.ts"
click node_emotion "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/emotionAnalyzer.ts"
click node_coach "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/presentationCoach.ts"
click node_specialist "https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/industrySpecialist.ts"
click node_nginx "https://github.com/himavarshithreddy/interviewos/blob/main/deploy/nginx.conf"
click node_deploysh "https://github.com/himavarshithreddy/interviewos/blob/main/deploy/deploy.sh"
click node_oracle "https://github.com/himavarshithreddy/interviewos/blob/main/deploy/oracle-setup.sh"

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_app,node_boot,node_ui_resume,node_ui_panel,node_ui_live,node_ui_dash,node_ui_error,node_client_api,node_vad,node_video,node_session,node_reportdl,node_audio,node_audutil toneBlue
class node_server_boot,node_ws,node_orchestrator,node_gemini,node_emotion,node_coach,node_specialist toneAmber
class node_nginx,node_deploysh,node_oracle toneMint
```

## Components

### Browser UI

React/Vite client that drives interview flow and displays outcomes.

- [App shell](https://github.com/himavarshithreddy/interviewos/blob/main/App.tsx): React root · Top-level client composition for the interview experience. · `App.tsx`
- [Browser entry](https://github.com/himavarshithreddy/interviewos/blob/main/index.tsx): Vite bootstrap · Browser startup entry point for mounting the app. · `index.tsx`
- [Resume upload](https://github.com/himavarshithreddy/interviewos/blob/main/components/ResumeUploader.tsx): feature UI · Initial flow for uploading candidate resume data. · `components/ResumeUploader.tsx`
- [Panel setup](https://github.com/himavarshithreddy/interviewos/blob/main/components/PanelConfiguration.tsx): feature UI · Configures interview panelists and interview settings. · `components/PanelConfiguration.tsx`
- [Live interview](https://github.com/himavarshithreddy/interviewos/blob/main/components/LiveInterview.tsx): feature UI · Runs the active conversational interview experience. · `components/LiveInterview.tsx`
- [Dashboard](https://github.com/himavarshithreddy/interviewos/blob/main/components/Dashboard.tsx): report UI · Displays the final interview report and analysis summary. · `components/Dashboard.tsx`
- [Error boundary](https://github.com/himavarshithreddy/interviewos/blob/main/src/components/ErrorBoundary.tsx): ui guard · Catches client rendering failures and protects the app shell. · `src/components/ErrorBoundary.tsx`
- [API client](https://github.com/himavarshithreddy/interviewos/blob/main/src/services/apiClient.ts): REST boundary · Browser-to-server request layer for structured backend calls. · `src/services/apiClient.ts`
- [Voice activity](https://github.com/himavarshithreddy/interviewos/blob/main/src/hooks/useVAD.ts): hook · Client-side voice activity detection for live session behavior. · `src/hooks/useVAD.ts`
- [Video analysis](https://github.com/himavarshithreddy/interviewos/blob/main/src/hooks/useVideoAnalysis.ts): hook · Periodic capture and upload path for visual analysis signals. · `src/hooks/useVideoAnalysis.ts`
- [Session state](https://github.com/himavarshithreddy/interviewos/blob/main/src/utils/sessionStorage.ts): persistence util · Persists interview state in browser storage across the session. · `src/utils/sessionStorage.ts`
- [Report export](https://github.com/himavarshithreddy/interviewos/blob/main/src/utils/reportDownload.ts): download util · Exports the final report from the browser UI. · `src/utils/reportDownload.ts`
- [Audio worklet](https://github.com/himavarshithreddy/interviewos/blob/main/public/worklets/audio-processor.js): media processor · Low-latency browser audio processing for the live interview stream. · `public/worklets/audio-processor.js`
- [Audio utils](https://github.com/himavarshithreddy/interviewos/blob/main/utils/audioUtils.ts): media util · Shared browser audio helpers used by the live media path. · `utils/audioUtils.ts`

### Backend Orchestration

Node API, WebSocket control plane, and Gemini-powered analysis services.

- [Server entry](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/index.ts): Node bootstrap · Starts the backend HTTP API and WebSocket server. · `server/src/index.ts`
- [Live socket](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/websocket/liveInterviewHandler.ts): WebSocket control · Orchestrates live interview metadata and coordination messages. · `server/src/websocket/liveInterviewHandler.ts`
- [Interview flow](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/interviewOrchestrator.ts): state orchestrator · Tracks interview state, topic depth, and panel progression. · `server/src/services/interviewOrchestrator.ts`
- [Gemini service](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/geminiService.ts): LLM integration · Core Gemini access for generation, reasoning, and structured scoring. · `server/src/services/geminiService.ts`
- [Emotion analysis](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/emotionAnalyzer.ts): analysis service · Specialized emotional and behavioral signal analysis. · `server/src/services/emotionAnalyzer.ts`
- [Presentation coach](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/presentationCoach.ts): analysis service · Evaluates delivery and presentation quality. · `server/src/services/presentationCoach.ts`
- [Industry specialist](https://github.com/himavarshithreddy/interviewos/blob/main/server/src/services/industrySpecialist.ts): domain service · Provides domain-specific panel questions and evaluation logic. · `server/src/services/industrySpecialist.ts`

### Deploy

Runtime and deployment assets for hosting behind a reverse proxy.

- [Nginx config](https://github.com/himavarshithreddy/interviewos/blob/main/deploy/nginx.conf): reverse proxy · Production proxy configuration for serving the app and backend. · `deploy/nginx.conf`
- [Deploy script](https://github.com/himavarshithreddy/interviewos/blob/main/deploy/deploy.sh): ops script · Deployment automation for provisioning and rollout. · `deploy/deploy.sh`
- [Oracle setup](https://github.com/himavarshithreddy/interviewos/blob/main/deploy/oracle-setup.sh): ops script · Host setup script for the target Linux VM environment. · `deploy/oracle-setup.sh`

## Connections

- Browser entry → App shell: mounts · Browser bootstrap mounts the React application.
- App shell → Resume upload: renders · App shell composes the resume upload flow.
- App shell → Panel setup: renders · App shell composes panel configuration.
- App shell → Live interview: renders · App shell composes the live interview experience.
- App shell → Dashboard: renders · App shell composes the report dashboard.
- App shell → Error boundary: wraps · Client app is protected by an error boundary.
- Resume upload → API client: uploads · Resume data is sent to backend services.
- Panel setup → API client: configures · Panel settings flow through the API client.
- Live interview → Voice activity: detects speech · Live interview uses voice activity detection.
- Live interview → Video analysis: captures video · Live interview periodically captures visual signals.
- Live interview → Session state: persists · Session state is stored locally during the interview.
- Live interview → Audio worklet: processes audio · Browser audio is processed in a worklet for low latency.
- Audio worklet → Audio utils: uses · The worklet relies on shared audio helpers.
- Live interview → Live socket: orchestrates · Live interview uses WebSocket control messages.
- Dashboard → Report export: exports · Dashboard supports report download.
- API client → Server entry: calls · REST traffic reaches the backend server.
- Server entry → Live socket: hosts · Backend entrypoint exposes the live interview socket.
- Server entry → Interview flow: routes · Backend routes interview analysis and coordination.
- Interview flow → Gemini service: invokes · Flow orchestration delegates reasoning to Gemini.
- Interview flow → Emotion analysis: evaluates · Orchestrator incorporates emotional signal analysis.
- Interview flow → Presentation coach: evaluates · Orchestrator incorporates presentation feedback.
- Interview flow → Industry specialist: specializes · Orchestrator can branch into domain-specific evaluation.
- Live socket → Interview flow: syncs state · Socket exchanges interview metadata with orchestration.
- Dashboard → API client: fetches report · Dashboard retrieves structured report data from backend.
- Deploy script → Nginx config: configures · Deployment script installs or updates the proxy setup.
- Deploy script → Oracle setup: prepares · Deployment targets an Oracle-hosted Linux environment.
- Server entry → Gemini service: uses · Backend services rely on Gemini credentials at runtime.