# jaskaran5109/ai-proctored-interview architecture

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

- Interactive diagram: https://gitdiagram.com/jaskaran5109/ai-proctored-interview
- Repository: https://github.com/jaskaran5109/ai-proctored-interview

## Overview

#### Purpose and Entry Points
This is a full-stack AI-proctored interview platform for candidate interviews, recruiter/session management, coding assessment, proctoring signals, and AI-assisted evaluation. The backend starts through `backend/src/server.js`, assembles Express application concerns in `backend/src/app.js`, and exposes APIs from `backend/src/routes/index.js`. The React frontend boots at `frontend/src/index.tsx` and selects application views in `frontend/src/App.tsx`.

#### Backend HTTP and Security Boundary
Express routes dispatch to domain controllers for authentication, interview/session operations, AI, and code execution: `backend/src/controllers/auth.controller.js`, `backend/src/controllers/session.controller.js`, and `backend/src/controllers/code.controller.js`. Authentication middleware protects applicable endpoints using JWT utilities, while rate limiting and centralized error translation form the request boundary: `backend/src/middleware/auth.middleware.js`, `backend/src/middleware/rateLimit.middleware.js`, `backend/src/middleware/error.middleware.js`.

#### Persistence and Domain Model
Database initialization is isolated in `backend/src/config/db.js`; model registration/relationships are centralized in `backend/src/models/index.js`. Controllers should use this model layer rather than directly coupling frontend workflows to storage. Seed support in `backend/src/utils/seed.js` indicates environment/bootstrap data may be required for usable interview flows.

#### Interview Orchestration
The interview lifecycle is coordinated as a service rather than embedded solely in controllers, with `backend/src/services/interview-flow.service.js` representing the primary workflow boundary. Session endpoints/controllers expose this lifecycle to clients through `backend/src/controllers/session.controller.js`. Live updates are likely supported through the socket utility, `backend/src/utils/socket.js`, separating real-time event wiring from REST request handling.

#### AI and Evaluation Integration
AI responsibilities are layered: `backend/src/controllers/ai.controller.js` accepts API-level requests, `backend/src/services/ai.service.js` implements application AI behavior, and `backend/src/ai/ollama.client.js` integrates with an Ollama runtime/service. This isolates prompts/model invocation from interview orchestration and enables AI assistance or evaluation without exposing the model provider directly to the frontend.

#### Code Assessment Execution
Code submission validation and execution are distinct from general interview orchestration: `backend/src/validators/code.validator.js`, `backend/src/controllers/code.controller.js`, and `backend/src/services/code-execution.service.js`. This is a material trust boundary because candidate-supplied code requires constrained execution infrastructure, even though the specific sandbox/runtime implementation is not represented in the tree.

#### Frontend Application Flows
The frontend uses page-level routes/views for authentication, dashboards, interview rooms, session details, and results: `frontend/src/pages/AuthPage.tsx`, `frontend/src/pages/InterviewPage.tsx`, and `frontend/src/pages/ResultPage.tsx`. API access is centralized through service modules such as `frontend/src/services/http.ts`, `frontend/src/services/interview.ts`, and `frontend/src/services/sessions.ts`, keeping UI components from owning transport details.

#### Client State and Interview Experience
Authentication bootstrap and persistent auth state are handled by `frontend/src/hooks/useAuthBootstrap.ts` and `frontend/src/store/authStore.ts`. Interview-specific monitoring and state are separated into `frontend/src/hooks/useInterviewMonitor.ts` and `frontend/src/stores/interviewStore.js`. The candidate/recruiter experience is composed from focused modules: live coding in `frontend/src/components/interview/LiveCodingWorkspace.tsx`, AI interaction in `frontend/src/components/interview/AssistantPanel.tsx`, and interview/session creation in `frontend/src/components/dashboard/CreateInterviewWizard.tsx`.

