Just to stash

src/auth.py

@@ -1,205 +0,0 @@
-from fastapi import HTTPException, status, Header, Depends
-from fastapi.security import OAuth2PasswordBearer
-from fastapi.concurrency import run_in_threadpool # For calling sync crud in async auth
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-
-from src import crud, models 
-
-from src.database import get_db
-from typing import Optional, Dict, Any # Added Any
-from datetime import datetime, timedelta
-from typing import Union # For type hinting
-from jose import JWTError, jwt
-from passlib.context import CryptContext
-
-# JWT Configuration - Loaded from models.py (which loads from .env)
-SECRET_KEY = models.JWT_SECRET_KEY
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 30
-
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/token/login") # Path to token endpoint
-
-pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto") # Password hashing context
-# Password hashing context from models.py
-
-def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """
-    Verifies a plain password against a hashed password.
-    Uses the CryptContext to verify the password.
-    """
-    return pwd_context.verify(plain_password, hashed_password)
-
-def get_password_hash(password: str) -> str:
-    """
-    Hashes a password using the CryptContext.
-    This is used when creating or updating user passwords.
-    """
-    return pwd_context.hash(password)
-
-
-# --- JWT Helper Functions ---
-def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
-    to_encode = data.copy()
-    if expires_delta:
-        expire = datetime.utcnow() + expires_delta
-    else:
-        expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
-    to_encode.update({"exp": expire, "iat": datetime.utcnow()}) # Add issued_at time
-    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
-    return encoded_jwt
-
-
-async def get_current_user_from_token(
-    token: str = Depends(oauth2_scheme),
-    db: SQLAlchemySessionType = Depends(get_db)
-) -> models.User: # Now aims to return the ORM User model
-    credentials_exception = HTTPException(
-        status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Could not validate credentials",
-        headers={"WWW-Authenticate": "Bearer"},
-    )
-    try:
-        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
-        username: Optional[str] = payload.get("sub")
-        if username is None:
-            raise credentials_exception
-        token_data = models.TokenData(username=username) # Use if TokenData has more fields
-    except jwt.ExpiredSignatureError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Token has expired",
-            headers={"WWW-Authenticate": "Bearer"},)
-    except jwt.PyJWTError:
-        raise credentials_exception
-    
-    # User is fetched using sync ORM function, so run in threadpool if this dep is used by async endpoint
-    user_orm = await run_in_threadpool(crud.get_user_by_username, db, username)
-    if user_orm is None:
-        raise credentials_exception
-    return user_orm # Return the ORM model instance
-
-async def get_current_active_user(
-    current_user: models.User = Depends(get_current_user_from_token)
-) -> models.User: # Expects and returns ORM User
-    if not current_user.is_active:
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Inactive user")
-    return current_user
-
-async def get_current_active_staff_user_from_token(
-    current_user: models.User = Depends(get_current_active_user)
-) -> models.User: # Expects and returns ORM User
-    if current_user.role not in [models.UserRole.STAFF, models.UserRole.ADMIN]:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Staff or admin access required")
-    return current_user
-
-async def get_current_active_admin_user_from_token(
-    current_user: models.User = Depends(get_current_active_user)
-) -> models.User: # Expects and returns ORM User
-    if current_user.role != models.UserRole.ADMIN:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required")
-    return current_user
-
-# Dependency to get and verify API key from header (Device Authentication)
-async def get_verified_device(
-    x_api_key: str = Header(..., description="The API Key for the ESP32 device."),
-    db: SQLAlchemySessionType = Depends(get_db)
-) -> models.Device: # Returns the ORM Device model
-    """
-    Verifies API key and returns the active ORM Device model.
-    """
-    if not x_api_key:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing API key")
-    
-    # Use run_in_threadpool as crud.get_device_by_api_key is sync
-    device_orm = await run_in_threadpool(crud.get_device_by_api_key, db, x_api_key)
-
-    if not device_orm:
-        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid API Key.")
-    if not device_orm.is_active:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Device is not active.")
-    return device_orm
-
-
-def authenticate_user(
-    username: str,
-    password: str,
-    db: SQLAlchemySessionType = Depends(get_db)
-) -> models.User: # Returns ORM User model
-    """
-    Authenticates a user by username and password.
-    Returns the ORM User model if successful, raises HTTPException otherwise.
-    """
-    user = crud.get_user_by_username(db, username)
-    
-    if not user:
-        return None  # User not found, return None
-    
-    is_password_valid = verify_password(password, user.hashed_password)
-    if not is_password_valid:
-        return None
-
-    return user  # Return the ORM User model if password is valid
-
-# Tag-based authentication (User/Student Authentication via RFID tag)
-async def authenticate_tag_user_or_student( # Renamed for clarity
-    tag_id: str = Header(..., alias="X-User-Tag-ID", description="RFID Tag ID of the user or student"),
-    db: SQLAlchemySessionType = Depends(get_db)
-) -> Union[models.Student, models.User]: # Returns Student or User ORM model
-    """
-    Authenticates a tag and returns the corresponding Student or User ORM model.
-    Used as a base for tag-based auth dependencies.
-    """
-    # Run sync ORM calls in threadpool
-    student_orm = await run_in_threadpool(crud.get_student_by_tag_id, db, tag_id)
-    if student_orm:
-        return student_orm # Return Student ORM model
-    
-    user_orm = await run_in_threadpool(crud.get_user_by_tag_id, db, tag_id) # get_user_by_tag_id checks is_active
-    if user_orm: # user_orm already checked for is_active in CRUD
-        return user_orm # Return User ORM model
-    
-    raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tag not registered or associated user/student is inactive.")
-
-# Dependency for current student via Tag ID
-async def get_current_student_via_tag(
-    authenticated_entity: Union[models.Student, models.User] = Depends(authenticate_tag_user_or_student)
-) -> models.Student:
-    if not isinstance(authenticated_entity, models.Student):
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Access restricted to students only.")
-    return authenticated_entity
-
-# Dependency for current staff or admin via Tag ID
-async def get_current_staff_or_admin_via_tag(
-    authenticated_entity: Union[models.Student, models.User] = Depends(authenticate_tag_user_or_student)
-) -> models.User:
-    if not isinstance(authenticated_entity, models.User): # It's a student
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Staff or admin access required.")
-    # authenticated_entity is User ORM model
-    if authenticated_entity.role not in [models.UserRole.STAFF, models.UserRole.ADMIN]:
-        # This case should ideally not be hit if authenticate_tag_user_or_student is correct
-        # and users fetched by tag are always staff/admin.
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="User role is not staff or admin.")
-    if not authenticated_entity.is_active: # Double check, though crud.get_user_by_tag_id should handle this
-        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="User is inactive.")
-    return authenticated_entity
-
-# Dependency for current admin via Tag ID
-async def get_current_admin_via_tag(
-    current_user: models.User = Depends(get_current_staff_or_admin_via_tag) # Leverages the staff_or_admin check
-) -> models.User:
-    if current_user.role != models.UserRole.ADMIN:
-        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required.")
-    return current_user
-
-
-# Department Access Verification (this is a utility, not a dependency itself)
-def verify_department_access( # Made sync as it's pure logic
-    user_role: models.UserRole,
-    user_department: Optional[models.ClearanceDepartment],
-    target_department: models.ClearanceDepartment
-) -> bool:
-    if user_role == models.UserRole.ADMIN:
-        return True
-    if user_role == models.UserRole.STAFF:
-        return user_department == target_department
-    return False

