| # Institutional Placement Engine Architecture (Core Engine) | |
| ## Executive Summary | |
| The Institutional Placement Engine is an air-gapped, zero-cloud system engineered to coordinate high-volume collegiate placement seasons. It provides deterministic academic eligibility evaluation, live institutional offer policy enforcement, NLP requirement extraction from announcement documents, constraint-based clash-free test/interview scheduling, and what-if impact simulation. | |
| --- | |
| ## 1. C4 Context Diagram | |
| ```mermaid | |
| flowchart TD | |
| Officer["Placement Officer<br>(Full Control, Policy Overrides, Publish)"] | |
| Coord["Student Coordinator<br>(Roster Import, Schedule View)"] | |
| Candidate["Student Candidate<br>(LAN Scoped View: Own Schedule & Status)"] | |
| Recruiter["Company Recruiter<br>(Read-Only: Company Shortlist & Panels)"] | |
| subgraph Institutional_LAN["Institutional Local Area Network (Air-Gapped)"] | |
| Engine["Campus Placement Engine<br>(FastAPI + React SPA on Port 8000)"] | |
| Database[("Encrypted Local SQLite<br>(WAL Mode, PRAGMA foreign_keys=ON)")] | |
| end | |
| Officer -->|"Administer Drives, Rules, Schedules"| Engine | |
| Coord -->|"Upload Rosters, Monitor Attendance"| Engine | |
| Candidate -->|"View Status & Personalized Schedule"| Engine | |
| Recruiter -->|"Download Shortlist & Interview Roster"| Engine | |
| Engine <-->|"Zero-Network Relational Persistence"| Database | |
| ``` | |
| --- | |
| ## 2. C4 Container Diagram | |
| ```mermaid | |
| flowchart LR | |
| subgraph Client_Tier["Client Tier (Browsers on Campus LAN)"] | |
| OfficerSPA["Officer Workspace SPA<br>(React 18 + Vite + Tailwind CSS)"] | |
| StudentSPA["Student Mobile Portal<br>(Responsive Single-Page App)"] | |
| end | |
| subgraph Application_Tier["Local Application Server (Port 8000)"] | |
| StaticServer["Static File Server<br>(Serves SPA App-Shell from /dist)"] | |
| AuthMiddleware["Argon2id Auth & Session Guard<br>(HttpOnly Cookies + CSRF)"] | |
| APIRouter["FastAPI REST API<br>(Pydantic Input Validation)"] | |
| subgraph Pure_Domain["Pure Domain Core (No I/O, Pure Logic)"] | |
| RuleEngine["AST Rule Evaluator<br>(Eligibility Evaluator)"] | |
| PolicyEngine["Offer Policy Checker<br>(Live Quota & Upgrades)"] | |
| SchedulerEngine["OR-Tools CP-SAT<br>(Constraint Scheduler)"] | |
| WhatIfEngine["What-If Impact Engine<br>(In-Memory Delta Engine)"] | |
| Extractor["Deterministic Extractor<br>(pdfplumber + regex)"] | |
| end | |
| RepoLayer["Repository & UoW Layer<br>(SQLAlchemy ORM Decoupled via Protocols)"] | |
| end | |
| subgraph Data_Tier["Encrypted Local Storage"] | |
| SQLiteDB[("SQLite Database<br>(AES-256 Encrypted Columns)")] | |
| EncBackups[("PBKDF2 Encrypted Backups<br>(.enc Archive)")] | |
| end | |
| OfficerSPA -->|"REST over LAN"| AuthMiddleware | |
| StudentSPA -->|"REST over LAN"| AuthMiddleware | |
| AuthMiddleware --> APIRouter | |
| APIRouter --> Pure_Domain | |
| Pure_Domain <--> RepoLayer | |
| RepoLayer <--> SQLiteDB | |
| RepoLayer -.->|"Encrypted Snapshot"| EncBackups | |
| ``` | |
| --- | |
| ## 3. Pure-Domain Architectural Blueprint | |
| The system strictly decouples business domain logic from infrastructure dependencies: | |
| ```mermaid | |
| flowchart TD | |
| subgraph Domain_Entities["Domain Models (Pydantic v2 Immutable Aggregates)"] | |
| Student["Student Aggregate<br>(Academics, Backlogs, Gaps, Offers)"] | |
| Drive["Drive Aggregate<br>(Company, CTC, Rounds, Panels)"] | |
| RuleSet["RuleSet AST<br>(CGPA, Backlogs, Branches, Age, Gaps)"] | |
| Policy["CollegeOfferPolicy<br>(Quotas, Dream Tiers, Multipliers)"] | |
| end | |
| subgraph Pure_Engines["Deterministic Functional Engines"] | |
| Evaluator["EligibilityEvaluator<br>evaluate(student, ruleset)"] | |
| Checker["policy_check<br>policy_check(student, drive, policy)"] | |
| Scheduler["PlacementSchedulerEngine<br>solve(drives, rooms, candidates)"] | |
| WhatIf["WhatIfEngine<br>apply_change(state, delta)"] | |
| end | |
| subgraph Results["Explainable Domain Verdicts"] | |
| Decision["DetailedEligibilityDecision<br>(Overall Verdict, Passed/Failed Rules, Hash)"] | |
| PolicyVerdict["PolicyCheckResult<br>(Status, Clause ID, Reason, What Unblocks)"] | |
| ScheduleGrid["ScheduleResult<br>(0 Clashes Verified, Grid Slots)"] | |
| Impact["ImpactReport<br>(Added/Removed, Dynamic Headline)"] | |
| end | |
| Student & RuleSet --> Evaluator --> Decision | |
| Student & Drive & Policy --> Checker --> PolicyVerdict | |
| Decision & PolicyVerdict --> Scheduler --> ScheduleGrid | |
| ScheduleGrid & PolicyVerdict --> WhatIf --> Impact | |
| ``` | |
| --- | |
| ## 4. Sequence Diagram: What-If Simulation Workflow | |
| Demonstrates how placement officers evaluate proposed cut-off or policy changes with instant in-memory feedback and zero database mutation: | |
| ```mermaid | |
| sequenceDiagram | |
| autonumber | |
| actor Officer as Placement Officer | |
| participant UI as What-If Panel (UI) | |
| participant API as FastAPI /api/what-if | |
| participant Engine as What-If Domain Engine | |
| participant AST as Rule Engine & Policy Checker | |
| participant DB as SQLite DB | |
| Officer->>UI: Adjusts CGPA cut-off (e.g. 7.0 -> 6.5) | |
| UI->>API: POST /api/what-if/preview (DriveId, Delta) | |
| API->>DB: Fetch current Student & Drive state | |
| DB-->>API: Active Domain Aggregates | |
| API->>Engine: apply_change(current_state, delta) | |
| Note over Engine: Pure in-memory simulation (No DB mutation) | |
| Engine->>AST: Re-evaluate affected candidate pool | |
| AST-->>Engine: Delta shortlists & offer policy impacts | |
| Engine->>Engine: Run minimal-disturbance clash check | |
| Engine->>Engine: Compute data-driven dynamic headline | |
| Engine-->>API: ImpactReport (Added, Removed, Clashes, Headline) | |
| API-->>UI: 200 OK (JSON Impact Report) | |
| UI-->>Officer: Displays "Lowering cut-off adds 38 students; 6 clash with Northwind" | |
| ``` | |
| --- | |
| ## 5. Sequence Diagram: Clash-Free Constraint Scheduling | |
| Demonstrates the OR-Tools CP-SAT constraint formulation solving 600 students across 12 drives in ~1 second: | |
| ```mermaid | |
| sequenceDiagram | |
| autonumber | |
| actor Officer as Placement Officer | |
| participant UI as Scheduler Workspace | |
| participant API as FastAPI /api/schedule | |
| participant Solver as PlacementSchedulerEngine (OR-Tools) | |
| participant Model as CP-SAT Constraint Model | |
| participant DB as SQLite DB | |
| Officer->>UI: Clicks "Generate Clash-Free Schedule" | |
| UI->>API: POST /api/schedule/run (DriveIds, RoomIds, Config) | |
| API->>DB: Query eligible candidates & room availability | |
| DB-->>API: Shortlisted Candidates, Rooms, Panels | |
| API->>Solver: build_and_solve(drives, rooms, candidates) | |
| Solver->>Model: Create Interval Variables (15-min slots) | |
| Solver->>Model: Add Room NoOverlap Constraints | |
| Solver->>Model: Add Panel NoOverlap Constraints | |
| Solver->>Model: Add Student NoOverlap Constraints (with walking buffer) | |
| Solver->>Model: Add Soft Objectives (Minimize waiting, balance panels) | |
| Solver->>Solver: Solve CP-SAT Model (deterministic offline) | |
| Solver-->>API: ScheduleResult (Feasible, 0 Clashes, 312 Scheduled Items) | |
| API->>DB: Persist Schedule & Slots (Draft Version) | |
| API-->>UI: 200 OK (Interactive Rooms x Time Grid) | |
| UI-->>Officer: Displays Schedule Board with "0 Clashes Verified" Badge | |
| ``` | |
| --- | |
| ## 6. Relational Database Schema (ERD) | |
| ```mermaid | |
| erDiagram | |
| STUDENTS ||--o{ ACADEMIC_RECORDS : "has" | |
| STUDENTS ||--o{ BACKLOGS : "has" | |
| STUDENTS ||--o{ GAP_YEARS : "has" | |
| STUDENTS ||--o{ OFFERS : "holds" | |
| STUDENTS ||--o{ ELIGIBILITY_DECISIONS : "evaluated" | |
| COMPANIES ||--o{ DRIVES : "conducts" | |
| DRIVES ||--o{ DRIVE_REQUIREMENT_VERSIONS : "versions" | |
| DRIVES ||--o{ PANELS : "hosts" | |
| DRIVES ||--o{ SCHEDULE_SLOTS : "includes" | |
| DRIVES ||--o{ ELIGIBILITY_DECISIONS : "receives" | |
| ROOMS ||--o{ SCHEDULE_SLOTS : "accommodates" | |
| SCHEDULES ||--o{ SCHEDULE_SLOTS : "contains" | |
| STUDENTS { | |
| string id PK | |
| string roll_no UK | |
| string name | |
| string email | |
| string branch | |
| string program | |
| float cgpa | |
| float tenth_percentage | |
| float twelfth_percentage | |
| float diploma_percentage | |
| date date_of_birth | |
| string gender_encrypted | |
| string caste_encrypted | |
| int version | |
| } | |
| ACADEMIC_RECORDS { | |
| string id PK | |
| string student_id FK | |
| int semester | |
| float sgpa | |
| } | |
| BACKLOGS { | |
| string id PK | |
| string student_id FK | |
| string subject | |
| int semester | |
| string status | |
| date cleared_on | |
| } | |
| OFFERS { | |
| string id PK | |
| string student_id FK | |
| string company | |
| float ctc_lpa | |
| float fixed_pay_lpa | |
| date offer_date | |
| string source | |
| string status | |
| boolean is_dream | |
| } | |
| DRIVES { | |
| string id PK | |
| string company_id FK | |
| string company_name | |
| date drive_date | |
| string mode | |
| float ctc_lpa | |
| boolean is_dream | |
| string status | |
| int version | |
| } | |
| SCHEDULE_SLOTS { | |
| string id PK | |
| string schedule_id FK | |
| string drive_id FK | |
| string room_id FK | |
| string student_id FK | |
| int round_number | |
| datetime start_time | |
| datetime end_time | |
| } | |
| ROOMS { | |
| string id PK | |
| string name | |
| string room_type | |
| int capacity | |
| boolean has_computers | |
| } | |
| ELIGIBILITY_DECISIONS { | |
| string id PK | |
| string student_id FK | |
| string drive_id FK | |
| string status | |
| string overall_student_reason | |
| string data_snapshot_hash | |
| datetime evaluated_at | |
| } | |
| ``` | |