# 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.
QuizMaster is a full-stack MEAN (MongoDB, Express, Angular, Node.js) application designed to facilitate seamless online quiz generation and assessment. It provides distinct interfaces for administrators to manage quizzes and monitor users, and for students to track their progress, take timed quizzes, and view immediate results.
**Hire Guru** (formerly QuizMaster) is a premium, enterprise-grade Interview & Candidate Assessment Portal built on the robust **MEAN stack** (MongoDB, Express, Angular, Node.js). Designed for modern recruitment operations, it combines role-based hiring dashboards with a secure, browser-locked candidate test-taking engine, local AI quiz builders, and digital canvas signature compliance checks.
-**Backend API (Render):**[https://quiz-master-b3zl.onrender.com](https://quiz-master-b3zl.onrender.com)
The candidate quiz engine is protected by a multi-layered security wrapper:
***Fullscreen Lock & Detection**: Requests fullscreen status on quiz start, tracking user attempts to escape.
***Window Focus & Tab Monitor**: Intercepts `visibilitychange` and browser window `blur` events to detect app/tab-switching.
***Warning Warning Overlay**: Displays a modal alert for focus violations. Submits tests automatically upon reaching the transgression threshold (3 counts) with a `violation: true` stamp.
***Keyboard Shortcut Blocker**: Blocks Inspect Tool hooks (`F12`, `Ctrl+Shift+I`) and standard copy-paste bindings.
***Countdown Session Protection**: Retains warning counts and syncs timers in local storage in the event of an accidental page refresh (`F5`).
### 🤖 2. Local AI Ollama Quiz Generation
Empowers hiring managers to generate full structured quizzes instantly using offline AI models:
* Integrates natively with local Ollama chat instances (`/api/chat`).
* Prompts local LLM models to compile multiple-choice questions matching target skills and difficulty levels, returning structured JSON directly into Mongoose.
* Gracefully falls back to helpful setup messages if local Ollama servers are offline.
### ✍️ 3. Compliant Canvas-Drawn Signatures
Ensures evaluators sign off securely:
* Evaluators draw their official signatures directly on an interactive canvas in their profile dashboard.
* Signature is stored securely as a Base64 image payload.
* Feedback forms restrict submissions until the evaluator's signature is drawn and saved, providing legally audit-ready evaluations.
### 📂 4. Coding Challenge ZIP & Review Pipelines
* Candidates or PMs can upload compressed zip code test files (restricted to `5MB` upload limits for server safety).
* Evaluators can download and validate challenges directly from the details drawer, transitioning pipeline phases instantly from `coding_phase` to `evaluation`.
### 👥 5. Cohort Scheduling & Random Quiz Cascading
***Group Scheduling**: HR/Admins can schedule assessments for entire classes or teams concurrently.
***Randomized Assignment**: Supports selecting a list of quiz bundles and cascading a random quiz selection to each candidate, minimizing collaboration during testing.
---
---
## ✨ Key Features
## 🎭 Enterprise Role Matrix
### 👨🏫 Admin Dashboard
Hire Guru implements strict role-based dashboard layouts tailored to each stakeholder:
***Secure Admin Access:** Pre-configured admin accounts can log in to access the management portal.
***Quiz Generation:** Easily create new quizzes by uploading question banks (supports multi-select questions and manual entry overrides).
***User Management:** View all registered students, monitor active/online status, and track their test history and scores.
***Submissions Overview:** Drill down into specific quiz submissions to analyze class performance.
### 🎓 Student Dashboard
***Administrator**: Manages global database configurations, registers staff accounts, imports Excel spreadsheets, and coordinates pipelines.
***Registration & Authentication:** Secure student sign-up and JWT-based login mechanism.
***HR Coordinator**: Monitors stats, schedules individual or group assessments, reviews all candidate files, and executes the final hiring decisions ("Offer", "On Hold", "Rejected").
***Available Quizzes:** Browse newly assigned active quizzes in an intuitive grid view.
***Interactive Test taking Engine:** Take dynamically loaded, timed quizzes with progress tracking and persistent layout.
***Interviewer**: Examines technical profiles, validates technical challenges, and adds detailed ratings and reviews.
***Result Tracking:** Instant evaluation upon test submission with visual indicators of performance (`Good`, `Average`, `Poor`).
***Candidate**: Enters a clean, dark-themed dashboard to launch assigned quizzes, view progress tracking steps, upload zip files, and see current phase status.
***Profile Analytics:** Review entire quiz history and statistical average tracking from your profile dashboard.
---
---
## 💻 Tech Stack
## 💻 Tech Stack
***Frontend:** Angular 17/18, TypeScript, RxJS, Vanilla CSS (Custom dark theme with CSS custom properties)
The UI utilizes a highly customized and responsive **dark mode** design (`#0f1117`) focusing on readability, glassmorphism interactions, and clean spacing for the ultimate test-taking experience without distractions.
Hire Guru uses a responsive custom **Dark Cyber Theme** (`#0f1117`) centered around optimal text readability during intense assessments. Features elegant HSL customized borders, glassmorphic card overlays, responsive CSS flex grids, and smooth animations.
---
---
## 🤝 Contributing
## 🤝 Contributing & License
Contributions, issues, and feature requests are welcome!
Contributions, feedback, and issue submissions are welcome. Please open a pull request or file a ticket under the repository issues tab. Distributed under the **MIT License**.
Feel free to check the [issues page](https://github.com/AravindR-K/Quiz-Master/issues) if you want to contribute.
## 📝 License
This project is open-source and available under the [MIT License](LICENSE).
# 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!