src/config.py

@@ -1,15 +0,0 @@
-from pydantic_settings import BaseSettings
-import os
-from dotenv import load_dotenv
-
-load_dotenv()
-
-class Settings(BaseSettings):
-    POSTGRES_URI: str
-    JWT_SECRET_KEY: str = os.getenv("JWT_SECRET_KEY", "default_secret_key")
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 30
-    
-    class Config:
-        env_file = ".env"
-
-settings = Settings()

src/crud/__init__.py

@@ -1,83 +0,0 @@
-"""
-CRUD Package Initializer
-
-This file makes the 'crud' directory a Python package and imports all the
-public CRUD functions from the submodules. This allows you to import any
-CRUD function directly from `src.crud` instead of the specific submodule,
-keeping the router imports clean.
-"""
-
-from .students import (
-    create_student,
-    get_all_students,
-    get_student_by_student_id,
-    get_student_by_tag_id,
-    update_student_tag_id,
-    delete_student,
-)
-from .users import (
-    create_user,
-    get_user_by_username,
-    get_user_by_tag_id,
-    update_user_tag_id,
-    get_user_by_id,
-    delete_user,
-    hash_password,  # Import hash_password from users module
-    get_all_users
-)
-from .devices import (
-    get_device_by_id_str,
-    get_device_by_api_key,
-    create_device_log,
-    update_device_last_seen,
-    delete_device,
-)
-from .clearance import (
-    get_clearance_statuses_by_student_id,
-    update_clearance_status,
-    delete_clearance_status,
-    get_all_clearance_status,
-    get_student_clearance_status
-)
-from .tag_linking import (
-    create_pending_tag_link,
-    get_pending_link_by_id,
-    delete_pending_link_by_device_id,
-    get_pending_links,
-)
-
-# Export all functions
-__all__ = [
-    # Users
-    'create_user',
-    'get_user_by_username',
-    'get_user_by_tag_id',
-    'update_user_tag_id',
-    'get_user_by_id',
-    'delete_user',
-    'hash_password',
-    'get_all_users',
-    # Students
-    'create_student',
-    'get_all_students',
-    'get_student_by_student_id',
-    'get_student_by_tag_id',
-    'update_student_tag_id',
-    'delete_student',
-    # Devices
-    'get_device_by_id_str',
-    'get_device_by_api_key',
-    'create_device_log',
-    'update_device_last_seen',
-    'delete_device',
-    # Clearance
-    'get_clearance_statuses_by_student_id',
-    'update_clearance_status',
-    'delete_clearance_status',
-    # Tag Linking
-    'create_pending_tag_link',
-    'get_pending_link_by_device_id',
-    'get_pending_link_by_token',
-    'delete_pending_link_by_id',
-    'get_all_pending_links',
-]

src/crud/clearance.py

@@ -1,102 +0,0 @@
-"""
-CRUD operations for student Clearance Statuses.
-"""
-from sqlalchemy.orm import Session
-from fastapi import HTTPException, status
-
-from src import models
-
-def get_clearance_statuses_by_student_id(db: Session, student_id: str) -> list[models.ClearanceStatus]:
-    """
-    Fetches all existing clearance status records for a given student.
-    """
-    return db.query(models.ClearanceStatus).filter(models.ClearanceStatus.student_id == student_id).all()
-
-def update_clearance_status(
-    db: Session,
-    student_id: str,
-    department: models.ClearanceDepartment,
-    new_status: models.ClearanceStatusEnum,
-    remarks: str,
-    cleared_by_user_id: int
-) -> models.ClearanceStatus:
-    """
-    Updates or creates a clearance status for a student in a specific department.
-    """
-    student = db.query(models.Student).filter(models.Student.student_id == student_id).first()
-    if not student:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Student with ID '{student_id}' not found."
-        )
-
-    existing_status = db.query(models.ClearanceStatus).filter(
-        models.ClearanceStatus.student_id == student_id,
-        models.ClearanceStatus.department == department
-    ).first()
-
-    if existing_status:
-        existing_status.status = new_status
-        existing_status.remarks = remarks
-        existing_status.cleared_by = cleared_by_user_id
-        db_status = existing_status
-    else:
-        db_status = models.ClearanceStatus(
-            student_id=student_id,
-            department=department,
-            status=new_status,
-            remarks=remarks,
-            cleared_by=cleared_by_user_id
-        )
-        db.add(db_status)
-
-    db.commit()
-    db.refresh(db_status)
-    return db_status
-
-def delete_clearance_status(
-    db: Session,
-    student_id: str,
-    department: models.ClearanceDepartment
-) -> models.ClearanceStatus | None:
-    """
-    Deletes a specific clearance status record for a student.
-
-    This effectively resets the status for that department to the default state.
-    Returns the deleted object if found, otherwise returns None.
-    """
-    status_to_delete = db.query(models.ClearanceStatus).filter(
-        models.ClearanceStatus.student_id == student_id,
-        models.ClearanceStatus.department == department
-    ).first()
-
-    if status_to_delete:
-        db.delete(status_to_delete)
-        db.commit()
-
-    return status_to_delete
-
-
-def get_all_clearance_status(db: Session) -> list[models.ClearanceStatus]:
-    """
-    Retrieves all clearance statuses from the database.
-    
-    This function is useful for administrative purposes, allowing staff to view
-    all clearance records across all students and departments.
-    """
-    return db.query(models.ClearanceStatus).all()
-
-def get_student_clearance_status(
-    db: Session,
-    student_id: str,
-    department: models.ClearanceDepartment
-) -> models.ClearanceStatus | None:
-    """
-    Retrieves the clearance status for a specific student in a specific department.
-    
-    Returns None if no status exists for that student and department.
-    """
-    return db.query(models.ClearanceStatus).filter(
-        models.ClearanceStatus.student_id == student_id,
-        models.ClearanceStatus.department == department
-    ).first()

src/crud/devices.py

@@ -1,52 +0,0 @@
-"""
-CRUD operations for Devices and Device Logs.
-"""
-from sqlalchemy.orm import Session
-from datetime import datetime
-from fastapi import HTTPException, status
-
-from src import models
-
-def get_device_by_id_str(db: Session, device_id: str) -> models.Device | None:
-    """Fetches a device by its public device_id string."""
-    return db.query(models.Device).filter(models.Device.device_id == device_id).first()
-
-def get_device_by_api_key(db: Session, api_key: str) -> models.Device | None:
-    """Fetches a device by its unique API key for authentication."""
-    return db.query(models.Device).filter(models.Device.api_key == api_key).first()
-
-def update_device_last_seen(db: Session, device_id: int):
-    """Updates the last_seen timestamp for a device."""
-    db.query(models.Device).filter(models.Device.id == device_id).update({"last_seen": datetime.utcnow()})
-    db.commit()
-
-def create_device_log(db: Session, log_data: dict):
-    """Creates a new log entry for a device action."""
-    new_log = models.DeviceLog(**log_data)
-    db.add(new_log)
-    db.commit()
-    db.refresh(new_log)
-    return new_log
-
-def delete_device(db: Session, device_id_str: str) -> models.Device:
-    """
-    Deletes a device and all of its associated records (logs, pending links).
-    """
-    device_to_delete = get_device_by_id_str(db, device_id_str)
-    if not device_to_delete:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Device with ID '{device_id_str}' not found."
-        )
-    
-    device_pk_id = device_to_delete.id
-
-    # Delete all dependent records first to maintain foreign key integrity
-    db.query(models.DeviceLog).filter(models.DeviceLog.device_fk_id == device_pk_id).delete(synchronize_session=False)
-    db.query(models.PendingTagLink).filter(models.PendingTagLink.device_id_fk == device_pk_id).delete(synchronize_session=False)
-
-    # Now delete the device itself
-    db.delete(device_to_delete)
-    db.commit()
-
-    return device_to_delete

