File size: 13,564 Bytes
788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 35e8172 788eab4 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 | # Institutional Campus Placement Eligibility & Scheduling Engine
[](https://fastapi.tiangolo.com)
[](https://reactjs.org/)
[](https://vitejs.dev/)
[](https://tailwindcss.com/)
[](https://developers.google.com/optimization)
[](https://sqlite.org/)
[](#deployment-options)
[](https://huggingface.co/spaces/deeep-sec/campus-placement-engine-demo)
[](#verification--testing)
[](LICENSE)
An institutional-grade campus recruitment operations and scheduling engine designed for collegiate Training & Placement Cells (TPO) and enterprise recruitment. Coordinates recruitment drives, thousands of student academic profiles, institutional multi-offer policies, and conflict-free interview scheduling. **Deployable anywhere**: publicly on cloud platforms (Hugging Face Spaces, Docker containers, cloud VMs) as well as private institutional networks with complete data sovereignty and privacy.
---
## Executive Overview
College placement offices face massive logistical hurdles every recruitment season:
1. **Drive Announcement Chaos**: JDs arrive via unstructured emails with conflicting cut-offs, branch aliases ("CS", "CSE", "CompSci"), and backlog requirements.
2. **Deterministic Eligibility**: Manual filtering leads to human error, missed cut-offs, and student disputes.
3. **Offer Policy Enforcement**: Tracking "one student, one offer" vs. Dream Company CTC multipliers is nearly impossible on spreadsheets.
4. **Interview Clashes**: Manually assigning hundreds of students to multi-panel interviews across physical cabins leads to double-bookings and room overlap.
5. **Data Privacy**: Student transcripts and academic records require strict role-based access control and encryption.
**The Placement Engine** solves all five challenges through a modern hybrid, mathematically verified software architecture.
---
## Architectural Workflow
```mermaid
flowchart TD
subgraph INGESTION ["1. Ingestion & Roster Normalization"]
CSV["Student Roster (CSV / XLSX)"] --> Importer["Multi-Format Student Importer"]
Importer --> Normalizer["Alias Resolver & Degree Mapper"]
Normalizer --> DB[("Local SQLite WAL Store")]
Notice["Unstructured Announcement"] --> NLP["AST Sentence-Level Extractor"]
NLP --> Provenance["Provenance & Quote Tracker"]
Provenance --> DriveReq["Versioned Drive Requirements"]
end
subgraph POLICY ["2. Eligibility & Policy Reasoning"]
DB --> Eval["Pure AST Eligibility Evaluator"]
DriveReq --> Eval
PolicyEngine["Institutional Offer Policy Engine"] --> Eval
Eval --> DecTable["Eligible Candidates & Audit Snapshots"]
end
subgraph SOLVER ["3. Constraint Optimization"]
DecTable --> CPSAT["Google OR-Tools CP-SAT Discrete Solver"]
Rooms["Physical Rooms & Interview Cabins"] --> CPSAT
CPSAT --> Verifier["Independent Non-Overlapping Verifier"]
Verifier --> Grid["0-Clash Multitrack Interview Schedule"]
end
subgraph DEPLOYMENT ["4. Air-Gapped Multi-Persona Access"]
Grid --> OfficerUI["TPO Officer Workspace"]
Grid --> StudentUI["Student Mobile / Laptop LAN Portal"]
Grid --> RecruiterUI["Corporate Recruiter Dashboard"]
Grid --> Exporter["Lossless Company Format Exporter"]
end
```
---
## Key Features
### 1. Deterministic NLP Requirement Extractor
- Paste unstructured announcement emails or upload PDFs/DOCXs.
- Automatically isolates CGPA thresholds, branch aliases, backlog tolerances, and gap-year limits.
- **Provable Provenance**: Every extracted criterion references the exact sentence and character offset in the source document.
- Interactive side-by-side review window allowing officers to accept, edit, or reject values with confidence ratings.
### 2. Live Visual Rule Editor & Policy Simulator
- Real-time interactive sliders for CGPA, 10th %, 12th %, and backlog tolerances.
- **In-Memory Instant Counter**: Displays the exact number and percentage of eligible candidates as sliders move without writing to disk.
- Interactive Simulator allowing officers to test edge cases (e.g. lateral entry diploma vs. 12th math, cleared backlogs) without mutating production state.
### 3. Google OR-Tools CP-SAT Discrete Scheduler
- Formulates multi-room, multi-panel interview scheduling as an exact Integer Linear Programming (ILP) satisfaction model.
- **Zero-Clashes Verification**: Mathematically enforces continuous interval non-overlapping constraints:
- A student cannot be in two interviews at the same time.
- An interview panel or room cannot host more than one candidate at the same time.
- Enforces lunch breaks, panel capacity, and round durations.
- Provisions additional parallel cabins automatically for large batches.
### 4. What-If Simulation & Atomic Publishing
- Test requirement adjustments in-memory before committing.
- Generates impact headlines (e.g., *"Lowering cut-off from 7.5 to 7.0 adds 32 students; 0 schedule clashes detected"*).
- Versioned atomic publishing with one-click instant rollback protection.
### 5. Candidate Dispute Comparative Explainer
- Plain-English comparative breakdowns answering: *"Why was I not shortlisted for Google while my classmate was?"*
- Side-by-side rule criteria comparison showing exact metric deltas, cleared backlog records, and institutional offer tier blocks.
### 6. Recruiter Custom-Format Lossless Exporter
- Upload company-specific spreadsheet templates.
- Maps database fields to custom company column headers.
- Round-trip fidelity testing asserting lossless data round-trips with zero data truncation.
### 7. 100% Offline Architecture Self-Check
- Real-time network interceptor asserting **strictly 0 outbound HTTP telemetry**.
- System-font fallback typography (no Google Fonts / CDN queries).
- Local Argon2 password hashing and SQLite WAL mode on localhost loopback.
### 8. Luxury Dark Enterprise Theme
- Midnight Navy (`#060b14`) canvas with dark blue surfaces (`#0d1527`) and hairline slate borders (`#1b2b4d`).
- Vibrant emerald (`#10b981`) and cyan-green status accents.
- Unified blue-to-emerald gradient action buttons across all views.
- Fully responsive across desktop workstations, tablets, and mobile phones.
---
## Multi-User Institutional Personas
| Persona | Default Username | Default Password | Access Scope |
| :--- | :--- | :--- | :--- |
| **TPO Officer** | `officer` | `officer123` | Full Administrative Access: Roster, Rules, Policies, Solver, Publishing, Rollbacks |
| **Student Coordinator**| `coordinator` | `coord123` | Operational Access: View Roster, Monitor Live Schedule, Issue Access Codes |
| **Candidate (Eligible)**| `PIPE_001` | `123456` | Student Portal: Personal Drive Eligibility, Rule Explanations, Venue Timetable |
| **Candidate (Lateral)** | `PIPE_002` | `123456` | Student Portal: Diploma vs. 12th Grade Equivalence & Cleared Backlog Standing |
| **Candidate (Blocked)** | `PIPE_003` | `123456` | Student Portal: Institutional Offer Policy Standing (Existing Offer Blocked) |
| **Recruiter (Google)** | `recruiter_google`| `recruiter123` | Recruiter Portal: Company Shortlist Table & Print-Ready Interview Schedule |
---
## Quickstart
### Prerequisites
- **Python 3.11+**
- **Node.js 18+** & **npm**
### Single-Command Unified Launcher (Recommended)
```bash
# 1. Clone repository
git clone https://github.com/<your-username>/campus-placement-engine.git
cd campus-placement-engine
# 2. Setup virtual environment
python -m venv .venv
# Windows:
.\.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
# 3. Install dependencies
pip install -e ".[dev]"
# 4. Build frontend
cd frontend
npm install
npm run build
cd ..
# 5. Launch unified server
python scripts/lan_launcher.py
```
The launcher verifies the database schema, compiles the frontend bundle, and hosts the portal across public or private interfaces:
```text
============================================================================
INSTITUTIONAL PLACEMENT ELIGIBILITY & SCHEDULING ENGINE
HYBRID PUBLIC CLOUD & INSTITUTIONAL NETWORK DEPLOYMENT
============================================================================
[+] Status: ONLINE (READY FOR TRAFFIC)
[+] Security: Encrypted PII & Role-Based RBAC
[+] Storage Engine: SQLite WAL Mode (Concurrent Multi-User Access)
[+] Constraint Solver: Google OR-Tools CP-SAT
----------------------------------------------------------------------
--> TPO Officer Local: http://localhost:8000
--> Network / Cloud URL: http://0.0.0.0:8000
----------------------------------------------------------------------
```
---
## Deployment Options: Public Cloud & Local Networks
The engine is engineered for flexible deployment across both public internet and private institutional infrastructure:
### 1. Public Cloud & Hugging Face Spaces
- **Live Demo Space**: Accessible online at [deeep-sec/campus-placement-engine-demo](https://huggingface.co/spaces/deeep-sec/campus-placement-engine-demo).
- **Hugging Face Model / Container Engine**: Available at [deeep-sec/campus-placement-engine](https://huggingface.co/deeep-sec/campus-placement-engine).
- Run on any public cloud container platform (Docker, AWS ECS, Google Cloud Run, Render, or VPS) using port `7860` or `8000`.
### 2. On-Premise & Campus Local Network (Wi-Fi / Ethernet)
- For university placement offices conducting on-campus recruitment seasons, the engine can be hosted locally without mandatory internet dependency.
- **Shareable URL**: Look for the **"LAN Host"** pill in the top navigation bar or on the login screen to copy the server address for student mobile devices and recruiter laptops.
---
## Docker Deployment
Build and run a production-ready container in a single command:
```bash
# Build multi-stage container
docker build -t placement-engine .
# Run on port 8000
docker run -p 8000:7860 placement-engine
```
Access the portal at `http://localhost:8000`.
---
## Verification & Testing
The system includes a test suite covering unit logic, property-based invariants, AST parsing, and end-to-end integration workflows.
```bash
# Run complete test suite (149 tests)
pytest backend/tests -v
# Run with test coverage report
pytest --cov=backend/app --cov-report=term-missing backend/tests
# Run performance benchmarks (1,800 students)
python scripts/benchmark_scheduler.py
```
### Test Coverage Highlights
- **149 / 149 Unit & Integration Tests Passing**: 100% pass rate.
- **Air-Gap Guardrails**: Asserts that sockets attempting outbound external internet communication raise strict security errors.
- **CP-SAT Invariant Tests**: Mathematically verifies that schedule collision count is strictly zero across randomized multi-panel configurations.
- **Property-Based Testing**: Uses `hypothesis` to test AST rule evaluation across synthetic permutations of CGPAs, branches, and backlog counts.
---
## Technology Stack
| Layer | Technology | Purpose |
| :--- | :--- | :--- |
| **Backend API** | FastAPI 0.115+, Python 3.13 | High-throughput async REST endpoints & static file serving |
| **Constraint Solver** | Google OR-Tools 9.11 (CP-SAT) | Discrete optimization for non-overlapping interview timetable |
| **Database** | SQLite 3 with WAL Mode | ACID persistence, concurrent reads, optimistic version locking |
| **ORM & Migrations** | SQLAlchemy 2.0, Alembic | Schema versioning and relational mapping |
| **Frontend UI** | React 18, Vite 6, TypeScript | Interactive SPA with role-based routing and dark theme |
| **Styling** | Tailwind CSS 3.4 | Custom luxury dark palette, glass surfaces, matching buttons |
| **Icons** | Lucide React | Consistent UI iconography |
| **Security** | Argon2id, Cryptography (Fernet) | Zero-telemetry password hashing and encrypted audit trails |
---
## Security & Privacy Guarantee
- **Zero Outbound Telemetry**: Strict socket interceptor ensures no analytics, CDN fonts, or telemetry are transmitted outside the machine.
- **FERPA & DPDP Ready**: Demographic and protected attributes are strictly decoupled from academic cut-off evaluation.
- **Tamper-Evident Event Log**: All overrides, version publishing, and roster modifications are cryptographically recorded in an append-only audit replay log.
- **CSRF & Session Protection**: Cryptographic double-submit cookie validation on all state-mutating requests (`POST`, `PUT`, `DELETE`).
---
## License
This project is licensed under the [MIT License](LICENSE).
|