Main entry points: [`frontend/src/pages/InterviewPage.tsx`](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/pages/InterviewPage.tsx) (Interview room), [`backend/src/routes/index.js`](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/routes/index.js) (API routes), [`frontend/src/index.tsx`](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/index.tsx) (Client bootstrap & views), [`backend/src/services/interview-flow.service.js`](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/interview-flow.service.js) (Interview lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React Client"]
  node_client_boot["Client bootstrap &amp; views<br/>React entry<br/>[index.tsx]"]
  node_auth_state["Auth bootstrap &amp; state<br/>client state"]
  node_client_api["HTTP &amp; interview APIs<br/>client services<br/>[http.ts]"]
  node_interview_monitor["Interview monitoring<br/>client hook"]
  node_interview_state["Interview state<br/>client store<br/>[interviewStore.js]"]
  node_interview_room["Interview room<br/>UI component<br/>[InterviewPage.tsx]"]
  node_live_coding["Live coding workspace<br/>UI component"]
  node_assistant_panel["AI assistant panel<br/>UI component<br/>[AssistantPanel.tsx]"]
  node_interview_wizard["Create interview wizard<br/>UI component"]
end

subgraph group_backend["Backend API"]
  node_server["Server entry<br/>Node entry<br/>[server.js]"]
  node_express_app["Express application<br/>HTTP app<br/>[app.js]"]
  node_api_routes["API routes<br/>route registry<br/>[index.js]"]
  node_request_boundary{{"Auth, limits &amp; errors<br/>middleware<br/>[auth.middleware.js]"}}
  node_session_api["Session controller"]
  node_interview_flow["Interview lifecycle<br/>domain service"]
  node_ai_api["AI controller<br/>[ai.controller.js]"]
  node_ai_service["AI evaluation service<br/>application service<br/>[ai.service.js]"]
  node_code_api{{"Code controller &amp; validation<br/>controller boundary<br/>[code.controller.js]"}}
  node_code_execution{{"Code execution service"}}
  node_models["Domain models<br/>ORM model layer<br/>[index.js]"]
end

subgraph group_integrations["Runtime Integrations"]
  node_database[("Application database<br/>[db.js]")]
  node_socket["Live socket events<br/>realtime utility<br/>[socket.js]"]
  node_ollama{{"Ollama runtime<br/>AI provider<br/>[ollama.client.js]"}}
  node_sandbox{{"Constrained execution runtime<br/>external runtime"}}
end

node_client_boot -->|"initializes"| node_auth_state
node_client_boot -->|"renders"| node_interview_room
node_client_boot -->|"renders"| node_interview_wizard
node_interview_room -->|"uses"| node_interview_monitor
node_interview_monitor -->|"updates"| node_interview_state
node_interview_room -->|"composes"| node_live_coding
node_interview_room -->|"composes"| node_assistant_panel
node_auth_state -->|"authenticates requests"| node_client_api
node_interview_state -->|"uses"| node_client_api
node_client_api -->|"HTTPS API"| node_server
node_server -->|"starts"| node_express_app
node_express_app -->|"applies"| node_request_boundary
node_request_boundary -->|"protects"| node_api_routes
node_api_routes -->|"session endpoints"| node_session_api
node_api_routes -->|"AI endpoints"| node_ai_api
node_api_routes -->|"code endpoints"| node_code_api
node_session_api -->|"drives"| node_interview_flow
node_interview_flow -->|"persists lifecycle"| node_models
node_models -->|"reads and writes"| node_database
node_interview_flow -->|"publishes live updates"| node_socket
node_ai_api -->|"delegates"| node_ai_service
node_ai_service -->|"invokes models"| node_ollama
node_code_api -->|"submits validated code"| node_code_execution
node_code_execution -.->|"executes under constraints"| node_sandbox

click node_client_boot "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/index.tsx"
click node_auth_state "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/hooks/useAuthBootstrap.ts"
click node_client_api "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/services/http.ts"
click node_interview_monitor "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/hooks/useInterviewMonitor.ts"
click node_interview_state "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/stores/interviewStore.js"
click node_interview_room "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/pages/InterviewPage.tsx"
click node_live_coding "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/interview/LiveCodingWorkspace.tsx"
click node_assistant_panel "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/interview/AssistantPanel.tsx"
click node_interview_wizard "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/dashboard/CreateInterviewWizard.tsx"
click node_server "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/server.js"
click node_express_app "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/app.js"
click node_api_routes "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/routes/index.js"
click node_request_boundary "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/middleware/auth.middleware.js"
click node_session_api "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/session.controller.js"
click node_interview_flow "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/interview-flow.service.js"
click node_ai_api "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/ai.controller.js"
click node_ai_service "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/ai.service.js"
click node_code_api "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/code.controller.js"
click node_code_execution "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/code-execution.service.js"
click node_models "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/models/index.js"
click node_database "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/config/db.js"
click node_socket "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/utils/socket.js"
click node_ollama "https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/ai/ollama.client.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_client_boot,node_auth_state,node_client_api,node_interview_monitor,node_interview_state,node_interview_room,node_live_coding,node_assistant_panel,node_interview_wizard toneBlue
class node_server,node_express_app,node_api_routes,node_request_boundary,node_session_api,node_interview_flow,node_ai_api,node_ai_service,node_code_api,node_code_execution,node_models toneAmber
class node_database,node_socket,node_ollama,node_sandbox toneMint
```

## Components

### React Client

- [Client bootstrap & views](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/index.tsx): React entry · Boots the app and selects page-level views. · `frontend/src/index.tsx`
- [Auth bootstrap & state](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/hooks/useAuthBootstrap.ts): client state · `frontend/src/hooks/useAuthBootstrap.ts`
- [HTTP & interview APIs](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/services/http.ts): client services · Centralizes frontend transport and interview/session calls. · `frontend/src/services/http.ts`
- [Interview monitoring](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/hooks/useInterviewMonitor.ts): client hook · `frontend/src/hooks/useInterviewMonitor.ts`
- [Interview state](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/stores/interviewStore.js): client store · `frontend/src/stores/interviewStore.js`
- [Interview room](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/pages/InterviewPage.tsx): UI component · Composes the candidate live-interview experience. · `frontend/src/pages/InterviewPage.tsx`
- [Live coding workspace](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/interview/LiveCodingWorkspace.tsx): UI component · `frontend/src/components/interview/LiveCodingWorkspace.tsx`
- [AI assistant panel](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/interview/AssistantPanel.tsx): UI component · `frontend/src/components/interview/AssistantPanel.tsx`
- [Create interview wizard](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/frontend/src/components/dashboard/CreateInterviewWizard.tsx): UI component · `frontend/src/components/dashboard/CreateInterviewWizard.tsx`

### Backend API

- [Server entry](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/server.js): Node entry · `backend/src/server.js`
- [Express application](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/app.js): HTTP app · Assembles API concerns and middleware. · `backend/src/app.js`
- [API routes](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/routes/index.js): route registry · `backend/src/routes/index.js`
- [Auth, limits & errors](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/middleware/auth.middleware.js): middleware · JWT protection, rate limiting, and centralized error translation. · `backend/src/middleware/auth.middleware.js`
- [Session controller](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/session.controller.js): controller · `backend/src/controllers/session.controller.js`
- [Interview lifecycle](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/interview-flow.service.js): domain service · Coordinates interview workflow beyond HTTP controllers. · `backend/src/services/interview-flow.service.js`
- [AI controller](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/ai.controller.js): controller · `backend/src/controllers/ai.controller.js`
- [AI evaluation service](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/ai.service.js): application service · `backend/src/services/ai.service.js`
- [Code controller & validation](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/controllers/code.controller.js): controller boundary · Validates candidate code before execution. · `backend/src/controllers/code.controller.js`
- [Code execution service](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/services/code-execution.service.js): execution service · Trust boundary for candidate-supplied code. · `backend/src/services/code-execution.service.js`
- [Domain models](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/models/index.js): ORM model layer · Registers persistence models and relationships. · `backend/src/models/index.js`

### Runtime Integrations

- [Application database](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/config/db.js): database · `backend/src/config/db.js`
- [Live socket events](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/utils/socket.js): realtime utility · `backend/src/utils/socket.js`
- [Ollama runtime](https://github.com/jaskaran5109/ai-proctored-interview/blob/main/backend/src/ai/ollama.client.js): AI provider · Model invocation is isolated behind a client. · `backend/src/ai/ollama.client.js`
- **Constrained execution runtime**: external runtime · Underlying sandbox implementation is not represented.

## Connections

- Client bootstrap & views → Auth bootstrap & state: initializes
- Client bootstrap & views → Interview room: renders
- Client bootstrap & views → Create interview wizard: renders
- Interview room → Interview monitoring: uses
- Interview monitoring → Interview state: updates
- Interview room → Live coding workspace: composes
- Interview room → AI assistant panel: composes
- Auth bootstrap & state → HTTP & interview APIs: authenticates requests
- Interview state → HTTP & interview APIs: uses
- HTTP & interview APIs → Server entry: HTTPS API
- Server entry → Express application: starts
- Express application → Auth, limits & errors: applies
- Auth, limits & errors → API routes: protects
- API routes → Session controller: session endpoints
- API routes → AI controller: AI endpoints
- API routes → Code controller & validation: code endpoints
- Session controller → Interview lifecycle: drives
- Interview lifecycle → Domain models: persists lifecycle
- Domain models → Application database: reads and writes
- Interview lifecycle → Live socket events: publishes live updates
- AI controller → AI evaluation service: delegates
- AI evaluation service → Ollama runtime: invokes models
- Code controller & validation → Code execution service: submits validated code
- Code execution service → Constrained execution runtime: executes under constraints