src/crud/students.py

@@ -1,79 +0,0 @@
-"""
-CRUD operations for Students.
-"""
-from sqlalchemy.orm import Session
-from fastapi import HTTPException, status
-
-from src import models
-
-def get_student_by_student_id(db: Session, student_id: str) -> models.Student | None:
-    """Fetches a student by their unique student ID."""
-    return db.query(models.Student).filter(models.Student.student_id == student_id).first()
-
-def get_student_by_tag_id(db: Session, tag_id: str) -> models.Student | None:
-    """Fetches a student by their RFID tag ID."""
-    return db.query(models.Student).filter(models.Student.tag_id == tag_id).first()
-
-def get_all_students(db: Session, skip: int = 0, limit: int = 100) -> list[models.Student]:
-    """Fetches all students with pagination."""
-    return db.query(models.Student).offset(skip).limit(limit).all()
-
-def create_student(db: Session, student: models.StudentCreate) -> models.Student:
-    """Creates a new student in the database."""
-    db_student = get_student_by_student_id(db, student.student_id)
-    if db_student:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"Student with ID '{student.student_id}' already exists."
-        )
-    
-    new_student = models.Student(**student.model_dump())
-    db.add(new_student)
-    db.commit()
-    db.refresh(new_student)
-    return new_student
-
-def update_student_tag_id(db: Session, student_id: str, tag_id: str) -> models.Student:
-    """Updates the RFID tag ID for a specific student."""
-    db_student = get_student_by_student_id(db, student_id)
-    if not db_student:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
-    
-    existing_tag_user = get_student_by_tag_id(db, tag_id)
-    if existing_tag_user and existing_tag_user.student_id != student_id:
-        raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
-            detail=f"Tag ID '{tag_id}' is already assigned to another student."
-        )
-
-    db_student.tag_id = tag_id
-    db.commit()
-    db.refresh(db_student)
-    return db_student
-
-def delete_student(db: Session, student_id: str) -> models.Student:
-    """
-    Deletes a student and all of their associated clearance records.
-    
-    This function first finds the student, then deletes all related rows in the
-    'clearance_statuses' table before finally deleting the student record
-    to maintain database integrity.
-    """
-    student_to_delete = get_student_by_student_id(db, student_id)
-    if not student_to_delete:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Student with ID '{student_id}' not found."
-        )
-
-    # First, delete all associated clearance statuses for this student.
-    # This is crucial to prevent foreign key constraint violations.
-    db.query(models.ClearanceStatus).filter(
-        models.ClearanceStatus.student_id == student_id
-    ).delete(synchronize_session=False)
-
-    # Now, delete the student record itself.
-    db.delete(student_to_delete)
-    db.commit()
-    
-    return student_to_delete

src/crud/tag_linking.py

@@ -1,46 +0,0 @@
-"""
-CRUD operations for the PendingTagLink model.
-"""
-from sqlalchemy.orm import Session
-from datetime import datetime
-
-from src import models
-
-def create_pending_tag_link(db: Session, link_details: models.PrepareTagLinkRequest, initiated_by_id: int, expires_at: datetime) -> models.PendingTagLink:
-    """Creates a new pending tag link request in the database."""
-    
-    device = db.query(models.Device).filter(models.Device.device_id == link_details.device_identifier).first()
-    if not device:
-        # This check should ideally be in the router, but adding here as a safeguard
-        return None
-
-    new_link = models.PendingTagLink(
-        device_id_fk=device.id,
-        target_user_type=link_details.target_user_type,
-        target_identifier=link_details.target_identifier,
-        initiated_by_user_id=initiated_by_id,
-        expires_at=expires_at,
-    )
-    db.add(new_link)
-    db.commit()
-    db.refresh(new_link)
-    return new_link
-
-def get_pending_links(db: Session, device_id: int) -> models.PendingTagLink | None:
-    """
-    Fetches the active (non-expired) pending tag link for a specific device.
-    """
-    return db.query(models.PendingTagLink).offset(0).limit(limit=1000).all()
-
-def get_pending_link_by_id(db: Session, link_id: int) -> models.PendingTagLink | None:
-    """
-    Fetches a pending tag link by its ID.
-    """
-    return db.query(models.PendingTagLink).filter(models.PendingTagLink.id == link_id).first()
-
-def delete_pending_link_by_device_id(db: Session, link_id: int):
-    """Deletes a pending link, typically after it has been used."""
-    link_to_delete = db.query(models.PendingTagLink).filter(models.PendingTagLink.id == link_id).first()
-    if link_to_delete:
-        db.delete(link_to_delete)
-        db.commit()

src/crud/users.py

