first commit

.github/workflows/backend-ci.yml

@@ -0,0 +1,82 @@
+name: Backend CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-ci.yml'
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-ci.yml'
+
+jobs:
+  lint-and-test:
+    name: Lint & Verify Backend
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: backend
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+          cache: 'pip'
+          cache-dependency-path: backend/requirements.txt
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install System Dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends build-essential libpq-dev
+
+      - name: Install Python Dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install ruff
+
+      - name: Generate Prisma Client
+        run: |
+          python -m prisma generate
+
+      - name: Run Ruff Linter
+        run: |
+          ruff check app/ main.py
+
+  docker-build:
+    name: Verify Docker Build
+    runs-on: ubuntu-latest
+    needs: lint-and-test
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker Image
+        uses: docker/build-push-action@v5
+        with:
+          context: backend
+          file: backend/Dockerfile
+          push: false
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.github/workflows/frontend-ci.yml

@@ -0,0 +1,46 @@
+name: Frontend CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-ci.yml'
+  pull_request:
+    branches:
+      - main
+      - master
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-ci.yml'
+
+jobs:
+  build:
+    name: Lint & Build Frontend
+    runs-on: ubuntu-latest
+
+    defaults:
+      run:
+        working-directory: frontend
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Run Linter
+        run: npm run lint
+
+      - name: Build Application
+        run: npm run build

.gitignore

@@ -0,0 +1,35 @@
+# OS Specific
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+desktop.ini
+
+# IDEs and Editors
+.vscode/
+!.vscode/extensions.json
+.idea/
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.swp
+*.swo
+*~
+.project
+.classpath
+.cproject
+.settings/
+
+# Logs
+logs/
+*.log
+
+# Local/Private
+.env
+.env.local
+.env.*.local
+.env*

README.md

