# 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.
# Interviewer and Project Manager Workflow Implementation
This plan outlines the steps required to complete Task 1 (Building PM and Interviewer Dashboards & Interview Views) and Task 2 (Finalizing the PDF Document Generation & Download workflow).
## Task 1: Interviewer and Project Manager Platforms
Currently, the `ProjectManager` and `Interviewer` folders have shell components (e.g., `dashboard`, `individual-interview`, `group-interview`). We need to populate these and wire up the navigation.
### Proposed Changes
#### 1. Routing Updates (`src/app/app.routes.ts`)
Update the routes to properly map to the specific components you've created for the PM and Interviewer, rather than reusing the Admin components:
We will mirror the look of the admin/hr dashboard but simplify it for these roles. They do not need to create quizzes or manage users. The dashboard will strictly show their pending evaluation metrics and a quick action link to navigate to their interviews.
#### 4. Individual & Group Interview Components
For both PM and Interviewer roles, we will copy the functionality from the Admin/HR `individual-interview` and `group-interview` modules. However, we will restrict administrative capabilities:
-**Remove** the "Create New Interview" button.
-**Remove** the "Delete Interview" action.
-**Remove** the "Final Decision" accept/reject section since only Admin/HR should finalize the overall hiring decision.
-**Keep** the interview list (which correctly filters to only the interviews they are assigned to).
-**Keep** the "Evaluation" form inside the interview detail modal so they can submit their own comments and recommendations.
## Task 2: Evaluation Summary Document & Download
Once the PM and Interviewer can successfully submit their evaluations, we will solidify the PDF download button logic.
Currently, we added a "Download PDF" button in the HR/Admin individual interview modal. Based on your request, we will ensure that:
1. The **Download Evaluation Summary** button is prominently visible in the Interview Details modal across all roles (Admin, HR, PM, Interviewer).
2. The button will generate the structured PDF form (matching Images 3 & 4), containing pre-filled sections for:
- Interviewer Comments, Recommendation, Signature, and Date
- PM Comments, Recommendation, Signature, and Date
- HR Comments, Recommendation, Signature, and Date
3. Data from the database will seamlessly populate these sections. If a specific crew member hasn't evaluated yet, their section will print blank so it can be physically filled if desired, just like we implemented for HR in the previous session.
## User Review Required
> [!IMPORTANT]
> - Are you okay with removing the "Create New Interview" and "Finalize Decision" buttons from the PM and Interviewer views? (Usually, only Admins or HR schedule the interviews and make the final hire/reject decision).
> - Should the "Download Evaluation Summary" button only be enabled/visible after **everyone** (HR, PM, Interviewers) has completed their evaluations, or should they be able to download a partially filled document at any time? Currently, the logic restricts downloading until everyone has finished.
Please approve this plan so I can start executing Task 1 immediately!