@@ -1,189 +0,0 @@
-"""
-CRUD operations for Users (Admins, Staff).
-"""
-from sqlalchemy.orm import Session
-from fastapi import HTTPException, status
-import bcrypt
-
-from src import models
-
-def hash_password(password: str) -> str:
-    """Hashes a password using bcrypt."""
-    return bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
-
-def get_user_by_username(db: Session, username: str) -> models.User | None:
-    """
-    Retrieves a user by their username.
-    """
-    return db.query(models.User).filter(models.User.username == username).first()
-
-def get_user_by_id(db: Session, user_id: int) -> models.User | None:
-    """
-    Retrieves a user by their ID.
-    """
-    return db.query(models.User).filter(models.User.id == user_id).first()
-
-def get_all_users(db: Session, skip: int = 0, limit: int = 100) -> list[models.User]:
-    """
-    Retrieves all users with pagination.
-    """
-    return db.query(models.User).offset(skip).limit(limit).all()
-
-def get_user_by_tag_id(db: Session, tag_id: str) -> models.User | None:
-    """
-    Retrieves a user by their TAG_ID.
-    """
-    return db.query(models.User).filter(models.User.tag_id == tag_id).first()
-
-def update_user_tag_id(db: Session, username: str, new_tag_id: str) -> models.User:
-    """
-    Updates a user's tag_id.
-    """
-    # Check if the new tag_id is already in use
-    existing_user_with_tag = get_user_by_tag_id(db, new_tag_id)
-    if existing_user_with_tag:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Tag ID '{new_tag_id}' is already assigned to another user."
-        )
-    
-    # Get the user to update
-    user = get_user_by_username(db, username)
-    if not user:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"User '{username}' not found."
-        )
-    
-    # Update the tag_id
-    user.tag_id = new_tag_id
-    db.commit()
-    db.refresh(user)
-    
-    return user
-
-def create_user(db: Session, user_data: models.UserCreate) -> models.User:
-    """
-    Creates a new user account.
-    """
-    # Check if username already exists
-    existing_user = get_user_by_username(db, user_data.username)
-    if existing_user:
-        raise HTTPException(
-            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=f"Username '{user_data.username}' is already registered."
-        )
-
-    # Check if tag_id is already in use (if provided)
-    if user_data.tag_id:
-        existing_tag_user = get_user_by_tag_id(db, user_data.tag_id)
-        if existing_tag_user:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Tag ID '{user_data.tag_id}' is already assigned to another user."
-            )
-
-    # Hash the password
-    hashed_password = hash_password(user_data.password)
-    
-    # Create new user
-    db_user = models.User(
-        username=user_data.username,
-        name=user_data.name,
-        hashed_password=hashed_password,
-        role=user_data.role,
-        department=user_data.department,
-        tag_id=user_data.tag_id,
-        is_active=user_data.is_active if user_data.is_active is not None else True
-    )
-    
-    db.add(db_user)
-    db.commit()
-    db.refresh(db_user)
-    
-    return db_user
-
-def update_user(db: Session, user_id: int, user_update: models.UserCreate) -> models.User:
-    """
-    Updates an existing user.
-    """
-    db_user = get_user_by_id(db, user_id)
-    if not db_user:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"User with ID {user_id} not found."
-        )
-
-    # Check if new username is already taken (if changed)
-    if user_update.username != db_user.username:
-        existing_user = get_user_by_username(db, user_update.username)
-        if existing_user:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Username '{user_update.username}' is already taken."
-            )
-
-    # Check if new tag_id is already in use (if changed and provided)
-    if user_update.tag_id and user_update.tag_id != db_user.tag_id:
-        existing_tag_user = get_user_by_tag_id(db, user_update.tag_id)
-        if existing_tag_user:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail=f"Tag ID '{user_update.tag_id}' is already assigned to another user."
-            )
-
-    # Update fields
-    db_user.username = user_update.username
-    db_user.name = user_update.name
-    if user_update.password:  # Only update password if provided
-        db_user.hashed_password = hash_password(user_update.password)
-    db_user.role = user_update.role
-    db_user.department = user_update.department
-    db_user.tag_id = user_update.tag_id
-    db_user.is_active = user_update.is_active if user_update.is_active is not None else True
-
-    db.commit()
-    db.refresh(db_user)
-    
-    return db_user
-
-def delete_user(db: Session, username_to_delete: str, current_admin: models.User) -> models.User:
-    """
-    Deletes a user, ensuring an admin cannot delete themselves or the last admin.
-    """
-    if username_to_delete == current_admin.username:
-        raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
-            detail="Admins cannot delete their own account."
-        )
-
-    user_to_delete = get_user_by_username(db, username_to_delete)
-    if not user_to_delete:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"User '{username_to_delete}' not found."
-        )
-
-    # Prevent deleting the last admin account
-    if user_to_delete.role == models.UserRole.ADMIN:
-        admin_count = db.query(models.User).filter(models.User.role == models.UserRole.ADMIN).count()
-        if admin_count <= 1:
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
-                detail="Cannot delete the last remaining admin account."
-            )
-
-    # Handle dependencies: set foreign keys to NULL where a user is referenced
-    db.query(models.ClearanceStatus).filter(models.ClearanceStatus.cleared_by == user_to_delete.id).update({"cleared_by": None})
-    
-    # Check if PendingTagLink model exists before trying to delete
-    try:
-        db.query(models.PendingTagLink).filter(models.PendingTagLink.initiated_by_user_id == user_to_delete.id).delete()
-    except AttributeError:
-        # PendingTagLink model doesn't exist, skip this cleanup
-        pass
-
-    db.delete(user_to_delete)
-    db.commit()
-    
-    return user_to_delete

src/crud/utils.py

@@ -1,14 +0,0 @@
-"""
-Utility functions for CRUD operations.
-"""
-import bcrypt
-
-def hash_password(password: str) -> str:
-    """Hashes a password using bcrypt."""
-    return bcrypt.hashpw(password.encode('utf-8'), bcrypt.gensalt()).decode('utf-8')
-
-def verify_password(plain_password: str, hashed_password_str: str) -> bool:
-    """Verifies a plain password against a hashed password."""
-    if not plain_password or not hashed_password_str:
-        return False
-    return bcrypt.checkpw(plain_password.encode('utf-8'), hashed_password_str.encode('utf-8'))

src/database.py

@@ -1,96 +0,0 @@
-"""
-This module handles database connection, session management, table creation,
-and initial data seeding.
-"""
-import sqlalchemy
-from sqlalchemy.orm import sessionmaker, Session as SQLAlchemySessionType
-from datetime import datetime
-
-# Import the centralized settings object
-from src.config import settings 
-
-# Import Enums, Base, and specific ORM models needed for initialization
-from src.models import (
-    Base,
-    ClearanceDepartment,
-    ClearanceStatusEnum,
-    Student as StudentORM,
-    ClearanceStatus as ClearanceStatusORM
-)
-
-# --- Database Engine Setup ---
-# Create the SQLAlchemy engine using the URI from our secure settings.
-engine = sqlalchemy.create_engine(
-    settings.POSTGRES_URI,
-    pool_pre_ping=True  # Helps prevent errors from stale connections
-)
-
-# --- Session Management ---
-# Create a configured "Session" class. This is our session factory.
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-
-def get_db():
-    """
-    FastAPI dependency that creates and yields a new database session
-    for each request, and ensures it's closed afterward.
-    """
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-
-# --- Database Initialization Functions ---
-
-def create_db_and_tables():
-    """
-    Creates all database tables defined in `src/models.py` if they do not exist.
-    This function should be called once on application startup.
-    """
-    try:
-        print("Attempting to create database tables (if they don't exist)...")
-        Base.metadata.create_all(bind=engine)
-        print("Database tables are ready.")
-    except Exception as e:
-        print(f"FATAL: Error during database table creation: {e}")
-        print("Please ensure your database is accessible and the POSTGRES_URI is correct.")
-        # In a real production app, you might want to exit here if the DB is critical
-        raise
-
-def initialize_student_clearance_statuses(db: SQLAlchemySessionType, student_id_str: str):
-    """
-    Creates default 'NOT_COMPLETED' clearance status entries for all required
-    departments for a newly created student. This ensures every student's
-    clearance record is complete from the start.
-    """
-    student = db.query(StudentORM).filter(StudentORM.student_id == student_id_str).first()
-    if not student:
-        print(f"Warning: Student '{student_id_str}' not found when trying to initialize clearance statuses.")
-        return
-
-    for dept in ClearanceDepartment:
-        # Check if a status for this department already exists
-        exists = db.query(ClearanceStatusORM).filter(
-            ClearanceStatusORM.student_id == student_id_str,
-            ClearanceStatusORM.department == dept
-        ).first()
-
-        if not exists:
-            # If it doesn't exist, create the default record
-            new_status = ClearanceStatusORM(
-                student_id=student_id_str,
-                department=dept,
-                status=ClearanceStatusEnum.NOT_COMPLETED
-            )
-            db.add(new_status)
-    
-    # Commit all the new statuses at once
-    try:
-        db.commit()
-    except Exception as e:
-        print(f"Error committing initial clearance statuses for student {student_id_str}: {e}")
-        db.rollback()
-        raise
-
-# Alias for backward compatibility
-initialize_student_clearance_statuses_orm = initialize_student_clearance_statuses

src/models.py

