FEAT: Backend code completed done

src/auth.py

@@ -0,0 +1,85 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer, APIKeyHeader
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+from datetime import datetime, timedelta, timezone
+from typing import Optional
+from sqlmodel import Session, select
+
+from src.database import get_session
+from src.models import User
+from src.config import settings
+
+# --- Security Configuration ---
+
+# Password hashing context using bcrypt
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+# OAuth2 scheme for token-based authentication
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")
+
+# API key header for device authentication
+api_key_header = APIKeyHeader(name="X-API-Key", auto_error=True)
+
+# --- Password Utilities ---
+
+def verify_password(plain_password: str, hashed_password: str) -> bool:
+    """Verifies a plain password against a hashed password."""
+    return pwd_context.verify(plain_password, hashed_password)
+
+def hash_password(password: str) -> str:
+    """Hashes a plain password."""
+    return pwd_context.hash(password)
+
+# --- JWT Token Utilities ---
+
+def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -> str:
+    """
+    Generates a new JWT access token.
+    """
+    to_encode = data.copy()
+    if expires_delta:
+        expire = datetime.now(timezone.utc) + expires_delta
+    else:
+        # Default expiration time: 15 minutes
+        expire = datetime.now(timezone.utc) + timedelta(minutes=15)
+    
+    to_encode.update({"exp": expire})
+    encoded_jwt = jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
+    return encoded_jwt
+
+# --- User Authentication and Authorization ---
+
+async def get_current_user(token: str = Depends(oauth2_scheme), db: Session = Depends(get_session)) -> User:
+    """
+    Decodes the JWT token to get the current user.
+    Raises an exception if the token is invalid or the user doesn't exist.
+    """
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    
+    try:
+        payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
+        username: Optional[str] = payload.get("sub")
+        if username is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+    
+    user = db.exec(select(User).where(User.username == username)).first()
+    if user is None:
+        raise credentials_exception
+        
+    return user
+
+async def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
+    """
+    Ensures the user retrieved from the token is active.
+    """
+    if not current_user.is_active:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Inactive user")
+    return current_user
+

src/config.py

@@ -0,0 +1,15 @@
+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

