# tejasbanginwar/ai-mock-interview-platform architecture

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

- Interactive diagram: https://gitdiagram.com/tejasbanginwar/ai-mock-interview-platform
- Repository: https://github.com/tejasbanginwar/ai-mock-interview-platform

## Overview

1. **System split: two runtime boundaries**
   - The repo is organized as a **React/Vite frontend** in `InterviewAI/` and a **Python/Flask backend** in `backend/`.
   - The frontend runs as a browser SPA; the backend is a separate local API service.

2. **Frontend is the primary user-facing application**
   - `src/main.tsx` bootstraps the app, `App.tsx` and the `pages/` directory define the route-level screens.
   - Key screens are `Home`, `Practice`, `Interview`, `Results`, `SignInPage`, `SignUpPage`, plus `NotFound`.

3. **Interview workflow is page-driven**
   - The likely user journey is: landing/sign-in → practice or interview session → results/feedback.
   - `ResumeUpload` suggests the interview flow can be personalized by uploaded resume content.
   - `Navigation`, `NavLink`, and `ProtectedRoute` indicate a routed app with some client-side access control.

4. **Real-time webcam monitoring is a major frontend-to-backend data flow**
   - `FaceDetectionVideo` and `useFaceDetection` are the core bridge for camera-based monitoring.
   - The browser captures webcam frames, converts them to image payloads, and sends them to the backend’s face-detection endpoint.
   - This is the main cross-process interaction in the system.

5. **Backend exposes a small ML-oriented API**
   - `backend/app.py` is the entry point and, per the docs, provides at least:
     - `GET /health`
     - `POST /detect-faces`
   - The API receives base64 image data from the frontend and returns face-detection results for UI enforcement/feedback.

6. **Computer-vision and model assets live behind the backend boundary**
   - The backend README and repo root assets point to **MediaPipe** and **OpenCV** for face monitoring.
   - `emotion_model_final.pth` and `emotion_classes.pkl` indicate the backend also has an ML model layer for emotion-related inference, even though the exact route wiring is not visible from the tree.
   - `backend/answer_audio/` contains per-session UUID folders with `question_###.wav` files, suggesting persisted voice-answer artifacts for later processing or review.

7. **Tab switching and page visibility are handled locally in the browser**
   - `usePageVisibility` and `TabSwitchWarning` implement anti-cheating / exam-proctoring behavior on the client.
   - This is separate from face detection: it monitors browser state rather than camera input.
   - `ProtectedRoute` likely keeps certain pages gated without relying on backend auth.

8. **Audio/voice answer handling is represented as session artifacts**
   - The `backend/answer_audio/.../*.wav` files show that audio responses are stored by interview session ID.
   - That implies a second analysis path besides face detection: voice answers can be captured, saved, and later used for scoring or review.

9. **UI composition is modular and library-based**
   - The frontend uses a large `components/ui/` set consistent with a shadcn/Radix-style component library.
   - `tailwind.config.ts`, `postcss.config.js`, and `src/index.css` show styling is utility-first and centralized in the frontend.
   - These libraries are presentation infrastructure, not core business logic.

10. **Operational model is local-development oriented**
   - The documented default ports are `8080` for the frontend and `5000` for the backend.
   - CORS is expected because the browser SPA talks to a separate API origin.
   - The repo is designed for a dual-process developer setup rather than a monolithic deployment.

11. **Architecture diagram takeaway**
   - Draw the browser SPA as the main interaction surface.
   - Show three browser-side subsystems: routing/UI, webcam capture + tab monitoring, and local session handling.
   - Show the Flask backend as a separate ML/vision service receiving image frames and persisting session audio artifacts.
   - The strongest dependency arrows are: **user → SPA**, **SPA → Flask API for face detection**, and **SPA-local monitoring for tab visibility/proctoring**.