@@ -1,304 +0,0 @@
-"""
-Pydantic Models for data validation and serialization.
-SQLAlchemy Models for database table definitions.
-"""
-from pydantic import BaseModel, Field
-from typing import List, Optional, Union
-from enum import Enum
-from datetime import datetime
-
-from sqlalchemy import (
-    Boolean, Column, ForeignKey, Integer, String, DateTime,
-    create_engine, Enum as SQLAlchemyEnum
-)
-from sqlalchemy.orm import relationship, sessionmaker, declarative_base
-
-# ==============================================================================
-# Shared Enums (used by both SQLAlchemy and Pydantic)
-# ==============================================================================
-
-class ClearanceStatusEnum(str, Enum):
-    NOT_COMPLETED = "NOT_COMPLETED"
-    PENDING = "PENDING"
-    COMPLETED = "COMPLETED"
-    REJECTED = "REJECTED"
-
-class ClearanceDepartment(str, Enum):
-    DEPARTMENT = "DEPARTMENT"
-    BURSARY = "BURSARY"
-    LIBRARY = "LIBRARY"
-    ALUMNI = "ALUMNI"
-
-class UserRole(str, Enum):
-    ADMIN = "ADMIN"
-    STAFF = "STAFF"
-
-class TargetUserType(str, Enum):
-    STUDENT = "STUDENT"
-    STAFF_ADMIN = "STAFF_ADMIN"
-
-class OverallClearanceStatusEnum(str, Enum):
-    PENDING = "PENDING"
-    COMPLETED = "COMPLETED"
-
-class UserTypeEnum(str, Enum):
-    """Enum for user types."""
-    STUDENT = "student"
-    USER = "user"
-
-
-Base = declarative_base()
-
-class User(Base):
-    """Database model for Users (Admins, Staff)."""
-    __tablename__ = "users"
-    id = Column(Integer, primary_key=True, index=True)
-    username = Column(String, unique=True, index=True, nullable=False)
-    hashed_password = Column(String, nullable=False)
-    name = Column(String, nullable=False)
-    role = Column(SQLAlchemyEnum(UserRole), default=UserRole.STAFF, nullable=False)
-    department = Column(SQLAlchemyEnum(ClearanceDepartment), nullable=True)
-    is_active = Column(Boolean, default=True)
-    tag_id = Column(String, unique=True, index=True, nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-
-class Student(Base):
-    """Database model for Students."""
-    __tablename__ = "students"
-    id = Column(Integer, primary_key=True, index=True)
-    student_id = Column(String, unique=True, index=True, nullable=False)
-    name = Column(String, nullable=False)
-    department = Column(String, nullable=False)
-    tag_id = Column(String, unique=True, index=True, nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-    clearance_statuses = relationship("ClearanceStatus", back_populates="student")
-
-
-class ClearanceStatus(Base):
-    """Database model for individual clearance items for a student."""
-    __tablename__ = "clearance_statuses"
-    id = Column(Integer, primary_key=True, index=True)
-    student_id = Column(String, ForeignKey("students.student_id"), nullable=False)
-    department = Column(SQLAlchemyEnum(ClearanceDepartment), nullable=False)
-    status = Column(SQLAlchemyEnum(ClearanceStatusEnum), default=ClearanceStatusEnum.NOT_COMPLETED, nullable=False)
-    remarks = Column(String, nullable=True)
-    cleared_by = Column(Integer, ForeignKey("users.id"), nullable=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-    
-    student = relationship("Student", back_populates="clearance_statuses")
-    cleared_by_user = relationship("User", foreign_keys=[cleared_by])
-
-
-class Device(Base):
-    """Database model for RFID reader devices."""
-    __tablename__ = "devices"
-    id = Column(Integer, primary_key=True, index=True)
-    name = Column(String, nullable=False)
-    description = Column(String, nullable=True)
-    device_id = Column(String, unique=True, index=True, nullable=True)
-    location = Column(String, nullable=True)
-    api_key = Column(String, unique=True, index=True, nullable=False)
-    is_active = Column(Boolean, default=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-
-class PendingTagLink(Base):
-    """Database model for pending tag link requests."""
-    __tablename__ = "pending_tag_links"
-    id = Column(Integer, primary_key=True, index=True)
-    device_id_fk = Column(Integer, ForeignKey("devices.id"), nullable=False)
-    target_user_type = Column(SQLAlchemyEnum(TargetUserType), nullable=False)
-    target_identifier = Column(String, nullable=False)
-    initiated_by_user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
-    expires_at = Column(DateTime, nullable=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    
-    # Relationships
-    device = relationship("Device", foreign_keys=[device_id_fk])
-    initiated_by = relationship("User", foreign_keys=[initiated_by_user_id])
-
-
-
-class DeviceLog(Base):
-    """Database model for device activity logs."""
-    __tablename__ = "device_logs"
-    id = Column(Integer, primary_key=True, index=True)
-    device_fk_id = Column(Integer, ForeignKey("devices.id"), nullable=True)
-    actual_device_id_str = Column(String, nullable=True)
-    tag_id_scanned = Column(String, nullable=True)
-    user_type = Column(String, nullable=True)
-    action = Column(String, nullable=False)
-    timestamp = Column(DateTime, default=datetime.utcnow)
-
-
-# --- User and Auth Models ---
-class UserBase(BaseModel):
-    username: str
-    name: str
-    role: UserRole = UserRole.STAFF
-    department: Optional[ClearanceDepartment] = None
-    tag_id: Optional[str] = None
-    is_active: Optional[bool] = True
-
-class UserCreate(UserBase):
-    password: str
-
-class UserResponse(BaseModel):
-    id: int
-    username: str
-    name: str
-    role: UserRole
-    department: Optional[ClearanceDepartment] = None
-    tag_id: Optional[str] = None
-    is_active: bool
-    created_at: datetime
-    updated_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-class Token(BaseModel):
-    access_token: str
-    token_type: str
-
-class TokenData(BaseModel):
-    username: Optional[str] = None
-
-# --- Student and Clearance Models ---
-class StudentBase(BaseModel):
-    student_id: str = Field(..., example="CST/18/123")
-    name: str = Field(..., example="John Doe")
-    department: str = Field(..., example="Computer Science")
-
-class StudentCreate(StudentBase):
-    tag_id: Optional[str] = None
-
-class StudentResponse(StudentBase):
-    id: int
-    tag_id: Optional[str] = None
-    created_at: datetime
-    updated_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-class ClearanceStatusCreate(BaseModel):
-    student_id: str
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-
-class ClearanceStatusResponse(BaseModel):
-    id: int
-    student_id: str
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-    cleared_by: Optional[int] = None
-    created_at: datetime
-    updated_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-class ClearanceStatusItem(BaseModel):
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-    updated_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-class ClearanceDetail(BaseModel):
-    student_id: str
-    name: str
-    department: str
-    overall_status: OverallClearanceStatusEnum
-    clearance_items: List[ClearanceStatusItem]
-
-class ClearanceStatusUpdate(BaseModel):
-    department: ClearanceDepartment
-    status: ClearanceStatusEnum
-    remarks: Optional[str] = None
-
-# --- Device Models ---
-class DeviceCreateAdmin(BaseModel):
-    name: str
-    description: Optional[str] = None
-    device_id: Optional[str] = None
-    location: Optional[str] = None
-
-class DeviceRegister(BaseModel):
-    device_id: str
-    location: str
-
-class DeviceResponse(BaseModel):
-    id: int
-    name: str
-    description: Optional[str] = None
-    device_id: Optional[str] = None
-    location: Optional[str] = None
-    api_key: str
-    is_active: bool
-    created_at: datetime
-    updated_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-# --- Tag and Device Models ---
-class TagLinkRequest(BaseModel):
-    tag_id: str = Field(..., example="A1B2C3D4")
-    
-class PrepareDeviceRequest(BaseModel):
-    device_id_str: str = Field(..., example="RFID-READER-01")
-    user_id_str: str # Can be student_id or username
-    user_type: UserTypeEnum
-
-
-class PrepareTagLinkRequest(BaseModel):
-    """Request to prepare a device for tag linking."""
-    device_identifier: str = Field(..., description="The device ID that will scan for tags")
-    target_user_type: TargetUserType = Field(..., description="Type of user (STUDENT or STAFF_ADMIN)")
-    target_identifier: str = Field(..., description="Student ID or username to link the tag to")
-
-class PendingTagLinkResponse(BaseModel):
-    """Response model for pending tag link information."""
-    id: int
-    device_id_fk: int
-    target_user_type: TargetUserType
-    target_identifier: str
-    initiated_by_user_id: int
-    expires_at: datetime
-    created_at: datetime
-    
-    class Config:
-        from_attributes = True
-
-class ScannedTagSubmit(BaseModel):
-    """Request when submitting a scanned tag for linking."""
-    scanned_tag_id: str = Field(..., description="The scanned RFID tag ID")
-
-
-# --- New RFID Models ---
-class RfidScanRequest(BaseModel):
-    """Request body for the unified RFID scan endpoint."""
-    tag_id: str = Field(..., description="The ID scanned from the RFID tag.", example="A1B2C3D4")
-    device_id: str = Field(..., description="The unique identifier of the RFID reader device.", example="RFID-READER-01")
-
-class RfidLinkSuccessResponse(BaseModel):
-    """Success response when a tag is linked."""
-    message: str = "Tag linked successfully."
-    user_id: str
-    user_type: UserTypeEnum
-
-# JWT Configuration
-import os
-JWT_SECRET_KEY = os.getenv("JWT_SECRET_KEY", "your-secret-key")

src/routers/admin.py

@@ -1,83 +0,0 @@
-"""
-Admin-only endpoints for managing system-wide operations like tag linking
-and deleting core resources like users and devices.
-"""
-from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session
-from datetime import datetime, timedelta
-
-from src import crud, models
-from src.auth import get_current_active_admin_user_from_token, get_current_active_user
-from src.database import get_db
-
-router = APIRouter(
-    prefix="/api/admin",
-    tags=["Admin"],
-    dependencies=[Depends(get_current_active_admin_user_from_token)]
-)
-
-@router.post("/prepare-tag-link", status_code=status.HTTP_202_ACCEPTED, response_model=dict)
-async def prepare_device_for_tag_linking(
-    request: models.PrepareTagLinkRequest,
-    current_user: models.User = Depends(get_current_active_user),
-    db: Session = Depends(get_db)
-):
-    """
-    Admin: Initiates a request to link a tag. This creates a temporary,
-    expiring 'PendingTagLink' record for a device.
-    """
-    device = await run_in_threadpool(crud.get_device_by_id_str, db, request.device_identifier)
-    if not device or not device.is_active:
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Device not found or is inactive.")
-    
-    if request.target_user_type == models.TargetUserType.STUDENT:
-        target = await run_in_threadpool(crud.get_student_by_student_id, db, request.target_identifier)
-    else:
-        target = await run_in_threadpool(crud.get_user_by_username, db, request.target_identifier)
-    
-    if not target:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"{request.target_user_type.value} '{request.target_identifier}' not found."
-        )
-
-    expiry_time = datetime.utcnow() + timedelta(minutes=2)
-    await run_in_threadpool(
-        crud.create_pending_tag_link, db, request, current_user.id, expiry_time
-    )
-    return {
-        "message": "Device is ready to link tag.",
-        "device_id": device.device_id,
-        "target": request.target_identifier,
-        "expires_at": expiry_time.isoformat()
-    }
-
-@router.delete("/users/{username}", status_code=status.HTTP_200_OK, response_model=dict)
-async def delete_user_endpoint(
-    username: str,
-    db: Session = Depends(get_db),
-    current_admin: models.User = Depends(get_current_active_admin_user_from_token)
-):
-    """
-    Admin: Permanently deletes a user (staff or other admin).
-    """
-    try:
-        deleted_user = await run_in_threadpool(crud.delete_user, db, username, current_admin)
-        return {"message": "User deleted successfully", "username": deleted_user.username}
-    except HTTPException as e:
-        raise e
-
-@router.delete("/devices/{device_id_str}", status_code=status.HTTP_200_OK, response_model=dict)
-async def delete_device_endpoint(
-    device_id_str: str,
-    db: Session = Depends(get_db)
-):
-    """
-    Admin: Permanently deletes a registered RFID device and all its logs.
-    """
-    try:
-        deleted_device = await run_in_threadpool(crud.delete_device, db, device_id_str)
-        return {"message": "Device deleted successfully", "device_id": deleted_device.device_id}
-    except HTTPException as e:
-        raise e

src/routers/clearance.py

@@ -1,68 +0,0 @@
-"""
-Router for staff and admin clearance operations.
-"""
-from fastapi import APIRouter, Depends, HTTPException, status
-from sqlalchemy.orm import Session
-from fastapi.concurrency import run_in_threadpool
-
-from src import crud, models
-from src.database import get_db
-from src.auth import get_current_active_user, get_current_active_staff_user_from_token
-from src.utils import format_student_clearance_details
-
-router = APIRouter(
-    prefix="/api/clearance",
-    tags=["Clearance"],
-    dependencies=[Depends(get_current_active_staff_user_from_token)]
-)
-
-class ClearanceUpdatePayload(models.BaseModel):
-    status: models.ClearanceStatusEnum
-    remarks: str | None = None
-
-@router.put("/{student_id_str}", response_model=models.ClearanceDetail)
-async def update_student_clearance(
-    student_id_str: str,
-    payload: ClearanceUpdatePayload,
-    db: Session = Depends(get_db),
-    current_user: models.User = Depends(get_current_active_staff_user_from_token)
-):
-    """
-    Staff/Admin: Update a student's clearance status for their department.
-    """
-    if not current_user.department:
-        raise HTTPException(status_code=403, detail="Your user account is not assigned to a clearable department.")
-
-    await run_in_threadpool(
-        crud.update_clearance_status, db, student_id_str, current_user.department, payload.status, payload.remarks, current_user.id
-    )
-    
-    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
-    return await format_student_clearance_details(db, student_orm)
-
-@router.delete("/{student_id_str}/{department_str}", response_model=models.ClearanceDetail)
-async def reset_student_clearance(
-    student_id_str: str,
-    department_str: str,
-    db: Session = Depends(get_db),
-    current_user: models.User = Depends(get_current_active_staff_user_from_token)
-):
-    """
-    Staff/Admin: Reset a student's clearance status for a department.
-    Admins can reset for any department; staff only for their own.
-    """
-    try:
-        target_department = models.ClearanceDepartment(department_str.upper())
-    except ValueError:
-        raise HTTPException(status_code=400, detail=f"'{department_str}' is not a valid department.")
-
-    if current_user.role != models.UserRole.ADMIN and current_user.department != target_department:
-        raise HTTPException(status_code=403, detail=f"You can only reset clearance for your own department.")
-
-    await run_in_threadpool(crud.delete_clearance_status, db, student_id_str, target_department)
-    
-    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
-    if not student_orm:
-         raise HTTPException(status_code=404, detail="Student not found.")
-         
-    return await format_student_clearance_details(db, student_orm)

src/routers/devices.py

@@ -1,89 +0,0 @@
-"""
-Router for device interactions, specifically for submitting a scanned tag.
-This endpoint is intended to be called by the physical RFID reader device.
-"""
-from fastapi import APIRouter, Depends, HTTPException, status, Header
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session
-from typing import Union
-
-from src import crud, models
-from src.database import get_db
-from src.utils import format_student_clearance_details
-
-async def get_authenticated_device(x_api_key: str = Header(...), db: Session = Depends(get_db)) -> models.Device:
-    """Dependency to authenticate a device by its API key."""
-    device = await run_in_threadpool(crud.get_device_by_api_key, db, x_api_key)
-    if not device or not device.is_active:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Invalid API Key or Inactive Device",
-        )
-    return device
-
-router = APIRouter(
-    prefix="/api/devices",
-    tags=["Devices"],
-    dependencies=[Depends(get_authenticated_device)]
-)
-
-@router.post("/devices/register", response_model=models.DeviceResponse)
-async def register_device_endpoint( # Async endpoint
-    device_data: models.DeviceRegister, # Pydantic model from ESP32
-    db: SQLAlchemySessionType = Depends(get_db)
-):
-    """
-    ESP32 devices self-register or re-register. Uses ORM.
-    """
-    # crud.register_device_esp is sync, call with run_in_threadpool
-    try:
-        registered_device_orm = await run_in_threadpool(crud.register_device, db, device_data)
-    except HTTPException as e: # Catch HTTPExceptions raised by CRUD (e.g., device already exists)
-        raise e
-    return registered_device_orm # Pydantic DeviceResponse converts from ORM model
-
-
-@router.post(
-    "/submit-tag",
-    response_model=Union[models.ClearanceDetail, models.UserResponse, dict],
-    summary="Endpoint for RFID devices to submit a scanned tag ID."
-)
-async def device_submit_scanned_tag(
-    scanned_tag: models.ScannedTagSubmit,
-    device: models.Device = Depends(get_authenticated_device),
-    db: Session = Depends(get_db)
-):
-    """
-    Handles a tag submission from an authenticated RFID device.
-    It can either link a tag if a pending link exists or fetch user details.
-    """
-    tag_id = scanned_tag.scanned_tag_id
-    pending_link = await run_in_threadpool(crud.get_pending_link_by_device, db, device.id)
-
-    if pending_link:
-        # Registration Mode
-        target_type, target_id = pending_link.target_user_type, pending_link.target_identifier
-        try:
-            if target_type == models.TargetUserType.STUDENT:
-                await run_in_threadpool(crud.update_student_tag_id, db, target_id, tag_id)
-            else:
-                await run_in_threadpool(crud.update_user_tag_id, db, target_id, tag_id)
-        finally:
-            await run_in_threadpool(crud.delete_pending_link, db, pending_link.id)
-        
-        await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"TAG_LINK_SUCCESS: {target_type.value} {target_id}"})
-        return {"message": "Tag linked successfully", "user_id": target_id, "user_type": target_type}
-    else:
-        # Fetching Mode
-        student = await run_in_threadpool(crud.get_student_by_tag_id, db, tag_id)
-        if student:
-            await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"FETCH_SUCCESS: Student {student.student_id}"})
-            return await format_student_clearance_details(db, student)
-
-        user = await run_in_threadpool(crud.get_user_by_tag_id, db, tag_id)
-        if user:
-            await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": f"FETCH_SUCCESS: User {user.username}"})
-            return models.UserResponse.from_orm(user)
-        
-        await run_in_threadpool(crud.create_device_log, db, {"device_fk_id": device.id, "tag_id_scanned": tag_id, "action": "FETCH_FAIL: Tag not found"})
-        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Tag ID '{tag_id}' not found.")

