# 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
    }
```