@@ -0,0 +1,83 @@
+"""
+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

@@ -0,0 +1,58 @@
+from sqlmodel import Session, select
+from typing import List, Optional
+
+from src.models import Student, ClearanceStatus, ClearanceUpdate, Department, ClearanceProcess
+
+def get_clearance_status_for_student(db: Session, student: Student) -> List[ClearanceStatus]:
+    """
+    Retrieves all clearance statuses for a given student object.
+    """
+    return student.clearance_statuses
+
+def update_clearance_status(db: Session, clearance_update: ClearanceUpdate) -> Optional[ClearanceStatus]:
+    """
+    Updates the clearance status for a student in a specific department.
+
+    This function performs a direct lookup on the ClearanceStatus table, which is
+    more efficient than fetching the student and iterating through their statuses.
+    """
+    # First, find the student to ensure they exist.
+    student = db.exec(select(Student).where(Student.matric_no == clearance_update.matric_no)).first()
+    if not student:
+        return None # Student not found
+
+    # Directly query for the specific clearance status record.
+    statement = select(ClearanceStatus).where(
+        ClearanceStatus.student_id == student.id,
+        ClearanceStatus.department == clearance_update.department
+    )
+    status_to_update = db.exec(statement).first()
+
+    if not status_to_update:
+        # This case should theoretically not happen if students are created correctly,
+        # but it's a good safeguard.
+        return None 
+
+    # Update the status and commit the change.
+    status_to_update.status = clearance_update.status
+    db.add(status_to_update)
+    db.commit()
+    db.refresh(status_to_update)
+    
+    return status_to_update
+
+def is_student_fully_cleared(db: Session, matric_no: str) -> bool:
+    """
+    Checks if a student has been approved by all required departments.
+    """
+    student = db.exec(select(Student).where(Student.matric_no == matric_no)).first()
+    if not student:
+        return False # Or raise an error, depending on desired behavior
+
+    # Check if any of the student's clearance statuses are NOT 'approved'.
+    for status in student.clearance_statuses:
+        if status.status != ClearanceProcess.APPROVED:
+            return False
+            
+    # If the loop completes without returning, all statuses are approved.
+    return True

src/crud/devices.py

@@ -0,0 +1,74 @@
+from sqlmodel import Session, select
+import secrets
+from typing import List, Optional
+
+from src.models import Device, DeviceCreate, Department
+
+def create_device(db: Session, device: DeviceCreate) -> Optional[Device]:
+    """
+    Creates a new device for a department.
+    Generates a unique API key for authentication.
+    Returns None if a device with the same name already exists.
+    """
+    # Check for existing device with the same name to prevent duplicates
+    existing_device = db.exec(select(Device).where(Device.device_name == device.device_name)).first()
+    if existing_device:
+        return None
+
+    # Generate a secure, URL-safe API key
+    api_key = secrets.token_urlsafe(32)
+    
+    db_device = Device(
+        device_name=device.device_name,
+        department=device.department,
+        api_key=api_key,
+        is_active=True
+    )
+    
+    db.add(db_device)
+    db.commit()
+    db.refresh(db_device)
+    return db_device
+
+def get_device_by_api_key(db: Session, api_key: str) -> Optional[Device]:
+    """Retrieves an active device by its API key."""
+    statement = select(Device).where(Device.api_key == api_key, Device.is_active == True)
+    return db.exec(statement).first()
+
+def get_device_by_name(db: Session, device_name: str) -> Optional[Device]:
+    """Retrieves a device by its unique name."""
+    return db.exec(select(Device).where(Device.device_name == device_name)).first()
+
+def get_all_devices(db: Session, skip: int = 0, limit: int = 100) -> List[Device]:
+    """Retrieves a list of all devices."""
+    return db.exec(select(Device).offset(skip).limit(limit)).all()
+
+def update_device(db: Session, device_id: int, device_update: dict) -> Optional[Device]:
+    """
+    Updates a device's mutable properties (e.g., name, active status).
+    The API key is immutable and cannot be changed here.
+    """
+    db_device = db.get(Device, device_id)
+    if not db_device:
+        return None
+    
+    # Exclude API key from updates for security
+    device_update.pop("api_key", None)
+
+    for key, value in device_update.items():
+        setattr(db_device, key, value)
+        
+    db.add(db_device)
+    db.commit()
+    db.refresh(db_device)
+    return db_device
+
+def delete_device(db: Session, device_id: int) -> Optional[Device]:
+    """Deletes a device from the database."""
+    db_device = db.get(Device, device_id)
+    if not db_device:
+        return None
+    
+    db.delete(db_device)
+    db.commit()
+    return db_device

src/crud/students.py

@@ -0,0 +1,98 @@
+from sqlmodel import Session, select
+from typing import List, Optional
+
+from src.models import Student, StudentCreate, StudentUpdate, RFIDTag, ClearanceStatus, Department, ClearanceProcess
+from src.auth import hash_password
+
+# --- Read Operations ---
+
+def get_student_by_id(db: Session, student_id: int) -> Optional[Student]:
+    """Retrieves a student by their primary key ID."""
+    return db.get(Student, student_id)
+
+def get_student_by_matric_no(db: Session, matric_no: str) -> Optional[Student]:
+    """Retrieves a student by their unique matriculation number."""
+    return db.exec(select(Student).where(Student.matric_no == matric_no)).first()
+
+def get_student_by_tag_id(db: Session, tag_id: str) -> Optional[Student]:
+    """Retrieves a student by their linked RFID tag ID."""
+    statement = select(Student).join(RFIDTag).where(RFIDTag.tag_id == tag_id)
+    return db.exec(statement).first()
+
+def get_all_students(db: Session, skip: int = 0, limit: int = 100) -> List[Student]:
+    """Retrieves a paginated list of all students."""
+    return db.exec(select(Student).offset(skip).limit(limit)).all()
+
+# --- Write Operations ---
+
+def create_student(db: Session, student: StudentCreate) -> Student:
+    """
+    Creates a new student and initializes their clearance statuses.
+
+    This is a critical business logic function. When a student is created,
+    this function automatically creates a 'pending' clearance record for every
+    department defined in the `Department` enum.
+    """
+    hashed_pass = hash_password(student.password)
+    db_student = Student(
+        matric_no=student.matric_no,
+        full_name=student.full_name,
+        email=student.email,
+        hashed_password=hashed_pass,
+        # Department will be set from the StudentCreate model
+        department=student.department 
+    )
+    
+    # --- Auto-populate clearance statuses ---
+    initial_statuses = []
+    for dept in Department:
+        status = ClearanceStatus(
+            department=dept,
+            status=ClearanceProcess.PENDING
+        )
+        initial_statuses.append(status)
+    
+    db_student.clearance_statuses = initial_statuses
+    # --- End of auto-population ---
+
+    db.add(db_student)
+    db.commit()
+    db.refresh(db_student)
+    return db_student
+
+def update_student(db: Session, student_id: int, student_update: StudentUpdate) -> Optional[Student]:
+    """
+    Updates a student's information.
+    If a new password is provided, it will be hashed.
+    """
+    db_student = db.get(Student, student_id)
+    if not db_student:
+        return None
+
+    update_data = student_update.model_dump(exclude_unset=True)
+    
+    if "password" in update_data:
+        update_data["hashed_password"] = hash_password(update_data.pop("password"))
+
+    for key, value in update_data.items():
+        setattr(db_student, key, value)
+    
+    db.add(db_student)
+    db.commit()
+    db.refresh(db_student)
+    return db_student
+
+def delete_student(db: Session, student_id: int) -> Optional[Student]:
+    """
+
+    Deletes a student from the database.
+    All associated clearance statuses and the linked RFID tag will also be 
+    deleted automatically due to the cascade settings in the data models.
+    """
+    db_student = db.get(Student, student_id)
+    if not db_student:
+        return None
+    
+    db.delete(db_student)
+    db.commit()
+    return db_student

src/crud/tag_linking.py

@@ -0,0 +1,65 @@
+from sqlmodel import Session, select
+from typing import Optional, Union
+
+from src.models import RFIDTag, User, Student, TagLink
+
+def link_tag(db: Session, link_data: TagLink) -> Optional[RFIDTag]:
+    """
+    Links an RFID tag to a user or student.
+
+    This function performs several crucial validation checks:
+    1. Ensures the tag is not already linked to another person.
+    2. Ensures the target user/student does not already have a tag.
+    3. Ensures either a matric_no or username is provided.
+
+    Returns the new RFIDTag object on success, None on failure.
+    The calling router is responsible for raising the appropriate HTTP exception.
+    """
+    # 1. Check if the tag is already in use
+    existing_tag = db.exec(select(RFIDTag).where(RFIDTag.tag_id == link_data.tag_id)).first()
+    if existing_tag:
+        return None # Failure: Tag already exists
+
+    target_person: Optional[Union[User, Student]] = None
+    
+    if link_data.matric_no:
+        target_person = db.exec(select(Student).where(Student.matric_no == link_data.matric_no)).first()
+    elif link_data.username:
+        target_person = db.exec(select(User).where(User.username == link_data.username)).first()
+    else:
+        return None # Failure: No identifier provided
+
+    if not target_person:
+        return None # Failure: Target person not found
+        
+    # 2. Check if the person already has a tag linked
+    if target_person.rfid_tag:
+        return None # Failure: Person already has a tag
+
+    # Create and link the new tag
+    new_tag = RFIDTag(tag_id=link_data.tag_id)
+    if isinstance(target_person, Student):
+        new_tag.student_id = target_person.id
+    else:
+        new_tag.user_id = target_person.id
+        
+    db.add(new_tag)
+    db.commit()
+    db.refresh(new_tag)
+    
+    return new_tag
+
+def unlink_tag(db: Session, tag_id: str) -> Optional[RFIDTag]:
+    """
+    Unlinks an RFID tag, making it available for re-assignment.
+    Returns the deleted tag object on success, None if the tag doesn't exist.
+    """
+    tag_to_delete = db.exec(select(RFIDTag).where(RFIDTag.tag_id == tag_id)).first()
+    
+    if not tag_to_delete:
+        return None # Tag not found
+        
+    db.delete(tag_to_delete)
+    db.commit()
+    
+    return tag_to_delete

src/crud/users.py

@@ -0,0 +1,85 @@
+from sqlmodel import Session, select
+from typing import List, Optional
+
+from src.models import User, UserCreate, UserUpdate, RFIDTag
+from src.auth import hash_password
+
+# --- Read Operations ---
+
+def get_user_by_id(db: Session, user_id: int) -> Optional[User]:
+    """Retrieves a user by their primary key ID."""
+    return db.get(User, user_id)
+
+def get_user_by_username(db: Session, username: str) -> Optional[User]:
+    """Retrieves a user by their unique username."""
+    return db.exec(select(User).where(User.username == username)).first()
+
+def get_user_by_email(db: Session, email: str) -> Optional[User]:
+    """Retrieves a user by their unique email."""
+    return db.exec(select(User).where(User.email == email)).first()
+
+def get_user_by_tag_id(db: Session, tag_id: str) -> Optional[User]:
+    """Retrieves a user by their linked RFID tag ID."""
+    statement = select(User).join(RFIDTag).where(RFIDTag.tag_id == tag_id)
+    return db.exec(statement).first()
+
+def get_all_users(db: Session, skip: int = 0, limit: int = 100) -> List[User]:
+    """Retrieves a paginated list of all users."""
+    return db.exec(select(User).offset(skip).limit(limit)).all()
+
+# --- Write Operations ---
+
+def create_user(db: Session, user: UserCreate) -> User:
+    """
+    Creates a new user.
+    - Hashes the password before saving.
+    - The router should handle checks for existing username/email to provide clean HTTP errors.
+    """
+    hashed_pass = hash_password(user.password)
+    db_user = User(
+        username=user.username,
+        email=user.email,
+        full_name=user.full_name,
+        hashed_password=hashed_pass,
+        role=user.role
+    )
+    db.add(db_user)
+    db.commit()
+    db.refresh(db_user)
+    return db_user
+
+def update_user(db: Session, user_id: int, user_update: UserUpdate) -> Optional[User]:
+    """
+    Updates a user's information.
+    - If a new password is provided, it will be hashed.
+    """
+    db_user = db.get(User, user_id)
+    if not db_user:
+        return None
+
+    update_data = user_update.model_dump(exclude_unset=True)
+    
+    # Hash password if it's being updated
+    if "password" in update_data:
+        update_data["hashed_password"] = hash_password(update_data.pop("password"))
+
+    for key, value in update_data.items():
+        setattr(db_user, key, value)
+    
+    db.add(db_user)
+    db.commit()
+    db.refresh(db_user)
+    return db_user
+
+def delete_user(db: Session, user_id: int) -> Optional[User]:
+    """
+    Deletes a user from the database.
+    The linked RFID tag will also be deleted due to cascade settings.
+    """
+    db_user = db.get(User, user_id)
+    if not db_user:
+        return None
+    
+    db.delete(db_user)
+    db.commit()
+    return db_user

src/crud/utils.py

@@ -0,0 +1,14 @@
+"""
+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