src/routers/rfid.py

@@ -1,83 +0,0 @@
-"""
-Router for handling all RFID interactions.
-"""
-from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session
-from typing import Union
-
-from src import crud, models
-from src.database import get_db
-from src.utils import format_student_clearance_details # Using a utility for DRY code
-
-router = APIRouter(
-    prefix="/api/rfid",
-    tags=["RFID"],
-)
-
-@router.post(
-    "/scan",
-    response_model=Union[models.ClearanceDetail, models.RfidLinkSuccessResponse, models.UserResponse],
-    summary="Unified endpoint for all RFID tag scans."
-)
-async def handle_rfid_scan(
-    scan_data: models.RfidScanRequest,
-    db: Session = Depends(get_db),
-):
-    """
-    This endpoint intelligently handles an RFID tag scan.
-
-    - **Registration Mode**: If an admin has prepared the device to link a tag
-      to a user, this endpoint will perform the link and return a success message.
-    
-    - **Fetching Mode**: If the device is not in registration mode, this endpoint
-      will look up the user/student by the tag ID and return their details
-      (e.g., clearance status for a student).
-    """
-    # 1. Get the device that sent the scan
-    device = await run_in_threadpool(crud.get_device_by_id, db, scan_data.device_id)
-    if not device:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Device with ID '{scan_data.device_id}' not found."
-        )
-
-    # 2. Check if the device is in "Registration Mode"
-    if device.link_for_user_id and device.link_for_user_type:
-        user_id_to_link = device.link_for_user_id
-        user_type_to_link = device.link_for_user_type
-
-        # Link the tag based on the user type
-        if user_type_to_link == models.UserTypeEnum.STUDENT:
-            await run_in_threadpool(crud.update_student_tag_id, db, user_id_to_link, scan_data.tag_id)
-        elif user_type_to_link == models.UserTypeEnum.USER:
-            await run_in_threadpool(crud.update_user_tag_id, db, user_id_to_link, scan_data.tag_id)
-        
-        # Clear the registration mode from the device
-        await run_in_threadpool(crud.clear_device_link_for_user, db, device.device_id_str)
-        
-        return models.RfidLinkSuccessResponse(
-            user_id=user_id_to_link,
-            user_type=user_type_to_link
-        )
-        
-    # 3. If not in registration mode, it's "Fetching Mode"
-    else:
-        # First, check if the tag belongs to a student
-        student = await run_in_threadpool(crud.get_student_by_tag_id, db, scan_data.tag_id)
-        if student:
-            # If a student is found, format and return their full clearance details
-            return await format_student_clearance_details(db, student)
-
-        # If not a student, check if it belongs to other users (staff/admin)
-        user = await run_in_threadpool(crud.get_user_by_tag_id, db, scan_data.tag_id)
-        if user:
-            # For a staff/admin, just return their basic profile info
-            return models.UserResponse.from_orm(user)
-        
-        # If the tag is not found anywhere, raise an error
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Tag ID '{scan_data.tag_id}' is not associated with any user."
-        )
-