Main entry points: [`InterviewAI/src/App.tsx`](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/App.tsx) (App shell), [`backend/app.py`](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/backend/app.py) (Flask API), [`InterviewAI/src/pages/Interview.tsx`](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Interview.tsx) (Interview), [`InterviewAI/src/hooks/useFaceDetection.ts`](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/hooks/useFaceDetection.ts) (Face detection hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend SPA"]
  node_src_main(("main<br/>entrypoint<br/>[main.tsx]"))
  node_app_shell["App shell<br/>spa shell<br/>[App.tsx]"]
  node_home_page["Home<br/>page<br/>[Home.tsx]"]
  node_practice_page["Practice<br/>page<br/>[Practice.tsx]"]
  node_interview_page["Interview<br/>page<br/>[Interview.tsx]"]
  node_results_page["Results<br/>page<br/>[Results.tsx]"]
  node_signin_page["Sign in<br/>auth page<br/>[SignInPage.tsx]"]
  node_signup_page["Sign up<br/>auth page<br/>[SignUpPage.tsx]"]
  node_notfound_page["Not found<br/>route fallback<br/>[NotFound.tsx]"]
  node_navigation["Navigation<br/>nav component<br/>[Navigation.tsx]"]
  node_protected_route["Protected route<br/>route guard<br/>[ProtectedRoute.tsx]"]
  node_resume_upload["Resume upload<br/>session input<br/>[ResumeUpload.tsx]"]
  node_face_video["Face video<br/>camera bridge"]
  node_face_hook["Face detection hook<br/>client hook"]
  node_visibility_hook["Page visibility<br/>client hook"]
  node_tab_warning["Tab warning<br/>proctoring UI"]
end

subgraph group_backend["Backend API"]
  node_backend_app["Flask API<br/>service entrypoint<br/>[app.py]"]
  node_audio_store[("Answer audio<br/>session store")]
end

subgraph group_ml["ML Assets"]
  node_emotion_model{{"Emotion model<br/>ml model"}}
  node_emotion_classes["Emotion classes<br/>ml metadata"]
end

node_src_main -->|"bootstraps"| node_app_shell
node_app_shell -->|"routes to"| node_home_page
node_app_shell -->|"routes to"| node_practice_page
node_app_shell -->|"routes to"| node_interview_page
node_app_shell -->|"routes to"| node_results_page
node_app_shell -->|"routes to"| node_signin_page
node_app_shell -->|"routes to"| node_signup_page
node_app_shell -->|"falls back to"| node_notfound_page
node_app_shell -->|"composes"| node_navigation
node_app_shell -->|"guards"| node_protected_route
node_interview_page -->|"uses"| node_resume_upload
node_interview_page -->|"captures"| node_face_video
node_face_video -->|"delegates to"| node_face_hook
node_face_hook -->|"POST /detect-faces"| node_backend_app
node_visibility_hook -->|"drives"| node_tab_warning
node_interview_page -->|"monitors"| node_visibility_hook
node_backend_app -->|"persists"| node_audio_store
node_backend_app -->|"loads"| node_emotion_model
node_backend_app -->|"loads"| node_emotion_classes
node_face_hook -->|"uses API"| node_backend_app
node_protected_route -->|"redirects"| node_signin_page

click node_src_main "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/main.tsx"
click node_app_shell "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/App.tsx"
click node_home_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Home.tsx"
click node_practice_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Practice.tsx"
click node_interview_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Interview.tsx"
click node_results_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Results.tsx"
click node_signin_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/SignInPage.tsx"
click node_signup_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/SignUpPage.tsx"
click node_notfound_page "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/NotFound.tsx"
click node_navigation "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/Navigation.tsx"
click node_protected_route "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/ProtectedRoute.tsx"
click node_resume_upload "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/ResumeUpload.tsx"
click node_face_video "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/FaceDetectionVideo.tsx"
click node_face_hook "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/hooks/useFaceDetection.ts"
click node_visibility_hook "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/hooks/usePageVisibility.ts"
click node_tab_warning "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/TabSwitchWarning.tsx"
click node_backend_app "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/backend/app.py"
click node_audio_store "https://github.com/tejasbanginwar/ai-mock-interview-platform/tree/main/backend/answer_audio"
click node_emotion_model "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/emotion_model_final.pth"
click node_emotion_classes "https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/emotion_classes.pkl"

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_src_main,node_app_shell,node_home_page,node_practice_page,node_interview_page,node_results_page,node_signin_page,node_signup_page,node_notfound_page,node_navigation,node_protected_route,node_resume_upload,node_face_video,node_face_hook,node_visibility_hook,node_tab_warning toneBlue
class node_backend_app,node_audio_store toneAmber
class node_emotion_model,node_emotion_classes toneMint
```

## Components

### Frontend SPA

React/Vite browser application and client-side proctoring flows

- [main](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/main.tsx): entrypoint · Vite bootstrap for the React app · `InterviewAI/src/main.tsx`
- [App shell](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/App.tsx): spa shell · Top-level frontend composition and routing host · `InterviewAI/src/App.tsx`
- [Home](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Home.tsx): page · Landing page for the interview platform · `InterviewAI/src/pages/Home.tsx`
- [Practice](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Practice.tsx): page · Practice-oriented interview screen · `InterviewAI/src/pages/Practice.tsx`
- [Interview](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Interview.tsx): page · Live interview session screen · `InterviewAI/src/pages/Interview.tsx`
- [Results](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/Results.tsx): page · Feedback and outcome view after a session · `InterviewAI/src/pages/Results.tsx`
- [Sign in](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/SignInPage.tsx): auth page · Authentication entry screen · `InterviewAI/src/pages/SignInPage.tsx`
- [Sign up](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/SignUpPage.tsx): auth page · Account creation screen · `InterviewAI/src/pages/SignUpPage.tsx`
- [Not found](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/pages/NotFound.tsx): route fallback · Fallback screen for unknown routes · `InterviewAI/src/pages/NotFound.tsx`
- [Navigation](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/Navigation.tsx): nav component · Primary app navigation and route links · `InterviewAI/src/components/Navigation.tsx`
- [Protected route](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/ProtectedRoute.tsx): route guard · Client-side access gating for secured pages · `InterviewAI/src/components/ProtectedRoute.tsx`
- [Resume upload](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/ResumeUpload.tsx): session input · Uploads resume content to personalize the interview flow · `InterviewAI/src/components/ResumeUpload.tsx`
- [Face video](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/FaceDetectionVideo.tsx): camera bridge · Webcam capture and frame transport to backend detection · `InterviewAI/src/components/FaceDetectionVideo.tsx`
- [Face detection hook](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/hooks/useFaceDetection.ts): client hook · Coordinates webcam frame handling and API calls · `InterviewAI/src/hooks/useFaceDetection.ts`
- [Page visibility](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/hooks/usePageVisibility.ts): client hook · Detects tab switching and page visibility changes · `InterviewAI/src/hooks/usePageVisibility.ts`
- [Tab warning](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/InterviewAI/src/components/TabSwitchWarning.tsx): proctoring UI · Warns when the interview page loses visibility · `InterviewAI/src/components/TabSwitchWarning.tsx`

### Backend API

Flask service for face detection and interview session artifacts

- [Flask API](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/backend/app.py): service entrypoint · Backend API entrypoint exposing health and face detection routes · `backend/app.py`
- [Answer audio](https://github.com/tejasbanginwar/ai-mock-interview-platform/tree/main/backend/answer_audio): session store · Persisted per-session voice answer artifacts · `backend/answer_audio`

### ML Assets

Persisted model and class metadata used by backend inference

- [Emotion model](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/emotion_model_final.pth): ml model · Serialized emotion inference model · `emotion_model_final.pth`
- [Emotion classes](https://github.com/tejasbanginwar/ai-mock-interview-platform/blob/main/emotion_classes.pkl): ml metadata · Class labels used by the emotion model · `emotion_classes.pkl`

## Connections

- main → App shell: bootstraps · Entry point mounts the application shell
- App shell → Home: routes to · Main landing route
- App shell → Practice: routes to · Practice session route
- App shell → Interview: routes to · Live interview route
- App shell → Results: routes to · Post-session feedback route
- App shell → Sign in: routes to · Sign-in route
- App shell → Sign up: routes to · Sign-up route
- App shell → Not found: falls back to · Unknown routes render fallback screen
- App shell → Navigation: composes · Shared navigation chrome
- App shell → Protected route: guards · Restricts access to protected interview flows
- Interview → Resume upload: uses · Personalizes the interview from uploaded resume data
- Interview → Face video: captures · Embedding of live camera monitoring
- Face video → Face detection hook: delegates to · Component relies on hook for frame processing and API transport
- Face detection hook → Flask API: POST /detect-faces · Sends base64 image payloads for face detection
- Page visibility → Tab warning: drives · Visibility state controls proctoring warning UI
- Interview → Page visibility: monitors · Tracks browser tab focus during interview
- Flask API → Answer audio: persists · Stores session answer recordings as wav artifacts
- Flask API → Emotion model: loads · Inference model used behind the backend boundary
- Flask API → Emotion classes: loads · Label metadata for emotion inference
- Face detection hook → Flask API: uses API · Cross-process browser-to-server monitoring flow
- Protected route → Sign in: redirects · Unauthenticated users are sent to auth flow