@@ -0,0 +1,35 @@
+from sqlmodel import create_engine, Session, SQLModel
+from src.config import settings
+
+# --- Database Engine Setup ---
+
+# The database URL is constructed from the application settings.
+# This makes it easy to switch between different database environments (e.g., dev, test, prod).
+DATABASE_URL = settings.POSTGRES_URI
+engine = create_engine(DATABASE_URL, echo=True) # echo=True logs SQL queries, useful for debugging
+
+# --- Database Initialization ---
+
+def create_db_and_tables():
+    """
+    Creates all database tables defined by SQLModel metadata.
+    This function is called once at application startup.
+    """
+    print("Initializing database...")
+    SQLModel.metadata.create_all(engine)
+    print("Database tables created successfully (if they didn't exist).")
+
+# --- Database Session Management ---
+
+def get_session():
+    """
+    A FastAPI dependency that provides a database session for each request.
+    It ensures that the session is always closed after the request is finished,
+    even if an error occurs.
+    """
+    with Session(engine) as session:
+        try:
+            yield session
+        finally:
+            session.close()
+

src/models.py

@@ -0,0 +1,130 @@
+from sqlmodel import Field, Relationship, SQLModel
+from typing import List, Optional
+from enum import Enum as PyEnum
+
+# --- Enums for Controlled Vocabularies ---
+# Using enums ensures data consistency for categorical fields.
+
+class UserRole(str, PyEnum):
+    STUDENT = "student"
+    STAFF = "staff"
+    ADMIN = "admin"
+
+class Department(str, PyEnum):
+    LIBRARY = "library"
+    BURSARY = "bursary"
+    ALUMNI = "alumni"
+    DEPARTMENTAL = "departmental"
+
+class ClearanceProcess(str, PyEnum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+
+# --- Database Table Models ---
+
+# Represents a User (Staff or Admin)
+class User(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    username: str = Field(index=True, unique=True)
+    email: str = Field(unique=True)
+    full_name: Optional[str] = None
+    hashed_password: str
+    role: UserRole = Field(default=UserRole.STAFF)
+    is_active: bool = Field(default=True)
+
+    # One-to-one relationship with an RFID tag
+    rfid_tag: Optional["RFIDTag"] = Relationship(back_populates="user")
+
+# Represents a Student
+class Student(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    matric_no: str = Field(index=True, unique=True)
+    full_name: str
+    email: str = Field(unique=True)
+    department: Department
+    hashed_password: str
+
+    # One-to-many relationship with clearance statuses
+    clearance_statuses: List["ClearanceStatus"] = Relationship(
+        back_populates="student", sa_relationship_kwargs={"cascade": "all, delete-orphan"}
+    )
+    # One-to-one relationship with an RFID tag
+    rfid_tag: Optional["RFIDTag"] = Relationship(back_populates="student")
+
+# Represents an RFID tag, linking it to either a User or a Student
+class RFIDTag(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    tag_id: str = Field(index=True, unique=True, description="The unique ID from the RFID chip")
+    
+    # Foreign keys to link to User or Student (only one should be set)
+    user_id: Optional[int] = Field(default=None, foreign_key="user.id")
+    student_id: Optional[int] = Field(default=None, foreign_key="student.id")
+
+    # Relationships back to the owner of the tag
+    user: Optional[User] = Relationship(back_populates="rfid_tag")
+    student: Optional[Student] = Relationship(back_populates="rfid_tag")
+
+# Represents a single clearance status for a student in a specific department
+class ClearanceStatus(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    department: Department
+    status: ClearanceProcess = Field(default=ClearanceProcess.PENDING)
+    
+    student_id: int = Field(foreign_key="student.id")
+    student: Student = Relationship(back_populates="clearance_statuses")
+
+# Represents a physical ESP32 device
+class Device(SQLModel, table=True):
+    id: Optional[int] = Field(default=None, primary_key=True)
+    device_name: str = Field(index=True, unique=True)
+    api_key: str = Field(unique=True)
+    is_active: bool = Field(default=True)
+    department: Department
+
+# --- Pydantic Models for API Operations ---
+# These models define the shape of data for creating and updating records via the API.
+
+# For Users
+class UserCreate(SQLModel):
+    username: str
+    email: str
+    password: str
+    full_name: Optional[str] = None
+    role: UserRole = UserRole.STAFF
+
+class UserUpdate(SQLModel):
+    email: Optional[str] = None
+    full_name: Optional[str] = None
+    password: Optional[str] = None
+    is_active: Optional[bool] = None
+
+# For Students
+class StudentCreate(SQLModel):
+    matric_no: str
+    full_name: str
+    email: str
+    password: str
+
+class StudentUpdate(SQLModel):
+    full_name: Optional[str] = None
+    email: Optional[str] = None
+    password: Optional[str] = None
+
+# For Devices
+class DeviceCreate(SQLModel):
+    device_name: str
+    department: Department
+
+# For Tag Linking
+class TagLink(SQLModel):
+    tag_id: str
+    matric_no: Optional[str] = None
+    username: Optional[str] = None
+
+# For Clearance Updates
+class ClearanceUpdate(SQLModel):
+    matric_no: str
+    department: Department
+    status: ClearanceProcess
+

src/routers/admin.py

@@ -0,0 +1,225 @@
+from fastapi import APIRouter, Depends, HTTPException, status, Query
+from sqlmodel import Session
+from typing import List, Optional, Dict
+
+from src.database import get_session
+from src.auth import get_current_active_user
+from src.models import (
+    User, UserCreate, UserRead, UserUpdate, Role,
+    Student, StudentCreate, StudentRead, StudentUpdate, StudentReadWithClearance,
+    TagLink, RFIDTagRead, TagScan,
+    Device, DeviceCreate, DeviceRead
+)
+from src.crud import users as user_crud
+from src.crud import students as student_crud
+from src.crud import tag_linking as tag_crud
+from src.crud import devices as device_crud
+
+# In-memory storage for last scanned tags by an admin.
+# Key: admin user ID, Value: last scanned tag ID.
+# This is simple and effective for a non-distributed system.
+admin_scanned_tags: Dict[int, str] = {}
+
+# Define the router.
+# It's accessible to both Admins and Staff, providing a unified management panel.
+router = APIRouter(
+    prefix="/admin",
+    tags=["Administration"],
+    dependencies=[Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))],
+)
+
+# --- Admin Tag Scanning for Web UI ---
+
+@router.post("/tags/scan", status_code=status.HTTP_204_NO_CONTENT)
+def report_scanned_tag(
+    scan_data: TagScan,
+    current_user: User = Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))
+):
+    """
+    (Admin & Staff) Endpoint for the admin's desk RFID reader to report a scanned tag.
+    The backend stores this tag ID temporarily against the admin's user ID.
+    """
+    admin_scanned_tags[current_user.id] = scan_data.tag_id
+    return
+
+@router.get("/tags/scan", response_model=TagScan)
+def retrieve_scanned_tag(
+    current_user: User = Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))
+):
+    """
+    (Admin & Staff) Endpoint for the admin's web portal to retrieve the last scanned tag.
+    The tag is removed after being retrieved to prevent re-use.
+    """
+    tag_id = admin_scanned_tags.pop(current_user.id, None)
+    if not tag_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No tag has been scanned recently.")
+    return TagScan(tag_id=tag_id)
+
+
+# --- Student Management (Admin + Staff) ---
+
+@router.post("/students/", response_model=StudentReadWithClearance, status_code=status.HTTP_201_CREATED)
+def create_student(student: StudentCreate, db: Session = Depends(get_session)):
+    """(Admin & Staff) Creates a new student and initializes their clearance status."""
+    db_student = student_crud.get_student_by_matric_no(db, matric_no=student.matric_no)
+    if db_student:
+        raise HTTPException(status_code=400, detail="Matriculation number already registered")
+    return student_crud.create_student(db=db, student=student)
+
+@router.get("/students/", response_model=List[StudentReadWithClearance])
+def read_all_students(skip: int = 0, limit: int = 100, db: Session = Depends(get_session)):
+    """(Admin & Staff) Retrieves a list of all student records."""
+    return student_crud.get_all_students(db, skip=skip, limit=limit)
+
+@router.get("/students/lookup", response_model=StudentReadWithClearance)
+def lookup_student(
+    matric_no: Optional[str] = Query(None, description="Matriculation number of the student."),
+    tag_id: Optional[str] = Query(None, description="RFID tag ID linked to the student."),
+    db: Session = Depends(get_session)
+):
+    """(Admin & Staff) Looks up a single student by Matric Number OR Tag ID."""
+    if not matric_no and not tag_id:
+        raise HTTPException(status_code=400, detail="A matric_no or tag_id must be provided.")
+    if matric_no and tag_id:
+        raise HTTPException(status_code=400, detail="Provide either matric_no or tag_id, not both.")
+
+    db_student = None
+    if matric_no:
+        db_student = student_crud.get_student_by_matric_no(db, matric_no=matric_no)
+    elif tag_id:
+        db_student = student_crud.get_student_by_tag_id(db, tag_id=tag_id)
+    
+    if not db_student:
+        raise HTTPException(status_code=404, detail="Student not found with the provided identifier.")
+    return db_student
+
+
+@router.get("/students/{student_id}", response_model=StudentReadWithClearance)
+def read_single_student(student_id: int, db: Session = Depends(get_session)):
+    """(Admin & Staff) Retrieves a single student's complete record by their internal ID."""
+    db_student = student_crud.get_student_by_id(db, student_id=student_id)
+    if not db_student:
+        raise HTTPException(status_code=404, detail="Student not found")
+    return db_student
+
+@router.put("/students/{student_id}", response_model=StudentReadWithClearance)
+def update_student_details(student_id: int, student: StudentUpdate, db: Session = Depends(get_session)):
+    """(Admin & Staff) Updates a student's information."""
+    updated_student = student_crud.update_student(db, student_id=student_id, student_update=student)
+    if not updated_student:
+        raise HTTPException(status_code=404, detail="Student not found")
+    return updated_student
+
+# --- Tag Management (Admin + Staff) ---
+
+@router.post("/tags/link", response_model=RFIDTagRead)
+def link_rfid_tag(link_data: TagLink, db: Session = Depends(get_session)):
+    """(Admin & Staff) Links an RFID tag to a student or user."""
+    new_tag = tag_crud.link_tag(db, link_data)
+    if not new_tag:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail="Could not link tag. The tag may already be in use, or the user/student already has a tag."
+        )
+    return new_tag
+
+@router.delete("/tags/{tag_id}/unlink", response_model=RFIDTagRead)
+def unlink_rfid_tag(tag_id: str, db: Session = Depends(get_session)):
+    """(Admin & Staff) Unlinks an RFID tag, making it available again."""
+    deleted_tag = tag_crud.unlink_tag(db, tag_id)
+    if not deleted_tag:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="RFID Tag not found.")
+    return deleted_tag
+
+
+# --- Super Admin Only Functions ---
+
+def require_super_admin(current_user: User = Depends(get_current_active_user())):
+    """Dependency to ensure a user has the ADMIN role."""
+    if current_user.role != Role.ADMIN:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="This action requires Super Admin privileges."
+        )
+
+@router.post("/users/", response_model=UserRead, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_super_admin)])
+def create_user(user: UserCreate, db: Session = Depends(get_session)):
+    """(Super Admin Only) Creates a new user (Staff or Admin)."""
+    db_user = user_crud.get_user_by_username(db, username=user.username)
+    if db_user:
+        raise HTTPException(status_code=400, detail="Username already registered")
+    return user_crud.create_user(db=db, user=user)
+
+@router.get("/users/", response_model=List[UserRead], dependencies=[Depends(require_super_admin)])
+def read_all_users(db: Session = Depends(get_session)):
+    """(Super Admin Only) Retrieves a list of all users."""
+    return user_crud.get_all_users(db)
+
+@router.get("/users/lookup", response_model=UserRead, dependencies=[Depends(require_super_admin)])
+def lookup_user(
+    username: Optional[str] = Query(None, description="Username of the user."),
+    tag_id: Optional[str] = Query(None, description="RFID tag ID linked to the user."),
+    db: Session = Depends(get_session)
+):
+    """(Super Admin Only) Looks up a single user by Username OR Tag ID."""
+    if not username and not tag_id:
+        raise HTTPException(status_code=400, detail="A username or tag_id must be provided.")
+    if username and tag_id:
+        raise HTTPException(status_code=400, detail="Provide either username or tag_id, not both.")
+
+    db_user = None
+    if username:
+        db_user = user_crud.get_user_by_username(db, username=username)
+    elif tag_id:
+        db_user = user_crud.get_user_by_tag_id(db, tag_id=tag_id)
+    
+    if not db_user:
+        raise HTTPException(status_code=404, detail="User not found with the provided identifier.")
+    return db_user
+
+@router.put("/users/{user_id}", response_model=UserRead, dependencies=[Depends(require_super_admin)])
+def update_user_details(user_id: int, user: UserUpdate, db: Session = Depends(get_session)):
+    """(Super Admin Only) Updates a user's details (e.g., role)."""
+    updated_user = user_crud.update_user(db, user_id=user_id, user_update=user)
+    if not updated_user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return updated_user
+
+@router.delete("/users/{user_id}", response_model=UserRead, dependencies=[Depends(require_super_admin)])
+def delete_user_account(user_id: int, db: Session = Depends(get_session), current_user: User = Depends(get_current_active_user())):
+    """(Super Admin Only) Deletes a user account."""
+    if current_user.id == user_id:
+        raise HTTPException(status_code=400, detail="Cannot delete your own account.")
+    deleted_user = user_crud.delete_user(db, user_id=user_id)
+    if not deleted_user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return deleted_user
+
+@router.delete("/students/{student_id}", response_model=StudentRead, dependencies=[Depends(require_super_admin)])
+def delete_student_record(student_id: int, db: Session = Depends(get_session)):
+    """(Super Admin Only) Deletes a student record and all associated data."""
+    deleted_student = student_crud.delete_student(db, student_id=student_id)
+    if not deleted_student:
+        raise HTTPException(status_code=404, detail="Student not found")
+    return deleted_student
+
+@router.post("/devices/", response_model=DeviceRead, status_code=status.HTTP_201_CREATED, dependencies=[Depends(require_super_admin)])
+def create_device(device: DeviceCreate, db: Session = Depends(get_session)):
+    """(Super Admin Only) Registers a new RFID hardware device."""
+    db_device = device_crud.get_device_by_location(db, location=device.location)
+    if db_device:
+        raise HTTPException(status_code=400, detail=f"A device at location '{device.location}' already exists.")
+    return device_crud.create_device(db=db, device=device)
+
+@router.get("/devices/", response_model=List[DeviceRead], dependencies=[Depends(require_super_admin)])
+def read_all_devices(db: Session = Depends(get_session)):
+    """(Super Admin Only) Retrieves a list of all registered devices."""
+    return device_crud.get_all_devices(db)
+
+@router.delete("/devices/{device_id}", response_model=DeviceRead, dependencies=[Depends(require_super_admin)])
+def delete_device_registration(device_id: int, db: Session = Depends(get_session)):
+    """(Super Admin Only) De-authorizes a hardware device."""
+    deleted_device = device_crud.delete_device(db, device_id=device_id)
+    if not deleted_device:
+        raise HTTPException(status_code=404, detail="Device not found")
+    return deleted_device

