# Hire Guru Interview Portal — Architecture & Technical Reference
This document provides a complete technical guide to the codebase of the **Hire Guru** Interview Portal. It covers both the **Express/Node.js/MongoDB Backend** and the **Angular 17+ Frontend**, detailing every directory, file, model schema, API endpoint, and standalone frontend component.
---
## 1. Directory Tree & Architecture Overview
The application follows a clean, decoupled Client-Server architecture:
***Backend**: A RESTful Express server communicating with a MongoDB database using Mongoose.
***Frontend**: A modern Angular application featuring standalone components, reactive signals, and custom route guards.
```
Quiz-Master/
├── Backend/
│ ├── config/ # DB Connection utilities
│ ├── middleware/ # Authentication and file upload middlewares
***What they do**: Define assessment blueprints and individual question banks.
***How they do it**:
*`Quiz.js` configures time limits, difficulty settings, and assignees.
*`Question.js` stores questions, options, and index mappings for automated grading.
---
### 2.2 API Routers & Controllers (`Backend/routes/`)
All API routes start with `/api` and are mapped in `server.js`:
#### 1. Authentication Endpoints (`/api/auth`)
File: `routes/auth.js`
*`POST /register`: Registers new candidates and links them to a default group.
*`POST /login`: Validates credentials, sets `isLoggedIn: true` via an optimized `updateOne` query (avoiding pre-save password re-hashing), and generates a JWT.
*`POST /logout`: Updates `isLoggedIn: false` and invalidates client session state.
*`POST /signature`: Updates the logged-in staff member's Base64 digital signature.
*`GET /me`: Returns currently validated session payload.
#### 2. Interview Operations (`/api/interview`)
File: `routes/interview.js`
*`POST /`: Creates an individual interview and sets up quiz trackers.
*`POST /group`: Creates a batch of interviews for an entire candidate group. Supports automatic random assignment of quizzes from target sets.
*`GET /`: Fetches interviews. Evaluators are restricted to seeing interviews where they are explicitly assigned or named as a creator.
*`PUT /:id/evaluate`: Saves or updates an evaluator's feedback and auto-advances the status.
*`PUT /:id/decision`: Sets the absolute final selection outcome and switches state to `completed`.
*`POST /:id/coding-submission`: Saves the uploaded zip file to `/uploads` using multer middleware.
*`PUT /:id/validate-coding`: Validates code quality and advances the interview phase.
---
### 2.3 Middleware Stack (`Backend/middleware/`)
***Auth Middleware (`auth.js`)**:
Extracts the Bearer token from the `Authorization` header, decodes the JWT signature, and checks the database for verification. The `authorize(...roles)` function implements role-based route blocking:
Uses `multer` configured to accept `.zip`, `.rar`, and images, renaming them securely with unique timestamps.
---
## 3. Frontend Architecture (Angular 17+)
The frontend is a lightweight, responsive SPA using Angular's standalone components.
### 3.1 Core Navigation & Role Guards (`guards/auth.guard.ts`)
Navigation access is secured by Angular route guards, matching active token payload checks:
*`adminGuard`: Validates role is `admin`.
*`hrGuard`: Validates role is `hr`.
*`pmGuard`: Validates role is `pm`.
*`interviewerGuard`: Validates role is `interviewer`.
*`candidateGuard`: Validates role is `candidate`.
---
### 3.2 Key Pages & Features (`pages/`)
#### 1. HR Portal Components (`pages/hr/`)
***dashboard/**: Renders candidate pipelines, overview counts, and validation queues.
***individual-interview/**: HR interface to create individual candidates, assign exactly one Interviewer, PM, and HR via clean radio selectors, and assign specific aptitude tests.
***profile/**: Holds resume storage settings and topics of interest comfortable ratings.
***take-quiz/**: The secure assessment room featuring a live countdown, full-screen lock request, cheat counters, tab change watchers, and the auto-grading system.
***What it does**: Tracks exam environment security and blocks external windows.
***How it does it**:
* Attaches native browser event listeners to `window` for `blur` and `focus`.
* Tracks visibility state changes in `document.hidden`.
* Triggers warning modals via a shared RXJS state pipeline and records cheat transgression counters.
#### 2. Quiz API Service (`quiz.service.ts`)
* Acts as the central reactive client communicating with backend endpoints `/api/interview`, `/api/auth`, and `/api/hr` to pass score arrays, validation parameters, and candidate profile signatures.
# Hire Guru Interview Portal — Functional & User Flow Documentation
This document explains the end-to-end user flows, state lifecycles, and core functional features of the **Hire Guru** (formerly Quiz-Master) Interview Portal. It maps how Candidates, HRs, Project Managers, Interviewers, and Admins interact with the system to transition a candidate from registration to final selection.
---
## 1. System Overview & Role Matrix
The Hire Guru portal is an enterprise interview and evaluation platform designed to automate and track candidate assessments.
| **HR** | Full operational control. Creates/deletes interviews, manages candidates, generates quizzes, reviews all feedback, registers other users, signs/makes the **Final Selection Decision** (Hire, On Hold, Reject). |
| **Admin** | Full system administration. Can manage groups, generate/edit quizzes, review candidate histories, view logs, register all staff, and override/make final decisions. |
G --> G1[Interviewer, PM, & HR Submit Evaluations]
G1 --> H{All Appointed Evaluations Submitted?}
H -- Yes --> I[All Evaluations Done Badge Active]
H -- No --> J[Evaluations Pending State]
I --> K[Phase 4: Final Decision Phase]
K --> K1[Admin / HR reviews all scores, comments, & signatures]
K1 --> L[HR or Admin records Decision: Offer, Reject, On Hold, 2nd Round]
L --> M[Phase 5: Completed]
```
---
## 3. Detailed Step-by-Step State Lifecycle
An interview always progresses through a strict, linear state machine governed by the `status` attribute (`pending` $\rightarrow$ `quiz_phase` $\rightarrow$ `coding_phase` $\rightarrow$ `evaluation` $\rightarrow$ `completed`).
### Phase 1: Registration & Interview Creation
1.**Candidate Registration**: A candidate registers on the portal by entering their name, email, password, and selecting an assessment group (e.g., *Fresher*, *Intern*, *Final Year*).
2.**Scheduling & Assignment**:
* An Admin, HR, or PM opens the Scheduling Modal.
* They enter candidate details, position, tech stack, source, date/time, and choose **exactly one** evaluator for each of the three mandatory slots: **Interviewer, PM, and HR**. (Single selection radio-buttons enforce strict ownership).
* They select one or more Aptitude or Technical Quizzes to assign.
***State Transition**: If quizzes are assigned, the interview status is initialized to `quiz_phase`. If no quizzes are assigned, it falls back to `pending`.
1.**Candidate Workspace**: Upon logging in, the candidate is routed to their dashboard where they see the list of active assigned quizzes.
2.**Test Environment**:
* The candidate enters the standalone `take-quiz` dashboard.
* A timer starts automatically (pulled from MongoDB).
***Full-Screen Enforcement**: The portal requests full-screen mode immediately. If the user cancels it, an alert is shown.
3.**Anti-Cheat Monitoring Engine**:
* The frontend active monitoring service tracks browser focus and window events.
***Tab Switched / Window Blurred**: If the candidate opens another tab or window, an anti-cheat tracking event triggers.
***Warning Actions**: On tab switches or exiting full-screen, the application shows a high-priority warning popup, increments a transgression counter, and logs a violation event to the database.
***Automatic Submission**: If the candidate exceeds the maximum allowed transgressions (typically 3 tab switches) or if the test timer reaches zero, the anti-cheat system immediately calls the submission API, auto-submitting the exam, flagging the quiz record as `violation: true` in the DB, and locking the candidate out.
4.**Transition**: Once all assigned quizzes are completed (or auto-submitted due to a violation), the candidate's dashboard shifts to prompt them for the coding round. The interview transitions to `coding_phase`.
### Phase 3: Coding Challenge Phase
1.**Submitting Code**:
* The candidate performs their coding challenge.
* The interviewer/PM uploads the completed zip file on behalf of the candidate via the evaluation modal, or the candidate uploads their submission directly.
***Backend Storage**: The node backend saves this file to the `uploads/` folder with an absolute static route accessible for review.
2.**Validation**:
* The assigned Interviewer, PM, or HR reviews the code.
* They click the **Validate** button.
***State Transition**: The interview status is updated to `evaluation`.
### Phase 4: Staff Evaluation Phase
1.**Evaluating Candidates**:
* The appointed Interviewer, PM, and HR log into their respective dashboard views.
* In the evaluation panel, each role can enter qualitative feedback comments and choose a recommendation: `offer` (Hire), `on_hold`, `rejected`, or `2nd_round`.
***Signatures**: Digital signatures (stored as base64 images generated in the profile page) are automatically attached to their feedback form.
2.**Evaluation Progression Indicator**:
* As each assigned member completes their review, the system tracks the evaluation count against the appointed list.
* When all appointed evaluators have submitted their feedback, the system lights up the `All evaluations done` green badge.
### Phase 5: Final Selection & Completion
1.**Making the Final Call**:
* Only **Admin** and **HR** users have the administrative privilege to see the final decision form.
* They review the compiled feedback, quiz scores, anti-cheat violation flags, and evaluator signatures.
* They select the final action: `accepted` (Offer), `rejected`, `on_hold`, or `2nd_round`.
2.**Interview Closure**:
* The interview state updates to `completed`.
* The candidate can view their history and results (if public) on their dashboard.
---
## 4. Anti-Cheat Security System Technical Details
The **Anti-Cheat Engine** resides in the frontend standalone Angular service (`anti-cheat.service.ts`). It handles key validation actions:
***Focus / Blur Hook**: Uses JavaScript's `window.addEventListener('blur', ...)` and `document.addEventListener('visibilitychange', ...)` to detect if the user leaves the tab.
***State Persistence**: If the candidate attempts to refresh the browser to clear warnings, the backend tracks active submission attempts, maintaining warning status logs to prevent session overrides.