src/routers/students.py

@@ -1,64 +0,0 @@
-"""
-Router for all CRUD operations related to students.
-"""
-from fastapi import APIRouter, HTTPException, status, Depends
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from typing import List
-
-from src import crud, models
-from src.auth import get_current_active_admin_user_from_token
-from src.database import get_db
-from src.utils import format_student_clearance_details
-
-router = APIRouter(
-    prefix="/api/students",
-    tags=["students"],
-    )
-
-@router.post("/", response_model=models.StudentResponse, status_code=status.HTTP_201_CREATED)
-async def create_student_endpoint(
-    student_data: models.StudentCreate,
-    db: SQLAlchemySessionType = Depends(get_db),
-):
-    """Admin: Create a new student."""
-    try:
-        created_student_orm = await run_in_threadpool(crud.create_student, db, student_data)
-        return created_student_orm
-    except HTTPException as e:
-        raise e
-
-@router.get("/", response_model=List[models.StudentResponse])
-async def get_students_endpoint(
-    skip: int = 0,
-    limit: int = 100,
-    db: SQLAlchemySessionType = Depends(get_db),
-):
-    """Admin: Get a list of all students."""
-    students_orm_list = await run_in_threadpool(crud.get_all_students, db, skip, limit)
-    return students_orm_list
-
-@router.get("/{student_id_str}", response_model=models.ClearanceDetail)
-async def get_student_clearance_endpoint(
-    student_id_str: str,
-    db: SQLAlchemySessionType = Depends(get_db),
-):
-    """Admin: Get detailed clearance status for a specific student."""
-    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, student_id_str)
-    if not student_orm:
-        raise HTTPException(status_code=404, detail="Student not found")
-    return await format_student_clearance_details(db, student_orm)
-
-@router.delete("/{student_id_str}", status_code=status.HTTP_200_OK, response_model=dict)
-async def delete_student_endpoint(
-    student_id_str: str,
-    db: SQLAlchemySessionType = Depends(get_db),
-):
-    """
-    Admin: Permanently deletes a student and all associated records.
-    """
-    try:
-        deleted_student = await run_in_threadpool(crud.delete_student, db, student_id_str)
-        return {"message": "Student deleted successfully", "student_id": deleted_student.student_id}
-    except HTTPException as e:
-        raise e