src/routers/clearance.py

@@ -0,0 +1,38 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session
+
+from src.database import get_session
+from src.auth import get_current_active_user
+from src.models import User, Role, ClearanceStatus, ClearanceUpdate, ClearanceStatusRead
+from src.crud import clearance as clearance_crud
+
+router = APIRouter(
+    prefix="/clearance",
+    tags=["Clearance"],
+    dependencies=[Depends(get_current_active_user(required_roles=[Role.STAFF, Role.ADMIN]))],
+)
+
+@router.put("/update", response_model=ClearanceStatusRead)
+def update_student_clearance_status(
+    clearance_update: ClearanceUpdate, 
+    db: Session = Depends(get_session),
+    # The current_user object is injected by the dependency
+    current_user: User = Depends(get_current_active_user(required_roles=[Role.STAFF, Role.ADMIN]))
+):
+    """
+    Endpoint for staff to update a student's clearance status.
+    A staff member can only approve for their own department.
+    (Future enhancement could enforce this rule more strictly).
+    """
+    # A potential security check: ensure staff's department matches clearance_update.department
+    # For now, we trust the role.
+    
+    updated_status = clearance_crud.update_clearance_status(db, clearance_update)
+    
+    if not updated_status:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail=f"No clearance record found for student {clearance_update.matric_no} in department {clearance_update.department}"
+        )
+        
+    return updated_status

