himavarshithreddy/interviewos

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.