src/routers/token.py

@@ -1,45 +0,0 @@
-"""
-Router for handling user authentication and issuing JWT tokens.
-"""
-from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.security import OAuth2PasswordRequestForm
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session
-from datetime import timedelta
-
-from src import models
-from src.database import get_db
-from src.auth import create_access_token, authenticate_user
-from src.config import settings
-
-router = APIRouter(
-    prefix="/api",
-    tags=["Authentication Token"]
-)
-
-@router.post("/token", response_model=models.Token)
-async def login_for_access_token(
-    form_data: OAuth2PasswordRequestForm = Depends(),
-    db: Session = Depends(get_db)
-):
-    """
-    Provides a JWT token for authenticated users.
-    
-    This is the primary login endpoint. It takes a username and password
-    and returns an access token if the credentials are valid.
-    """
-    user = authenticate_user(db, form_data.username, form_data.password)
-    if not user:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Incorrect username or password",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-    
-    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
-    access_token = create_access_token(
-        data={"sub": user.username, "role": user.role.value},
-        expires_delta=access_token_expires
-    )
-    
-    return {"access_token": access_token, "token_type": "bearer"}

src/routers/users.py

@@ -1,50 +0,0 @@
-"""
-Router for managing users (staff, admins).
-"""
-from fastapi import APIRouter, Depends, HTTPException, status
-from fastapi.concurrency import run_in_threadpool
-from sqlalchemy.orm import Session
-from typing import List
-
-from src import crud, models
-from src.database import get_db
-from src.auth import get_current_active_user, get_current_active_admin_user_from_token
-
-router = APIRouter(
-    prefix="/api/users",
-    tags=["Users"],
-)
-
-@router.post("/", response_model=models.UserResponse, status_code=status.HTTP_201_CREATED, dependencies=[Depends(get_current_active_admin_user_from_token)])
-async def create_new_user(user: models.UserCreate, db: Session = Depends(get_db)):
-    """
-    Admin: Create a new user (staff or admin).
-    """
-    db_user = await run_in_threadpool(crud.get_user_by_username, db, user.username)
-    if db_user:
-        raise HTTPException(status_code=400, detail="Username already registered")
-    return await run_in_threadpool(crud.create_user, db, user)
-
-@router.get("/", response_model=List[models.UserResponse], dependencies=[Depends(get_current_active_admin_user_from_token)])
-async def read_users(skip: int = 0, limit: int = 100, db: Session = Depends(get_db)):
-    """
-    Admin: Retrieve a list of all users.
-    """
-    users = await crud.get_all_users(db, skip=skip, limit=limit) # Assumes get_all_users exists in crud.users
-    return users
-
-@router.get("/all", response_model=list[models.UserResponse], dependencies=[Depends(get_current_active_admin_user_from_token)])
-async def get_all_users(db: Session = Depends(get_db)):
-    """
-    Admin: Get a list of all users.
-    """
-    users = await run_in_threadpool(crud.get_all_users, db)
-    return users
-
-@router.get("/me", response_model=models.UserResponse)
-async def read_users_me(current_user: models.User = Depends(get_current_active_user)):
-    """
-    Get profile information for the currently authenticated user.
-    """
-    return current_user
-

src/utils.py

@@ -1,51 +0,0 @@
-from typing import List, Dict, Any
-from sqlalchemy.orm import Session as SQLAlchemySessionType
-from fastapi.concurrency import run_in_threadpool
-
-from src import crud, models
-
-async def format_student_clearance_details(
-    db: SQLAlchemySessionType,
-    student_orm: models.Student
-) -> models.ClearanceDetail:
-    """
-    Formats clearance details for a student.
-    
-    Args:
-        db (SQLAlchemySessionType): Database session.
-        student_orm (models.Student): ORM model of the student.
-    
-    Returns:
-        models.ClearanceDetail: Formatted clearance details.
-    """
-    statuses_orm_list = await run_in_threadpool(crud.get_clearance_statuses_by_student_id, db, student_orm.student_id)
-    
-    clearance_items_models: List[models.ClearanceStatusItem] = []
-    overall_status_val = models.OverallClearanceStatusEnum.COMPLETED
-
-    
-    if not statuses_orm_list:
-        overall_status_val = models.OverallClearanceStatusEnum.PENDING
-    
-    for status_orm in statuses_orm_list:
-        item = models.ClearanceStatusItem(
-            department=status_orm.department,
-            status=status_orm.status,
-            remarks=status_orm.remarks,
-            updated_at=status_orm.updated_at
-        )
-        clearance_items_models.append(item)
-        if item.status != models.ClearanceStatusEnum.COMPLETED:
-            overall_status_val = models.OverallClearanceStatusEnum.PENDING
-            
-    if not statuses_orm_list and overall_status_val == models.OverallClearanceStatusEnum.COMPLETED:
-         overall_status_val = models.OverallClearanceStatusEnum.PENDING
-
-    return models.ClearanceDetail(
-        student_id=student_orm.student_id,
-        name=student_orm.name,
-        department=student_orm.department,
-        clearance_items=clearance_items_models,
-        overall_status=overall_status_val
-    )
-