src/routers/devices.py

@@ -0,0 +1,68 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session
+from typing import List
+
+from src.database import get_session
+from src.auth import get_current_active_user
+from src.models import Role, Device, DeviceCreate, DeviceRead
+from src.crud import devices as device_crud
+
+# Define the router with admin-only access
+router = APIRouter(
+    prefix="/devices",
+    tags=["Devices"],
+    dependencies=[Depends(get_current_active_user(required_roles=[Role.ADMIN]))],
+)
+
+@router.post("/", response_model=DeviceRead, status_code=status.HTTP_201_CREATED)
+def create_device(
+    device: DeviceCreate, 
+    db: Session = Depends(get_session)
+):
+    """
+    Admin endpoint to register a new RFID hardware device.
+    
+    This generates a unique API key that the device must use to authenticate.
+    A device's location must be unique.
+    """
+    # Check if a device with the same location already exists
+    db_device = device_crud.get_device_by_location(db, location=device.location)
+    if db_device:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"A device at location '{device.location}' already exists."
+        )
+    
+    # Create the new device and its API key
+    return device_crud.create_device(db=db, device=device)
+
+
+@router.get("/", response_model=List[DeviceRead])
+def read_all_devices(
+    skip: int = 0, 
+    limit: int = 100, 
+    db: Session = Depends(get_session)
+):
+    """
+    Admin endpoint to retrieve a list of all registered hardware devices.
+    """
+    return device_crud.get_all_devices(db, skip=skip, limit=limit)
+
+
+@router.delete("/{device_id}", response_model=DeviceRead)
+def delete_device(
+    device_id: int, 
+    db: Session = Depends(get_session)
+):
+    """
+    Admin endpoint to delete/de-authorize a hardware device.
+    
+    This will render the device's API key invalid.
+    """
+    db_device = device_crud.delete_device(db, device_id=device_id)
+    if not db_device:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Device not found."
+        )
+    return db_device

