# Computer-Based Examination System (CBT)
# Standard Operating Procedure (SOP) & Institute Operations Manual

**Document Code:** CBT-SOP-2026-V1  
**Target Audience:** School Principals, College Deans, Coaching Directors, IT Administrators, Lab Technicians, and Exam Invigilators  
**System Version:** Institutional Standalone & Local Network Edition  
**Software Architect & Lead Engineer:** Pankaj Kumar  
**Official Developer Contact:** [mpitpankajk@gmail.com](mailto:mpitpankajk@gmail.com)  

---

## Table of Contents
1. [Executive Summary & System Architecture](#1-executive-summary--system-architecture)
2. [Hardware & Network Infrastructure Requirements](#2-hardware--network-infrastructure-requirements)
3. [Software Prerequisites & 1-Click Installation](#3-software-prerequisites--1-click-installation)
4. [Institution Profile Registration & Automated Branding](#4-institution-profile-registration--automated-branding)
5. [Daily Operation & Server Startup](#5-daily-operation--server-startup)
6. [Local Network (Wi-Fi / LAN) Setup & Windows Firewall Configuration](#6-local-network-wi-fi--lan-setup--windows-firewall-configuration)
7. [Student ID & Password Batch Management & Admit Cards](#7-student-id--password-batch-management--admit-cards)
8. [Question Paper Preparation via Excel (.xlsx)](#8-question-paper-preparation-via-excel-xlsx)
9. [Live Examination Invigilation & Master Control Center](#9-live-examination-invigilation--master-control-center)
10. [Student Exam Interface & Anti-Cheat Capabilities](#10-student-exam-interface--anti-cheat-capabilities)
11. [Automated Grading, Merit Lists & Official Reports](#11-automated-grading-merit-lists--official-reports)
12. [Student Self-Registration, Plans & Payment Approvals (Optional)](#12-student-self-registration-plans--payment-approvals-optional)
13. [Comprehensive Troubleshooting Matrix & FAQs](#13-comprehensive-troubleshooting-matrix--faqs)
14. [Pre-Exam, Exam-Day & Post-Exam Standard Checklists](#14-pre-exam-exam-day--post-exam-standard-checklists)
15. [Emergency Quick Reference Card](#15-emergency-quick-reference-card)

---

## 1. Executive Summary & System Architecture

The **CBT Examination System** is an enterprise-grade, high-performance web application engineered specifically for educational institutions, schools, colleges, competitive coaching centers, and testing academies.

### Key Architectural Strengths
- **Zero Internet Dependency:** The system operates 100% autonomously within the institute's local area network (LAN or Wi-Fi). No active internet connection, broadband link, or external cloud service is required during the examination.
- **Client Device Agnostic:** Students can take tests using existing desktop PCs in computer labs, laptops, Chromebooks, Android tablets, iPads, or smartphones via any standard modern web browser.
- **Fail-Safe Real-Time Autosave:** Every student response, radio selection, and mark-for-review action is instantly committed to the server's persistent SQLite database via WebSocket and REST APIs. In the event of a power outage or PC reboot, student answers remain 100% safe.
- **NTA & GATE Standard Interface:** Familiar test layout featuring color-coded question palettes, section switching, timer synchronization, and review summaries.
- **Live Invigilator Command Center:** Centralized real-time monitoring of all active candidates, with master controls to Start, Pause, Resume, Extend Time (+5 mins), and Force-Submit tests.
- **Automated Instant Evaluation:** Zero manual grading effort. Produces rank lists, scorecards, question analytics, and official PDF answer sheets in one click.

---

## 2. Hardware & Network Infrastructure Requirements

### 2.1 Server Machine (Administrator / Teacher's PC)
The computer hosting the CBT server acts as the central node for all student machines:
- **Operating System:** Windows 10, Windows 11, Windows Server (64-bit), or Linux/macOS.
- **Processor:** Intel Core i3 (6th Gen or newer) / AMD Ryzen 3 or higher.
- **RAM:** 4 GB minimum (8 GB recommended for 100+ concurrent students).
- **Storage:** 1 GB free hard drive / SSD space.
- **Network Interface:** Ethernet Gigabit LAN port (strongly recommended) or 5GHz Wi-Fi.

### 2.2 Client Devices (Student Exam Terminals)
Any computer, laptop, or mobile device that connects to the local network:
- **Hardware:** Desktop PC, Laptop, Tablet, or Smartphone.
- **Supported Browsers:** Google Chrome, Microsoft Edge, Mozilla Firefox, Brave, Safari, or Chromium (any modern browser from the last 5 years).
- **RAM:** 1 GB or higher.
- **Display:** Minimum resolution 1024x768 for desktop PCs; fully responsive for mobile screens.

### 2.3 Network Equipment (Wi-Fi Router / LAN Switch)
- **Small Exam (Up to 30 Candidates):** A standard consumer Wi-Fi router (Wi-Fi 5 / 802.11ac or Wi-Fi 6).
- **Medium Exam (30 to 80 Candidates):** Dual-band Wi-Fi router (2.4GHz + 5GHz) or a 24-Port 100/1000 Mbps Ethernet switch.
- **Large Exam (100+ Candidates):** Commercial Managed Gigabit Switch or multiple Wi-Fi Access Points (APs) sharing the same subnet router.
- *Notice: Internet connection is NOT needed on the router. Only local IP assignment (DHCP) is required.*

---

## 3. Software Prerequisites & 1-Click Installation

### Step 3.1: Install Python (One-Time Setup)
If Python is not already installed on the host server PC:
1. Visit the official website: [https://www.python.org/downloads/](https://www.python.org/downloads/)
2. Download **Python 3.10** or higher (e.g. 3.11, 3.12, 3.13).
3. Run the downloaded installer.
4. **CRITICAL STEP:** At the bottom of the very first installation screen, check the box:
   ```
   [x] Add python.exe to PATH (or "Add Python to PATH")
   ```
5. Click **Install Now** and complete setup.

> **CRITICAL WARNING:** Failing to check *"Add Python to PATH"* will prevent the Windows launcher files (`setup_and_install.bat` and `run_cbt.bat`) from recognizing Python.

### Step 3.2: Unzip the Application Package
1. Extract the provided `CBT_Setup.zip` (or copy the `CBT_Setup` folder) to your desired location, e.g.:
   ```
   C:\CBT_Setup
   ```
   *(or `D:\CBT_Setup`)*

### Step 3.3: Execute 1-Click Setup
1. Inside the `CBT_Setup` directory, double-click:
   ```
   setup_and_install.bat
   ```
2. The automated script will:
   - Check and verify your Python environment.
   - Create an isolated virtual environment (`venv`).
   - Automatically install all required modules (`fastapi`, `uvicorn`, `openpyxl`, `reportlab`, `qrcode`, `websockets`, `jinja2`).
   - Start the CBT web server on port `8000`.
   - Automatically launch your web browser to the **Institute Setup & Registration Page** (`http://localhost:8000/setup`).

---

## 4. Institution Profile Registration & Automated Branding

When launching the software for the first time, you will see the **Institute Setup & Registration** page.

### Configuration Fields
1. **School / College / Institute Name** *(Required)*:  
   *Example: "Apex International Academy & Institute of Engineering"*
2. **Campus / Center Address** *(Required)*:  
   *Example: "Campus 1, Sector 12, Civil Lines, Prayagraj, UP - 211001"*
3. **Official Contact Mobile / Landline** *(Required)*:  
   *Example: "+91 98765 43210"*
4. **Official Contact Email** *(Required)*:  
   *Example: "admissions@apexacademy.edu"*
5. **Registration / Affiliation Number** *(Optional)*:  
   *Example: "AFF/CBSE/2026/8941"*
6. **UDISE+ / Center Code** *(Optional)*:  
   *Example: "UDISE-09140203011"*
7. **New Admin Password** *(Optional, default is `admin123`)*:  
   *Enter a secure password for administrator access.*

### Applying Configuration
Click **"Save Profile & Launch Examination System"**.
- Your institution's branding is now permanently applied across all student login pages, test screens, PDF admit cards, and final score sheets.
- Developer credits (**Pankaj Kumar** - `mpitpankajk@gmail.com`) remain permanently recorded in system dialogs and footers.

---

## 5. Daily Operation & Server Startup

After completing the initial setup, you only need to run one file for daily operation.

### How to Launch the Server
1. Double-click the file:
   ```
   run_cbt.bat
   ```
2. A black terminal window will open, indicating:
   ```
   ===============================================================================
                     CBT EXAMINATION SYSTEM - SERVER LAUNCHER
                Software Developed by Pankaj Kumar (mpitpankajk@gmail.com)
   ===============================================================================
   Starting CBT Examination Server on port 8000...
   Portal URL: http://localhost:8000
   ```
3. Your browser will automatically open to `http://localhost:8000`.
4. Keep this terminal window minimized in the taskbar. **Do NOT close this window during an examination.**

---

## 6. Local Network (Wi-Fi / LAN) Setup & Windows Firewall Configuration

To allow student computers and mobile devices to access the exam portal, follow these steps:

### Step 6.1: Connect to the Same Network
Ensure that the Server PC and all Student PCs/mobiles are connected to the **same Wi-Fi router or wired LAN switch**.

### Step 6.2: Identify the Server's Local IP Address
1. Open the Admin Dashboard (`http://localhost:8000/admin`).
2. Look at the top left card: **"Local Exam Address"**.
3. It displays your machine's exact network address, for example:
   ```
   http://192.168.1.15:8000
   ```
4. Click the **"Scan QR"** button to display a high-resolution QR code on the projector or screen. Mobile and tablet users can simply scan this QR code to open the exam portal instantly!

### Step 6.3: Windows Defender Firewall Configuration (Crucial)
If student devices fail to load the address or show *"Site can't be reached"*, Windows Firewall is blocking inbound connections on port 8000.

**Method A: 1-Line PowerShell Command (Run as Administrator):**
```powershell
New-NetFirewallRule -DisplayName "CBT Exam Server Port 8000" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow
```

**Method B: GUI Steps:**
1. Press `Windows Key + R`, type `control firewall.cpl`, and press Enter.
2. Click **Advanced settings** on the left menu.
3. Click **Inbound Rules** -> Click **New Rule...** on the right panel.
4. Select **Port** -> Click **Next**.
5. Select **TCP**, and under **Specific local ports**, enter: `8000` -> Click **Next**.
6. Select **Allow the connection** -> Click **Next**.
7. Keep all three checked: **Domain, Private, Public** -> Click **Next**.
8. Name the rule: `CBT Exam Server` -> Click **Finish**.

Now, all student devices can instantly connect!

---

## 7. Student ID & Password Batch Management & Admit Cards

Administrators have complete control over student credentials with zero manual password generation hassle.

### Step 7.1: Batch Create Student Accounts
1. Log into Admin Dashboard: `http://localhost:8000/admin`.
2. Scroll to the **Student Credentials & Accounts** section.
3. Click **"Batch Generate IDs"**:
   - **Prefix:** Enter batch prefix, e.g. `STU-` or `2026-`
   - **Count:** Number of students to generate, e.g. `50`
   - **Batch Name:** e.g. `Batch Class 10A`
4. Click **Generate Accounts**.
5. The system automatically creates unique Roll Numbers (e.g. `STU-1001` to `STU-1050`) and generates strong, memorable passwords for each candidate.

### Step 7.2: Export Credentials to Excel
- Click **"Export Credentials Excel"** to download an Excel sheet containing all student User IDs, Names, Batch tags, and Passwords for administrative records.

### Step 7.3: Print Official Admit Cards
- Click **"Print Admit Cards"** to render clean, ready-to-print admit slips for all candidates.
- Each admit card includes:
  - Institute Name and Watermark
  - Candidate Roll Number / User ID
  - Password
  - Examination Instructions
  - Candidate Signature and Invigilator Verification fields

---

## 8. Question Paper Preparation via Excel (.xlsx)

You do not need to type questions one-by-one into a web form. Question papers are prepared directly in Microsoft Excel or Google Sheets.

### Step 8.1: Download Sample Excel Template
1. In the Admin Dashboard, click **"Download Sample Excel"** (or use `sample_questions.xlsx` provided in the package root).
2. Open the file to inspect the formatting.

### Step 8.2: Excel Column Structure
Ensure your `.xlsx` spreadsheet contains the following standard columns:

| Column Header | Description | Example Values |
|---|---|---|
| **Question Number** | Question sequence index | `1`, `2`, `3`, `4` |
| **Question Text** | Full text of the question (multi-line supported) | `What is the SI unit of electric current?` |
| **Option A** | First answer choice | `Volt` |
| **Option B** | Second answer choice | `Ampere` |
| **Option C** | Third answer choice | `Ohm` |
| **Option D** | Fourth answer choice | `Watt` |
| **Correct Option** | Correct option letter (must be single letter) | `B` |
| **Marks** | Positive marks awarded for correct answer | `4.0` |
| **Negative Marks** | Marks deducted for incorrect answer (or 0) | `1.0` |
| **Section / Subject** | Subject category for multi-section tests | `Physics`, `Chemistry`, `Mathematics`, `GK` |
| **Explanation** | Detailed rationale shown in post-exam solutions | `Ampere is the SI unit of current (I = Q/t).` |

### Step 8.3: Upload and Publish the Test Paper
1. In Admin Dashboard, click **"Upload New Test Paper"**.
2. Enter:
   - **Test Title:** e.g. *"Terminal Mock Test 2026 - Science & Mathematics"*
   - **Description:** e.g. *"Full syllabus entrance test with negative marking"*
   - **Duration (Minutes):** e.g. `60` (or `90`, `180`)
   - **Default Correct Marks:** e.g. `4.0`
   - **Default Negative Marks:** e.g. `1.0`
3. Click **Browse** and select your `.xlsx` file.
4. Click **"Create & Upload Test"**.
5. The system validates all rows and questions instantly. Your test is now ready to conduct!

---

## 9. Live Examination Invigilation & Master Control Center

On examination day, the invigilator manages the entire session from the **Live Invigilator Monitor** (`http://localhost:8000/admin/live/<test_id>`).

### Step 9.1: Students Assemble and Log In
1. Students open their browser and visit: `http://<SERVER_IP>:8000`
2. Students enter their **User ID** and **Password** from their Admit Card.
3. Once logged in, students see the **Exam Instructions & Ready Screen** with a waiting message:  
   *"Exam is waiting for the invigilator to start. Please wait..."*

### Step 9.2: Real-Time Student Grid
On the Invigilator screen, every student appears in a live monitoring card showing:
- 🟢 **Online Status:** Green badge indicates connected WebSocket; Red indicates disconnected/offline.
- **Current Question:** Shows the exact question number the student is currently reading.
- **Progress Counter:** Number of questions Answered, Marked for Review, and Unvisited.
- **Tab Switch Warning Count:** Tracks any anti-cheat browser minimization violations.

### Step 9.3: Master Exam Controls
At the top of the Invigilator screen are five master control buttons:
1. **▶ START TEST FOR ALL:**
   - Instantly unfreezes all connected student screens.
   - Synchronizes countdown timers and begins the examination simultaneously for the whole hall.
2. **⏸ PAUSE TEST:**
   - Freezes all student screens with an official on-screen alert: *"Test is paused by the administrator."*
   - Halts all timers. Useful for making hall announcements or handling emergencies.
3. **▶ RESUME TEST:**
   - Resumes countdown timers and unfreezes student screens.
4. **⏱ +5 MINS EXTENDER:**
   - Dynamically injects 5 additional minutes into all active student countdown timers in real time.
5. **⏹ END TEST:**
   - Force-submits all active student sessions simultaneously.
   - Compiles final answers and permanently locks the examination.

### Step 9.4: Anti-Cheat Live Event Ticker
The live monitor maintains a scrolling security log capturing real-time student activity:
- Student login and connection events.
- Answers recorded.
- Anti-cheat tab-switching alerts with exact timestamps (e.g. `STU-1014 switched browser tab at 10:14:22`).

---

## 10. Student Exam Interface & Anti-Cheat Capabilities

### 10.1 Interface Elements (NTA / GATE Style)
- **Top Bar:** Shows Test Title, Candidate Name, Roll Number, and Synchronized Countdown Timer.
- **Question Palette (Right / Drawer):**
  - 🟩 **Green:** Answered
  - 🟥 **Red:** Visited, but not answered
  - 🟪 **Purple:** Marked for Review
  - ⬜ **Gray:** Not yet visited
- **Action Buttons:**
  - **Save & Next:** Commits answer and advances to next question.
  - **Mark for Review & Next:** Tags question for later inspection.
  - **Clear Response:** Unselects the chosen option.
  - **Previous / Next:** Navigation between questions.
  - **Submit Test:** Opens review summary modal before final confirmation.

### 10.2 Anti-Cheat Security
- **Fullscreen Locking:** Exam runs in full-window mode.
- **Tab-Switch Detection:** If a student switches browser tabs or opens another application, the system immediately displays a prominent security warning modal and increments their anti-cheat violation counter on the admin screen.
- **Right-Click & Copy-Paste Prevention:** Context menus and keyboard shortcuts (`Ctrl+C`, `Ctrl+V`, `F12`) are disabled on student terminals.

---

## 11. Automated Grading, Merit Lists & Official Reports

Once the examination concludes, the software automatically grades every response without human error.

### 11.1 Results & Leaderboard Dashboard
Navigate to: `http://localhost:8000/admin/results/<test_id>`
- **KPI Metrics:** Total Candidates, Average Score, Highest Score, Lowest Score, Passing Ratio.
- **Merit Table:** Complete ranked list displaying:
  - Rank (#1, #2, #3, ...)
  - Candidate Roll Number & Name
  - Total Attempted Questions
  - Correct Answers count
  - Incorrect Answers count
  - Accuracy Percentage
  - Final Marks Awarded (accounting for negative marking)

### 11.2 One-Click Excel Export
- Click **"Export Excel Report"** to download the comprehensive scorecard (`.xlsx`) containing detailed candidate breakdowns.

### 11.3 Official PDF Answer Sheet Generation
- Click **"Download Answer Sheet (PDF)"** next to any candidate to view or save their official test booklet.
- The PDF contains:
  - Official Institute Header, Registration Number, and Candidate Details.
  - Score summary table with awarded marks and accuracy.
  - Question-by-question candidate response comparison:
    - Candidate's chosen option
    - System correct answer
    - Status (Correct / Incorrect / Unattempted)
    - Full explanation / solution key.

### 11.4 Bulk PDF Answer Sheets ZIP Download
- Click **"Download All Answer Sheets (ZIP)"** to generate and package every student's individual PDF answer sheet into a single downloadable ZIP file.

### 11.5 Email Integration (SMTP)
- If configured under Admin Settings, click **"Email All Answer Sheets"** to automatically dispatch individual scorecards to student email inboxes.

---

## 12. Student Self-Registration, Plans & Payment Approvals (Optional)

If your institution conducts open mock tests or charges test fees:
- **Student Self-Registration:** Students can visit `http://<SERVER_IP>:8000/register` to create their own accounts.
- **Free Trial:** First-time registered students can claim 1 free mock test credit.
- **Credit Packages:** Students view plans at `/student/plans` and submit payments via UPI QR code (`/student/payment/<plan_id>`) entering their bank UTR / Reference number.
- **Admin Payment Verification:** Admin reviews pending payments at `/api/admin/payments` and clicks **Approve** to immediately credit test attempts to the student.

*(Note: For internal school/college exams, this module is completely optional. Admin can simply batch-create free student accounts.)*

---

## 13. Comprehensive Troubleshooting Matrix & FAQs

| Issue / Error Symptom | Root Cause | Exact Solution |
|---|---|---|
| **`python: command not found`** when running `setup_and_install.bat` | Python was installed without the PATH environment variable checked. | Re-run the Python installer, select **Modify**, and make sure **Add python.exe to PATH** is checked. Click Install. |
| **Student screens show *"Site can't be reached"* or *"Connection Timed Out"*** | Windows Defender Firewall on the host PC is blocking incoming traffic on port 8000. | Open PowerShell as Administrator and run: `New-NetFirewallRule -DisplayName "CBT Port 8000" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow`. Verify both devices are on the same Wi-Fi. |
| **Server console window was accidentally closed during the exam** | Terminal was closed or host PC was restarted. | **Do not panic!** Double-click `run_cbt.bat` again. The server will restart instantly. All previous student answers are safely preserved in the database. Students can refresh and continue. |
| **A student's PC crashed, had a power cut, or restarted** | Hardware failure on student client machine. | Restart the student PC (or move them to any spare PC). Have them log in with the same User ID and Password. Their answers and remaining time will resume exactly where they left off. |
| **Excel question upload displays an error message** | Incorrect column names or missing Correct Option in the `.xlsx` file. | Verify column names match the sample file. Ensure the **Correct Option** column contains only a single capital letter (`A`, `B`, `C`, or `D`). Remove any completely empty rows at the end of the sheet. |
| **Student forgot their password on exam day** | Lost admit card or forgotten password. | Admin can view or copy the student's password directly from the Admin Dashboard table, or click **Reset Password** to generate a new one instantly. |
| **Forgot Administrator Password** | Lost credentials. | The default password is `admin123`. If changed and forgotten, open `.env` or contact the lead developer at `mpitpankajk@gmail.com`. |

---

## 14. Pre-Exam, Exam-Day & Post-Exam Standard Checklists

### 14.1 Pre-Exam Checklist (T minus 24 Hours)
- [ ] Verify Python is installed and `run_cbt.bat` launches cleanly.
- [ ] Prepare question paper in Excel format and upload via Admin Dashboard.
- [ ] Review question paper in Admin Dashboard to ensure question count and marks are correct.
- [ ] Batch-generate student IDs and export credentials to Excel.
- [ ] Print Admit Cards and distribute to candidates.
- [ ] Connect a test student device to the Wi-Fi/LAN and confirm `http://<SERVER_IP>:8000` loads properly.

### 14.2 Exam-Day Checklist (T minus 30 Minutes)
- [ ] Boot Host Server PC and connect via wired Ethernet cable to router.
- [ ] Launch `run_cbt.bat` and minimize the window.
- [ ] Log in as Admin and open the **Live Invigilator Monitor** (`/admin/live/<test_id>`).
- [ ] Project or write the Server IP address (e.g. `http://192.168.1.15:8000`) on the hall whiteboard.
- [ ] Instruct students to log in and wait on the instruction screen.
- [ ] Verify all student cards turn 🟢 Green (Online) on the live monitor.
- [ ] At official exam start time, click **"START TEST FOR ALL"**.

### 14.3 Post-Exam Checklist (Immediately After Exam)
- [ ] Click **"END TEST"** on the live monitor to freeze all submissions.
- [ ] Navigate to **Results & Ranking** (`/admin/results/<test_id>`).
- [ ] Click **"Export Excel Report"** and save a backup copy on a USB flash drive.
- [ ] Click **"Download All Answer Sheets (ZIP)"** for institutional compliance and archiving.
- [ ] Close server window and power down client machines safely.

---

## 15. Emergency Quick Reference Card

```
================================================================================
               CBT EXAMINATION SYSTEM - EMERGENCY QUICK CARD
================================================================================

1. START SERVER:
   Double-click:  run_cbt.bat
   Default Admin: http://localhost:8000/admin
   User:          admin
   Password:      admin123 (or custom password set in setup)

2. STUDENT LAB ACCESS URL:
   http://<YOUR_LOCAL_IP>:8000
   (Find your local IP in Admin Dashboard or Console window)

3. QUICK FIREWALL UNBLOCK (Run in Admin PowerShell):
   New-NetFirewallRule -DisplayName "CBT 8000" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow

4. IF POWER CUT / SERVER ACCIDENTALLY CLOSED:
   Just double-click run_cbt.bat again.
   Zero data loss! All student selections are auto-saved.

5. DEVELOPER SUPPORT CONTACT:
   Pankaj Kumar | mpitpankajk@gmail.com
================================================================================
```

---
*End of Standard Operating Procedure Document.*