@@ -0,0 +1,165 @@
+# Smart Attendance System
+
+An asynchronous, AI-powered multi-layered attendance verification system designed to eliminate buddy punching, proxy check-ins, and attendance fraud. The project consists of a FastAPI backend using TensorFlow/DeepFace, a Next.js web application for administration/teachers, and a Flutter mobile application for students.
+
+---
+
+## 🚀 Key Features
+
+### 1. Multi-Layered AI Verification
+To mark attendance, the student uploads a live selfie which undergoes three independent stages of verification:
+- **Facial Recognition**: Matches the student's live face embedding against their registered template using the **FaceNet** model (via **DeepFace**) with **128-dimensional** vector embeddings stored in PostgreSQL using `pgvector`.
+- **Liveness Detection**: Employs a custom-trained **MobileNetV2** model to check if the submission is a real person, preventing spoofing attempts using photos, videos, or masks.
+- **Background Validation**: Utilizes a custom **MobileNetV1** model to verify that the background of the image matches the expected classroom environment.
+
+### 2. Location & Geofencing
+- Verifies student's physical location against active class coordinates.
+- Teachers define geofenced regions (latitude, longitude, and radius in meters).
+- Submissions outside the geofence boundary are automatically flagged or rejected.
+
+### 3. Device Binding (Anti-Proxy)
+- Restricts each student account to a single mobile device.
+- Generates and binds a unique hardware UUID (`device_uuid`) on first login.
+- Students must submit a **Device Change Request** to be approved by administrators/teachers before they can log in on a new device.
+
+### 4. Real-time Communication & Notifications
+- Websocket-based live connection to push real-time attendance updates to teachers' dashboards.
+- Firebase Cloud Messaging (FCM) integration to dispatch push notifications for new sessions, reminders, and leave status updates.
+
+### 5. Gamification Suite
+- Encourages student attendance through engagement features including current/highest streaks, levels, leaderboards, and point systems.
+
+---
+
+## 🛠️ Technology Stack & Versions
+
+| Layer | Technology | Version / Specification | Key Libraries |
+| :--- | :--- | :--- | :--- |
+| **Backend** | Python 3.11 / FastAPI | `0.115.6` | Prisma ORM, TensorFlow `2.15.0`, DeepFace `0.0.93`, OpenCV `4.10.0`, Redis `5.2.1` |
+| **Frontend** | Next.js (React 19) | `16.2.6` | Tailwind CSS `4.x`, Recharts `3.8.1`, Zustand `5.0.13`, Leaflet Map `1.9.4` |
+| **Mobile** | Flutter SDK | `^3.8.0` | Riverpod `^2.6.1`, Dio `^5.7.0`, Geolocator `^13.0.2`, Hive `^2.2.3` |
+| **Database** | PostgreSQL | 15+ | `pgvector` extension enabled for biometric representations |
+
+---
+
+## 📂 Project Structure
+
+```
+.
+├── backend/            # FastAPI python application, database migrations, and AI models
+│   ├── app/            # Application source code (api, core, db, middleware, services, etc.)
+│   ├── models/         # Local folder for downloading/caching TF models
+│   ├── prisma/         # Prisma schema and seeding configurations
+│   └── main.py         # App entrypoint
+├── frontend/           # Next.js web application for admins and teachers
+│   ├── src/            # Next.js pages/components
+│   └── package.json    # Frontend dependency definitions
+└── mobile/             # Flutter student companion app
+    ├── lib/            # Flutter implementation source code
+    └── pubspec.yaml    # Flutter dependency configuration
+```
+
+---
+
+## ⚙️ Getting Started
+
+### Prerequisites
+1. **Python 3.11** installed on the host system.
+2. **Node.js 20+** and **npm** installed.
+3. **Flutter SDK (v3.8.x+)** and target development environment (Android/iOS simulator or physical device).
+4. **PostgreSQL** database with `pgvector` extension enabled.
+5. **Redis Server** running locally or accessible via network.
+6. A **HuggingFace** token (`HF_TOKEN`) to download pre-trained liveness & background models.
+
+---
+
+### 1. Backend Setup
+
+1. **Navigate to the directory**:
+   ```bash
+   cd backend
+   ```
+
+2. **Configure environment variables**:
+   Create a `.env` file by copying the template:
+   ```bash
+   cp .env.example .env
+   ```
+   Fill in the required fields (database connection strings, Redis URL, JWT Secret, and HF token if required).
+
+3. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+4. **Prepare the database (Prisma)**:
+   Ensure your PostgreSQL service is running and has the `pgvector` extension enabled, then run:
+   ```bash
+   python -m prisma db push
+   python -m prisma generate
+   ```
+
+5. **Seed the database (Optional)**:
+   ```bash
+   python prisma/seed.py
+   ```
+
+6. **Start the server**:
+   ```bash
+   uvicorn main:app --reload --port 8000
+   ```
+   Interactive API documentation will be available at [http://localhost:8000/docs](http://localhost:8000/docs).
+
+---
+
+### 2. Frontend Setup
+
+1. **Navigate to the directory**:
+   ```bash
+   cd frontend
+   ```
+
+2. **Configure environment variables**:
+   Ensure a `.env.local` file exists:
+   ```env
+   NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+4. **Start the development server**:
+   ```bash
+   npm run dev
+   ```
+   The dashboard will be running at [http://localhost:3000](http://localhost:3000).
+
+---
+
+### 3. Mobile Setup
+
+1. **Navigate to the directory**:
+   ```bash
+   cd mobile
+   ```
+
+2. **Get Flutter packages**:
+   ```bash
+   flutter pub get
+   ```
+
+3. **Run the application**:
+   Make sure you have an active emulator or connected device:
+   ```bash
+   flutter run
+   ```
+
+---
+
+## 🔒 Security & Verification Parameters
+The verification strictness can be controlled globally via the administrator settings page or in `.env`:
+* **Face Embedding matching threshold**: Standard threshold is configured to `0.75` (cosine similarity/confidence score).
+* **Liveness Detection threshold**: Values above `0.5` denote real face image inputs.
+* **Geofencing validation**: Distance calculated dynamically using the Haversine formula based on student's GPS reports and active class geofence boundaries.

backend/.env.example

@@ -0,0 +1,23 @@
+# Project Settings
+PROJECT_NAME="Smart Attendance System API"
+API_V1_STR="/api/v1"
+
+# Database Configuration
+# Replace with actual PostgreSQL connection credentials
+DATABASE_URL="postgresql://postgres:postgres@localhost:5432/smart_attendance?schema=public"
+
+# JWT Security
+# Generate a secure secret using: openssl rand -hex 32
+JWT_SECRET="supersecretkeychangeinproduction"
+JWT_ALGORITHM="HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES=1440
+
+# Redis Cache
+REDIS_URL="redis://localhost:6379/0"
+
+# AI Thresholds
+PASS_THRESHOLD=0.75
+
+# Environment (development / production)
+ENVIRONMENT="development"
+

backend/.gitignore

@@ -0,0 +1,66 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.flakes8
+.installed.cfg
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# Firebase & Secrets
+firebase-credentials.json
+google-services.json
+
+# Prisma
+prisma/client/
+*.db
+*.sqlite3
+
+# Logs
+logs/
+*.log
+
+# Project specific
+static/
+uploads/
+!static/.gitkeep
+!uploads/.gitkeep
+
+# AI/ML
+*.h5
+*.pb
+*.pt
+*.pth
+*.pkl
+*.joblib
+*.onnx
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/

backend/.python-version

@@ -0,0 +1 @@
+3.11

backend/app/__init__.py

@@ -0,0 +1,13 @@
+import sys
+
+try:
+    import tf_keras
+    import tensorflow as tf
+    import keras._tf_keras.keras.layers as compatibility_layers
+
+    compatibility_layers.LocallyConnected2D = tf_keras.layers.LocallyConnected2D
+    sys.modules["tensorflow.keras.layers.LocallyConnected2D"] = tf_keras.layers.LocallyConnected2D
+    tf.keras.layers.LocallyConnected2D = tf_keras.layers.LocallyConnected2D
+except Exception:
+    pass
+

backend/app/api/admin.py

@@ -0,0 +1,388 @@
+from functools import wraps
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from prisma.models import User
+
+from app.api.dependencies import RoleChecker, get_current_user
+from app.db.client import db
+from app.repositories.attendance_repo import AttendanceRepository
+from app.schemas.student import StudentCreate, StudentResponse, StudentUpdate
+from app.schemas.teacher import TeacherCreate, TeacherResponse, TeacherUpdate
+from app.schemas.admin import (
+    ClassCreate, ClassUpdate, ClassResponse, AssignTeacherRequest, EnrollRequest,
+    DepartmentCreate, DepartmentUpdate, DepartmentResponse,
+    AuditLogResponse, AdminStatsResponse, AdminResetPasswordRequest,
+)
+from app.schemas.master_data import (
+    SubjectCreate, SubjectUpdate, SubjectResponse,
+    ClassroomCreate, ClassroomUpdate, ClassroomResponse,
+    DesignationCreate, DesignationUpdate, DesignationResponse,
+)
+from app.services.admin_service import AdminService
+from app.services.absentee_scanner import run_absentee_scan
+
+admin_protection = Depends(RoleChecker(allowed_roles=["ADMIN"]))
+router = APIRouter(prefix="/admin", tags=["Admin System Operations"], dependencies=[admin_protection])
+
+
+def _get_client_ip(request: Request) -> str:
+    forwarded = request.headers.get("X-Forwarded-For")
+    if forwarded:
+        return forwarded.split(",")[0].strip()
+    return request.client.host if request.client else "unknown"
+
+
+def _handle_value_err(func):
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except ValueError as err:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=str(err))
+        except Exception as err:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+    return wrapper
+
+
+def _handle_generic_err(func):
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await func(*args, **kwargs)
+        except Exception as err:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+    return wrapper
+
+
+@router.post("/users/student", response_model=StudentResponse, status_code=status.HTTP_201_CREATED)
+@_handle_generic_err
+async def create_student(data: StudentCreate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.create_student(data, actor=current_user.email, ip=_get_client_ip(request))
+
+
+@router.post("/users/teacher", response_model=TeacherResponse, status_code=status.HTTP_201_CREATED)
+@_handle_generic_err
+async def create_teacher(data: TeacherCreate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.create_teacher(data, actor=current_user.email, ip=_get_client_ip(request))
+
+
+@router.post("/classes", response_model=ClassResponse, status_code=status.HTTP_201_CREATED)
+@_handle_value_err
+async def create_class(data: ClassCreate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.create_class(data, actor=current_user.email, ip=_get_client_ip(request))
+
+
+@router.put("/classes/{class_id}/assign-teacher", response_model=ClassResponse)
+@_handle_value_err
+async def assign_teacher(class_id: str, data: AssignTeacherRequest, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.assign_teacher(class_id=class_id, teacher_id=data.teacher_id, actor=current_user.email, ip=_get_client_ip(request))
+
+
+@router.post("/classes/{class_id}/enroll", status_code=status.HTTP_200_OK)
+@_handle_value_err
+async def enroll_students(class_id: str, data: EnrollRequest, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()) -> dict:
+    enrolled_count = await admin_service.enroll_students(class_id=class_id, student_ids=data.student_ids, actor=current_user.email, ip=_get_client_ip(request))
+    return {"status": "success", "enrolled_count": enrolled_count}
+
+
+@router.get("/users/students", response_model=list[StudentResponse])
+async def get_students(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_students()
+
+
+@router.get("/users/students/{id}", response_model=StudentResponse)
+async def get_student_by_id(id: str, admin_service: AdminService = Depends()):
+    student = await db.student.find_unique(where={"id": id}, include={"user": True, "department": True})
+    if not student:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
+    return StudentResponse(
+        id=student.id, user_id=student.userId, enrollment_number=student.enrollmentNumber,
+        email=student.user.email if student.user else "", first_name=student.firstName,
+        last_name=student.lastName, phone=student.phone, gender=student.gender,
+        date_of_birth=student.dateOfBirth, department_id=student.departmentId,
+        department_name=student.department.name if student.department else None,
+        semester=student.semester, batch=student.batch,
+    )
+
+
+@router.put("/users/students/{id}", response_model=StudentResponse)
+@_handle_generic_err
+async def update_student(id: str, data: StudentUpdate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.update_student(id, data.model_dump(exclude_unset=True), actor=current_user.email, ip=_get_client_ip(request))
+
+
+
+@router.get("/users/teachers", response_model=list[TeacherResponse])
+async def get_teachers(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_teachers()
+
+
+@router.get("/users/teachers/{id}", response_model=TeacherResponse)
+async def get_teacher_by_id(id: str):
+    teacher = await db.teacher.find_unique(where={"id": id}, include={"user": True, "department": True, "designation": True})
+    if not teacher:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Teacher not found")
+    return TeacherResponse(
+        id=teacher.id, user_id=teacher.userId, email=teacher.user.email if teacher.user else "",
+        employee_id=teacher.employeeId, first_name=teacher.firstName, last_name=teacher.lastName,
+        department_id=teacher.departmentId, designation_id=teacher.designationId,
+        department=teacher.department.name if teacher.department else "",
+        designation=teacher.designation.name if teacher.designation else "",
+        phone=teacher.phone, qualification=teacher.qualification, specialization=teacher.specialization,
+        experience_years=teacher.experienceYears, joining_date=teacher.joiningDate,
+    )
+
+
+@router.put("/users/teachers/{id}", response_model=TeacherResponse)
+@_handle_generic_err
+async def update_teacher(id: str, data: TeacherUpdate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.update_teacher(id, data.model_dump(exclude_unset=True), actor=current_user.email, ip=_get_client_ip(request))
+
+
+@router.put("/users/{user_id}/reset-password")
+async def reset_user_password(user_id: str, data: AdminResetPasswordRequest, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    try:
+        await admin_service.reset_user_password(user_id, data.new_password, actor=current_user.email, ip=_get_client_ip(request))
+        return {"status": "success", "message": "Password updated successfully"}
+    except ValueError as err:
+        raise HTTPException(status_code=404, detail=str(err))
+    except Exception as err:
+        raise HTTPException(status_code=400, detail=str(err))
+
+
+@router.get("/classes", response_model=list[ClassResponse])
+async def get_classes(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_classes()
+
+
+@router.get("/classes/{class_id}", response_model=ClassResponse)
+async def get_class_by_id(class_id: str, admin_service: AdminService = Depends()):
+    cls = await db.academicclass.find_unique(where={"id": class_id}, include={"subject": True, "classroom": True, "enrollments": True})
+    if not cls:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Class not found")
+    return ClassResponse(
+        id=cls.id, name=cls.name, subject_name=cls.subject.name if cls.subject else "",
+        subject_code=cls.subject.code if cls.subject else "", teacherId=cls.teacherId,
+        classroom_name=cls.classroom.name if cls.classroom else None,
+        semester=cls.semester, batch=cls.batch, max_students=cls.maxStudents,
+        enrolled_count=len(cls.enrollments) if cls.enrollments else 0,
+        enrolled_student_ids=[e.studentId for e in cls.enrollments] if cls.enrollments else [],
+    )
+
+
+@router.put("/classes/{class_id}", response_model=ClassResponse)
+@_handle_generic_err
+async def update_class(class_id: str, data: ClassUpdate, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    return await admin_service.update_class(class_id, data.model_dump(exclude_unset=True), actor=current_user.email, ip=_get_client_ip(request))
+
+
+# --- Departments ---
+@router.get("/departments", response_model=list[DepartmentResponse])
+async def get_departments(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_departments()
+
+
+@router.get("/departments/{id}", response_model=DepartmentResponse)
+async def get_department(id: str, admin_service: AdminService = Depends()):
+    dept = await admin_service.get_department_by_id(id)
+    if not dept:
+        raise HTTPException(status_code=404, detail="Department not found")
+    return dept
+
+
+@router.post("/departments", response_model=DepartmentResponse)
+@_handle_generic_err
+async def create_department(data: DepartmentCreate, admin_service: AdminService = Depends()):
+    return await admin_service.create_department(data.name, data.code, data.head, data.description)
+
+
+@router.put("/departments/{id}", response_model=DepartmentResponse)
+@_handle_generic_err
+async def update_department(id: str, data: DepartmentUpdate, admin_service: AdminService = Depends()):
+    return await admin_service.update_department(id, data.model_dump(exclude_unset=True))
+
+
+@router.delete("/departments/{id}")
+async def delete_department(id: str, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    try:
+        await admin_service.delete_department(id, actor=current_user.email, ip=_get_client_ip(request))
+        return {"status": "success"}
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(err))
+    except Exception:
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+# --- Subjects ---
+@router.get("/subjects", response_model=list[SubjectResponse])
+async def get_subjects(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_subjects()
+
+
+@router.get("/subjects/{id}", response_model=SubjectResponse)
+async def get_subject(id: str, admin_service: AdminService = Depends()):
+    sub = await admin_service.get_subject_by_id(id)
+    if not sub:
+        raise HTTPException(status_code=404, detail="Subject not found")
+    return sub
+
+
+@router.post("/subjects", response_model=SubjectResponse)
+@_handle_generic_err
+async def create_subject(data: SubjectCreate, admin_service: AdminService = Depends()):
+    return await admin_service.create_subject(data.name, data.code, data.description)
+
+
+@router.put("/subjects/{id}", response_model=SubjectResponse)
+@_handle_generic_err
+async def update_subject(id: str, data: SubjectUpdate, admin_service: AdminService = Depends()):
+    return await admin_service.update_subject(id, data.model_dump(exclude_unset=True))
+
+
+@router.delete("/subjects/{id}")
+async def delete_subject(id: str, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    try:
+        await admin_service.delete_subject(id, actor=current_user.email, ip=_get_client_ip(request))
+        return {"status": "success"}
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(err))
+    except Exception:
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+# --- Classrooms ---
+@router.get("/classrooms", response_model=list[ClassroomResponse])
+async def get_classrooms(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_classrooms()
+
+
+@router.get("/classrooms/{id}", response_model=ClassroomResponse)
+async def get_classroom(id: str, admin_service: AdminService = Depends()):
+    classroom = await admin_service.get_classroom_by_id(id)
+    if not classroom:
+        raise HTTPException(status_code=404, detail="Classroom not found")
+    return classroom
+
+
+@router.post("/classrooms", response_model=ClassroomResponse)
+@_handle_generic_err
+async def create_classroom(data: ClassroomCreate, admin_service: AdminService = Depends()):
+    return await admin_service.create_classroom(data.name, data.building, data.capacity)
+
+
+@router.put("/classrooms/{id}", response_model=ClassroomResponse)
+@_handle_generic_err
+async def update_classroom(id: str, data: ClassroomUpdate, admin_service: AdminService = Depends()):
+    return await admin_service.update_classroom(id, data.model_dump(exclude_unset=True))
+
+
+@router.delete("/classrooms/{id}")
+async def delete_classroom(id: str, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    try:
+        await admin_service.delete_classroom(id, actor=current_user.email, ip=_get_client_ip(request))
+        return {"status": "success"}
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(err))
+    except Exception:
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+# --- Designations ---
+@router.get("/designations", response_model=list[DesignationResponse])
+async def get_designations(admin_service: AdminService = Depends()):
+    return await admin_service.get_all_designations()
+
+
+@router.get("/designations/{id}", response_model=DesignationResponse)
+async def get_designation(id: str, admin_service: AdminService = Depends()):
+    desig = await admin_service.get_designation_by_id(id)
+    if not desig:
+        raise HTTPException(status_code=404, detail="Designation not found")
+    return desig
+
+
+@router.post("/designations", response_model=DesignationResponse)
+@_handle_generic_err
+async def create_designation(data: DesignationCreate, admin_service: AdminService = Depends()):
+    return await admin_service.create_designation(data.name, data.code, data.description)
+
+
+@router.put("/designations/{id}", response_model=DesignationResponse)
+@_handle_generic_err
+async def update_designation(id: str, data: DesignationUpdate, admin_service: AdminService = Depends()):
+    return await admin_service.update_designation(id, data.model_dump(exclude_unset=True))
+
+
+@router.delete("/designations/{id}")
+async def delete_designation(id: str, request: Request, current_user: User = Depends(get_current_user), admin_service: AdminService = Depends()):
+    try:
+        await admin_service.delete_designation(id, actor=current_user.email, ip=_get_client_ip(request))
+        return {"status": "success"}
+    except ValueError as err:
+        raise HTTPException(status_code=400, detail=str(err))
+    except Exception:
+        raise HTTPException(status_code=500, detail="Internal server error")
+
+
+# --- Misc Admin ---
+@router.get("/audit", response_model=list[AuditLogResponse])
+async def get_audit_logs(admin_service: AdminService = Depends()):
+    return await admin_service.get_audit_logs()
+
+
+@router.get("/stats", response_model=AdminStatsResponse)
+async def get_admin_stats(admin_service: AdminService = Depends()):
+    return await admin_service.get_stats()
+
+
+@router.post("/scan-absentees", status_code=status.HTTP_200_OK)
+async def scan_absentee_anomalies(
+    contamination: float = 0.10,
+    attendance_repo: AttendanceRepository = Depends(),
+) -> list[dict]:
+    records = await attendance_repo.get_all_absences()
+    if not records or len(records) < 5:
+        return []
+    
+    student_map = {}
+    for r in records:
+        if r.student:
+            first_name = r.student.firstName or ""
+            last_name = r.student.lastName or ""
+            full_name = f"{first_name} {last_name}".strip() or "Unknown Student"
+            student_map[r.studentId] = {
+                "student_name": full_name,
+                "enrollment_number": r.student.enrollmentNumber,
+            }
+
+    rows = [{"student_id": r.studentId, "status": r.status, "day_of_week": r.createdAt.strftime("%A")} for r in records]
+    try:
+        flagged = await run_absentee_scan(attendance_records=rows, contamination=contamination)
+        for item in flagged:
+            s_id = item.get("student_id")
+            s_info = student_map.get(s_id, {})
+            item["student_name"] = s_info.get("student_name", "Unknown Student")
+            item["enrollment_number"] = s_info.get("enrollment_number", "N/A")
+        return flagged
+    except Exception as err:
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"Outlier pattern extraction failed: {str(err)}")
+
+
+# --- System Config ---
+from app.schemas.system_config import SystemConfigResponse, SystemConfigUpdate
+from app.services.system_config_service import SystemConfigService
+
+@router.get("/config", response_model=SystemConfigResponse)
+async def get_system_config(config_service: SystemConfigService = Depends()):
+    return await config_service.get_config()
+
+
+@router.patch("/config", response_model=SystemConfigResponse)
+async def update_system_config(data: SystemConfigUpdate, config_service: SystemConfigService = Depends()):
+    return await config_service.update_config(
+        is_face_recognition_enabled=data.is_face_recognition_enabled,
+        is_gps_verification_enabled=data.is_gps_verification_enabled,
+        is_ai_background_validation_enabled=data.is_ai_background_validation_enabled,
+    )
+
+

backend/app/api/auth.py

@@ -0,0 +1,140 @@
+from datetime import datetime, timezone
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from prisma.models import User
+
+from app.api.dependencies import get_current_user, reusable_oauth2
+from app.core.config import settings
+from app.core.logging_config import get_logger
+from app.core.security import decode_access_token
+from app.db.client import db
+from app.db.redis import get_redis
+from app.repositories.student_repo import StudentRepository
+from app.schemas.auth import Token, UserLogin, UserProfileResponse, DeviceChangeRequestCreate
+from app.schemas.student import StudentCreate, StudentResponse
+from app.schemas.teacher import TeacherCreate, TeacherResponse
+from app.services.auth_service import AuthService
+from app.services.device_change_service import DeviceChangeService
+
+logger = get_logger("app.api.auth")
+
+router = APIRouter(prefix="/auth", tags=["Authentication"])
+
+_RATE_LIMIT_WINDOW = 60
+_RATE_LIMIT_MAX = 10
+
+
+async def _rate_limit(request: Request) -> None:
+    if settings.ENVIRONMENT == "development":
+        return
+    forwarded = request.headers.get("X-Forwarded-For")
+    ip = forwarded.split(",")[0].strip() if forwarded else (request.client.host if request.client else "unknown")
+    key = f"ratelimit:auth:{ip}"
+    r = await get_redis()
+    count = await r.incr(key)
+    if count == 1:
+        await r.expire(key, _RATE_LIMIT_WINDOW)
+    if count > _RATE_LIMIT_MAX:
+        raise HTTPException(status_code=status.HTTP_429_TOO_MANY_REQUESTS, detail="Too many requests. Please try again later.")
+
+
+@router.post("/login", response_model=Token)
+async def login(login_data: UserLogin, request: Request, auth_service: AuthService = Depends()) -> Token:
+    await _rate_limit(request)
+    token = await auth_service.authenticate(login_data)
+    if not token:
+        logger.warning("Failed login: %s", login_data.email)
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Incorrect email or password")
+    return token
+
+
+@router.post("/register/student", response_model=StudentResponse, status_code=status.HTTP_201_CREATED)
+async def register_student(data: StudentCreate, request: Request, auth_service: AuthService = Depends()) -> StudentResponse:
+    await _rate_limit(request)
+    student = await auth_service.register_student(data)
+    if not student:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="User with this email is already registered")
+    return student
+
+
+@router.post("/register/teacher", response_model=TeacherResponse, status_code=status.HTTP_201_CREATED)
+async def register_teacher(data: TeacherCreate, request: Request, auth_service: AuthService = Depends()) -> TeacherResponse:
+    await _rate_limit(request)
+    teacher = await auth_service.register_teacher(data)
+    if not teacher:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="User with this email is already registered")
+    return teacher
+
+
+@router.get("/me", response_model=UserProfileResponse)
+async def get_me(current_user: User = Depends(get_current_user)) -> UserProfileResponse:
+    student_profile = None
+    teacher_profile = None
+
+    if current_user.role == "STUDENT":
+        student = await db.student.find_unique(where={"userId": current_user.id})
+        if student:
+            embedding = await StudentRepository().get_face_embedding(student.id)
+            student_profile = {
+                "id": student.id,
+                "enrollment_number": student.enrollmentNumber,
+                "first_name": student.firstName,
+                "last_name": student.lastName,
+                "face_registered": embedding is not None and len(embedding) > 0,
+            }
+    elif current_user.role == "TEACHER":
+        teacher = await db.teacher.find_unique(where={"userId": current_user.id})
+        if teacher:
+            teacher_profile = {
+                "id": teacher.id,
+                "department": teacher.department.name if teacher.department else "",
+                "designation": teacher.designation.name if teacher.designation else "",
+                "employee_id": teacher.employeeId,
+                "first_name": teacher.firstName,
+                "last_name": teacher.lastName,
+            }
+
+    return UserProfileResponse(
+        id=current_user.id,
+        email=current_user.email,
+        role=current_user.role,
+        is_active=current_user.isActive,
+        student_profile=student_profile,
+        teacher_profile=teacher_profile,
+    )
+
+
+
+@router.post("/logout", status_code=status.HTTP_200_OK)
+async def logout(token: str = Depends(reusable_oauth2)) -> dict:
+    payload = decode_access_token(token)
+    if payload:
+        exp = payload.get("exp")
+        if exp:
+            ttl = exp - int(datetime.now(timezone.utc).timestamp())
+            if ttl > 0:
+                try:
+                    await get_redis().setex(f"denylist:{token}", ttl, "revoked")
+                    logger.info("Token revoked: user=%s", payload.get("sub"))
+                except Exception as cache_err:
+                    logger.warning("Failed to add token to Redis denylist: %s", cache_err)
+    return {"status": "success", "message": "Successfully logged out."}
+@router.post("/request-device-change", status_code=status.HTTP_200_OK)
+async def request_device_change(
+    data: DeviceChangeRequestCreate,
+    request: Request,
+    device_change_service: DeviceChangeService = Depends(),
+) -> dict:
+    await _rate_limit(request)
+    await device_change_service.request_device_change(data)
+    return {"status": "success", "message": "Device change request submitted successfully."}
+
+
+# --- System Config (Public) ---
+from app.schemas.system_config import SystemConfigResponse
+from app.services.system_config_service import SystemConfigService
+
+@router.get("/config", response_model=SystemConfigResponse)
+async def get_public_system_config(config_service: SystemConfigService = Depends()):
+    return await config_service.get_config()
+

backend/app/api/dependencies.py

@@ -0,0 +1,108 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from prisma.models import User, Student, Teacher
+
+from app.core.logging_config import get_logger
+from app.core.security import decode_access_token
+from app.repositories.user_repo import UserRepository
+from app.repositories.student_repo import StudentRepository
+from app.repositories.teacher_repo import TeacherRepository
+
+logger = get_logger("app.auth")
+
+reusable_oauth2 = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+
+_UNAUTHORIZED = HTTPException(status_code=status.HTTP_401_UNAUTHORIZED)
+_FORBIDDEN = {"STUDENT": "Access forbidden: Students only", "TEACHER": "Access forbidden: Teachers only"}
+_INACTIVE = "User account is inactive or disabled"
+
+
+async def _check_token_revoked(token: str) -> None:
+    try:
+        from app.db.redis import get_redis
+        if await get_redis().get(f"denylist:{token}"):
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Token has been revoked",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+    except HTTPException:
+        raise
+    except Exception:
+        pass
+
+
+async def _validate_token_payload(token: str) -> dict:
+    await _check_token_revoked(token)
+    payload = decode_access_token(token)
+    if not payload:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Could not validate credentials",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+    user_id = payload.get("sub")
+    if not user_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Subject not found in token",
+        )
+    return payload
+
+
+async def get_current_user(token: str = Depends(reusable_oauth2)) -> User:
+    payload = await _validate_token_payload(token)
+    user_id = payload.get("sub")
+    user = await UserRepository().get_by_id(user_id)
+    if not user or not user.isActive:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=_INACTIVE,
+        )
+    return user
+
+
+async def get_current_student(current_user: User = Depends(get_current_user)) -> Student:
+    if current_user.role != "STUDENT":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=_FORBIDDEN["STUDENT"])
+    student = await StudentRepository().get_by_user_id(current_user.id)
+    if not student:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student profile not found")
+    return student
+
+
+async def get_current_teacher(current_user: User = Depends(get_current_user)) -> Teacher:
+    if current_user.role != "TEACHER":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail=_FORBIDDEN["TEACHER"])
+    teacher = await TeacherRepository().get_by_user_id(current_user.id)
+    if not teacher:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Teacher profile not found")
+    return teacher
+
+
+class RoleChecker:
+    def __init__(self, allowed_roles: list[str]) -> None:
+        self.allowed_roles = allowed_roles
+
+    def __call__(self, current_user: User = Depends(get_current_user)) -> User:
+        if current_user.role not in self.allowed_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Access denied: Insufficient permissions",
+            )
+        return current_user
+
+
+async def get_current_user_from_token(token: str) -> User:
+    await _check_token_revoked(token)
+    payload = decode_access_token(token)
+    if not payload:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Could not validate credentials")
+    user_id = payload.get("sub")
+    if not user_id:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Subject not found in token")
+    user = await UserRepository().get_by_id(user_id)
+    if not user or not user.isActive:
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail=_INACTIVE)
+    return user
+

backend/app/api/logs.py

@@ -0,0 +1,20 @@
+import logging
+
+from fastapi import APIRouter, status
+
+from app.core.logging_config import get_logger
+from app.schemas.log import LogEvent
+
+router = APIRouter(prefix="/logs", tags=["Logging"])
+
+logger = get_logger("app.client")
+
+
+@router.post("", status_code=status.HTTP_200_OK)
+async def ingest_log(log_event: LogEvent) -> dict:
+    logger.log(
+        getattr(logging, log_event.level.upper(), logging.INFO),
+        "[%s] [%s] %s",
+        log_event.source, log_event.timestamp, log_event.message,
+    )
+    return {"status": "success"}

backend/app/api/student.py

@@ -0,0 +1,308 @@
+import os
+import uuid
+import shutil
+from datetime import datetime, timezone, date, timedelta
+
+from fastapi import APIRouter, Depends, HTTPException, UploadFile, File, Form, status
+from prisma.models import Student
+
+from app.api.dependencies import get_current_student
+from app.core.config import settings
+from app.core.logging_config import get_logger
+from app.core.security import create_access_token
+from app.db.client import db
+from app.repositories.leave_repo import LeaveRepository
+
+from app.schemas.attendance import AttendanceMarkResponse, AttendanceAnalyzeResponse
+from app.schemas.student import StudentAttendanceHistoryResponse, StudentClassResponse
+from app.schemas.leave import LeaveRequestResponse, LeaveRequestListResponse
+from app.services.attendance_service import AttendanceService, AttendanceSubmission
+from app.services.student_service import StudentService
+from app.services.gamification_service import GamificationService
+
+logger = get_logger("app.api.student")
+
+router = APIRouter(prefix="/student", tags=["Student Features"])
+
+_MAX_IMAGE_SIZE = 5 * 1024 * 1024
+_VALID_IMAGE_TYPES = {"image/jpeg", "image/png", "image/jpg"}
+
+
+def _save_uploaded_image(upload_file: UploadFile, folder: str) -> str:
+    target_dir = os.path.join(settings.UPLOAD_DIR, folder)
+    os.makedirs(target_dir, exist_ok=True)
+    ext = os.path.splitext(upload_file.filename or "")[1] or ".jpg"
+    target_path = os.path.join(target_dir, f"{uuid.uuid4()}{ext}")
+    with open(target_path, "wb") as buffer:
+        shutil.copyfileobj(upload_file.file, buffer)
+    return target_path
+
+
+
+def _validate_image(image: UploadFile) -> None:
+    if image.content_type not in _VALID_IMAGE_TYPES:
+        raise HTTPException(
+            status_code=status.HTTP_415_UNSUPPORTED_MEDIA_TYPE,
+            detail="Unsupported media type. Upload must be a valid JPEG or PNG image.",
+        )
+    if image.size is not None and image.size > _MAX_IMAGE_SIZE:
+        raise HTTPException(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            detail="Payload too large. Uploaded image cannot exceed 5MB.",
+        )
+
+
+def _make_leave_response(leave, student_name: str, enrollment_number: str = None) -> LeaveRequestResponse:
+    return LeaveRequestResponse(
+        id=leave.id,
+        student_id=leave.studentId,
+        student_name=student_name or "Unknown",
+        enrollment_number=enrollment_number or (leave.student.enrollmentNumber if leave.student else "N/A"),
+        start_date=leave.startDate,
+        end_date=leave.endDate,
+        reason=leave.reason,
+        document_url=leave.documentUrl,
+        status=leave.status,
+        approved_by=leave.approvedBy,
+        approver_note=leave.approverNote,
+        created_at=leave.createdAt,
+        updated_at=leave.updatedAt,
+    )
+
+
+def _student_name(student: Student) -> str:
+    if not student:
+        return "Unknown"
+    return f"{student.firstName or ''} {student.lastName or ''}".strip()
+
+
+@router.post("/attendance/mark", response_model=AttendanceMarkResponse)
+async def mark_attendance(
+    session_id: str = Form(...),
+    latitude: float = Form(...),
+    longitude: float = Form(...),
+    accuracy: float = Form(...),
+    image: UploadFile | None = File(None),
+    student: Student = Depends(get_current_student),
+    attendance_service: AttendanceService = Depends(),
+) -> AttendanceMarkResponse:
+    image_path = None
+    if image:
+        _validate_image(image)
+        image_path = _save_uploaded_image(image, "attendance")
+    submission = AttendanceSubmission(
+        student_id=student.id, session_id=session_id,
+        latitude=latitude, longitude=longitude, accuracy=accuracy, image_path=image_path,
+    )
+    try:
+        attendance = await attendance_service.mark_attendance(submission)
+        return AttendanceMarkResponse.model_validate(attendance)
+    except ValueError as err:
+        if image_path and os.path.exists(image_path):
+            os.remove(image_path)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+
+
+@router.post("/attendance/analyze", response_model=AttendanceAnalyzeResponse)
+async def analyze_attendance(
+    session_id: str = Form(...),
+    latitude: float = Form(...),
+    longitude: float = Form(...),
+    accuracy: float = Form(...),
+    image: UploadFile | None = File(None),
+    student: Student = Depends(get_current_student),
+    attendance_service: AttendanceService = Depends(),
+) -> AttendanceAnalyzeResponse:
+    """Run AI scoring and validation without saving the attendance record.
+
+    Returns scores and a short-lived review_token (5 min) that the student
+    can use to confirm submission via POST /attendance/confirm.
+    """
+    image_path = None
+    if image:
+        _validate_image(image)
+        image_path = _save_uploaded_image(image, "attendance")
+    submission = AttendanceSubmission(
+        student_id=student.id, session_id=session_id,
+        latitude=latitude, longitude=longitude, accuracy=accuracy, image_path=image_path,
+    )
+    try:
+        result = await attendance_service.analyze_attendance(submission)
+        return AttendanceAnalyzeResponse(**result)
+    except ValueError as err:
+        if image_path and os.path.exists(image_path):
+            os.remove(image_path)
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+
+
+@router.post("/attendance/confirm", response_model=AttendanceMarkResponse)
+async def confirm_attendance(
+    review_token: str = Form(...),
+    student: Student = Depends(get_current_student),
+    attendance_service: AttendanceService = Depends(),
+) -> AttendanceMarkResponse:
+    """Confirm a previously analyzed attendance submission.
+
+    Accepts the review_token returned by POST /attendance/analyze and saves
+    the attendance record without re-running AI inference.
+    """
+    try:
+        attendance = await attendance_service.confirm_attendance(student.id, review_token)
+        return AttendanceMarkResponse.model_validate(attendance)
+    except ValueError as err:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+
+
+@router.post("/register-face", status_code=status.HTTP_200_OK)
+async def register_face(
+    image: UploadFile = File(...),
+    student: Student = Depends(get_current_student),
+    attendance_service: AttendanceService = Depends(),
+) -> dict:
+    _validate_image(image)
+    image_path = _save_uploaded_image(image, "registration")
+    try:
+        success = await attendance_service.register_face(student.id, image_path)
+        if not success:
+            raise ValueError("Could not extract a valid face from the image.")
+        return {"status": "success", "message": "Face embedding registered successfully."}
+    except ValueError as err:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=str(err))
+    finally:
+        if os.path.exists(image_path):
+            os.remove(image_path)
+
+
+@router.get("/my-attendance", response_model=StudentAttendanceHistoryResponse)
+async def get_my_attendance(
+    student: Student = Depends(get_current_student),
+    student_service: StudentService = Depends(),
+) -> StudentAttendanceHistoryResponse:
+    return await student_service.get_student_attendance_history(student.userId)
+
+
+@router.get("/classes", response_model=list[StudentClassResponse])
+async def get_my_classes(
+    student: Student = Depends(get_current_student),
+    student_service: StudentService = Depends(),
+) -> list[StudentClassResponse]:
+    return await student_service.get_student_classes(student.userId)
+
+
+@router.post("/fcm-token", status_code=status.HTTP_200_OK)
+async def register_fcm_token(
+    payload: dict,
+    student: Student = Depends(get_current_student),
+) -> dict:
+    token = payload.get("token")
+    if not token:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="FCM token is required.")
+    await db.student.update(where={"id": student.id}, data={"fcmToken": token})
+    return {"status": "success", "message": "FCM token registered."}
+
+
+@router.post("/attendance/{attendance_id}/note", status_code=status.HTTP_200_OK)
+async def submit_flagged_note(
+    attendance_id: str,
+    payload: dict,
+    student: Student = Depends(get_current_student),
+) -> dict:
+    note = payload.get("note", "").strip()
+    if not note:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Note cannot be empty.")
+    if len(note) > 500:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Note cannot exceed 500 characters.")
+    record = await db.attendance.find_unique(where={"id": attendance_id})
+    if not record or record.studentId != student.id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Attendance record not found.")
+    if record.status != "Flagged":
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Notes can only be added to flagged records.")
+    await db.attendance.update(where={"id": attendance_id}, data={"studentNote": note})
+    return {"status": "success", "message": "Note submitted successfully."}
+
+
+@router.get("/leaves", response_model=LeaveRequestListResponse)
+async def get_my_leaves(
+    student: Student = Depends(get_current_student),
+    leave_repo: LeaveRepository = Depends(),
+) -> LeaveRequestListResponse:
+    leaves = await leave_repo.get_by_student_id(student.id)
+    leave_responses = [_make_leave_response(req, _student_name(req.student)) for req in leaves]
+    return LeaveRequestListResponse(
+        leaves=leave_responses,
+        total=len(leave_responses),
+        pending=sum(1 for req in leaves if req.status == "PENDING"),
+        approved=sum(1 for req in leaves if req.status == "APPROVED"),
+        rejected=sum(1 for req in leaves if req.status == "REJECTED"),
+    )
+
+
+@router.post("/leaves", response_model=LeaveRequestResponse, status_code=status.HTTP_201_CREATED)
+async def create_leave_request(
+    start_date: str = Form(...),
+    end_date: str = Form(...),
+    reason: str = Form(...),
+    document: UploadFile = File(None),
+    student: Student = Depends(get_current_student),
+    leave_repo: LeaveRepository = Depends(),
+) -> LeaveRequestResponse:
+    try:
+        s_date = date.fromisoformat(start_date)
+        e_date = date.fromisoformat(end_date)
+    except ValueError:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Invalid date format. Use YYYY-MM-DD.")
+    if e_date < s_date:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="End date must be after or equal to start date.")
+    if len(reason) < 10 or len(reason) > 500:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Reason must be between 10 and 500 characters.")
+
+    document_url = None
+    if document and document.filename:
+        try:
+            upload_dir = "static/leaves"
+            os.makedirs(upload_dir, exist_ok=True)
+            ext = os.path.splitext(document.filename)[1]
+            filename = f"leave_{student.id}_{int(datetime.now().timestamp())}{ext}"
+            file_path = os.path.join(upload_dir, filename)
+            with open(file_path, "wb") as f:
+                f.write(await document.read())
+            document_url = f"/static/leaves/{filename}"
+        except Exception:
+            raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="Could not save leave document.")
+
+    leave = await leave_repo.create({
+        "studentId": student.id,
+        "startDate": datetime.combine(s_date, datetime.min.time()).replace(tzinfo=timezone.utc),
+        "endDate": datetime.combine(e_date, datetime.max.time()).replace(tzinfo=timezone.utc),
+        "reason": reason,
+        "documentUrl": document_url,
+        "status": "PENDING",
+    })
+    return _make_leave_response(leave, _student_name(student), student.enrollmentNumber)
+
+
+@router.get("/smart-pass", response_model=dict)
+async def get_smart_pass(student: Student = Depends(get_current_student)) -> dict:
+    qr_token = create_access_token(
+        subject=student.userId,
+        role="STUDENT",
+        expires_delta=timedelta(seconds=30),
+        extra_data={"student_id": student.id, "enrollment_number": student.enrollmentNumber, "type": "smart_pass"},
+    )
+    return {
+        "qr_token": qr_token,
+        "expires_at": (datetime.now(timezone.utc) + timedelta(seconds=30)).isoformat(),
+        "student_name": _student_name(student),
+        "enrollment_number": student.enrollmentNumber,
+    }
+
+
+@router.get("/stats", response_model=dict)
+async def get_my_stats(student: Student = Depends(get_current_student)) -> dict:
+    return await GamificationService().get_student_stats(student.id)
+
+
+@router.get("/leaderboard", response_model=dict)
+async def get_leaderboard(student: Student = Depends(get_current_student)) -> dict:
+    return await GamificationService().get_leaderboard(student.id)
+

backend/app/api/teacher.py

@@ -0,0 +1,247 @@
+from datetime import datetime
+from typing import Optional
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from prisma.models import Teacher
+
+from app.api.dependencies import get_current_teacher
+from app.db.client import db
+from app.repositories.attendance_repo import AttendanceRepository
+from app.repositories.leave_repo import LeaveRepository
+from app.schemas.teacher import (
+    SessionResponse, SessionStart, GeofenceUpsert, GeofenceResponse,
+    AcademicClassWithGeofenceResponse, SessionAttendanceResponse,
+    ClassStatsResponse, AttendanceManualOverride, SessionWithClassResponse,
+    BulkMarkRequest, AbsentStudentItem, DeviceChangeResponse, DeviceChangeApprove
+)
+from app.schemas.attendance import AttendanceReview, FlaggedAttendanceResponse
+from app.schemas.leave import LeaveRequestResponse, LeaveRequestApprove
+from app.services.session_service import SessionService
+from app.services.attendance_service import AttendanceService
+from app.services.teacher_service import TeacherService
+from app.services.leave_service import LeaveService
+from app.services.device_change_service import DeviceChangeService
+
+router = APIRouter(prefix="/teacher", tags=["Teacher Features"])
+
+
+def _make_leave_response(leave) -> LeaveRequestResponse:
+    name = f"{leave.student.firstName or ''} {leave.student.lastName or ''}".strip()
+    return LeaveRequestResponse(
+        id=leave.id, student_id=leave.studentId, student_name=name or "Unknown",
+        enrollment_number=leave.student.enrollmentNumber,
+        start_date=leave.startDate, end_date=leave.endDate, reason=leave.reason,
+        document_url=leave.documentUrl, status=leave.status, approved_by=leave.approvedBy,
+        approver_note=leave.approverNote, created_at=leave.createdAt, updated_at=leave.updatedAt,
+    )
+
+
+@router.post("/sessions/start", response_model=SessionResponse)
+async def start_session(
+    data: SessionStart,
+    teacher: Teacher = Depends(get_current_teacher),
+    session_service: SessionService = Depends(),
+) -> SessionResponse:
+    session = await session_service.start_session(data, teacher.id)
+    if not session:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Could not open session. Class not found or unauthorized.")
+    return session
+
+
+@router.post("/sessions/{id}/stop", status_code=status.HTTP_200_OK)
+async def stop_session(
+    id: str,
+    teacher: Teacher = Depends(get_current_teacher),
+    session_service: SessionService = Depends(),
+) -> dict:
+    if not await session_service.stop_session(id, teacher.id):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Session not found, already stopped, or unauthorized.")
+    return {"status": "success", "message": "Session closed successfully."}
+
+
+@router.get("/attendance/flagged", response_model=list[FlaggedAttendanceResponse])
+async def get_flagged_attendance(
+    teacher: Teacher = Depends(get_current_teacher),
+    attendance_repo: AttendanceRepository = Depends(),
+) -> list[FlaggedAttendanceResponse]:
+    classes = await db.academicclass.find_many(where={"teacherId": teacher.id})
+    my_class_ids = [c.id for c in classes]
+    records = await db.attendance.find_many(
+        where={"status": "Flagged", "session": {"is": {"academicClassId": {"in": my_class_ids}}}},
+        include={
+            "student": {"include": {"user": True}},
+            "session": {"include": {"academicClass": {"include": {"subject": True}}}},
+        },
+    )
+    return [
+        FlaggedAttendanceResponse(
+            id=r.id,
+            enrollment_number=r.student.enrollmentNumber if r.student else "N/A",
+            student_name=(
+                f"{r.student.firstName or ''} {r.student.lastName or ''}".strip()
+                if r.student else "Unknown Student"
+            ),
+            class_name=ac.subject.name if (ac := r.session.academicClass if r.session else None) and ac.subject else (ac.name if ac else "N/A"),
+            subject=ac.subject.name if ac and ac.subject else (ac.name if ac else "N/A"),
+            face_score=r.faceScore, liveness_score=r.livenessScore,
+            background_score=r.backgroundScore, final_ai_score=r.finalAiScore,
+            gps_latitude=r.gpsLatitude, gps_longitude=r.gpsLongitude,
+            created_at=r.createdAt,
+            student_note=r.studentNote,
+        )
+        for r in records
+    ]
+
+
+@router.get("/attendance/{id}", response_model=FlaggedAttendanceResponse)
+async def get_attendance_by_id(id: str, attendance_repo: AttendanceRepository = Depends()):
+    r = await attendance_repo.get_by_id(id)
+    if not r:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Attendance record not found")
+    ac = r.session.academicClass if r.session else None
+    return FlaggedAttendanceResponse(
+        id=r.id, enrollment_number=r.student.enrollmentNumber if r.student else "N/A",
+        student_name=(f"{r.student.firstName or ''} {r.student.lastName or ''}".strip() if r.student else "Unknown Student"),
+        class_name=ac.name if ac else "N/A", subject=ac.subject.name if ac and ac.subject else (ac.name if ac else "N/A"),
+        face_score=r.faceScore, liveness_score=r.livenessScore,
+        background_score=r.backgroundScore, final_ai_score=r.finalAiScore,
+        gps_latitude=r.gpsLatitude, gps_longitude=r.gpsLongitude, created_at=r.createdAt,
+        student_note=r.studentNote,
+    )
+
+
+@router.put("/attendance/{id}/review", status_code=status.HTTP_200_OK)
+async def review_flagged_attendance(
+    id: str,
+    review: AttendanceReview,
+    teacher: Teacher = Depends(get_current_teacher),
+    attendance_service: AttendanceService = Depends(),
+) -> dict:
+    if not await attendance_service.review_attendance(attendance_id=id, status=review.status, remarks=review.remarks):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Attendance record not found, is not currently flagged, or review failed.")
+    return {"status": "success", "message": f"Attendance record has been {review.status}."}
+
+
+@router.get("/my-classes", response_model=list[AcademicClassWithGeofenceResponse])
+async def get_my_classes(
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> list[AcademicClassWithGeofenceResponse]:
+    return await teacher_service.get_classes_by_teacher_user_id(teacher.userId)
+
+
+@router.post("/classes/{class_id}/geofence", response_model=GeofenceResponse)
+async def upsert_geofence(
+    class_id: str, data: GeofenceUpsert,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> GeofenceResponse:
+    return await teacher_service.upsert_geofence(user_id=teacher.userId, class_id=class_id, data=data)
+
+
+@router.get("/sessions/{session_id}/attendance", response_model=SessionAttendanceResponse)
+async def get_session_attendance(
+    session_id: str,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> SessionAttendanceResponse:
+    return await teacher_service.get_session_attendance_roster(user_id=teacher.userId, session_id=session_id)
+
+
+@router.get("/classes/{class_id}/stats", response_model=ClassStatsResponse)
+async def get_class_stats(
+    class_id: str,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> ClassStatsResponse:
+    return await teacher_service.get_class_stats(user_id=teacher.userId, class_id=class_id)
+
+
+@router.post("/sessions/{session_id}/override", status_code=status.HTTP_200_OK)
+async def manual_override_attendance(
+    session_id: str, data: AttendanceManualOverride,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> dict:
+    if not await teacher_service.manual_override_attendance(user_id=teacher.userId, session_id=session_id, student_id=data.student_id, status_val=data.status):
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Failed to apply attendance manual override.")
+    return {"status": "success", "message": f"Attendance overridden to {data.status}."}
+
+
+@router.get("/sessions/all", response_model=list[SessionWithClassResponse])
+async def get_teacher_sessions(
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> list[SessionWithClassResponse]:
+    return await teacher_service.get_teacher_sessions(user_id=teacher.userId)
+
+
+@router.get("/sessions/{session_id}/absent-students", response_model=list[AbsentStudentItem])
+async def get_absent_students(
+    session_id: str,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> list[AbsentStudentItem]:
+    return await teacher_service.get_absent_students(session_id=session_id, user_id=teacher.userId)
+
+
+@router.post("/sessions/{session_id}/mark-bulk", status_code=status.HTTP_200_OK)
+async def bulk_mark_attendance(
+    session_id: str, data: BulkMarkRequest,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> dict:
+    count = await teacher_service.bulk_mark_attendance(session_id=session_id, user_id=teacher.userId, request=data)
+    return {"status": "success", "count": count}
+
+
+@router.get("/classes/{class_id}/export-attendance", response_model=list[dict])
+async def export_class_attendance(
+    class_id: str,
+    from_date: Optional[datetime] = None,
+    to_date: Optional[datetime] = None,
+    teacher: Teacher = Depends(get_current_teacher),
+    teacher_service: TeacherService = Depends(),
+) -> list[dict]:
+    return await teacher_service.export_class_attendance(class_id=class_id, user_id=teacher.userId, from_date=from_date, to_date=to_date)
+
+
+@router.get("/leaves/pending", response_model=list[LeaveRequestResponse])
+async def get_pending_leaves(
+    teacher: Teacher = Depends(get_current_teacher),
+    leave_repo: LeaveRepository = Depends(),
+) -> list[LeaveRequestResponse]:
+    return [_make_leave_response(leave) for leave in await leave_repo.get_pending_for_teacher(teacher.id)]
+
+
+@router.put("/leaves/{leave_id}/approve", status_code=status.HTTP_200_OK)
+async def approve_leave(
+    leave_id: str, data: LeaveRequestApprove,
+    teacher: Teacher = Depends(get_current_teacher),
+    leave_service: LeaveService = Depends(),
+) -> dict:
+    result = await leave_service.approve_leave(leave_id=leave_id, teacher_id=teacher.id, status=data.status, approver_note=data.approver_note)
+    if not result:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Leave request not found.")
+    return {"status": "success", "message": f"Leave request {data.status.lower()} successfully."}
+
+
+@router.get("/device-changes/pending", response_model=list[DeviceChangeResponse])
+async def get_pending_device_changes(
+    teacher: Teacher = Depends(get_current_teacher),
+    device_change_service: DeviceChangeService = Depends(),
+) -> list[DeviceChangeResponse]:
+    return await device_change_service.get_pending_requests(teacher_id=teacher.id)
+
+
+@router.put("/device-changes/{request_id}/approve", status_code=status.HTTP_200_OK)
+async def approve_device_change(
+    request_id: str, data: DeviceChangeApprove,
+    teacher: Teacher = Depends(get_current_teacher),
+    device_change_service: DeviceChangeService = Depends(),
+) -> dict:
+    result = await device_change_service.approve_request(request_id=request_id, teacher_id=teacher.id, new_status=data.status)
+    if not result:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Device change request not found or not pending.")
+    return {"status": "success", "message": f"Device change request {data.status.lower()} successfully."}
+

backend/app/api/ws.py

@@ -0,0 +1,177 @@
+import asyncio
+import json
+from typing import Dict, Set
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+from app.api.dependencies import get_current_user_from_token
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.websocket")
+
+router = APIRouter(prefix="/ws", tags=["WebSocket"])
+
+_PING_INTERVAL = 25
+_PONG_TIMEOUT = 15
+
+
+class ConnectionManager:
+    def __init__(self):
+        self.student_connections: Dict[str, Set[WebSocket]] = {}
+        self.teacher_connections: Dict[str, Set[WebSocket]] = {}
+        self._heartbeat_task: asyncio.Task | None = None
+
+    async def connect_student(self, websocket: WebSocket, student_id: str):
+        await websocket.accept()
+        self.student_connections.setdefault(student_id, set()).add(websocket)
+        logger.info("WebSocket student connected: %s", student_id)
+
+    async def connect_teacher(self, websocket: WebSocket, teacher_id: str):
+        await websocket.accept()
+        self.teacher_connections.setdefault(teacher_id, set()).add(websocket)
+        logger.info("WebSocket teacher connected: %s", teacher_id)
+
+    def disconnect(self, websocket: WebSocket, user_type: str, user_id: str):
+        connections = self.student_connections if user_type == "student" else self.teacher_connections
+        if user_id in connections:
+            connections[user_id].discard(websocket)
+            if not connections[user_id]:
+                del connections[user_id]
+        logger.info("WebSocket %s disconnected: %s", user_type, user_id)
+
+    async def send_personal_message(self, message: dict, student_id: str):
+        conns = self.student_connections.get(student_id)
+        if not conns:
+            return
+        disconnected = set()
+        for connection in conns:
+            try:
+                await connection.send_json(message)
+            except Exception as e:
+                logger.warning("Failed to send message to %s: %s", student_id, e)
+                disconnected.add(connection)
+        for conn in disconnected:
+            self.student_connections[student_id].discard(conn)
+
+    async def broadcast_to_teachers(self, message: dict):
+        disconnected = set()
+        for teacher_id, conns in self.teacher_connections.items():
+            for conn in conns:
+                try:
+                    await conn.send_json(message)
+                except Exception as e:
+                    logger.warning("Failed to send to teacher %s: %s", teacher_id, e)
+                    disconnected.add(conn)
+        for conn in disconnected:
+            for teacher_id, conns in self.teacher_connections.items():
+                conns.discard(conn)
+                if not conns:
+                    del self.teacher_connections[teacher_id]
+
+    async def _heartbeat_loop(self):
+        while True:
+            await asyncio.sleep(_PING_INTERVAL)
+            ping = {"type": "ping"}
+            disconnected = set()
+
+            for sid, conns in list(self.student_connections.items()):
+                for conn in list(conns):
+                    try:
+                        await asyncio.wait_for(
+                            conn.send_json(ping), timeout=_PONG_TIMEOUT
+                        )
+                    except Exception:
+                        disconnected.add((conn, "student", sid))
+
+            for tid, conns in list(self.teacher_connections.items()):
+                for conn in list(conns):
+                    try:
+                        await asyncio.wait_for(
+                            conn.send_json(ping), timeout=_PONG_TIMEOUT
+                        )
+                    except Exception:
+                        disconnected.add((conn, "teacher", tid))
+
+            for conn, utype, uid in disconnected:
+                self.disconnect(conn, utype, uid)
+
+            if disconnected:
+                logger.info(
+                    "Heartbeat cleaned %d stale connections", len(disconnected)
+                )
+
+    def start_heartbeat(self):
+        if self._heartbeat_task is None:
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+            logger.info("WebSocket heartbeat started")
+
+    def stop_heartbeat(self):
+        if self._heartbeat_task is not None:
+            self._heartbeat_task.cancel()
+            self._heartbeat_task = None
+            logger.info("WebSocket heartbeat stopped")
+
+    @property
+    def total_connections(self) -> int:
+        student_count = sum(len(c) for c in self.student_connections.values())
+        teacher_count = sum(len(c) for c in self.teacher_connections.values())
+        return student_count + teacher_count
+
+manager = ConnectionManager()
+
+
+@router.websocket("/connect")
+async def websocket_endpoint(websocket: WebSocket):
+    try:
+        await websocket.accept()
+        auth_data = await websocket.receive_text()
+        auth_json = json.loads(auth_data)
+
+        if auth_json.get("type") != "auth" or not auth_json.get("token"):
+            await websocket.close(code=1008, reason="Authentication required")
+            return
+
+        user = await get_current_user_from_token(auth_json["token"])
+        if not user:
+            await websocket.close(code=1008, reason="Unauthorized")
+            return
+
+        if user.role == "STUDENT" and user.student:
+            student_id = user.student.id
+            await manager.connect_student(websocket, student_id)
+            await websocket.send_json({"type": "connected", "message": "WebSocket connection established", "user_id": student_id, "role": "student"})
+            try:
+                while True:
+                    data = await asyncio.wait_for(websocket.receive_text(), timeout=_PING_INTERVAL)
+                    if data == "ping":
+                        await websocket.send_json({"type": "pong"})
+            except asyncio.TimeoutError:
+                logger.info("WebSocket ping timeout for student %s", student_id)
+            except WebSocketDisconnect:
+                manager.disconnect(websocket, "student", student_id)
+
+        elif user.role == "TEACHER" and user.teacher:
+            teacher_id = user.teacher.id
+            await manager.connect_teacher(websocket, teacher_id)
+            await websocket.send_json({"type": "connected", "message": "WebSocket connection established", "user_id": teacher_id, "role": "teacher"})
+            try:
+                while True:
+                    data = await asyncio.wait_for(websocket.receive_text(), timeout=_PING_INTERVAL)
+                    if data == "ping":
+                        await websocket.send_json({"type": "pong"})
+            except asyncio.TimeoutError:
+                logger.info("WebSocket ping timeout for teacher %s", teacher_id)
+            except WebSocketDisconnect:
+                manager.disconnect(websocket, "teacher", teacher_id)
+
+        else:
+            await websocket.close(code=1008, reason="Unauthorized: Student or Teacher profile required")
+
+    except Exception as e:
+        logger.error("WebSocket error: %s", e, exc_info=True)
+        try:
+            await websocket.close(code=1011, reason="Internal server error")
+        except Exception:
+            pass
+
+

backend/app/core/config.py

@@ -0,0 +1,41 @@
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore"
+    )
+
+    PROJECT_NAME: str = "Smart Attendance System API"
+    API_V1_STR: str = "/api/v1"
+    DATABASE_URL: str = "postgresql://postgres:postgres@localhost:5432/smart_attendance"
+    JWT_SECRET: str = Field(default="", description="JWT signing secret (must be set via JWT_SECRET env var)")
+
+    @field_validator("JWT_SECRET")
+    @classmethod
+    def jwt_secret_must_be_set(cls, v: str) -> str:
+        if not v:
+            raise ValueError(
+                "JWT_SECRET environment variable is required. "
+                "Set it in your .env file for security."
+            )
+        return v
+
+    JWT_ALGORITHM: str = "HS256"
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 1440
+    REDIS_URL: str = "redis://localhost:6379/0"
+    UPLOAD_DIR: str = "static"
+    FACE_WEIGHT: float = 0.50
+    LIVENESS_WEIGHT: float = 0.30
+    BACKGROUND_WEIGHT: float = 0.20
+    PASS_THRESHOLD: float = 0.75
+    FRONTEND_URL: str = Field(default="http://localhost:3000", description="Frontend URL for CORS")
+    ENVIRONMENT: str = "development"
+    LOG_LEVEL: str = Field(default="DEBUG", description="Logging level: DEBUG, INFO, WARNING, ERROR, CRITICAL")
+
+
+settings = Settings()
+

backend/app/core/logging_config.py

@@ -0,0 +1,37 @@
+import logging
+
+_SILENCED_LOGGERS = [
+    "uvicorn.access", "httpx", "httpcore", "deepface",
+    "tensorflow", "absl", "h5py", "PIL", "numba",
+    "huggingface_hub", "filelock", "urllib3", "werkzeug", "asyncio",
+]
+
+_FORMAT = logging.Formatter(
+    "%(asctime)s [%(levelname)-8s] [%(name)s] %(message)s",
+    datefmt="%Y-%m-%dT%H:%M:%S",
+)
+
+
+def setup_logging(level: str | None = None) -> None:
+    if level is None:
+        from app.core.config import settings
+        level = settings.LOG_LEVEL
+
+    effective_level = getattr(logging, level.upper(), logging.DEBUG)
+
+    console = logging.StreamHandler()
+    console.setFormatter(_FORMAT)
+
+    for logger_name in ["app", "app.access"]:
+        logger = logging.getLogger(logger_name)
+        logger.setLevel(effective_level)
+        logger.propagate = False
+        logger.handlers.clear()
+        logger.addHandler(console)
+
+    for name in _SILENCED_LOGGERS:
+        logging.getLogger(name).setLevel(logging.ERROR)
+
+
+def get_logger(name: str) -> logging.Logger:
+    return logging.getLogger(name)

backend/app/core/security.py

@@ -0,0 +1,46 @@
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import bcrypt
+import jwt
+
+from app.core.config import settings
+
+
+def hash_password(password: str) -> str:
+    return bcrypt.hashpw(password.encode(), bcrypt.gensalt(rounds=12)).decode()
+
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    try:
+        return bcrypt.checkpw(plain_password.encode(), hashed_password.encode())
+    except (ValueError, TypeError):
+        return False
+
+
+def create_access_token(
+    subject: str,
+    role: str,
+    expires_delta: timedelta | None = None,
+    extra_data: dict[str, Any] | None = None,
+) -> str:
+    expire = datetime.now(timezone.utc) + (
+        expires_delta if expires_delta
+        else timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    )
+    to_encode: dict[str, Any] = {
+        "sub": subject,
+        "role": role,
+        "exp": int(expire.timestamp()),
+    }
+    if extra_data:
+        to_encode.update(extra_data)
+    return jwt.encode(to_encode, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_access_token(token: str) -> dict[str, Any] | None:
+    try:
+        return jwt.decode(token, settings.JWT_SECRET, algorithms=[settings.JWT_ALGORITHM])
+    except jwt.PyJWTError:
+        return None
+

backend/app/db/client.py

@@ -0,0 +1,24 @@
+from app.core.logging_config import get_logger
+from prisma import Prisma
+
+logger = get_logger("app.db")
+
+db = Prisma()
+
+
+async def connect_db() -> None:
+    try:
+        await db.connect()
+        logger.info("Connected to database")
+    except Exception as e:
+        logger.error("Failed to connect to database: %s", e, exc_info=True)
+        raise
+
+
+async def disconnect_db() -> None:
+    try:
+        if db.is_connected():
+            await db.disconnect()
+    except Exception as e:
+        logger.error("Error disconnecting database: %s", e, exc_info=True)
+

backend/app/db/redis.py

@@ -0,0 +1,39 @@
+from redis.asyncio import Redis
+from app.core.config import settings
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.redis")
+
+redis_client: Redis | None = None
+
+
+async def connect_redis() -> Redis:
+    global redis_client
+    if redis_client is None:
+        try:
+            redis_client = Redis.from_url(settings.REDIS_URL, decode_responses=True)
+            await redis_client.ping()
+            logger.info("Connected to Redis")
+        except Exception as err:
+            logger.error("Failed to connect to Redis at %s: %s", settings.REDIS_URL, err, exc_info=True)
+            redis_client = None
+            raise
+    return redis_client
+
+
+async def disconnect_redis() -> None:
+    global redis_client
+    if redis_client is not None:
+        try:
+            await redis_client.close()
+        except Exception as err:
+            logger.error("Error closing Redis connection: %s", err, exc_info=True)
+        finally:
+            redis_client = None
+
+
+def get_redis() -> Redis:
+    if redis_client is None:
+        raise RuntimeError("Redis client is not initialized. Please call connect_redis during startup.")
+    return redis_client
+

backend/app/middleware/request_logging.py

@@ -0,0 +1,25 @@
+import time
+from fastapi import Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.access")
+
+
+class RequestLoggingMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next) -> Response:
+        start_ts = time.perf_counter()
+        method = request.method
+        path = request.url.path
+
+        try:
+            response: Response = await call_next(request)
+        except Exception as exc:
+            elapsed_ms = int((time.perf_counter() - start_ts) * 1000)
+            logger.error("%s %s — %dms | error=%s", method, path, elapsed_ms, exc, exc_info=True)
+            raise
+
+        elapsed_ms = int((time.perf_counter() - start_ts) * 1000)
+        log = logger.warning if response.status_code >= 400 else logger.info
+        log("%s %s %d %dms", method, path, response.status_code, elapsed_ms)
+        return response

backend/app/repositories/attendance_repo.py

@@ -0,0 +1,64 @@
+from typing import List
+
+from prisma.models import Attendance
+from app.db.client import db
+
+
+class AttendanceRepository:
+    async def get_by_id(self, attendance_id: str) -> Attendance | None:
+        return await db.attendance.find_unique(
+            where={"id": attendance_id},
+            include={
+                "student": {"include": {"user": True}},
+                "session": {"include": {"academicClass": {"include": {"subject": True}}}},
+            },
+        )
+
+    async def get_by_student_and_session(self, student_id: str, session_id: str) -> Attendance | None:
+        return await db.attendance.find_unique(
+            where={"studentId_sessionId": {"studentId": student_id, "sessionId": session_id}}
+        )
+
+    async def get_flagged(self) -> List[Attendance]:
+        return await db.attendance.find_many(
+            where={"status": "Flagged"},
+            include={
+                "student": {"include": {"user": True}},
+                "session": {"include": {"academicClass": {"include": {"subject": True}}}},
+            },
+        )
+
+    async def create(self, data_dict: dict) -> Attendance:
+        return await db.attendance.create(data=data_dict)
+
+    async def update_review(self, attendance_id: str, status: str, remarks: str) -> Attendance:
+        return await db.attendance.update(
+            where={"id": attendance_id}, data={"status": status, "remarks": remarks}
+        )
+
+    async def get_all_absences(self) -> List[Attendance]:
+        return await db.attendance.find_many(
+            where={"status": {"in": ["Absent", "Rejected"]}}, include={"student": True}
+        )
+
+    async def get_by_student_id(self, student_id: str) -> List[Attendance]:
+        return await db.attendance.find_many(
+            where={"studentId": student_id},
+            include={"session": {"include": {"academicClass": True}}},
+            order={"createdAt": "desc"},
+        )
+
+    async def get_by_session_id(self, session_id: str) -> List[Attendance]:
+        return await db.attendance.find_many(
+            where={"sessionId": session_id}, include={"student": True}
+        )
+
+    async def get_by_student_in_date_range(self, student_id: str, start_date, end_date) -> List[Attendance]:
+        return await db.attendance.find_many(
+            where={"studentId": student_id, "createdAt": {"gte": start_date, "lte": end_date}},
+            include={"session": True},
+            order={"createdAt": "desc"},
+        )
+
+    async def update(self, attendance_id: str, data: dict) -> Attendance:
+        return await db.attendance.update(where={"id": attendance_id}, data=data)

backend/app/repositories/class_repo.py

@@ -0,0 +1,12 @@
+from typing import List
+
+from prisma.models import AcademicClass
+from app.db.client import db
+
+
+class ClassRepository:
+    async def get_by_id(self, class_id: str) -> AcademicClass | None:
+        return await db.academicclass.find_unique(where={"id": class_id})
+
+    async def get_by_teacher_id(self, teacher_id: str) -> List[AcademicClass]:
+        return await db.academicclass.find_many(where={"teacherId": teacher_id})

backend/app/repositories/enrollment_repo.py

@@ -0,0 +1,19 @@
+from typing import List
+
+from prisma.models import Enrollment
+from app.db.client import db
+
+
+class EnrollmentRepository:
+    async def get_by_student_id(self, student_id: str) -> List[Enrollment]:
+        return await db.enrollment.find_many(
+            where={"studentId": student_id}, include={"academicClass": True}
+        )
+
+    async def get_by_class_id(self, class_id: str) -> List[Enrollment]:
+        return await db.enrollment.find_many(
+            where={"academicClassId": class_id}, include={"student": True}
+        )
+
+    async def enroll_student(self, student_id: str, class_id: str) -> Enrollment:
+        return await db.enrollment.create(data={"studentId": student_id, "academicClassId": class_id})

backend/app/repositories/geofence_repo.py

@@ -0,0 +1,18 @@
+from prisma.models import Geofence
+from app.db.client import db
+
+
+class GeofenceRepository:
+    async def get_by_class_id(self, class_id: str) -> Geofence | None:
+        return await db.geofence.find_unique(where={"academicClassId": class_id})
+
+    async def upsert_geofence(self, class_id: str, latitude: float, longitude: float, radius: float) -> Geofence:
+        existing = await self.get_by_class_id(class_id)
+        if existing:
+            return await db.geofence.update(
+                where={"academicClassId": class_id},
+                data={"latitude": latitude, "longitude": longitude, "radiusMeters": radius},
+            )
+        return await db.geofence.create(
+            data={"academicClassId": class_id, "latitude": latitude, "longitude": longitude, "radiusMeters": radius}
+        )

backend/app/repositories/leave_repo.py

@@ -0,0 +1,44 @@
+from datetime import datetime, timezone
+from typing import List, Optional
+
+from prisma.models import LeaveRequest
+from app.db.client import db
+
+
+class LeaveRepository:
+    async def create(self, data: dict) -> LeaveRequest:
+        return await db.leaverequest.create(data=data, include={"student": True})
+
+    async def get_by_id(self, leave_id: str) -> Optional[LeaveRequest]:
+        return await db.leaverequest.find_unique(where={"id": leave_id}, include={"student": True})
+
+    async def get_by_student_id(self, student_id: str) -> List[LeaveRequest]:
+        return await db.leaverequest.find_many(
+            where={"studentId": student_id}, include={"student": True}, order={"createdAt": "desc"}
+        )
+
+    async def get_pending_for_teacher(self, teacher_id: str) -> List[LeaveRequest]:
+        enrollments = await db.enrollment.find_many(
+            where={"academicClass": {"is": {"teacherId": teacher_id}}},
+            include={"student": True},
+        )
+        student_ids = [e.studentId for e in enrollments]
+        return await db.leaverequest.find_many(
+            where={"studentId": {"in": student_ids}, "status": "PENDING"},
+            include={"student": True},
+            order={"createdAt": "asc"},
+        )
+
+    async def update_status(
+        self, leave_id: str, status: str, approved_by: str, approver_note: Optional[str] = None
+    ) -> Optional[LeaveRequest]:
+        return await db.leaverequest.update(
+            where={"id": leave_id},
+            data={
+                "status": status,
+                "approvedBy": approved_by,
+                "approverNote": approver_note,
+                "updatedAt": datetime.now(timezone.utc),
+            },
+        )
+

backend/app/repositories/session_repo.py

@@ -0,0 +1,34 @@
+from datetime import datetime, timezone
+
+from prisma.models import Session
+from app.db.client import db
+
+
+class SessionRepository:
+    async def get_by_id(self, session_id: str) -> Session | None:
+        return await db.session.find_unique(where={"id": session_id})
+
+    async def get_active_session_by_class(self, class_id: str) -> Session | None:
+        now = datetime.now(timezone.utc)
+        return await db.session.find_first(
+            where={"academicClassId": class_id, "isActive": True, "endTime": {"gt": now}}
+        )
+
+    async def create(self, class_id: str, start_time: datetime, end_time: datetime) -> Session:
+        return await db.session.create(
+            data={"academicClassId": class_id, "startTime": start_time, "endTime": end_time, "isActive": True}
+        )
+
+    async def deactivate(self, session_id: str) -> Session:
+        return await db.session.update(where={"id": session_id}, data={"isActive": False})
+
+    async def get_sessions_in_date_range(self, start_date: datetime, end_date: datetime):
+        return await db.session.find_many(
+            where={"startTime": {"gte": start_date, "lte": end_date}},
+            include={"academicClass": True},
+        )
+
+    async def get_by_class_id(self, class_id: str):
+        return await db.session.find_many(
+            where={"academicClassId": class_id}, order={"startTime": "desc"}
+        )

backend/app/repositories/student_repo.py

@@ -0,0 +1,47 @@
+from typing import List
+
+from prisma.models import Student
+from app.db.client import db
+
+
+class StudentRepository:
+    async def get_by_id(self, student_id: str) -> Student | None:
+        return await db.student.find_unique(where={"id": student_id}, include={"user": True})
+
+    async def get_by_user_id(self, user_id: str) -> Student | None:
+        return await db.student.find_unique(where={"userId": user_id}, include={"user": True})
+
+    async def get_by_enrollment(self, enrollment: str) -> Student | None:
+        return await db.student.find_unique(where={"enrollmentNumber": enrollment}, include={"user": True})
+
+    async def create(self, user_id: str, enrollment: str) -> Student:
+        return await db.student.create(data={"userId": user_id, "enrollmentNumber": enrollment})
+
+    async def update_face_embedding(self, student_id: str, embedding: List[float]) -> bool:
+        await db.execute_raw("UPDATE students SET face_embedding = $1::vector WHERE id = $2", embedding, student_id)
+        return True
+
+    async def get_face_embedding(self, student_id: str) -> List[float] | None:
+        records = await db.query_raw("SELECT face_embedding::text FROM students WHERE id = $1", student_id)
+        if not records or not records[0].get("face_embedding"):
+            return None
+        val = records[0]["face_embedding"]
+        if isinstance(val, list):
+            return [float(x) for x in val]
+        if isinstance(val, str):
+            cleaned = val.strip("[]")
+            return [float(x) for x in cleaned.split(",")] if cleaned else []
+        return None
+
+    async def update_streak(self, student_id: str, current_streak: int, highest_streak: int) -> bool:
+        await db.student.update(
+            where={"id": student_id},
+            data={"currentStreak": current_streak, "highestStreak": highest_streak},
+        )
+        return True
+
+    async def get_all_active(self) -> List[Student]:
+        return await db.student.find_many(
+            where={"user": {"is": {"isActive": True}}},
+            include={"user": True},
+        )

backend/app/repositories/system_config_repo.py

@@ -0,0 +1,40 @@
+from prisma.models import SystemConfiguration
+from app.db.client import db
+
+
+class SystemConfigRepository:
+    async def get_config(self) -> SystemConfiguration:
+        """
+        Gets the system configuration. If it doesn't exist, creates a default one.
+        """
+        config = await db.systemconfiguration.find_first()
+        if not config:
+            config = await db.systemconfiguration.create(
+                data={
+                    "isFaceRecognitionEnabled": True,
+                    "isGpsVerificationEnabled": True,
+                    "isAiBackgroundValidationEnabled": True,
+                }
+            )
+        return config
+
+    async def update_config(
+        self,
+        is_face_recognition_enabled: bool | None = None,
+        is_gps_verification_enabled: bool | None = None,
+        is_ai_background_validation_enabled: bool | None = None,
+    ) -> SystemConfiguration:
+        config = await self.get_config()
+        
+        update_data = {}
+        if is_face_recognition_enabled is not None:
+            update_data["isFaceRecognitionEnabled"] = is_face_recognition_enabled
+        if is_gps_verification_enabled is not None:
+            update_data["isGpsVerificationEnabled"] = is_gps_verification_enabled
+        if is_ai_background_validation_enabled is not None:
+            update_data["isAiBackgroundValidationEnabled"] = is_ai_background_validation_enabled
+            
+        return await db.systemconfiguration.update(
+            where={"id": config.id},
+            data=update_data,
+        )

backend/app/repositories/teacher_repo.py

@@ -0,0 +1,10 @@
+from prisma.models import Teacher
+from app.db.client import db
+
+
+class TeacherRepository:
+    async def get_by_id(self, teacher_id: str) -> Teacher | None:
+        return await db.teacher.find_unique(where={"id": teacher_id}, include={"user": True})
+
+    async def get_by_user_id(self, user_id: str) -> Teacher | None:
+        return await db.teacher.find_unique(where={"userId": user_id}, include={"user": True})

backend/app/repositories/user_repo.py

@@ -0,0 +1,13 @@
+from prisma.models import User
+from app.db.client import db
+
+
+class UserRepository:
+    async def get_by_email(self, email: str) -> User | None:
+        return await db.user.find_unique(where={"email": email})
+
+    async def get_by_id(self, user_id: str) -> User | None:
+        return await db.user.find_unique(where={"id": user_id})
+
+    async def create(self, email: str, password_hash: str, role: str) -> User:
+        return await db.user.create(data={"email": email, "hashedPassword": password_hash, "role": role})

backend/app/schemas/admin.py

@@ -0,0 +1,97 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class ClassCreate(BaseModel):
+    name: str = Field(..., min_length=2, max_length=100, description="Name of the class e.g. CS-101-A")
+    subject_id: str = Field(..., description="UUID of the linked Subject")
+    teacher_id: str = Field(..., min_length=36, max_length=36, description="UUID of the associated Teacher profile")
+    classroom_id: Optional[str] = Field(None, description="UUID of the assigned Classroom (optional)")
+    semester: Optional[int] = Field(None, ge=1, le=8, description="Academic semester (1–8)")
+    batch: Optional[str] = Field(None, max_length=20, description="Batch year range e.g. 2022-2026")
+    max_students: Optional[int] = Field(None, ge=1, description="Maximum student capacity for the class")
+
+
+class ClassUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=2, max_length=100)
+    subject_id: Optional[str] = Field(None)
+    teacher_id: Optional[str] = Field(None, min_length=36, max_length=36)
+    classroom_id: Optional[str] = Field(None)
+    semester: Optional[int] = Field(None, ge=1, le=8)
+    batch: Optional[str] = Field(None, max_length=20)
+    max_students: Optional[int] = Field(None, ge=1)
+
+
+class AssignTeacherRequest(BaseModel):
+    teacher_id: str = Field(..., min_length=36, max_length=36, description="UUID of the Teacher profile to assign")
+
+
+class EnrollRequest(BaseModel):
+    student_ids: list[str] = Field(..., min_length=1, description="List of Student UUIDs to enroll in the class")
+
+
+class ClassResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the Academic Class")
+    name: str = Field(..., description="Name of the class")
+    subject_name: str = Field(..., description="Resolved subject name")
+    subject_code: str = Field(..., description="Resolved subject code")
+    teacher_id: str = Field(..., alias="teacherId", description="Teacher ID associated with this class")
+    classroom_name: Optional[str] = Field(None, description="Resolved classroom name")
+    semester: Optional[int] = Field(None, description="Academic semester")
+    batch: Optional[str] = Field(None, description="Batch year range")
+    max_students: Optional[int] = Field(None, description="Maximum student capacity")
+    enrolled_count: int = Field(0, description="Current number of enrolled students")
+    enrolled_student_ids: list[str] = Field(default_factory=list, description="List of student IDs currently enrolled")
+
+
+class DepartmentCreate(BaseModel):
+    name: str = Field(..., min_length=3, max_length=100)
+    code: str = Field(..., min_length=2, max_length=10)
+    head: Optional[str] = None
+    description: Optional[str] = None
+
+
+class DepartmentUpdate(BaseModel):
+    name: Optional[str] = Field(None, min_length=3, max_length=100)
+    code: Optional[str] = Field(None, min_length=2, max_length=10)
+    head: Optional[str] = None
+    description: Optional[str] = None
+
+
+class DepartmentResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    code: str
+    head: Optional[str] = None
+    description: Optional[str] = None
+    classCount: int = 0
+
+
+class AuditLogResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str
+    timestamp: datetime
+    eventType: str
+    severity: str
+    actor: str
+    target: str
+    description: str
+    ip: Optional[str] = Field(None, alias="ipAddress")
+    meta: Optional[dict] = Field(None, alias="metadata")
+
+
+class AdminStatsResponse(BaseModel):
+    studentCount: int
+    teacherCount: int
+    classCount: int
+
+
+class AdminResetPasswordRequest(BaseModel):
+    new_password: str = Field(..., min_length=8, description="New password for the user")

backend/app/schemas/attendance.py

@@ -0,0 +1,56 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class AttendanceMarkResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the attendance record")
+    student_id: str = Field(..., validation_alias="studentId", description="Student UUID")
+    session_id: str = Field(..., validation_alias="sessionId", description="Session UUID")
+    status: str = Field(..., description="Outcome of the weighted decision: 'Present' or 'Flagged'")
+    face_score: float = Field(..., validation_alias="faceScore", description="AI Face similarity score (0.0 to 1.0)")
+    liveness_score: float = Field(..., validation_alias="livenessScore", description="AI Face liveness score (0.0 to 1.0)")
+    background_score: float = Field(..., validation_alias="backgroundScore", description="AI Background learning-environment score (0.0 to 1.0)")
+    final_ai_score: float = Field(..., validation_alias="finalAiScore", description="Composite decision engine score (0.0 to 1.0)")
+    gps_latitude: float = Field(..., validation_alias="gpsLatitude", description="Submitted GPS Latitude")
+    gps_longitude: float = Field(..., validation_alias="gpsLongitude", description="Submitted GPS Longitude")
+    created_at: datetime = Field(..., validation_alias="createdAt", description="Verification timestamp")
+
+
+class FlaggedAttendanceResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Attendance Record UUID")
+    enrollment_number: str = Field(..., description="Student enrollment number")
+    student_name: str = Field(..., description="Student full email or name context")
+    class_name: str = Field(..., description="Class name")
+    subject: str = Field(..., description="Course Subject")
+    face_score: float = Field(..., validation_alias="faceScore", description="Similarity confidence")
+    liveness_score: float = Field(..., validation_alias="livenessScore", description="Liveness confidence")
+    background_score: float = Field(..., validation_alias="backgroundScore", description="Background confidence")
+    final_ai_score: float = Field(..., validation_alias="finalAiScore", description="Composite engine decision score")
+    gps_latitude: float = Field(..., validation_alias="gpsLatitude", description="Submitted GPS Latitude")
+    gps_longitude: float = Field(..., validation_alias="gpsLongitude", description="Submitted GPS Longitude")
+    created_at: datetime = Field(..., validation_alias="createdAt", description="Verification timestamp")
+    student_note: Optional[str] = Field(None, validation_alias="studentNote", description="Student note on flagged record")
+
+
+class AttendanceAnalyzeResponse(BaseModel):
+    """Returned by the analyze endpoint — scores only, no record saved yet."""
+    face_score: float = Field(..., description="AI Face similarity score (0.0 to 1.0)")
+    liveness_score: float = Field(..., description="AI Face liveness score (0.0 to 1.0)")
+    background_score: float = Field(..., description="AI Background score (0.0 to 1.0)")
+    final_ai_score: float = Field(..., description="Composite weighted score (0.0 to 1.0)")
+    predicted_status: str = Field(..., description="'Present' or 'Flagged' — what would be saved on confirm")
+    review_token: str = Field(..., description="Short-lived signed token to confirm submission without re-running AI")
+
+
+class AttendanceReview(BaseModel):
+    status: str = Field(..., pattern="^(Approved|Rejected)$", description="Review decision: 'Approved' or 'Rejected'")
+    remarks: Optional[str] = Field(default="", max_length=250, description="Audit notes/justification from the teacher")
+
+
+

backend/app/schemas/auth.py

@@ -0,0 +1,31 @@
+from typing import Optional
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class UserLogin(BaseModel):
+    email: EmailStr = Field(..., description="Unique email address of the user")
+    password: str = Field(..., min_length=8, max_length=100, description="Plaintext password")
+    device_uuid: Optional[str] = Field(None, description="Hardware device UUID for student device binding")
+
+
+class Token(BaseModel):
+    access_token: str = Field(..., description="Signed JWT access token")
+    token_type: str = Field("bearer", description="Token protocol type")
+    role: str = Field(..., description="Role of the authenticated user (STUDENT, TEACHER, ADMIN)")
+
+
+class UserProfileResponse(BaseModel):
+    id: str = Field(..., description="Unique UUID of the user")
+    email: EmailStr = Field(..., description="Email address of the user")
+    role: str = Field(..., description="Assigned role of the user")
+    is_active: bool = Field(..., description="System status flag")
+    student_profile: Optional[dict] = Field(None, description="Detailed student profile if role is STUDENT")
+    teacher_profile: Optional[dict] = Field(None, description="Detailed teacher profile if role is TEACHER")
+
+
+class DeviceChangeRequestCreate(BaseModel):
+    email: EmailStr = Field(..., description="Unique email address of the user")
+    password: str = Field(..., min_length=8, max_length=100, description="Plaintext password")
+    new_device_uuid: str = Field(..., description="The new hardware device UUID")
+    reason: Optional[str] = Field(None, description="Optional reason for changing the device")

backend/app/schemas/leave.py

@@ -0,0 +1,49 @@
+from datetime import datetime, date
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator, ConfigDict
+
+
+class LeaveRequestCreate(BaseModel):
+    start_date: date = Field(..., description="Leave start date")
+    end_date: date = Field(..., description="Leave end date")
+    reason: str = Field(..., min_length=10, max_length=500, description="Reason for leave")
+    document_url: Optional[str] = Field(None, description="Supporting document URL (medical certificate, etc.)")
+
+    @field_validator('end_date')
+    @classmethod
+    def validate_date_range(cls, v, info):
+        if 'start_date' in info.data and v < info.data['start_date']:
+            raise ValueError('end_date must be after or equal to start_date')
+        return v
+
+
+class LeaveRequestResponse(BaseModel):
+    id: str
+    student_id: str
+    student_name: str
+    enrollment_number: str
+    start_date: datetime
+    end_date: datetime
+    reason: str
+    document_url: Optional[str]
+    status: str
+    approved_by: Optional[str]
+    approver_note: Optional[str]
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class LeaveRequestApprove(BaseModel):
+    status: str = Field(..., pattern="^(APPROVED|REJECTED)$", description="Approval status")
+    approver_note: Optional[str] = Field(None, max_length=300, description="Optional note from approver")
+
+
+class LeaveRequestListResponse(BaseModel):
+    leaves: list[LeaveRequestResponse]
+    total: int
+    pending: int
+    approved: int
+    rejected: int

backend/app/schemas/log.py

@@ -0,0 +1,35 @@
+from typing import Optional, Dict, Any
+from datetime import datetime, timezone
+
+from pydantic import BaseModel, Field, field_validator
+
+_VALID_SOURCES = {"frontend", "mobile"}
+_VALID_LEVELS = {"DEBUG", "INFO", "WARN", "WARNING", "ERROR", "CRITICAL"}
+
+
+class LogEvent(BaseModel):
+    source: str = Field(..., description="Origin of the log event: 'frontend' or 'mobile'")
+    level: str = Field(default="INFO", description="Severity: DEBUG, INFO, WARN, ERROR, CRITICAL")
+    message: str = Field(..., min_length=1, description="The human-readable log message")
+    timestamp: Optional[str] = Field(default=None, description="ISO-8601 UTC timestamp of the event")
+    context: Optional[Dict[str, Any]] = Field(default=None, description="Optional structured metadata")
+    user_id: Optional[str] = Field(default=None, description="Authenticated user ID at the time of the event")
+    platform_version: Optional[str] = Field(default=None, description="Client platform version")
+
+    @field_validator("source")
+    @classmethod
+    def validate_source(cls, value: str) -> str:
+        if value.lower() not in _VALID_SOURCES:
+            raise ValueError(f"Invalid log source '{value}'. Must be one of: {sorted(_VALID_SOURCES)}")
+        return value.lower()
+
+    @field_validator("level")
+    @classmethod
+    def validate_level(cls, value: str) -> str:
+        normalized = value.upper()
+        return normalized if normalized in _VALID_LEVELS else "INFO"
+
+    @field_validator("timestamp", mode="before")
+    @classmethod
+    def set_default_timestamp(cls, value: Optional[str]) -> str:
+        return value if value is not None else datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")

backend/app/schemas/master_data.py

@@ -0,0 +1,65 @@
+from pydantic import BaseModel, Field, ConfigDict
+
+
+
+class SubjectCreate(BaseModel):
+    name: str = Field(..., min_length=3, max_length=100)
+    code: str = Field(..., min_length=2, max_length=10)
+    description: str | None = None
+
+
+class SubjectUpdate(BaseModel):
+    name: str | None = Field(None, min_length=3, max_length=100)
+    code: str | None = Field(None, min_length=2, max_length=10)
+    description: str | None = None
+
+
+class SubjectResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    code: str
+    description: str | None = None
+
+
+class ClassroomCreate(BaseModel):
+    name: str = Field(..., min_length=1, max_length=100)
+    building: str | None = None
+    capacity: int | None = Field(None, ge=1)
+
+
+class ClassroomUpdate(BaseModel):
+    name: str | None = Field(None, min_length=1, max_length=100)
+    building: str | None = None
+    capacity: int | None = Field(None, ge=1)
+
+
+class ClassroomResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    building: str | None = None
+    capacity: int | None = None
+
+
+class DesignationCreate(BaseModel):
+    name: str = Field(..., min_length=3, max_length=100)
+    code: str = Field(..., min_length=2, max_length=10)
+    description: str | None = None
+
+
+class DesignationUpdate(BaseModel):
+    name: str | None = Field(None, min_length=3, max_length=100)
+    code: str | None = Field(None, min_length=2, max_length=10)
+    description: str | None = None
+
+
+class DesignationResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    name: str
+    code: str
+    description: str | None = None

backend/app/schemas/student.py

@@ -0,0 +1,81 @@
+from datetime import datetime
+from typing import Optional
+
+from pydantic import BaseModel, EmailStr, Field, ConfigDict
+
+
+class StudentCreate(BaseModel):
+    email: EmailStr = Field(..., description="Unique email address of the student")
+    password: str = Field(..., min_length=8, max_length=100, description="Secure account password")
+    enrollment_number: str = Field(..., min_length=5, max_length=30, description="University Enrollment Number")
+    first_name: str = Field(..., min_length=1, max_length=100, description="Student first name")
+    last_name: str = Field(..., min_length=1, max_length=100, description="Student last name")
+    phone: Optional[str] = Field(None, max_length=20, description="Contact phone number")
+    gender: Optional[str] = Field(None, description="Gender identity")
+    date_of_birth: Optional[datetime] = Field(None, description="Date of birth")
+    semester: Optional[int] = Field(None, ge=1, le=8, description="Current academic semester (1–8)")
+    batch: Optional[str] = Field(None, max_length=20, description="Batch year range e.g. 2022-2026")
+    department_id: Optional[str] = Field(None, description="UUID of the student's department")
+
+
+class StudentUpdate(BaseModel):
+    enrollment_number: Optional[str] = Field(None, min_length=5, max_length=30)
+    first_name: Optional[str] = Field(None, min_length=1, max_length=100)
+    last_name: Optional[str] = Field(None, min_length=1, max_length=100)
+    phone: Optional[str] = Field(None, max_length=20)
+    gender: Optional[str] = Field(None)
+    date_of_birth: Optional[datetime] = Field(None)
+    semester: Optional[int] = Field(None, ge=1, le=8)
+    batch: Optional[str] = Field(None, max_length=20)
+    department_id: Optional[str] = Field(None)
+
+
+class StudentResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str = Field(..., description="Unique UUID of the student record")
+    user_id: str = Field(..., description="Mapped User UUID")
+    enrollment_number: str = Field(..., description="Student enrollment number")
+    email: str = Field(..., description="Email address associated with the user profile")
+    first_name: Optional[str] = Field(None, description="Student first name")
+    last_name: Optional[str] = Field(None, description="Student last name")
+    phone: Optional[str] = Field(None, description="Contact phone number")
+    gender: Optional[str] = Field(None, description="Gender identity")
+    date_of_birth: Optional[datetime] = Field(None, description="Date of birth")
+    department_id: Optional[str] = Field(None, description="Raw department UUID")
+    department_name: Optional[str] = Field(None, description="Resolved department name")
+    semester: Optional[int] = Field(None, description="Current semester")
+    batch: Optional[str] = Field(None, description="Batch year range")
+
+
+class StudentAttendanceItem(BaseModel):
+    attendance_id: str = Field(..., description="UUID of attendance record")
+    class_id: str = Field(..., description="Class UUID")
+    class_name: str = Field(..., description="Class name")
+    subject: str = Field(..., description="Subject name")
+    session_id: str = Field(..., description="Session UUID")
+    status: str = Field(..., description="Attendance status (Present, Flagged, Absent)")
+    marked_at: datetime = Field(..., description="Timestamp marked")
+    face_score: Optional[float] = Field(None, description="AI face similarity score")
+    liveness_score: Optional[float] = Field(None, description="AI liveness score")
+    background_score: Optional[float] = Field(None, description="AI background score")
+    final_ai_score: Optional[float] = Field(None, description="Composite AI score")
+    teacher_note: Optional[str] = Field(None, description="Teacher review note/remarks")
+
+
+class StudentAttendanceHistoryResponse(BaseModel):
+    student_id: str = Field(..., description="Student profile UUID")
+    overall_attendance_percentage: float = Field(..., description="Overall attendance percentage over all enrolled courses")
+    history: list[StudentAttendanceItem] = Field(..., description="Detailed history itemized logs")
+
+
+class StudentClassResponse(BaseModel):
+    class_id: str = Field(..., description="Class UUID")
+    class_name: str = Field(..., description="Class name")
+    subject: str = Field(..., description="Subject name")
+    teacher_name: str = Field(..., description="Teacher name")
+    active_session_id: Optional[str] = Field(None, description="UUID of active session if any")
+    session_end_time: Optional[datetime] = Field(None, description="Active session end time if any")
+    latitude: Optional[float] = Field(None, description="Geofence center latitude")
+    longitude: Optional[float] = Field(None, description="Geofence center longitude")
+    radius_meters: Optional[float] = Field(None, description="Geofence radius in meters")

backend/app/schemas/system_config.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel, Field
+
+
+class SystemConfigResponse(BaseModel):
+    is_face_recognition_enabled: bool = Field(..., alias="isFaceRecognitionEnabled")
+    is_gps_verification_enabled: bool = Field(..., alias="isGpsVerificationEnabled")
+    is_ai_background_validation_enabled: bool = Field(..., alias="isAiBackgroundValidationEnabled")
+
+    class Config:
+        populate_by_name = True
+
+
+class SystemConfigUpdate(BaseModel):
+    is_face_recognition_enabled: bool | None = Field(None, alias="isFaceRecognitionEnabled")
+    is_gps_verification_enabled: bool | None = Field(None, alias="isGpsVerificationEnabled")
+    is_ai_background_validation_enabled: bool | None = Field(None, alias="isAiBackgroundValidationEnabled")

backend/app/schemas/teacher.py

@@ -0,0 +1,176 @@
+from datetime import datetime
+from typing import Optional, Literal
+
+from pydantic import BaseModel, EmailStr, Field, ConfigDict
+
+
+class TeacherCreate(BaseModel):
+    email: EmailStr = Field(..., description="Unique email address of the teacher")
+    password: str = Field(..., min_length=8, max_length=100, description="Secure account password")
+    employee_id: str = Field(..., min_length=3, max_length=30, description="Unique employee identifier e.g. EMP2024001")
+    first_name: str = Field(..., min_length=1, max_length=100, description="Teacher first name")
+    last_name: str = Field(..., min_length=1, max_length=100, description="Teacher last name")
+    department_id: str = Field(..., description="UUID of the teacher's department")
+    designation_id: str = Field(..., description="UUID of the teacher's designation")
+    phone: Optional[str] = Field(None, max_length=20, description="Contact phone number")
+    qualification: Optional[str] = Field(None, max_length=100, description="Academic qualification e.g. Ph.D, M.Tech")
+    specialization: Optional[str] = Field(None, max_length=100, description="Area of specialization e.g. Machine Learning")
+    experience_years: Optional[int] = Field(None, ge=0, description="Years of professional experience")
+    joining_date: Optional[datetime] = Field(None, description="Date of joining the institution")
+
+
+class TeacherUpdate(BaseModel):
+    employee_id: Optional[str] = Field(None, min_length=3, max_length=30)
+    first_name: Optional[str] = Field(None, min_length=1, max_length=100)
+    last_name: Optional[str] = Field(None, min_length=1, max_length=100)
+    department_id: Optional[str] = Field(None)
+    designation_id: Optional[str] = Field(None)
+    phone: Optional[str] = Field(None, max_length=20)
+    qualification: Optional[str] = Field(None, max_length=100)
+    specialization: Optional[str] = Field(None, max_length=100)
+    experience_years: Optional[int] = Field(None, ge=0)
+    joining_date: Optional[datetime] = Field(None)
+
+
+class TeacherResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str = Field(..., description="Unique UUID of the teacher record")
+    user_id: str = Field(..., description="Mapped User UUID")
+    email: str = Field(..., description="Email address associated with the user profile")
+    employee_id: str = Field(..., description="Unique employee ID")
+    first_name: str = Field(..., description="Teacher first name")
+    last_name: str = Field(..., description="Teacher last name")
+    department_id: str = Field(..., description="Raw department UUID")
+    designation_id: str = Field(..., description="Raw designation UUID")
+    department: str = Field(..., description="Resolved department name")
+    designation: str = Field(..., description="Resolved designation name")
+    phone: Optional[str] = Field(None, description="Contact phone number")
+    qualification: Optional[str] = Field(None, description="Academic qualification")
+    specialization: Optional[str] = Field(None, description="Area of specialization")
+    experience_years: Optional[int] = Field(None, description="Years of professional experience")
+    joining_date: Optional[datetime] = Field(None, description="Joining date")
+
+
+class SessionStart(BaseModel):
+    academic_class_id: str = Field(..., description="Target Class UUID for this session")
+    duration_minutes: int = Field(10, ge=1, le=180, description="Session validity window in minutes")
+
+
+class SessionResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the active session")
+    academic_class_id: str = Field(..., alias="academicClassId", description="Associated Class UUID")
+    start_time: datetime = Field(..., alias="startTime", description="Timestamp when the session opened")
+    end_time: datetime = Field(..., alias="endTime", description="Timestamp when the session will close")
+    is_active: bool = Field(..., alias="isActive", description="Current state of the session")
+
+
+class GeofenceUpsert(BaseModel):
+    latitude: float = Field(..., description="GPS Latitude coordinate")
+    longitude: float = Field(..., description="GPS Longitude coordinate")
+    radius_meters: float = Field(..., gt=0.0, description="Geofence boundary radius in meters")
+
+
+class GeofenceResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the Geofence record")
+    academic_class_id: str = Field(..., alias="academicClassId", description="Class ID")
+    latitude: float = Field(..., description="Latitude coordinate")
+    longitude: float = Field(..., description="Longitude coordinate")
+    radius_meters: float = Field(..., alias="radiusMeters", description="Radius in meters")
+    created_at: datetime = Field(..., alias="createdAt", description="Timestamp created")
+    updated_at: datetime = Field(..., alias="updatedAt", description="Timestamp updated")
+
+
+class AcademicClassWithGeofenceResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the Academic Class")
+    name: str = Field(..., description="Class name")
+    subject: str = Field(..., description="Resolved subject name")
+    teacher_id: str = Field(..., alias="teacherId", description="Teacher ID")
+    geofence: Optional[GeofenceResponse] = Field(None, description="Class geofence configuration")
+
+
+class StudentRosterItem(BaseModel):
+    student_id: str = Field(..., description="Student UUID")
+    enrollment_number: str = Field(..., description="Student enrollment number")
+    full_name: str = Field(..., description="Student full name (first + last)")
+    email: str = Field(..., description="Student email address")
+    status: str = Field(..., description="Attendance status (Present, Flagged, Absent)")
+    final_score: float = Field(..., description="Final calculated AI attendance score")
+    marked_at: Optional[datetime] = Field(None, description="Timestamp attendance was registered")
+
+
+class SessionAttendanceResponse(BaseModel):
+    session_id: str = Field(..., description="Session UUID")
+    class_name: str = Field(..., description="Class name")
+    roster: list[StudentRosterItem] = Field(..., description="Enrolled roster list details")
+
+
+class SessionTrendItem(BaseModel):
+    session_id: str = Field(..., description="Session UUID")
+    session_name: str = Field(..., description="Display name of session")
+    attendance_percentage: float = Field(..., description="Attendance percentage for session")
+
+
+class ClassStatsResponse(BaseModel):
+    class_id: str = Field(..., description="Class UUID")
+    total_sessions: int = Field(..., description="Total sessions held for class")
+    total_students: int = Field(..., description="Total student count enrolled in class")
+    overall_attendance_percentage: float = Field(..., description="Overall class attendance percentage")
+    history: list[SessionTrendItem] = Field(default_factory=list, description="Chronological list of sessions with stats")
+
+
+class AttendanceManualOverride(BaseModel):
+    student_id: str = Field(..., description="Student UUID to override")
+    status: str = Field(..., description="Target status (Present or Absent)")
+
+
+class SessionWithClassResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True, populate_by_name=True)
+
+    id: str = Field(..., description="Unique UUID of the session")
+    academic_class_id: str = Field(..., alias="academicClassId", description="Associated Class UUID")
+    class_name: str = Field(..., description="Class Name")
+    subject: str = Field(..., description="Resolved subject name")
+    start_time: datetime = Field(..., alias="startTime", description="Timestamp when session opened")
+    end_time: datetime = Field(..., alias="endTime", description="Timestamp when session closed")
+    is_active: bool = Field(..., alias="isActive", description="Current state of session")
+
+
+class BulkAttendanceRecord(BaseModel):
+    student_id: str = Field(..., description="Student UUID")
+    status: Literal["Present", "Absent"] = Field(..., description="Attendance status to set")
+
+
+class BulkMarkRequest(BaseModel):
+    records: list[BulkAttendanceRecord] = Field(..., min_length=1, description="List of student attendance records")
+
+
+class AbsentStudentItem(BaseModel):
+    student_id: str = Field(..., description="Student UUID")
+    enrollment_number: str = Field(..., description="Student enrollment number")
+    full_name: str = Field(..., description="Student full name")
+    email: str = Field(..., description="Student email address")
+
+
+class DeviceChangeResponse(BaseModel):
+    id: str = Field(..., description="Device Change Request UUID")
+    student_id: str = Field(..., description="Student UUID")
+    student_name: str = Field(..., description="Student full name")
+    enrollment_number: str = Field(..., description="Student enrollment number")
+    new_device_uuid: str = Field(..., description="New device UUID requested")
+    reason: Optional[str] = Field(None, description="Reason for device change")
+    status: str = Field(..., description="Request status (PENDING, APPROVED, REJECTED)")
+    approved_by: Optional[str] = Field(None, description="UUID of approver")
+    created_at: datetime = Field(..., description="Creation timestamp")
+    updated_at: datetime = Field(..., description="Last update timestamp")
+
+
+class DeviceChangeApprove(BaseModel):
+    status: Literal["APPROVED", "REJECTED"] = Field(..., description="Approval status decision")
+

backend/app/services/absentee_scanner.py

@@ -0,0 +1,56 @@
+import asyncio
+from typing import List, Dict, Any
+
+import pandas as pd
+from sklearn.ensemble import IsolationForest
+
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.ai.scanner")
+
+_REQUIRED_COLS = {'student_id', 'status', 'day_of_week'}
+
+
+def _run_isolation_forest(attendance_records: List[Dict[str, Any]], contamination: float) -> List[Dict[str, Any]]:
+    try:
+        if not attendance_records:
+            return []
+
+        df = pd.DataFrame(attendance_records)
+        if not _REQUIRED_COLS.issubset(df.columns):
+            logger.error("Missing required columns in attendance records. Required: %s", _REQUIRED_COLS)
+            return []
+
+        absences = df[df['status'] == 'Absent']
+        if absences.empty:
+            return []
+
+        profile = absences.groupby('student_id').size().reset_index(name='total_absences')
+        day_absences = pd.crosstab(absences['student_id'], absences['day_of_week']).reset_index()
+        profile = pd.merge(profile, day_absences, on='student_id', how='left').fillna(0)
+
+        features = profile.drop(columns=['student_id'])
+        model = IsolationForest(n_estimators=100, contamination=contamination, random_state=42)
+        model.fit(features)
+        
+        profile['pred'] = model.predict(features)
+        profile['anomaly_score'] = -model.decision_function(features)
+
+        flagged = profile[profile['pred'] == -1].copy()
+        flagged = flagged.sort_values(by='total_absences', ascending=False).drop(columns=['pred'])
+        return flagged.to_dict(orient='records')
+
+    except Exception as e:
+        logger.error("Error in IsolationForest absentee scan: %s", e, exc_info=True)
+        return []
+
+
+async def run_absentee_scan(attendance_records: List[Dict[str, Any]], contamination: float = 0.10) -> List[Dict[str, Any]]:
+    try:
+        flagged = await asyncio.to_thread(_run_isolation_forest, attendance_records, contamination)
+        if flagged:
+            logger.info("Absentee scan: %d at-risk students", len(flagged))
+        return flagged
+    except Exception as e:
+        logger.error("Failed to run async absentee scan wrapper: %s", e, exc_info=True)
+        return []

backend/app/services/admin_service.py

@@ -0,0 +1,361 @@
+from typing import List, Optional
+
+from prisma.models import Department, AuditLog, Subject, Classroom, Designation
+
+from app.core.security import hash_password
+from app.db.client import db
+from app.repositories.user_repo import UserRepository
+from app.repositories.student_repo import StudentRepository
+from app.repositories.teacher_repo import TeacherRepository
+from app.repositories.class_repo import ClassRepository
+from app.repositories.enrollment_repo import EnrollmentRepository
+from app.schemas.student import StudentCreate, StudentResponse
+from app.schemas.teacher import TeacherCreate, TeacherResponse
+from app.schemas.admin import ClassCreate, ClassResponse
+
+
+class AdminService:
+    def __init__(self) -> None:
+        self.user_repo = UserRepository()
+        self.student_repo = StudentRepository()
+        self.teacher_repo = TeacherRepository()
+        self.class_repo = ClassRepository()
+        self.enrollment_repo = EnrollmentRepository()
+
+    @staticmethod
+    async def _log_action(event_type: str, severity: str, actor: str, target: str, description: str, ip: Optional[str] = None) -> None:
+        await db.auditlog.create(data={
+            "eventType": event_type,
+            "severity": severity,
+            "actor": actor,
+            "target": target,
+            "description": description,
+            "ip": ip,
+        })
+
+    # --- Students ---
+
+    async def create_student(self, data: StudentCreate, actor: str = "system", ip: Optional[str] = None) -> StudentResponse:
+        if data.department_id:
+            if not await db.department.find_unique(where={"id": data.department_id}):
+                raise ValueError("Department not found.")
+
+        user = await db.user.create(data={
+            "email": data.email, "hashedPassword": hash_password(data.password), "role": "STUDENT",
+        })
+        student = await db.student.create(
+            data={k: v for k, v in {
+                "userId": user.id, "enrollmentNumber": data.enrollment_number,
+                "firstName": data.first_name, "lastName": data.last_name,
+                "phone": data.phone, "gender": data.gender, "dateOfBirth": data.date_of_birth,
+                "semester": data.semester, "batch": data.batch, "departmentId": data.department_id,
+            }.items() if v is not None},
+            include={"department": True},
+        )
+        await self._log_action("CREATE_STUDENT", "INFO", actor, student.id, f"Created student {data.email}", ip)
+        return StudentResponse(
+            id=student.id, user_id=user.id, enrollment_number=student.enrollmentNumber, email=user.email,
+            first_name=student.firstName, last_name=student.lastName, phone=student.phone,
+            gender=student.gender, date_of_birth=student.dateOfBirth,
+            department_id=student.departmentId,
+            department_name=student.department.name if student.department else None,
+            semester=student.semester, batch=student.batch,
+        )
+
+    async def get_all_students(self) -> List[StudentResponse]:
+        students = await db.student.find_many(include={"user": True, "department": True})
+        return [
+            StudentResponse(
+                id=s.id, user_id=s.userId, enrollment_number=s.enrollmentNumber,
+                email=s.user.email if s.user else "", first_name=s.firstName,
+                last_name=s.lastName, phone=s.phone, gender=s.gender,
+                date_of_birth=s.dateOfBirth, department_id=s.departmentId,
+                department_name=s.department.name if s.department else None,
+                semester=s.semester, batch=s.batch,
+            )
+            for s in students
+        ]
+
+    async def update_student(self, id: str, data: dict, actor: str = "system", ip: Optional[str] = None) -> StudentResponse:
+        mapping = {
+            "enrollment_number": "enrollmentNumber", "first_name": "firstName", "last_name": "lastName",
+            "phone": "phone", "gender": "gender", "date_of_birth": "dateOfBirth",
+            "semester": "semester", "batch": "batch", "department_id": "departmentId",
+        }
+        update_data = {mapping[k]: v for k, v in data.items() if k in mapping}
+        student = await db.student.update(where={"id": id}, data=update_data, include={"user": True, "department": True})
+        await self._log_action("UPDATE_STUDENT", "INFO", actor, id, f"Updated student {student.user.email if student.user else id}", ip)
+        return StudentResponse(
+            id=student.id, user_id=student.userId, enrollment_number=student.enrollmentNumber,
+            email=student.user.email if student.user else "", first_name=student.firstName,
+            last_name=student.lastName, phone=student.phone, gender=student.gender,
+            date_of_birth=student.dateOfBirth, department_id=student.departmentId,
+            department_name=student.department.name if student.department else None,
+            semester=student.semester, batch=student.batch,
+        )
+
+    # --- Teachers ---
+
+    async def create_teacher(self, data: TeacherCreate, actor: str = "system", ip: Optional[str] = None) -> TeacherResponse:
+        if not await db.department.find_unique(where={"id": data.department_id}):
+            raise ValueError(f"Department with id '{data.department_id}' not found.")
+        if not await db.designation.find_unique(where={"id": data.designation_id}):
+            raise ValueError(f"Designation with id '{data.designation_id}' not found.")
+
+        user = await db.user.create(data={
+            "email": data.email, "hashedPassword": hash_password(data.password), "role": "TEACHER",
+        })
+        teacher = await db.teacher.create(
+            data={k: v for k, v in {
+                "userId": user.id, "employeeId": data.employee_id,
+                "firstName": data.first_name, "lastName": data.last_name,
+                "departmentId": data.department_id, "designationId": data.designation_id,
+                "phone": data.phone, "qualification": data.qualification,
+                "specialization": data.specialization, "experienceYears": data.experience_years,
+                "joiningDate": data.joining_date,
+            }.items() if v is not None},
+            include={"department": True, "designation": True},
+        )
+        await self._log_action("CREATE_TEACHER", "INFO", actor, teacher.id, f"Created teacher {data.email}", ip)
+        return TeacherResponse(
+            id=teacher.id, user_id=user.id, email=user.email, employee_id=teacher.employeeId,
+            first_name=teacher.firstName, last_name=teacher.lastName,
+            department_id=teacher.departmentId, designation_id=teacher.designationId,
+            department=teacher.department.name, designation=teacher.designation.name,
+            phone=teacher.phone, qualification=teacher.qualification,
+            specialization=teacher.specialization, experience_years=teacher.experienceYears,
+            joining_date=teacher.joiningDate,
+        )
+
+    async def get_all_teachers(self) -> List[TeacherResponse]:
+        teachers = await db.teacher.find_many(include={"user": True, "department": True, "designation": True})
+        return [
+            TeacherResponse(
+                id=t.id, user_id=t.userId, email=t.user.email if t.user else "",
+                employee_id=t.employeeId, first_name=t.firstName, last_name=t.lastName,
+                department_id=t.departmentId, designation_id=t.designationId,
+                department=t.department.name if t.department else "",
+                designation=t.designation.name if t.designation else "",
+                phone=t.phone, qualification=t.qualification, specialization=t.specialization,
+                experience_years=t.experienceYears, joining_date=t.joiningDate,
+            )
+            for t in teachers
+        ]
+
+    async def update_teacher(self, id: str, data: dict, actor: str = "system", ip: Optional[str] = None) -> TeacherResponse:
+        mapping = {
+            "employee_id": "employeeId", "first_name": "firstName", "last_name": "lastName",
+            "department_id": "departmentId", "designation_id": "designationId", "phone": "phone",
+            "qualification": "qualification", "specialization": "specialization",
+            "experience_years": "experienceYears", "joining_date": "joiningDate",
+        }
+        update_data = {mapping[k]: v for k, v in data.items() if k in mapping}
+        teacher = await db.teacher.update(where={"id": id}, data=update_data, include={"user": True, "department": True, "designation": True})
+        await self._log_action("UPDATE_TEACHER", "INFO", actor, id, f"Updated teacher {teacher.user.email if teacher.user else id}", ip)
+        return TeacherResponse(
+            id=teacher.id, user_id=teacher.userId, email=teacher.user.email if teacher.user else "",
+            employee_id=teacher.employeeId, first_name=teacher.firstName, last_name=teacher.lastName,
+            department_id=teacher.departmentId, designation_id=teacher.designationId,
+            department=teacher.department.name if teacher.department else "",
+            designation=teacher.designation.name if teacher.designation else "",
+            phone=teacher.phone, qualification=teacher.qualification,
+            specialization=teacher.specialization, experience_years=teacher.experienceYears,
+            joining_date=teacher.joiningDate,
+        )
+
+    # --- Classes ---
+
+    async def create_class(self, data: ClassCreate, actor: str = "system", ip: Optional[str] = None) -> ClassResponse:
+        if not await self.teacher_repo.get_by_id(data.teacher_id):
+            raise ValueError("Teacher profile not found.")
+        if not await db.subject.find_unique(where={"id": data.subject_id}):
+            raise ValueError(f"Subject with id '{data.subject_id}' not found.")
+        if data.classroom_id and not await db.classroom.find_unique(where={"id": data.classroom_id}):
+            raise ValueError(f"Classroom with id '{data.classroom_id}' not found.")
+
+        cls = await db.academicclass.create(
+            data={k: v for k, v in {
+                "name": data.name, "teacherId": data.teacher_id, "subjectId": data.subject_id,
+                "classroomId": data.classroom_id, "semester": data.semester,
+                "batch": data.batch, "maxStudents": data.max_students,
+            }.items() if v is not None},
+            include={"subject": True, "classroom": True, "enrollments": True},
+        )
+        await self._log_action("CREATE_CLASS", "INFO", actor, cls.id, f"Created class {data.name}", ip)
+        return ClassResponse(
+            id=cls.id, name=cls.name, subject_name=cls.subject.name, subject_code=cls.subject.code,
+            teacherId=cls.teacherId, classroom_name=cls.classroom.name if cls.classroom else None,
+            semester=cls.semester, batch=cls.batch, max_students=cls.maxStudents,
+            enrolled_count=len(cls.enrollments) if cls.enrollments else 0,
+            enrolled_student_ids=[e.studentId for e in cls.enrollments] if cls.enrollments else [],
+        )
+
+    async def get_all_classes(self) -> List[ClassResponse]:
+        classes = await db.academicclass.find_many(include={"subject": True, "classroom": True, "enrollments": True})
+        return [
+            ClassResponse(
+                id=c.id, name=c.name, subject_name=c.subject.name if c.subject else "",
+                subject_code=c.subject.code if c.subject else "", teacherId=c.teacherId,
+                classroom_name=c.classroom.name if c.classroom else None,
+                semester=c.semester, batch=c.batch, max_students=c.maxStudents,
+                enrolled_count=len(c.enrollments) if c.enrollments else 0,
+                enrolled_student_ids=[e.studentId for e in c.enrollments] if c.enrollments else [],
+            )
+            for c in classes
+        ]
+
+    async def update_class(self, class_id: str, data: dict, actor: str = "system", ip: Optional[str] = None) -> ClassResponse:
+        renames = {"subject_id": "subjectId", "classroom_id": "classroomId", "teacher_id": "teacherId"}
+        for old, new in renames.items():
+            if old in data:
+                data[new] = data.pop(old)
+        cls = await db.academicclass.update(where={"id": class_id}, data=data, include={"subject": True, "classroom": True, "enrollments": True})
+        await self._log_action("UPDATE_CLASS", "INFO", actor, class_id, f"Updated class {cls.name}", ip)
+        return ClassResponse(
+            id=cls.id, name=cls.name, subject_name=cls.subject.name if cls.subject else "",
+            subject_code=cls.subject.code if cls.subject else "", teacherId=cls.teacherId,
+            classroom_name=cls.classroom.name if cls.classroom else None,
+            semester=cls.semester, batch=cls.batch, max_students=cls.maxStudents,
+            enrolled_count=len(cls.enrollments) if cls.enrollments else 0,
+            enrolled_student_ids=[e.studentId for e in cls.enrollments] if cls.enrollments else [],
+        )
+
+    async def assign_teacher(self, class_id: str, teacher_id: str, actor: str = "system", ip: Optional[str] = None) -> ClassResponse:
+        if not await self.class_repo.get_by_id(class_id):
+            raise ValueError("Academic class not found.")
+        if not await self.teacher_repo.get_by_id(teacher_id):
+            raise ValueError("Teacher profile not found.")
+        cls = await db.academicclass.update(where={"id": class_id}, data={"teacherId": teacher_id}, include={"subject": True, "classroom": True, "enrollments": True})
+        await self._log_action("ASSIGN_TEACHER", "INFO", actor, class_id, f"Assigned teacher {teacher_id} to class {cls.name}", ip)
+        return ClassResponse(
+            id=cls.id, name=cls.name, subject_name=cls.subject.name if cls.subject else "",
+            subject_code=cls.subject.code if cls.subject else "", teacherId=cls.teacherId,
+            classroom_name=cls.classroom.name if cls.classroom else None,
+            semester=cls.semester, batch=cls.batch, max_students=cls.maxStudents,
+            enrolled_count=len(cls.enrollments) if cls.enrollments else 0,
+            enrolled_student_ids=[e.studentId for e in cls.enrollments] if cls.enrollments else [],
+        )
+
+    async def enroll_students(self, class_id: str, student_ids: List[str], actor: str = "system", ip: Optional[str] = None) -> int:
+        if not await self.class_repo.get_by_id(class_id):
+            raise ValueError("Academic class not found.")
+        count = 0
+        for sid in student_ids:
+            if await self.student_repo.get_by_id(sid):
+                existing = await db.enrollment.find_first(
+                    where={"studentId": sid, "academicClassId": class_id}
+                )
+                if not existing:
+                    await self.enrollment_repo.enroll_student(sid, class_id)
+                    count += 1
+        await self._log_action("ENROLL_STUDENTS", "INFO", actor, class_id, f"Enrolled {count} student(s) in class", ip)
+        return count
+
+    # --- Master Data Helpers ---
+
+    @staticmethod
+    async def _validate_delete(entity_name: str, record, ref_field: str, ref_table_name: str):
+        if not record:
+            raise ValueError(f"{entity_name} not found.")
+        ref_count = await getattr(db, ref_table_name).count(where={ref_field: record.id})
+        if ref_count > 0:
+            raise ValueError(f"Cannot delete {entity_name.lower()} because it is currently assigned.")
+
+    # --- Departments ---
+
+    async def get_all_departments(self) -> List[Department]:
+        return await db.department.find_many()
+
+    async def get_department_by_id(self, id: str) -> Optional[Department]:
+        return await db.department.find_unique(where={"id": id})
+
+    async def create_department(self, name: str, code: str, head: Optional[str] = None, description: Optional[str] = None) -> Department:
+        return await db.department.create(data={"name": name, "code": code, "head": head, "description": description})
+
+    async def update_department(self, id: str, data: dict) -> Department:
+        return await db.department.update(where={"id": id}, data=data)
+
+    async def delete_department(self, id: str, actor: str = "system", ip: Optional[str] = None) -> None:
+        dept = await db.department.find_unique(where={"id": id})
+        await self._validate_delete("Department", dept, "departmentId", "teacher")
+        await self._validate_delete("Department", dept, "departmentId", "student")
+        await db.department.delete(where={"id": id})
+        await self._log_action("DELETE_DEPARTMENT", "WARNING", actor, id, f"Deleted department {dept.name if dept else id}", ip)
+
+    # --- Subjects ---
+
+    async def get_all_subjects(self) -> List[Subject]:
+        return await db.subject.find_many()
+
+    async def get_subject_by_id(self, id: str) -> Optional[Subject]:
+        return await db.subject.find_unique(where={"id": id})
+
+    async def create_subject(self, name: str, code: str, description: Optional[str] = None) -> Subject:
+        return await db.subject.create(data={"name": name, "code": code, "description": description})
+
+    async def update_subject(self, id: str, data: dict) -> Subject:
+        return await db.subject.update(where={"id": id}, data=data)
+
+    async def delete_subject(self, id: str, actor: str = "system", ip: Optional[str] = None) -> None:
+        sub = await db.subject.find_unique(where={"id": id})
+        await self._validate_delete("Subject", sub, "subjectId", "academicclass")
+        await db.subject.delete(where={"id": id})
+        await self._log_action("DELETE_SUBJECT", "WARNING", actor, id, f"Deleted subject {sub.name if sub else id}", ip)
+
+    # --- Classrooms ---
+
+    async def get_all_classrooms(self) -> List[Classroom]:
+        return await db.classroom.find_many()
+
+    async def get_classroom_by_id(self, id: str) -> Optional[Classroom]:
+        return await db.classroom.find_unique(where={"id": id})
+
+    async def create_classroom(self, name: str, building: Optional[str] = None, capacity: Optional[int] = None) -> Classroom:
+        return await db.classroom.create(data={"name": name, "building": building, "capacity": capacity})
+
+    async def update_classroom(self, id: str, data: dict) -> Classroom:
+        return await db.classroom.update(where={"id": id}, data=data)
+
+    async def delete_classroom(self, id: str, actor: str = "system", ip: Optional[str] = None) -> None:
+        classroom = await db.classroom.find_unique(where={"id": id})
+        await self._validate_delete("Classroom", classroom, "classroomId", "academicclass")
+        await db.classroom.delete(where={"id": id})
+        await self._log_action("DELETE_CLASSROOM", "WARNING", actor, id, f"Deleted classroom {classroom.name if classroom else id}", ip)
+
+    # --- Designations ---
+
+    async def get_all_designations(self) -> List[Designation]:
+        return await db.designation.find_many()
+
+    async def get_designation_by_id(self, id: str) -> Optional[Designation]:
+        return await db.designation.find_unique(where={"id": id})
+
+    async def create_designation(self, name: str, code: str, description: Optional[str] = None) -> Designation:
+        return await db.designation.create(data={"name": name, "code": code, "description": description})
+
+    async def update_designation(self, id: str, data: dict) -> Designation:
+        return await db.designation.update(where={"id": id}, data=data)
+
+    async def delete_designation(self, id: str, actor: str = "system", ip: Optional[str] = None) -> None:
+        desig = await db.designation.find_unique(where={"id": id})
+        await self._validate_delete("Designation", desig, "designationId", "teacher")
+        await db.designation.delete(where={"id": id})
+        await self._log_action("DELETE_DESIGNATION", "WARNING", actor, id, f"Deleted designation {desig.name if desig else id}", ip)
+
+    # --- Misc ---
+
+    async def get_audit_logs(self) -> List[AuditLog]:
+        return await db.auditlog.find_many(order={"timestamp": "desc"})
+
+    async def get_stats(self) -> dict:
+        return {
+            "studentCount": await db.student.count(),
+            "teacherCount": await db.teacher.count(),
+            "classCount": await db.academicclass.count(),
+        }
+
+    async def reset_user_password(self, user_id: str, new_password: str, actor: str = "system", ip: Optional[str] = None) -> None:
+        if not await db.user.find_unique(where={"id": user_id}):
+            raise ValueError("User not found.")
+        await db.user.update(where={"id": user_id}, data={"hashedPassword": hash_password(new_password)})
+        await self._log_action("RESET_PASSWORD", "WARNING", actor, user_id, "Reset user password", ip)

backend/app/services/ai_orchestrator.py

@@ -0,0 +1,174 @@
+import asyncio
+import os
+import shutil
+import threading
+from typing import List, Optional, Tuple
+
+import cv2
+import numpy as np
+import tensorflow as tf
+from deepface import DeepFace
+from huggingface_hub import hf_hub_download
+from tensorflow.keras.applications.mobilenet import preprocess_input
+
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.ai")
+
+os.environ.setdefault('TF_CPP_MIN_LOG_LEVEL', '3')
+os.environ.setdefault('TF_ENABLE_ONEDNN_OPTS', '0')
+os.environ.setdefault('CUDA_VISIBLE_DEVICES', '-1')
+
+BASE_MODELS_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../models"))
+LIVENESS_REPO = "prathamrajbhar/smart-attendance-liveness-detection"
+BACKGROUND_REPO = "prathamrajbhar/smart-attendance-background-validation"
+LIVENESS_FILENAME = "liveness_mobilenet_v2.h5"
+BACKGROUND_FILENAME = "background_mobilenet_v1.h5"
+
+LIVENESS_MODEL_PATH_V2 = os.path.join(BASE_MODELS_DIR, "liveness_detection", "liveness_mobilenet_v2.h5")
+LIVENESS_MODEL_PATH_V1 = os.path.join(BASE_MODELS_DIR, "liveness_detection", "liveness_mobilenet_v1.h5")
+BACKGROUND_MODEL_PATH = os.path.join(BASE_MODELS_DIR, "background_validation", "background_mobilenet_v1.h5")
+
+
+def _ensure_model_downloaded(repo_id: str, filename: str, local_path: str) -> str:
+    if os.path.exists(local_path):
+        return local_path
+    logger.info("Downloading model: %s/%s", repo_id, filename)
+    os.makedirs(os.path.dirname(local_path), exist_ok=True)
+    try:
+        downloaded = hf_hub_download(repo_id=repo_id, filename=filename, token=os.environ.get("HF_TOKEN"))
+        shutil.copy(downloaded, local_path)
+        return local_path
+    except Exception as e:
+        logger.error("Failed to download model from Hugging Face: %s", e, exc_info=True)
+        raise RuntimeError(f"Could not load model {filename} from {repo_id}: {e}") from e
+
+
+def _load_liveness_model(model_path: str) -> tf.keras.Model:
+    base = tf.keras.applications.MobileNetV2(input_shape=(224, 224, 3), include_top=False, weights=None)
+    x = base.output
+    x = tf.keras.layers.GlobalAveragePooling2D(name="global_average_pooling2d_3")(x)
+    x = tf.keras.layers.Dropout(0.001, name="dropout_3")(x)
+    outputs = tf.keras.layers.Dense(1, activation="sigmoid", name="dense_3")(x)
+    model = tf.keras.models.Model(inputs=base.input, outputs=outputs)
+    model.load_weights(model_path, by_name=True)
+    return model
+
+
+_liveness_path = LIVENESS_MODEL_PATH_V2 if os.path.exists(LIVENESS_MODEL_PATH_V2) else (LIVENESS_MODEL_PATH_V1 if os.path.exists(LIVENESS_MODEL_PATH_V1) else LIVENESS_MODEL_PATH_V2)
+_final_liveness_path = _ensure_model_downloaded(LIVENESS_REPO, LIVENESS_FILENAME, _liveness_path)
+_final_background_path = _ensure_model_downloaded(BACKGROUND_REPO, BACKGROUND_FILENAME, BACKGROUND_MODEL_PATH)
+
+liveness_model = _load_liveness_model(_final_liveness_path)
+background_model = tf.keras.models.load_model(_final_background_path)
+
+_liveness_lock = threading.Lock()
+_background_lock = threading.Lock()
+_deepface_lock = threading.Lock()
+
+
+class AIOrchestrator:
+    def _detect_and_crop_face(self, img: np.ndarray) -> Tuple[Optional[np.ndarray], Optional[Tuple[int, int, int, int]]]:
+        try:
+            with _deepface_lock:
+                faces = DeepFace.extract_faces(img_path=img, detector_backend="opencv", enforce_detection=True)
+            if not faces:
+                return None, None
+            fa = faces[0]["facial_area"]
+            x, y, w, h = fa["x"], fa["y"], fa["w"], fa["h"]
+            return img[y:y+h, x:x+w], (x, y, w, h)
+        except Exception as e:
+            logger.warning("DeepFace face extraction failed: %s", e)
+            return None, None
+
+    @staticmethod
+    def _preprocess_liveness(face_crop: np.ndarray) -> np.ndarray:
+        return np.expand_dims((cv2.resize(face_crop, (224, 224)).astype(np.float32) / 127.5) - 1.0, axis=0)
+
+    @staticmethod
+    def _preprocess_background(img: np.ndarray) -> np.ndarray:
+        return preprocess_input(np.expand_dims(cv2.resize(img, (224, 224)), axis=0).astype(np.float32))
+
+    def _run_face_comparison(self, stored_embedding: List[float], live_img: np.ndarray) -> float:
+        if not stored_embedding or live_img is None:
+            return 0.0
+        try:
+            with _deepface_lock:
+                results = DeepFace.represent(img_path=live_img, model_name="Facenet", enforce_detection=False)
+            if not results:
+                return 0.0
+            vec_s = np.array(stored_embedding, dtype=np.float32)
+            vec_l = np.array(results[0]["embedding"], dtype=np.float32)
+            norm_s, norm_l = np.linalg.norm(vec_s), np.linalg.norm(vec_l)
+            if norm_s == 0.0 or norm_l == 0.0:
+                return 0.0
+            return max(0.0, min(1.0, float(np.dot(vec_s, vec_l) / (norm_s * norm_l))))
+        except Exception as e:
+            logger.error("DeepFace face comparison failed safely: %s", e, exc_info=True)
+            return 0.0
+
+    def _run_liveness_inference(self, face_crop: np.ndarray) -> float:
+        if face_crop is None:
+            return 0.0
+        with _liveness_lock:
+            return float(liveness_model.predict(self._preprocess_liveness(cv2.cvtColor(face_crop, cv2.COLOR_RGB2BGR)), verbose=0)[0][0])
+
+    def _run_background_inference(self, img: np.ndarray) -> float:
+        if img is None:
+            return 0.0
+        with _background_lock:
+            return float(background_model.predict(self._preprocess_background(img), verbose=0)[0][0])
+
+    def _run_embedding_extraction(self, image_path: str) -> List[float]:
+        try:
+            img = cv2.imread(image_path)
+            if img is None:
+                return []
+            with _deepface_lock:
+                results = DeepFace.represent(img_path=cv2.cvtColor(img, cv2.COLOR_BGR2RGB), model_name="Facenet", enforce_detection=True)
+            return [float(v) for v in results[0]["embedding"]] if results else []
+        except Exception as e:
+            logger.error("DeepFace face embedding extraction failed safely: %s", e, exc_info=True)
+            return []
+
+    async def extract_face_embedding(self, image_path: str) -> List[float]:
+        if not os.path.exists(image_path):
+            return []
+        try:
+            return await asyncio.to_thread(self._run_embedding_extraction, image_path)
+        except Exception as e:
+            logger.error("Face embedding extraction thread run failed: %s", e, exc_info=True)
+            return []
+
+    async def analyze_attendance(self, image_path: str, face_embedding: List[float]) -> dict:
+        if not os.path.exists(image_path):
+            logger.warning("Image path does not exist for attendance analysis: %s", image_path)
+            return {"face_score": 0.0, "liveness_score": 0.0, "background_score": 0.0}
+
+        def _load_and_crop():
+            img = cv2.imread(image_path)
+            if img is None:
+                return None, None, None
+            img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+            face_crop, _ = self._detect_and_crop_face(img_rgb)
+            return img_rgb, face_crop, _
+
+        try:
+            img_rgb, face_crop, _ = await asyncio.to_thread(_load_and_crop)
+        except Exception as e:
+            logger.error("Failed to load and crop image: %s", e, exc_info=True)
+            return {"face_score": 0.0, "liveness_score": 0.0, "background_score": 0.0}
+
+        if img_rgb is None:
+            return {"face_score": 0.0, "liveness_score": 0.0, "background_score": 0.0}
+
+        try:
+            face_score, liveness_score, bg_score = await asyncio.gather(
+                asyncio.to_thread(self._run_face_comparison, face_embedding, img_rgb),
+                asyncio.to_thread(self._run_liveness_inference, face_crop),
+                asyncio.to_thread(self._run_background_inference, img_rgb),
+            )
+            return {"face_score": face_score, "liveness_score": liveness_score, "background_score": bg_score}
+        except Exception as e:
+            logger.error("Concurrent AI inference failed: %s", e, exc_info=True)
+            return {"face_score": 0.0, "liveness_score": 0.0, "background_score": 0.0}

backend/app/services/attendance_service.py

@@ -0,0 +1,465 @@
+import os
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from prisma.models import Attendance
+
+from app.core.config import settings
+from app.core.logging_config import get_logger
+from app.db.redis import get_redis
+from app.repositories.attendance_repo import AttendanceRepository
+from app.repositories.session_repo import SessionRepository
+from app.repositories.geofence_repo import GeofenceRepository
+from app.repositories.student_repo import StudentRepository
+from app.repositories.class_repo import ClassRepository
+from app.services.ai_orchestrator import AIOrchestrator
+from app.services.system_config_service import SystemConfigService
+from app.utils.geofencing import GPSCoordinate, calculate_haversine_distance, is_within_geofence
+from app.api.ws import manager
+
+logger = get_logger("app.attendance")
+
+
+class CachedSession:
+    def __init__(self, id: str, is_active: bool, academic_class_id: str, end_time: datetime):
+        self.id = id
+        self.isActive = is_active
+        self.academicClassId = academic_class_id
+        self.endTime = end_time
+
+
+@dataclass(frozen=True)
+class AttendanceSubmission:
+    student_id: str
+    session_id: str
+    latitude: float
+    longitude: float
+    accuracy: float
+    image_path: str | None = None
+
+
+class AttendanceService:
+    def __init__(self) -> None:
+        self.attendance_repo = AttendanceRepository()
+        self.session_repo = SessionRepository()
+        self.geofence_repo = GeofenceRepository()
+        self.student_repo = StudentRepository()
+        self.class_repo = ClassRepository()
+        self.ai_orchestrator = AIOrchestrator()
+
+    async def mark_attendance(self, submission: AttendanceSubmission) -> Attendance:
+        session = None
+        redis_client = None
+        cache_key = f"session:{submission.session_id}"
+
+        try:
+            redis_client = get_redis()
+            cached = await redis_client.get(cache_key)
+            if cached:
+                data = json.loads(cached)
+                end_time_str = data["endTime"].replace("Z", "+00:00")
+                session = CachedSession(
+                    id=data["id"], is_active=data["isActive"],
+                    academic_class_id=data["academicClassId"],
+                    end_time=datetime.fromisoformat(end_time_str),
+                )
+        except Exception:
+            logger.warning("Redis session cache read failed. Falling back to DB.")
+
+        if not session:
+            session = await self.session_repo.get_by_id(submission.session_id)
+            if not session:
+                raise ValueError("Attendance session is not active or not found.")
+
+            if redis_client:
+                try:
+                    now = datetime.now(timezone.utc)
+                    end = session.endTime.replace(tzinfo=timezone.utc) if session.endTime.tzinfo is None else session.endTime
+                    ttl = max(1, min(int((end - now).total_seconds()), 600))
+                    await redis_client.setex(cache_key, ttl, json.dumps({
+                        "id": session.id, "isActive": session.isActive,
+                        "academicClassId": session.academicClassId,
+                        "endTime": session.endTime.isoformat(),
+                    }))
+                except Exception as e:
+                    logger.warning("Redis session cache write failed: %s", e)
+
+        now = datetime.now(timezone.utc)
+        session_end = session.endTime.replace(tzinfo=timezone.utc) if session.endTime.tzinfo is None else session.endTime
+        if not session.isActive or session_end <= now:
+            if session.isActive:
+                await self.session_repo.deactivate(session.id)
+                try:
+                    await get_redis().delete(f"session:{session.id}")
+                except Exception:
+                    pass
+            raise ValueError("Attendance session is not active or not found.")
+
+        config = await SystemConfigService().get_config()
+
+        geofence_missing = False
+        remarks = None
+
+        if config.isGpsVerificationEnabled:
+            geofence = await self.geofence_repo.get_by_class_id(session.academicClassId)
+            if not geofence:
+                logger.warning("Missing geofence for class %s (student %s)", session.academicClassId, submission.student_id)
+                geofence_missing = True
+                remarks = "Missing Geofence Data"
+            else:
+                student_coord = GPSCoordinate(submission.latitude, submission.longitude)
+                classroom_coord = GPSCoordinate(geofence.latitude, geofence.longitude)
+                is_inside = is_within_geofence(
+                    student_coord=student_coord,
+                    classroom_coord=classroom_coord,
+                    base_radius=geofence.radiusMeters,
+                    student_accuracy=submission.accuracy,
+                )
+                if not is_inside:
+                    distance = calculate_haversine_distance(student_coord, classroom_coord)
+                    effective_radius = geofence.radiusMeters + submission.accuracy
+                    raise ValueError(
+                        f"Student is outside geofence boundary by {distance - effective_radius:.1f}m. "
+                        f"(Distance: {distance:.1f}m, Effective Allowed Radius: {effective_radius:.1f}m)"
+                    )
+
+        if config.isFaceRecognitionEnabled:
+            face_embedding = await self.student_repo.get_face_embedding(submission.student_id)
+            if not face_embedding:
+                raise ValueError("Student face embedding is not registered.")
+        else:
+            face_embedding = []
+
+        existing = await self.attendance_repo.get_by_student_and_session(submission.student_id, submission.session_id)
+        if existing:
+            raise ValueError("Attendance already submitted for this session.")
+
+        if config.isFaceRecognitionEnabled or config.isAiBackgroundValidationEnabled:
+            if not submission.image_path:
+                raise ValueError("Image is required when verification is enabled.")
+            ai_results = await self.ai_orchestrator.analyze_attendance(submission.image_path, face_embedding)
+        else:
+            ai_results = {"face_score": 1.0, "liveness_score": 1.0, "background_score": 1.0}
+            
+        if not config.isFaceRecognitionEnabled:
+            ai_results["face_score"] = 1.0
+            ai_results["liveness_score"] = 1.0
+            
+        if not config.isAiBackgroundValidationEnabled:
+            ai_results["background_score"] = 1.0
+        final_score = (
+            settings.FACE_WEIGHT * ai_results["face_score"]
+            + settings.LIVENESS_WEIGHT * ai_results["liveness_score"]
+            + settings.BACKGROUND_WEIGHT * ai_results["background_score"]
+        )
+        status = "Flagged" if geofence_missing else ("Present" if final_score >= settings.PASS_THRESHOLD else "Flagged")
+
+        attendance_record = await self.attendance_repo.create({
+            "studentId": submission.student_id, "sessionId": submission.session_id,
+            "status": status,
+            "faceScore": ai_results["face_score"], "livenessScore": ai_results["liveness_score"],
+            "backgroundScore": ai_results["background_score"], "finalAiScore": final_score,
+            "gpsLatitude": submission.latitude, "gpsLongitude": submission.longitude,
+            "remarks": remarks,
+        })
+
+        try:
+            msg = {"type": "attendance_updated", "session_id": submission.session_id, "status": status}
+            await manager.send_personal_message(msg, student_id=submission.student_id)
+            msg["student_id"] = submission.student_id
+            await manager.broadcast_to_teachers(msg)
+        except Exception as e:
+            logger.warning("WebSocket broadcast failed: %s", e)
+
+        if status == "Flagged":
+            try:
+                from app.services.notification_service import notify_student_attendance_flagged
+                student = await self.student_repo.get_by_id(submission.student_id)
+                if student and student.fcmToken:
+                    ac = await self.class_repo.get_by_id(session.academicClassId)
+                    class_name = ac.name if ac else "your class"
+                    await notify_student_attendance_flagged(student.fcmToken, student.firstName or "Student", class_name, attendance_record.id)
+            except Exception as e:
+                logger.warning("FCM notification failed: %s", e)
+
+        try:
+            from app.services.gamification_service import GamificationService
+            await GamificationService().update_streak(submission.student_id, status)
+        except Exception as e:
+            logger.warning("Streak update failed: %s", e)
+
+        if status == "Present" and submission.image_path and os.path.exists(submission.image_path):
+            try:
+                os.remove(submission.image_path)
+            except Exception as e:
+                logger.error("Failed to remove temp image %s: %s", submission.image_path, e, exc_info=True)
+
+        return attendance_record
+
+    async def analyze_attendance(self, submission: AttendanceSubmission) -> dict:
+        """Run all validation + AI scoring but do NOT save the record.
+
+        Returns a dict with scores, predicted status, and a short-lived
+        review_token that can be passed to mark_attendance to skip re-running AI.
+        """
+        from datetime import timedelta
+        from app.core.security import create_access_token
+
+        # ── Session validation ──────────────────────────────────────────────
+        session = None
+        redis_client = None
+        cache_key = f"session:{submission.session_id}"
+
+        try:
+            redis_client = get_redis()
+            cached = await redis_client.get(cache_key)
+            if cached:
+                data = json.loads(cached)
+                end_time_str = data["endTime"].replace("Z", "+00:00")
+                session = CachedSession(
+                    id=data["id"], is_active=data["isActive"],
+                    academic_class_id=data["academicClassId"],
+                    end_time=datetime.fromisoformat(end_time_str),
+                )
+        except Exception:
+            logger.warning("Redis session cache read failed. Falling back to DB.")
+
+        if not session:
+            session = await self.session_repo.get_by_id(submission.session_id)
+            if not session:
+                raise ValueError("Attendance session is not active or not found.")
+
+        now = datetime.now(timezone.utc)
+        session_end = session.endTime.replace(tzinfo=timezone.utc) if session.endTime.tzinfo is None else session.endTime
+        if not session.isActive or session_end <= now:
+            if session.isActive:
+                await self.session_repo.deactivate(session.id)
+                try:
+                    await get_redis().delete(f"session:{session.id}")
+                except Exception:
+                    pass
+            raise ValueError("Attendance session is not active or not found.")
+
+        config = await SystemConfigService().get_config()
+
+        # ── Geofence check ──────────────────────────────────────────────────
+        geofence_missing = False
+        if config.isGpsVerificationEnabled:
+            geofence = await self.geofence_repo.get_by_class_id(session.academicClassId)
+            if not geofence:
+                logger.warning("Missing geofence for class %s (student %s)", session.academicClassId, submission.student_id)
+                geofence_missing = True
+            else:
+                student_coord = GPSCoordinate(submission.latitude, submission.longitude)
+                classroom_coord = GPSCoordinate(geofence.latitude, geofence.longitude)
+                is_inside = is_within_geofence(
+                    student_coord=student_coord,
+                    classroom_coord=classroom_coord,
+                    base_radius=geofence.radiusMeters,
+                    student_accuracy=submission.accuracy,
+                )
+                if not is_inside:
+                    distance = calculate_haversine_distance(student_coord, classroom_coord)
+                    effective_radius = geofence.radiusMeters + submission.accuracy
+                    raise ValueError(
+                        f"Student is outside geofence boundary by {distance - effective_radius:.1f}m. "
+                        f"(Distance: {distance:.1f}m, Effective Allowed Radius: {effective_radius:.1f}m)"
+                    )
+
+        # ── Face embedding ──────────────────────────────────────────────────
+        if config.isFaceRecognitionEnabled:
+            face_embedding = await self.student_repo.get_face_embedding(submission.student_id)
+            if not face_embedding:
+                raise ValueError("Student face embedding is not registered.")
+        else:
+            face_embedding = []
+
+        # ── Duplicate check ─────────────────────────────────────────────────
+        existing = await self.attendance_repo.get_by_student_and_session(submission.student_id, submission.session_id)
+        if existing:
+            raise ValueError("Attendance already submitted for this session.")
+
+        # ── AI scoring ──────────────────────────────────────────────────────
+        if config.isFaceRecognitionEnabled or config.isAiBackgroundValidationEnabled:
+            if not submission.image_path:
+                raise ValueError("Image is required when verification is enabled.")
+            ai_results = await self.ai_orchestrator.analyze_attendance(submission.image_path, face_embedding)
+        else:
+            ai_results = {"face_score": 1.0, "liveness_score": 1.0, "background_score": 1.0}
+            
+        if not config.isFaceRecognitionEnabled:
+            ai_results["face_score"] = 1.0
+            ai_results["liveness_score"] = 1.0
+            
+        if not config.isAiBackgroundValidationEnabled:
+            ai_results["background_score"] = 1.0
+        final_score = (
+            settings.FACE_WEIGHT * ai_results["face_score"]
+            + settings.LIVENESS_WEIGHT * ai_results["liveness_score"]
+            + settings.BACKGROUND_WEIGHT * ai_results["background_score"]
+        )
+        predicted_status = "Flagged" if geofence_missing else ("Present" if final_score >= settings.PASS_THRESHOLD else "Flagged")
+
+        # ── Build review token (5-minute TTL) ───────────────────────────────
+        review_token = create_access_token(
+            subject=submission.student_id,
+            role="STUDENT",
+            expires_delta=timedelta(minutes=5),
+            extra_data={
+                "type": "attendance_review",
+                "session_id": submission.session_id,
+                "face_score": ai_results["face_score"],
+                "liveness_score": ai_results["liveness_score"],
+                "background_score": ai_results["background_score"],
+                "final_ai_score": final_score,
+                "predicted_status": predicted_status,
+                "geofence_missing": geofence_missing,
+                "image_path": submission.image_path,
+                "latitude": submission.latitude,
+                "longitude": submission.longitude,
+            },
+        )
+
+        return {
+            "face_score": ai_results["face_score"],
+            "liveness_score": ai_results["liveness_score"],
+            "background_score": ai_results["background_score"],
+            "final_ai_score": final_score,
+            "predicted_status": predicted_status,
+            "review_token": review_token,
+        }
+
+    async def confirm_attendance(self, student_id: str, review_token: str) -> "Attendance":
+        """Confirm a previously analyzed submission using its review token.
+
+        Decodes the token, validates it, and saves the attendance record
+        without re-running AI inference.
+        """
+        from app.core.security import decode_access_token
+
+        payload = decode_access_token(review_token)
+        if not payload or payload.get("type") != "attendance_review":
+            raise ValueError("Invalid or expired review token.")
+        if payload.get("sub") != student_id:
+            raise ValueError("Review token does not belong to this student.")
+
+        session_id = payload["session_id"]
+
+        # Re-check duplicate (student might have confirmed twice)
+        existing = await self.attendance_repo.get_by_student_and_session(student_id, session_id)
+        if existing:
+            raise ValueError("Attendance already submitted for this session.")
+
+        # Re-check session still active
+        session = await self.session_repo.get_by_id(session_id)
+        if not session:
+            raise ValueError("Attendance session is no longer active.")
+
+        now = datetime.now(timezone.utc)
+        session_end = session.endTime.replace(tzinfo=timezone.utc) if session.endTime.tzinfo is None else session.endTime
+        if not session.isActive or session_end <= now:
+            if session.isActive:
+                await self.session_repo.deactivate(session.id)
+                try:
+                    await get_redis().delete(f"session:{session.id}")
+                except Exception:
+                    pass
+            raise ValueError("Attendance session is no longer active.")
+
+        face_score = payload["face_score"]
+        liveness_score = payload["liveness_score"]
+        background_score = payload["background_score"]
+        final_score = payload["final_ai_score"]
+        predicted_status = payload["predicted_status"]
+        geofence_missing = payload.get("geofence_missing", False)
+        image_path = payload["image_path"]
+        latitude = payload["latitude"]
+        longitude = payload["longitude"]
+        remarks = "Missing Geofence Data" if geofence_missing else None
+
+        attendance_record = await self.attendance_repo.create({
+            "studentId": student_id,
+            "sessionId": session_id,
+            "status": predicted_status,
+            "faceScore": face_score,
+            "livenessScore": liveness_score,
+            "backgroundScore": background_score,
+            "finalAiScore": final_score,
+            "gpsLatitude": latitude,
+            "gpsLongitude": longitude,
+            "remarks": remarks,
+        })
+
+        try:
+            msg = {"type": "attendance_updated", "session_id": session_id, "status": predicted_status}
+            await manager.send_personal_message(msg, student_id=student_id)
+            msg["student_id"] = student_id
+            await manager.broadcast_to_teachers(msg)
+        except Exception as e:
+            logger.warning("WebSocket broadcast failed: %s", e)
+
+        if predicted_status == "Flagged":
+            try:
+                from app.services.notification_service import notify_student_attendance_flagged
+                student = await self.student_repo.get_by_id(student_id)
+                if student and student.fcmToken:
+                    ac = await self.class_repo.get_by_id(session.academicClassId)
+                    class_name = ac.name if ac else "your class"
+                    await notify_student_attendance_flagged(student.fcmToken, student.firstName or "Student", class_name, attendance_record.id)
+            except Exception as e:
+                logger.warning("FCM notification failed: %s", e)
+
+        try:
+            from app.services.gamification_service import GamificationService
+            await GamificationService().update_streak(student_id, predicted_status)
+        except Exception as e:
+            logger.warning("Streak update failed: %s", e)
+
+        if predicted_status == "Present" and image_path and os.path.exists(image_path):
+            try:
+                os.remove(image_path)
+            except Exception as e:
+                logger.error("Failed to remove temp image %s: %s", image_path, e, exc_info=True)
+
+        return attendance_record
+
+    async def register_face(self, student_id: str, image_path: str) -> bool:
+        embedding = await self.ai_orchestrator.extract_face_embedding(image_path)
+        if not embedding:
+            return False
+        await self.student_repo.update_face_embedding(student_id, embedding)
+        return True
+
+    async def review_attendance(self, attendance_id: str, status: str, remarks: str) -> bool:
+        record = await self.attendance_repo.get_by_id(attendance_id)
+        if not record or record.status != "Flagged":
+            return False
+
+        await self.attendance_repo.update_review(attendance_id, status, remarks)
+
+        try:
+            msg = {"type": "attendance_updated", "session_id": record.sessionId, "status": status}
+            await manager.send_personal_message(msg, student_id=record.studentId)
+            msg["student_id"] = record.studentId
+            await manager.broadcast_to_teachers(msg)
+        except Exception as e:
+            logger.warning("WebSocket broadcast failed: %s", e)
+
+        try:
+            from app.services.notification_service import notify_student_attendance_reviewed
+            student = await self.student_repo.get_by_id(record.studentId)
+            if student and student.fcmToken:
+                ac = await self.class_repo.get_by_id(record.session.academicClassId if record.session else "")
+                class_name = ac.name if ac else "your class"
+                await notify_student_attendance_reviewed(student.fcmToken, status, class_name)
+        except Exception as e:
+            logger.warning("FCM notification failed: %s", e)
+
+        try:
+            from app.services.gamification_service import GamificationService
+            await GamificationService().recalculate_student_streak(record.studentId)
+        except Exception as e:
+            logger.warning("Failed to recalculate streak for student %s: %s", record.studentId, e)
+
+        return True

backend/app/services/auth_service.py

@@ -0,0 +1,56 @@
+from typing import Optional
+
+from fastapi import HTTPException, status
+
+from app.core.security import hash_password, verify_password, create_access_token
+from app.db.client import db
+from app.repositories.user_repo import UserRepository
+from app.repositories.student_repo import StudentRepository
+from app.repositories.teacher_repo import TeacherRepository
+from app.schemas.auth import Token, UserLogin
+from app.schemas.student import StudentCreate, StudentResponse
+from app.schemas.teacher import TeacherCreate, TeacherResponse
+
+
+class AuthService:
+    def __init__(self) -> None:
+        self.user_repo = UserRepository()
+        self.student_repo = StudentRepository()
+        self.teacher_repo = TeacherRepository()
+
+    async def authenticate(self, login_data: UserLogin) -> Optional[Token]:
+        user = await self.user_repo.get_by_email(login_data.email)
+        if not user or not verify_password(login_data.password, user.hashedPassword):
+            return None
+
+        if user.role == "STUDENT":
+            student = await self.student_repo.get_by_user_id(user.id)
+            if student and login_data.device_uuid:
+                if not student.deviceUuid:
+                    await db.student.update(
+                        where={"id": student.id}, data={"deviceUuid": login_data.device_uuid}
+                    )
+                elif student.deviceUuid != login_data.device_uuid:
+                    raise HTTPException(
+                        status_code=status.HTTP_403_FORBIDDEN,
+                        detail="Account is bound to another device.",
+                    )
+
+        token = create_access_token(subject=user.id, role=user.role)
+        return Token(access_token=token, token_type="bearer", role=user.role)
+
+    async def register_student(self, data: StudentCreate) -> Optional[StudentResponse]:
+        if await self.user_repo.get_by_email(data.email):
+            return None
+        hashed = hash_password(data.password)
+        user = await self.user_repo.create(email=data.email, password_hash=hashed, role="STUDENT")
+        student = await self.student_repo.create(user_id=user.id, enrollment=data.enrollment_number)
+        return StudentResponse(id=student.id, user_id=user.id, enrollment_number=student.enrollmentNumber, email=user.email)
+
+    async def register_teacher(self, data: TeacherCreate) -> Optional[TeacherResponse]:
+        if await self.user_repo.get_by_email(data.email):
+            return None
+        hashed = hash_password(data.password)
+        user = await self.user_repo.create(email=data.email, password_hash=hashed, role="TEACHER")
+        teacher = await self.teacher_repo.create(user_id=user.id, department=data.department_id, designation=data.designation_id)
+        return TeacherResponse(id=teacher.id, user_id=user.id, department=teacher.department, designation=teacher.designation, email=user.email)

backend/app/services/device_change_service.py

@@ -0,0 +1,105 @@
+from typing import List
+from fastapi import HTTPException, status
+from app.db.client import db
+from app.core.security import verify_password
+from app.repositories.user_repo import UserRepository
+from app.repositories.student_repo import StudentRepository
+from app.schemas.auth import DeviceChangeRequestCreate
+from app.schemas.teacher import DeviceChangeResponse
+
+class DeviceChangeService:
+    def __init__(self) -> None:
+        self.user_repo = UserRepository()
+        self.student_repo = StudentRepository()
+
+    async def request_device_change(self, data: DeviceChangeRequestCreate) -> None:
+        user = await self.user_repo.get_by_email(data.email)
+        if not user or not verify_password(data.password, user.hashedPassword) or user.role != "STUDENT":
+            raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid email or password")
+        
+        student = await self.student_repo.get_by_user_id(user.id)
+        if not student:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student record not found")
+
+        # Check if already has pending request
+        pending_request = await db.devicechangerequest.find_first(
+            where={
+                "studentId": student.id,
+                "status": "PENDING"
+            }
+        )
+
+        if pending_request:
+            # Update existing pending request
+            await db.devicechangerequest.update(
+                where={"id": pending_request.id},
+                data={
+                    "newDeviceUuid": data.new_device_uuid,
+                    "reason": data.reason
+                }
+            )
+        else:
+            # Create new request
+            await db.devicechangerequest.create(
+                data={
+                    "studentId": student.id,
+                    "newDeviceUuid": data.new_device_uuid,
+                    "reason": data.reason,
+                    "status": "PENDING"
+                }
+            )
+
+    async def get_pending_requests(self, teacher_id: str) -> List[DeviceChangeResponse]:
+        # For simplicity, returning all pending requests in the system.
+        # Ideally, we would filter by department or class.
+        records = await db.devicechangerequest.find_many(
+            where={"status": "PENDING"},
+            include={
+                "student": {
+                    "include": {
+                        "user": True
+                    }
+                }
+            },
+            order={"createdAt": "desc"}
+        )
+
+        response_list = []
+        for r in records:
+            name = f"{r.student.firstName or ''} {r.student.lastName or ''}".strip()
+            response_list.append(DeviceChangeResponse(
+                id=r.id,
+                student_id=r.studentId,
+                student_name=name or "Unknown",
+                enrollment_number=r.student.enrollmentNumber,
+                new_device_uuid=r.newDeviceUuid,
+                reason=r.reason,
+                status=r.status,
+                approved_by=r.approvedBy,
+                created_at=r.createdAt,
+                updated_at=r.updatedAt
+            ))
+        return response_list
+
+    async def approve_request(self, request_id: str, teacher_id: str, new_status: str) -> bool:
+        request_record = await db.devicechangerequest.find_unique(where={"id": request_id})
+        if not request_record or request_record.status != "PENDING":
+            return False
+
+        if new_status == "APPROVED":
+            # Update student device_uuid
+            await db.student.update(
+                where={"id": request_record.studentId},
+                data={"deviceUuid": request_record.newDeviceUuid}
+            )
+
+        # Update request status
+        await db.devicechangerequest.update(
+            where={"id": request_id},
+            data={
+                "status": new_status,
+                "approvedBy": teacher_id
+            }
+        )
+
+        return True

backend/app/services/gamification_service.py

@@ -0,0 +1,293 @@
+from datetime import datetime, timedelta, timezone
+from typing import Tuple
+
+from app.core.logging_config import get_logger
+from app.repositories.student_repo import StudentRepository
+from app.repositories.attendance_repo import AttendanceRepository
+
+logger = get_logger("app.gamification")
+
+
+class GamificationService:
+    def __init__(self):
+        self.student_repo = StudentRepository()
+        self.attendance_repo = AttendanceRepository()
+
+    async def update_streak(self, student_id: str, attendance_status: str) -> dict:
+        """Helper to compatibility-wrap recalculate_student_streak."""
+        return await self.recalculate_student_streak(student_id)
+
+    async def recalculate_student_streak(self, student_id: str) -> dict:
+        """Recalculate student streak based on historical attendance logs and active sessions."""
+        student = await self.student_repo.get_by_id(student_id)
+        if not student:
+            return {"error": "Student not found"}
+
+        from app.db.client import db
+        enrollments = await db.enrollment.find_many(where={"studentId": student_id})
+        class_ids = [e.academicClassId for e in enrollments]
+        
+        if not class_ids:
+            await self.student_repo.update_streak(student_id, 0, student.highestStreak or 0)
+            await self._update_redis_score(student_id, 0, student.highestStreak or 0)
+            return {"current_streak": 0, "highest_streak": student.highestStreak or 0}
+
+        now = datetime.now(timezone.utc)
+        
+        # Get all sessions that have already started
+        sessions = await db.session.find_many(
+            where={
+                "academicClassId": {"in": class_ids},
+                "startTime": {"lte": now}
+            },
+            order={"startTime": "desc"}
+        )
+
+        attendance = await db.attendance.find_many(where={"studentId": student_id})
+        attendance_map = {a.sessionId: a for a in attendance}
+        
+        leaves = await db.leaverequest.find_many(where={"studentId": student_id, "status": "APPROVED"})
+
+        def is_on_leave(session_start: datetime) -> bool:
+            s_start = session_start.replace(tzinfo=timezone.utc) if session_start.tzinfo is None else session_start
+            for leave in leaves:
+                l_start = leave.startDate.replace(tzinfo=timezone.utc) if leave.startDate.tzinfo is None else leave.startDate
+                l_end = leave.endDate.replace(tzinfo=timezone.utc) if leave.endDate.tzinfo is None else leave.endDate
+                if l_start <= s_start <= l_end:
+                    return True
+            return False
+
+        # Filter out active sessions where student hasn't checked in yet
+        valid_sessions = []
+        for s in sessions:
+            s_end = s.endTime.replace(tzinfo=timezone.utc) if s.endTime.tzinfo is None else s.endTime
+            is_active = s.isActive and s_end > now
+            has_checked_in = s.id in attendance_map and attendance_map[s.id].status in ("Present", "Approved")
+            
+            if is_active and not has_checked_in:
+                continue
+            valid_sessions.append(s)
+
+        # 1. Current streak calculation (descending order)
+        current_streak = 0
+        for s in valid_sessions:
+            att = attendance_map.get(s.id)
+            status = att.status if att else None
+
+            if status in ("Present", "Approved"):
+                current_streak += 1
+            elif is_on_leave(s.startTime):
+                continue
+            elif status == "Flagged":
+                continue
+            else:
+                break
+
+        # 2. Highest streak calculation (ascending order)
+        highest_streak = student.highestStreak or 0
+        running_streak = 0
+        for s in reversed(valid_sessions):
+            att = attendance_map.get(s.id)
+            status = att.status if att else None
+
+            if status in ("Present", "Approved"):
+                running_streak += 1
+                highest_streak = max(highest_streak, running_streak)
+            elif is_on_leave(s.startTime):
+                continue
+            elif status == "Flagged":
+                continue
+            else:
+                running_streak = 0
+
+        highest_streak = max(highest_streak, current_streak)
+
+        await self.student_repo.update_streak(student_id, current_streak, highest_streak)
+        await self._update_redis_score(student_id, current_streak, highest_streak)
+        return {"current_streak": current_streak, "highest_streak": highest_streak}
+
+    async def calculate_consecutive_absences(self, student_id: str, days: int = 3) -> int:
+        end = datetime.now(timezone.utc)
+        records = await self.attendance_repo.get_by_student_in_date_range(
+            student_id=student_id, start_date=end - timedelta(days=7), end_date=end
+        )
+        consecutive = 0
+        for record in sorted(records, key=lambda r: r.createdAt, reverse=True):
+            if record.status == "Absent":
+                consecutive += 1
+            else:
+                break
+        return consecutive
+
+    async def get_student_stats(self, student_id: str) -> dict:
+        student = await self.student_repo.get_by_id(student_id)
+        if not student:
+            return {}
+
+        all_records = await self.attendance_repo.get_by_student_id(student_id)
+        total = len(all_records)
+        present = sum(1 for r in all_records if r.status in ("Present", "Approved"))
+        absent = sum(1 for r in all_records if r.status == "Absent")
+        flagged = sum(1 for r in all_records if r.status == "Flagged")
+        excused = sum(1 for r in all_records if r.status == "Excused")
+
+        return {
+            "current_streak": student.currentStreak or 0,
+            "highest_streak": student.highestStreak or 0,
+            "total_classes": total,
+            "present_count": present,
+            "absent_count": absent,
+            "flagged_count": flagged,
+            "excused_count": excused,
+            "attendance_percentage": round((present / total * 100) if total > 0 else 0, 2),
+        }
+
+    def _get_redis_client(self):
+        """Return the active Redis client if available."""
+        try:
+            from app.db.redis import get_redis
+            return get_redis()
+        except Exception as e:
+            logger.warning("Redis client not available: %s", e)
+            return None
+
+    async def _update_redis_score(self, student_id: str, current_streak: int, highest_streak: int) -> None:
+        """Update a student's score in the Redis leaderboard."""
+        try:
+            redis = self._get_redis_client()
+            if redis:
+                all_records = await self.attendance_repo.get_by_student_id(student_id)
+                present_count = sum(1 for r in all_records if r.status in ("Present", "Approved"))
+                new_points = present_count * 50 + highest_streak * 100 + current_streak * 20
+                await redis.zadd("leaderboard:points", {student_id: float(new_points)})
+        except Exception as e:
+            logger.warning("Failed to update leaderboard cache: %s", e)
+
+    async def get_leaderboard(self, current_student_id: str) -> dict:
+        """Fetch the leaderboard from Redis, falling back to DB if empty."""
+        redis = self._get_redis_client()
+        cache_key = "leaderboard:points"
+        
+        try:
+            if redis and not await redis.exists(cache_key):
+                await self._rebuild_leaderboard_cache(redis, cache_key)
+        except Exception as e:
+            logger.warning("Redis operation failed in leaderboard check: %s", e)
+
+        leaderboard_data = []
+        if redis:
+            leaderboard_data = await self._fetch_leaderboard_from_cache(redis, cache_key)
+
+        if not leaderboard_data:
+            return await self._get_leaderboard_from_db(current_student_id)
+
+        user_rank, user_points = await self._fetch_user_rank_and_points(redis, cache_key, current_student_id)
+        return {
+            "leaderboard": leaderboard_data,
+            "user_rank": user_rank,
+            "user_points": user_points
+        }
+
+    async def _rebuild_leaderboard_cache(self, redis, cache_key: str) -> None:
+        """Rebuild the leaderboard cache from DB data."""
+        if not redis:
+            return
+        try:
+            from app.db.client import db
+            students = await db.student.find_many(
+                where={"user": {"is": {"isActive": True}}},
+                include={"attendance": True}
+            )
+            scores_dict = {}
+            for s in students:
+                present_count = sum(1 for r in s.attendance if r.status in ("Present", "Approved"))
+                points = present_count * 50 + (s.highestStreak or 0) * 100 + (s.currentStreak or 0) * 20
+                scores_dict[s.id] = float(points)
+            if scores_dict:
+                await redis.zadd(cache_key, scores_dict)
+                await redis.expire(cache_key, 3600)
+        except Exception as e:
+            logger.error("Failed to rebuild leaderboard cache: %s", e, exc_info=True)
+
+    async def _fetch_leaderboard_from_cache(self, redis, cache_key: str) -> list:
+        """Fetch top 10 students from Redis cache and load details from DB."""
+        try:
+            top_members = await redis.zrevrange(cache_key, 0, 9, withscores=True)
+            if not top_members:
+                return []
+            top_ids = [m[0] for m in top_members]
+            from app.db.client import db
+            top_students = await db.student.find_many(where={"id": {"in": top_ids}})
+            students_map = {s.id: s for s in top_students}
+            
+            leaderboard_data = []
+            for s_id, score in top_members:
+                s = students_map.get(s_id)
+                if s:
+                    name = f"{s.firstName or ''} {s.lastName or ''}".strip() or "Student"
+                    leaderboard_data.append({
+                        "student_id": s_id,
+                        "name": name,
+                        "points": int(score),
+                        "current_streak": s.currentStreak or 0,
+                    })
+            return leaderboard_data
+        except Exception as e:
+            logger.error("Failed to fetch leaderboard from cache: %s", e, exc_info=True)
+            return []
+
+    async def _fetch_user_rank_and_points(self, redis, cache_key: str, student_id: str) -> Tuple[int | None, int]:
+        """Fetch rank and points for a specific user from Redis."""
+        if not redis:
+            return None, 0
+        try:
+            current_rank_0 = await redis.zrevrank(cache_key, student_id)
+            user_rank = current_rank_0 + 1 if current_rank_0 is not None else None
+            current_score = await redis.zscore(cache_key, student_id)
+            user_points = int(current_score) if current_score is not None else 0
+            return user_rank, user_points
+        except Exception as e:
+            logger.warning("Failed to fetch user rank from Redis: %s", e)
+            return None, 0
+
+    async def _get_leaderboard_from_db(self, current_student_id: str) -> dict:
+        """Generate leaderboard directly from database query (fallback)."""
+        try:
+            from app.db.client import db
+            students = await db.student.find_many(
+                where={"user": {"is": {"isActive": True}}},
+                include={"attendance": True}
+            )
+            student_list = []
+            for s in students:
+                present_count = sum(1 for r in s.attendance if r.status in ("Present", "Approved"))
+                points = present_count * 50 + (s.highestStreak or 0) * 100 + (s.currentStreak or 0) * 20
+                student_list.append((s, points))
+            
+            student_list.sort(key=lambda x: x[1], reverse=True)
+            
+            leaderboard_data = []
+            for s, points in student_list[:10]:
+                name = f"{s.firstName or ''} {s.lastName or ''}".strip() or "Student"
+                leaderboard_data.append({
+                    "student_id": s.id,
+                    "name": name,
+                    "points": points,
+                    "current_streak": s.currentStreak or 0,
+                })
+            
+            user_rank = None
+            user_points = 0
+            for index, (s, points) in enumerate(student_list):
+                if s.id == current_student_id:
+                    user_rank = index + 1
+                    user_points = points
+                    break
+            return {
+                "leaderboard": leaderboard_data,
+                "user_rank": user_rank,
+                "user_points": user_points
+            }
+        except Exception as e:
+            logger.error("Database fallback leaderboard query failed: %s", e, exc_info=True)
+            return {"leaderboard": [], "user_rank": None, "user_points": 0}

backend/app/services/leave_service.py

@@ -0,0 +1,65 @@
+from typing import Optional
+
+from prisma.models import LeaveRequest
+
+from app.core.logging_config import get_logger
+from app.repositories.leave_repo import LeaveRepository
+from app.repositories.attendance_repo import AttendanceRepository
+from app.repositories.enrollment_repo import EnrollmentRepository
+from app.repositories.session_repo import SessionRepository
+
+logger = get_logger("app.leave_service")
+
+
+class LeaveService:
+    def __init__(self):
+        self.leave_repo = LeaveRepository()
+        self.attendance_repo = AttendanceRepository()
+        self.enrollment_repo = EnrollmentRepository()
+        self.session_repo = SessionRepository()
+
+    async def approve_leave(self, leave_id: str, teacher_id: str, status: str, approver_note: Optional[str] = None) -> Optional[LeaveRequest]:
+        leave = await self.leave_repo.get_by_id(leave_id)
+        if not leave:
+            return None
+
+        updated_leave = await self.leave_repo.update_status(
+            leave_id=leave_id, status=status, approved_by=teacher_id, approver_note=approver_note
+        )
+
+        if status == "APPROVED":
+            await self._mark_excused_attendance(leave)
+            logger.info("Leave approved: student=%s dates=%s to %s", leave.studentId, leave.startDate, leave.endDate)
+
+        try:
+            from app.services.notification_service import notify_student_leave_status
+            if leave.student and leave.student.fcmToken:
+                await notify_student_leave_status(leave.student.fcmToken, status)
+        except Exception as e:
+            logger.warning("FCM notification failed: %s", e)
+
+        return updated_leave
+
+    async def _mark_excused_attendance(self, leave: LeaveRequest):
+        sessions = await self.session_repo.get_sessions_in_date_range(
+            start_date=leave.startDate, end_date=leave.endDate
+        )
+        enrollments = await self.enrollment_repo.get_by_student_id(leave.studentId)
+        enrolled_class_ids = {e.academicClassId for e in enrollments}
+        relevant_sessions = [s for s in sessions if s.academicClassId in enrolled_class_ids]
+
+        for session in relevant_sessions:
+            existing = await self.attendance_repo.get_by_student_and_session(
+                student_id=leave.studentId, session_id=session.id
+            )
+            data = {"status": "Excused", "remarks": f"Approved leave: {leave.reason}"}
+            if existing:
+                await self.attendance_repo.update(attendance_id=existing.id, data=data)
+            else:
+                await self.attendance_repo.create({
+                    "studentId": leave.studentId, "sessionId": session.id,
+                    "faceScore": 0.0, "livenessScore": 0.0, "backgroundScore": 0.0,
+                    "finalAiScore": 0.0, "gpsLatitude": 0.0, "gpsLongitude": 0.0,
+                    **data,
+                })
+

backend/app/services/notification_service.py

@@ -0,0 +1,70 @@
+import asyncio
+from typing import Optional
+
+from app.core.logging_config import get_logger
+
+logger = get_logger("app.notification")
+
+try:
+    import firebase_admin
+    from firebase_admin import credentials, messaging
+
+    _cred_path = "firebase-credentials.json"
+    try:
+        if not firebase_admin._apps:
+            cred = credentials.Certificate(_cred_path)
+            firebase_admin.initialize_app(cred)
+        _fcm_available = True
+        logger.info("Firebase Admin SDK initialized successfully")
+    except Exception as e:
+        _fcm_available = False
+        logger.warning("Firebase Admin SDK not available: %s. Push notifications disabled.", e)
+
+except ImportError:
+    _fcm_available = False
+    logger.info("firebase-admin not installed. Push notifications disabled.")
+
+
+async def send_push_notification(token: str, title: str, body: str, data: Optional[dict] = None) -> bool:
+    if not _fcm_available or not token:
+        return False
+
+    try:
+        message = messaging.Message(
+            notification=messaging.Notification(title=title, body=body),
+            data={k: str(v) for k, v in (data or {}).items()},
+            token=token,
+        )
+        response = await asyncio.to_thread(messaging.send, message)
+        logger.info("FCM sent: %s", response)
+        return True
+    except Exception as e:
+        logger.warning("FCM send failed: %s", e)
+        return False
+
+
+async def notify_student_attendance_flagged(student_fcm_token: str, student_name: str, class_name: str, attendance_id: str):
+    await send_push_notification(
+        token=student_fcm_token,
+        title="Attendance Flagged",
+        body=f"Hi {student_name}, your attendance for {class_name} has been flagged and requires review.",
+        data={"route": "/flagged_detail", "attendance_id": attendance_id},
+    )
+
+
+async def notify_student_attendance_reviewed(student_fcm_token: str, status: str, class_name: str):
+    await send_push_notification(
+        token=student_fcm_token,
+        title=f"Attendance {status}",
+        body=f"Your attendance for {class_name} has been reviewed and marked as {status}.",
+        data={"route": "/history"},
+    )
+
+
+async def notify_student_leave_status(student_fcm_token: str, status: str):
+    await send_push_notification(
+        token=student_fcm_token,
+        title=f"Leave {status}",
+        body=f"Your leave request has been {status.lower()}.",
+        data={"route": "/leave/history"},
+    )

backend/app/services/session_service.py

@@ -0,0 +1,115 @@
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+
+from app.core.logging_config import get_logger
+from app.db.redis import get_redis
+from app.repositories.session_repo import SessionRepository
+from app.repositories.class_repo import ClassRepository
+from app.schemas.teacher import SessionResponse, SessionStart
+
+logger = get_logger("app.session")
+
+
+class SessionService:
+    def __init__(self) -> None:
+        self.session_repo = SessionRepository()
+        self.class_repo = ClassRepository()
+
+    async def start_session(self, data: SessionStart, teacher_id: str) -> Optional[SessionResponse]:
+        subject_class = await self.class_repo.get_by_id(data.academic_class_id)
+        if not subject_class or subject_class.teacherId != teacher_id:
+            return None
+
+        active = await self.session_repo.get_active_session_by_class(data.academic_class_id)
+        if active:
+            await self.close_session(active.id)
+
+        now = datetime.now(timezone.utc)
+        session = await self.session_repo.create(
+            class_id=data.academic_class_id, start_time=now, end_time=now + timedelta(minutes=data.duration_minutes)
+        )
+        return SessionResponse.model_validate(session)
+
+    async def stop_session(self, session_id: str, teacher_id: str) -> bool:
+        session = await self.session_repo.get_by_id(session_id)
+        if not session or not session.isActive:
+            return False
+
+        subject_class = await self.class_repo.get_by_id(session.academicClassId)
+        if not subject_class or subject_class.teacherId != teacher_id:
+            return False
+
+        await self.close_session(session_id)
+        return True
+
+    async def close_session(self, session_id: str) -> None:
+        """Mark session as inactive, delete from Redis, and mark all unsubmitted students as Absent or Excused."""
+        session = await self.session_repo.get_by_id(session_id)
+        if not session or not session.isActive:
+            return
+
+        # 1. Deactivate in DB
+        await self.session_repo.deactivate(session_id)
+
+        # 2. Delete from Redis
+        try:
+            await get_redis().delete(f"session:{session_id}")
+        except Exception as e:
+            logger.warning("Failed to delete session from Redis: %s", e)
+
+        # 3. Get enrollments and existing attendance
+        from app.db.client import db
+        from app.services.gamification_service import GamificationService
+        
+        enrollments = await db.enrollment.find_many(
+            where={"academicClassId": session.academicClassId},
+            include={"student": {"include": {"leaveRequests": True}}}
+        )
+        
+        attendance_records = await db.attendance.find_many(where={"sessionId": session_id})
+        submitted_student_ids = {a.studentId for a in attendance_records}
+
+        gamification_service = GamificationService()
+        sess_start = session.startTime.replace(tzinfo=timezone.utc) if session.startTime.tzinfo is None else session.startTime
+
+        for enrollment in enrollments:
+            student = enrollment.student
+            if not student or student.id in submitted_student_ids:
+                continue
+
+            # Check if student was on approved leave during the session
+            on_leave = False
+            for leave in student.leaveRequests:
+                if leave.status == "APPROVED":
+                    l_start = leave.startDate.replace(tzinfo=timezone.utc) if leave.startDate.tzinfo is None else leave.startDate
+                    l_end = leave.endDate.replace(tzinfo=timezone.utc) if leave.endDate.tzinfo is None else leave.endDate
+                    if l_start <= sess_start <= l_end:
+                        on_leave = True
+                        break
+
+            # Create the record
+            status_val = "Excused" if on_leave else "Absent"
+            remarks_val = "Excused via approved leave request" if on_leave else "Session ended without student submission"
+            
+            try:
+                await db.attendance.create(data={
+                    "studentId": student.id,
+                    "sessionId": session_id,
+                    "status": status_val,
+                    "faceScore": 0.0,
+                    "livenessScore": 0.0,
+                    "backgroundScore": 0.0,
+                    "finalAiScore": 0.0,
+                    "gpsLatitude": 0.0,
+                    "gpsLongitude": 0.0,
+                    "remarks": remarks_val,
+                })
+            except Exception as e:
+                logger.warning("Failed to create default attendance for student %s: %s", student.id, e)
+                continue
+
+            # Recalculate streak
+            try:
+                await gamification_service.recalculate_student_streak(student.id)
+            except Exception as e:
+                logger.warning("Failed to recalculate streak for student %s: %s", student.id, e)