src/routers/rfid.py

@@ -0,0 +1,60 @@
+from fastapi import APIRouter, Depends, HTTPException, status, Security
+from fastapi.security import APIKeyHeader
+from sqlmodel import Session
+
+from src.database import get_session
+from src.auth import get_api_key
+from src.models import RFIDStatusResponse, RFIDScanRequest
+from src.crud import students as student_crud
+from src.crud import users as user_crud
+
+# Define the router and the API key security scheme
+router = APIRouter(prefix="/rfid", tags=["RFID"])
+api_key_header = APIKeyHeader(name="x-api-key", auto_error=False)
+
+@router.post("/check-status", response_model=RFIDStatusResponse)
+def check_rfid_status(
+    scan_data: RFIDScanRequest,
+    db: Session = Depends(get_session),
+    # This dependency ensures the request comes from a valid, registered device
+    api_key: str = Security(get_api_key),
+):
+    """
+    Public endpoint for hardware devices to check the status of a scanned RFID tag.
+    The device must provide a valid API key in the 'x-api-key' header.
+    """
+    tag_id = scan_data.tag_id
+
+    # 1. Check if the tag belongs to a student
+    student = student_crud.get_student_by_tag_id(db, tag_id=tag_id)
+    if student:
+        # Check overall clearance status
+        is_cleared = all(
+            status.status == "approved" for status in student.clearance_statuses
+        )
+        clearance_status_str = "Fully Cleared" if is_cleared else "Pending Clearance"
+        
+        return RFIDStatusResponse(
+            status="found",
+            full_name=student.full_name,
+            entity_type="Student",
+            clearance_status=clearance_status_str,
+        )
+
+    # 2. If not a student, check if it belongs to a user (staff/admin)
+    user = user_crud.get_user_by_tag_id(db, tag_id=tag_id)
+    if user:
+        return RFIDStatusResponse(
+            status="found",
+            full_name=user.full_name,
+            entity_type=user.role.value, # e.g. "Admin" or "Staff"
+            clearance_status="N/A",
+        )
+
+    # 3. If the tag is not linked to anyone
+    return RFIDStatusResponse(
+        status="unregistered",
+        full_name=None,
+        entity_type=None,
+        clearance_status=None,
+    )

src/routers/students.py

@@ -0,0 +1,29 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import Session
+
+from src.database import get_session
+from src.auth import get_current_active_student
+from src.models import Student, StudentReadWithClearance
+
+router = APIRouter(
+    prefix="/students",
+    tags=["Students"],
+)
+
+@router.get("/me", response_model=StudentReadWithClearance)
+def read_student_me(
+    # This dependency ensures the user is an authenticated student
+    # and injects their database object into the 'current_student' parameter.
+    current_student: Student = Depends(get_current_active_student)
+):
+    """
+    Endpoint for a logged-in student to retrieve their own profile
+    and clearance information. The user is identified via their JWT token.
+    """
+    # Because the dependency returns the full student object, we can just return it.
+    # No need for another database call.
+    if not current_student:
+         # This should not happen if the dependency is set up correctly
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
+    return current_student
+

src/routers/token.py

@@ -0,0 +1,41 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from sqlmodel import Session
+from datetime import timedelta
+
+from src.database import get_session
+from src.auth import authenticate_user, create_access_token
+from src.models import Token
+from src.config import settings
+
+router = APIRouter(tags=["Authentication"])
+
+@router.post("/token", response_model=Token)
+async def login_for_access_token(
+    form_data: OAuth2PasswordRequestForm = Depends(), 
+    db: Session = Depends(get_session)
+):
+    """
+    Provides a JWT access token for a valid user (student or staff).
+    
+    This is the primary login endpoint. It uses the standard OAuth2
+    password flow. The client sends 'username' and 'password' in a
+    form-data body.
+    """
+    # The authenticate_user function will check both Student and User tables
+    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"},
+        )
+        
+    # Create the JWT token
+    access_token_expires = timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+    access_token = create_access_token(
+        data={"sub": user.email}, expires_delta=access_token_expires
+    )
+    
+    return {"access_token": access_token, "token_type": "bearer"}

src/routers/users.py

@@ -0,0 +1,25 @@
+from fastapi import APIRouter, Depends
+from sqlmodel import Session
+
+from src.database import get_session
+from src.auth import get_current_active_user
+from src.models import User, UserRead, Role
+
+# Define the router
+router = APIRouter(
+    prefix="/users",
+    tags=["Users"],
+)
+
+@router.get("/me", response_model=UserRead)
+def read_user_me(
+    # This dependency ensures the user is an authenticated Admin or Staff
+    # and injects their database object into the 'current_user' parameter.
+    current_user: User = Depends(get_current_active_user(required_roles=[Role.ADMIN, Role.STAFF]))
+):
+    """
+    Endpoint for a logged-in user (Admin or Staff) to retrieve their own profile.
+    The user is identified via their JWT token.
+    """
+    # The dependency handles fetching the user, so we just return it.
+    return current_user

src/utils.py

@@ -0,0 +1,51 @@
+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
+    )
+