WIP: Backend Service to go up to write code for streamlit next

.gitignore copy

@@ -0,0 +1,186 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.
+.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# OS-generated files
+.DS_Store
+.DS_Store?
+._*
+Thumbs.db
+ehthumbs.db
+desktop.ini
+
+# Editor backup/swap files
+*~
+*.swp
+*.swo

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "7860"]

README copy.md

@@ -1 +0,0 @@
-# clearance_stud

main copy.py

@@ -0,0 +1,51 @@
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware # Keep if CORS is needed
+import uvicorn
+from contextlib import asynccontextmanager
+
+from src.database import create_db_tables, get_db 
+from src.routers import students, devices, clearance, token, users, admin
+
+@asynccontextmanager
+async def lifespan(app_instance: FastAPI):
+    """Handles application startup and shutdown events."""
+    print("Application startup...")
+    create_db_tables()
+    print("Database tables checked/created.")
+    yield
+    print("Application shutdown...")
+
+
+# FastAPI app instance
+app = FastAPI(
+    title="Undergraduate Clearance System API (ORM)",
+    description="API for managing student clearance and RFID interactions.",
+    version="1.1.0", # Incremented version
+    lifespan=lifespan
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins= ['*'],
+    allow_credentials=True,
+    allow_methods=["*"], # Allows all methods
+    allow_headers=["*"], # Allows all headers
+)
+
+# Include routers
+app.include_router(devices.router)
+app.include_router(students.router)
+app.include_router(clearance.router)
+app.include_router(token.router)
+app.include_router(users.router)
+app.include_router(admin.router)
+
+# Root endpoint
+@app.get("/", summary="Root endpoint", tags=["Default"])
+async def read_root():
+    """Basic root endpoint to confirm the API is running."""
+    return {"message": "Undergraduate Clearance System API is running"}
+
+# Run the FastAPI app using Uvicorn
+if __name__ == "__main__":
+    uvicorn.run("main:app", host="0.0.0.0", port=8000, reload=True)

src/auth.py

@@ -1,30 +1,164 @@
-from fastapi import HTTPException, status, Depends
-from src.database import database, devices # Import database instance and devices table
+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
 
-# Dependency to verify the API key sent by ESP32 devices
-async def verify_api_key(api_key: str = Depends(HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Missing API key"))):
-    """
-    Verifies if the provided API key is valid and corresponds to a registered device
-    using the 'databases' library.
+from src import crud, models
+from src.database import get_db
+from typing import Optional, Dict, Any # Added Any
+from datetime import datetime, timedelta
+import jwt
+from typing import Union # For type hinting
 
-    Args:
-        api_key: The API key provided in the request header or body.
+# JWT Configuration - Loaded from models.py (which loads from .env)
+SECRET_KEY = models.JWT_SECRET_KEY
+ALGORITHM = "HS256"
+ACCESS_TOKEN_EXPIRE_MINUTES = 30
 
-    Returns:
-        The database record of the device if the API key is valid.
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/token/login") # Path to token endpoint
+
+# --- 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
 
-    Raises:
-        HTTPException: If the API key is invalid or not found.
-    """
-    # Use 'databases' to execute a select query on the 'devices' table
-    query = devices.select().where(devices.c.api_key == api_key)
-    device = await database.fetch_one(query) # fetch_one returns a single record or None
 
-    if not device:
-        # Raise HTTPException if the API key is not found
+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="Invalid API key",
-            headers={"WWW-Authenticate": "Bearer"}, # Optional: Suggest Bearer token scheme
-        )
-    return device
+            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
+
+# 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/crud.py

@@ -1,151 +1,368 @@
-# Import database instance and tables from database.py
-from src.database import database, students, clearance_statuses, device_logs, devices
-from src.models import StudentCreate, ClearanceStatusCreate, TagScan, DeviceRegister # Import Pydantic models
-# Import necessary SQLAlchemy components for building queries
-from sqlalchemy import select, insert, update
-from datetime import datetime
-import secrets # For generating API keys
-from fastapi import HTTPException # Import HTTPException to raise errors
-
-# --- CRUD operations for Students ---
-
-async def create_student(student: StudentCreate):
-    """Creates a new student record in the database using 'databases'."""
-    # Build an insert query using SQLAlchemy
-    query = students.insert().values(
-        student_id=student.student_id,
-        name=student.name,
-        department=student.department,
-        tag_id=student.tag_id
+# ORM-based CRUD operations
+# All functions are now synchronous and expect a SQLAlchemy Session
+
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+from sqlalchemy import func, and_ # Add other SQLAlchemy functions as needed
+from datetime import datetime, timedelta
+import secrets
+import bcrypt
+from fastapi import HTTPException, status
+from typing import List, Optional, Union # Added Union
+
+from src import models # ORM models and Pydantic models
+from src.database import initialize_student_clearance_statuses_orm # ORM based init
+
+# --- Password Hashing ---
+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'))
+
+# --- Tag Uniqueness Checks (ORM) ---
+def is_tag_id_unique_for_student(db: SQLAlchemySessionType, tag_id: str, exclude_student_pk: Optional[int] = None) -> bool:
+    """Checks if tag_id is unique among students, optionally excluding one by PK."""
+    query = db.query(models.Student).filter(models.Student.tag_id == tag_id)
+    if exclude_student_pk:
+        query = query.filter(models.Student.id != exclude_student_pk)
+    return query.first() is None
+
+def is_tag_id_unique_for_user(db: SQLAlchemySessionType, tag_id: str, exclude_user_pk: Optional[int] = None) -> bool:
+    """Checks if tag_id is unique among users, optionally excluding one by PK."""
+    query = db.query(models.User).filter(models.User.tag_id == tag_id)
+    if exclude_user_pk:
+        query = query.filter(models.User.id != exclude_user_pk)
+    return query.first() is None
+
+def check_tag_id_globally_unique_for_target(
+    db: SQLAlchemySessionType,
+    tag_id: str,
+    target_type: models.TargetUserType, # Expecting the enum member
+    target_pk: Optional[int] = None 
+) -> None:
+    """
+    Raises HTTPException if tag_id is not globally unique, excluding the target if provided.
+    """
+    if target_type == models.TargetUserType.STUDENT:
+        if not is_tag_id_unique_for_student(db, tag_id, exclude_student_pk=target_pk):
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Tag ID '{tag_id}' is already assigned to another student.")
+        if not is_tag_id_unique_for_user(db, tag_id): 
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Tag ID '{tag_id}' is already assigned to a user.")
+    elif target_type == models.TargetUserType.STAFF_ADMIN:
+        if not is_tag_id_unique_for_user(db, tag_id, exclude_user_pk=target_pk):
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Tag ID '{tag_id}' is already assigned to another user.")
+        if not is_tag_id_unique_for_student(db, tag_id): 
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Tag ID '{tag_id}' is already assigned to a student.")
+
+
+# --- Student CRUD (ORM) ---
+def create_student(db: SQLAlchemySessionType, student_data: models.StudentCreate) -> models.Student:
+    existing_student_by_id = db.query(models.Student).filter(models.Student.student_id == student_data.student_id).first()
+    if existing_student_by_id:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Student ID already registered")
+
+    if student_data.email:
+        existing_student_by_email = db.query(models.Student).filter(models.Student.email == student_data.email).first()
+        if existing_student_by_email:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Email already registered")
+
+    if student_data.tag_id:
+        check_tag_id_globally_unique_for_target(db, student_data.tag_id, models.TargetUserType.STUDENT)
+
+    db_student = models.Student(
+        student_id=student_data.student_id,
+        name=student_data.name,
+        email=student_data.email,
+        department=student_data.department, 
+        tag_id=student_data.tag_id,
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow()
     )
-    # Execute the query asynchronously using 'databases'
-    last_record_id = await database.execute(query)
-    # Return the created student data including the generated ID
-    return {**student.dict(), "id": last_record_id}
-
-async def get_all_students():
-    """Retrieves all student records from the database using 'databases'."""
-    # Build a select query using SQLAlchemy
-    query = students.select()
-    # Execute the query and fetch all results asynchronously
-    return await database.fetch_all(query)
-
-async def get_student_by_student_id(student_id: str):
-    """Retrieves a student record by their student ID using 'databases'."""
-    # Build a select query with a where clause
-    query = students.select().where(students.c.student_id == student_id)
-    # Execute the query and fetch one result asynchronously
-    return await database.fetch_one(query)
-
-async def get_student_by_tag_id(tag_id: str):
-    """Retrieves a student record by their tag ID using 'databases'."""
-    # Build a select query with a where clause
-    query = students.select().where(students.c.tag_id == tag_id)
-    # Execute the query and fetch one result asynchronously
-    return await database.fetch_one(query)
-
-# --- CRUD operations for Clearance Statuses ---
-
-async def create_or_update_clearance_status(status_data: ClearanceStatusCreate):
-    """Creates a new clearance status or updates an existing one using 'databases'."""
-    # Check if clearance status already exists for this student and department
-    query = select(clearance_statuses).where(
-        (clearance_statuses.c.student_id == status_data.student_id) &
-        (clearance_statuses.c.department == status_data.department)
+    db.add(db_student)
+    db.commit()
+    db.refresh(db_student)
+    
+    initialize_student_clearance_statuses_orm(db, db_student.student_id)
+    return db_student
+
+def get_all_students(db: SQLAlchemySessionType, skip: int = 0, limit: int = 100) -> List[models.Student]:
+    return db.query(models.Student).offset(skip).limit(limit).all()
+
+def get_student_by_pk(db: SQLAlchemySessionType, student_pk: int) -> Optional[models.Student]:
+    return db.query(models.Student).filter(models.Student.id == student_pk).first()
+
+def get_student_by_student_id(db: SQLAlchemySessionType, student_id: str) -> Optional[models.Student]:
+    return db.query(models.Student).filter(models.Student.student_id == student_id).first()
+
+def get_student_by_tag_id(db: SQLAlchemySessionType, tag_id: str) -> Optional[models.Student]:
+    return db.query(models.Student).filter(models.Student.tag_id == tag_id).first()
+
+def update_student_tag_id(db: SQLAlchemySessionType, student_id_str: str, new_tag_id: str) -> models.Student:
+    student = get_student_by_student_id(db, student_id_str)
+    if not student:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
+    
+    if student.tag_id == new_tag_id: 
+        return student
+
+    check_tag_id_globally_unique_for_target(db, new_tag_id, models.TargetUserType.STUDENT, target_pk=student.id)
+    
+    student.tag_id = new_tag_id
+    student.updated_at = datetime.utcnow()
+    db.commit()
+    db.refresh(student)
+    return student
+
+# --- User (Staff/Admin) CRUD (ORM) ---
+def create_user(db: SQLAlchemySessionType, user_data: models.UserCreate) -> models.User:
+    existing_user = db.query(models.User).filter(models.User.username == user_data.username).first()
+    if existing_user:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Username already registered")
+
+    if user_data.tag_id:
+        check_tag_id_globally_unique_for_target(db, user_data.tag_id, models.TargetUserType.STAFF_ADMIN)
+
+    hashed_pass = hash_password(user_data.password)
+    db_user = models.User(
+        username=user_data.username,
+        hashed_password=hashed_pass,
+        role=user_data.role,  # Pass the enum member directly
+        department=user_data.department, # Pass the enum member directly (or None)
+        tag_id=user_data.tag_id,
+        is_active=user_data.is_active if user_data.is_active is not None else True,
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow()
     )
-    existing_status = await database.fetch_one(query)
+    db.add(db_user)
+    db.commit()
+    db.refresh(db_user)
+    return db_user
+
+def get_users(db: SQLAlchemySessionType, skip: int = 0, limit: int = 100) -> List[models.User]:
+    """Retrieves all staff/admin users with pagination."""
+    return db.query(models.User).offset(skip).limit(limit).all()
+
+def get_user_by_pk(db: SQLAlchemySessionType, user_pk: int) -> Optional[models.User]:
+    return db.query(models.User).filter(models.User.id == user_pk).first()
+    
+def get_user_by_username(db: SQLAlchemySessionType, username: str) -> Optional[models.User]:
+    return db.query(models.User).filter(models.User.username == username).first()
+
+def get_user_by_tag_id(db: SQLAlchemySessionType, tag_id: str) -> Optional[models.User]:
+    return db.query(models.User).filter(models.User.tag_id == tag_id, models.User.is_active == True).first()
+
+def update_user_tag_id(db: SQLAlchemySessionType, username_str: str, new_tag_id: str) -> models.User:
+    user = get_user_by_username(db, username_str)
+    if not user:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="User not found")
+    if not user.is_active:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Cannot update tag for an inactive user.")
+
+    if user.tag_id == new_tag_id: 
+        return user
+
+    check_tag_id_globally_unique_for_target(db, new_tag_id, models.TargetUserType.STAFF_ADMIN, target_pk=user.id)
+        
+    user.tag_id = new_tag_id
+    user.updated_at = datetime.utcnow()
+    db.commit()
+    db.refresh(user)
+    return user
+
+# --- Clearance Status CRUD (ORM) ---
+def create_or_update_clearance_status(
+    db: SQLAlchemySessionType,
+    status_data: models.ClearanceStatusCreate, # Pydantic model with enum members
+    cleared_by_user_pk: Optional[int] = None
+) -> models.ClearanceStatus:
+    
+    existing_status = db.query(models.ClearanceStatus).filter(
+        models.ClearanceStatus.student_id == status_data.student_id,
+        models.ClearanceStatus.department == status_data.department # Comparing enum member from Pydantic to ORM field
+    ).first()
 
     current_time = datetime.utcnow()
 
     if existing_status:
-        # Update existing status
-        query = update(clearance_statuses).where(
-            (clearance_statuses.c.student_id == status_data.student_id) &
-            (clearance_statuses.c.department == status_data.department)
-        ).values(
-            status=status_data.status,
-            remarks=status_data.remarks,
-            updated_at=current_time
-        )
-        await database.execute(query)
-        # Return the updated record including the existing ID and new timestamp
-        return {
-            **status_data.dict(),
-            "id": existing_status["id"],
-            "updated_at": current_time
-        }
+        existing_status.status = status_data.status # Assigning enum member, SQLAlchemy handles value
+        existing_status.remarks = status_data.remarks
+        existing_status.cleared_by = cleared_by_user_pk
+        existing_status.updated_at = current_time
+        db_model = existing_status
     else:
-        # Create new status
-        query = insert(clearance_statuses).values(
+        db_model = models.ClearanceStatus(
             student_id=status_data.student_id,
-            department=status_data.department,
-            status=status_data.status,
+            department=status_data.department, # Assign Pydantic enum member
+            status=status_data.status,         # Assign Pydantic enum member
             remarks=status_data.remarks,
+            cleared_by=cleared_by_user_pk,
+            created_at=current_time,
             updated_at=current_time
         )
-        last_record_id = await database.execute(query)
-        # Return the newly created record including the new ID and timestamp
-        return {
-            **status_data.dict(),
-            "id": last_record_id,
-            "updated_at": current_time
-        }
+        db.add(db_model)
+    
+    db.commit()
+    db.refresh(db_model)
+    return db_model
 
+def get_clearance_statuses_by_student_id(db: SQLAlchemySessionType, student_id_str: str) -> List[models.ClearanceStatus]:
+    return db.query(models.ClearanceStatus).filter(models.ClearanceStatus.student_id == student_id_str).all()
 
-async def get_clearance_statuses_by_student_id(student_id: str):
-    """Retrieves all clearance statuses for a given student ID using 'databases'."""
-    query = select(clearance_statuses).where(clearance_statuses.c.student_id == student_id)
-    return await database.fetch_all(query)
+# --- Device CRUD (ORM) ---
+def create_device(db: SQLAlchemySessionType, device_data: models.DeviceCreateAdmin) -> models.Device:
+    if device_data.device_id: 
+        existing_device_hw_id = db.query(models.Device).filter(models.Device.device_id == device_data.device_id).first()
+        if existing_device_hw_id:
+            raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Device with hardware ID '{device_data.device_id}' already exists.")
 
-# --- CRUD operations for Devices ---
+    api_key = secrets.token_urlsafe(32)
+    db_device = models.Device(
+        name=device_data.name,
+        description=device_data.description,
+        api_key=api_key,
+        device_id=device_data.device_id,
+        location=device_data.location,
+        is_active=True,
+        created_at=datetime.utcnow(),
+        updated_at=datetime.utcnow()
+    )
+    db.add(db_device)
+    db.commit()
+    db.refresh(db_device)
+    return db_device
 
-async def register_device(device_data: DeviceRegister):
-    """Registers a new device or updates an existing one, generating an API key using 'databases'."""
-    api_key = secrets.token_hex(16) # Generate a unique API key
+def register_device_esp(db: SQLAlchemySessionType, device_data: models.DeviceRegister) -> models.Device:
+    api_key = secrets.token_urlsafe(32)
     current_time = datetime.utcnow()
-
-    # Check if device already exists
-    query = select(devices).where(devices.c.device_id == device_data.device_id)
-    existing_device = await database.fetch_one(query)
+    existing_device = db.query(models.Device).filter(models.Device.device_id == device_data.device_id).first()
 
     if existing_device:
-        # Update existing device
-        query = update(devices).where(devices.c.device_id == device_data.device_id).values(
-            location=device_data.location,
-            api_key=api_key, # Assign a new API key on re-registration
-            last_seen=current_time
-        )
-        await database.execute(query)
+        existing_device.location = device_data.location
+        existing_device.api_key = api_key 
+        existing_device.last_seen = current_time
+        existing_device.updated_at = current_time
+        existing_device.is_active = True 
+        db_model = existing_device
     else:
-        # Create new device
-        query = insert(devices).values(
-            device_id=device_data.device_id,
+        db_model = models.Device(
+            device_id=device_data.device_id, 
             location=device_data.location,
             api_key=api_key,
-            last_seen=current_time
+            is_active=True,
+            last_seen=current_time,
+            created_at=current_time,
+            updated_at=current_time
         )
-        await database.execute(query)
+        db.add(db_model)
+    
+    db.commit()
+    db.refresh(db_model)
+    return db_model
+
+def get_device_by_pk(db: SQLAlchemySessionType, device_pk: int) -> Optional[models.Device]:
+    return db.query(models.Device).filter(models.Device.id == device_pk).first()
+
+def get_device_by_api_key(db: SQLAlchemySessionType, api_key: str) -> Optional[models.Device]:
+    return db.query(models.Device).filter(models.Device.api_key == api_key).first()
 
-    # Return the device details including the generated API key
-    # We need to fetch the newly created/updated device to get the assigned API key
-    query = select(devices).where(devices.c.device_id == device_data.device_id)
-    updated_device = await database.fetch_one(query)
-    return {"device_id": updated_device["device_id"], "location": updated_device["location"], "api_key": updated_device["api_key"]}
+def get_device_by_hardware_id(db: SQLAlchemySessionType, hardware_id: str) -> Optional[models.Device]:
+    return db.query(models.Device).filter(models.Device.device_id == hardware_id).first()
 
+def get_all_devices(db: SQLAlchemySessionType, skip: int = 0, limit: int = 100) -> List[models.Device]:
+    return db.query(models.Device).offset(skip).limit(limit).all()
 
-async def update_device_last_seen(device_id: str):
-    """Updates the 'last_seen' timestamp for a given device using 'databases'."""
-    query = update(devices).where(devices.c.device_id == device_id).values(last_seen=datetime.utcnow())
-    await database.execute(query)
+def update_device_last_seen(db: SQLAlchemySessionType, device_pk: int):
+    device = get_device_by_pk(db, device_pk)
+    if device:
+        device.last_seen = datetime.utcnow()
+        device.updated_at = datetime.utcnow()
+        db.commit()
 
-# --- CRUD operations for Device Logs ---
+# --- Device Log CRUD (ORM) ---
+def create_device_log(
+    db: SQLAlchemySessionType,
+    device_pk: Optional[int], 
+    action: str,
+    scanned_tag_id: Optional[str] = None,
+    user_type: Optional[str] = "unknown", # This remains a string as UserRole doesn't cover 'unknown'
+    actual_device_id_str: Optional[str] = None 
+):
+    db_log = models.DeviceLog(
+        device_fk_id=device_pk,
+        actual_device_id_str=actual_device_id_str,
+        tag_id_scanned=scanned_tag_id,
+        user_type=user_type,
+        action=action,
+        timestamp=datetime.utcnow()
+    )
+    db.add(db_log)
+    db.commit()
+    return db_log
+
+# --- Pending Tag Link CRUD (ORM) ---
+def create_pending_tag_link(
+    db: SQLAlchemySessionType,
+    device_pk: int,
+    target_user_type: models.TargetUserType, # Pydantic validated enum member
+    target_identifier: str, 
+    initiated_by_user_pk: int,
+    expires_in_minutes: int = 5
+) -> models.PendingTagLink:
+    
+    device = get_device_by_pk(db, device_pk)
+    if not device:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Device with PK {device_pk} not found.")
+    if not device.is_active:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Device '{device.name or device.device_id}' is not active.")
+
+    if target_user_type == models.TargetUserType.STUDENT:
+        student_target = get_student_by_student_id(db, target_identifier)
+        if not student_target:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Target student with ID '{target_identifier}' not found.")
+        if student_target.tag_id:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Student '{target_identifier}' already has a tag linked.")
+    elif target_user_type == models.TargetUserType.STAFF_ADMIN:
+        user_target = get_user_by_username(db, target_identifier)
+        if not user_target:
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Target user with username '{target_identifier}' not found.")
+        if not user_target.is_active:
+             raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Target user '{target_identifier}' is not active.")
+        if user_target.tag_id:
+            raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"User '{target_identifier}' already has a tag linked.")
+    
+    existing_link = db.query(models.PendingTagLink).filter(
+        models.PendingTagLink.device_id_fk == device_pk,
+        models.PendingTagLink.expires_at > datetime.utcnow()
+    ).first()
+    if existing_link:
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail=f"Device '{device.name or device.device_id}' is already awaiting a tag scan.")
 
-async def create_device_log(device_id: str, tag_id: str, action: str):
-    """Creates a log entry for device activity using 'databases'."""
-    query = device_logs.insert().values(
-        device_id=device_id,
-        tag_id=tag_id,
-        timestamp=datetime.utcnow(),
-        action=action
+    expires_at = datetime.utcnow() + timedelta(minutes=expires_in_minutes)
+    db_pending_link = models.PendingTagLink(
+        device_id_fk=device_pk,
+        target_user_type=target_user_type, # Assign Pydantic enum member
+        target_identifier=target_identifier,
+        initiated_by_user_id=initiated_by_user_pk,
+        expires_at=expires_at,
+        created_at=datetime.utcnow()
     )
-    await database.execute(query)
+    db.add(db_pending_link)
+    db.commit()
+    db.refresh(db_pending_link)
+    return db_pending_link
+
+def get_active_pending_tag_link_by_device_pk(db: SQLAlchemySessionType, device_pk: int) -> Optional[models.PendingTagLink]:
+    return db.query(models.PendingTagLink).filter(
+        models.PendingTagLink.device_id_fk == device_pk,
+        models.PendingTagLink.expires_at > datetime.utcnow()
+    ).order_by(models.PendingTagLink.created_at.desc()).first()
+
+def delete_pending_tag_link(db: SQLAlchemySessionType, pending_link_pk: int):
+    link = db.query(models.PendingTagLink).filter(models.PendingTagLink.id == pending_link_pk).first()
+    if link:
+        db.delete(link)
+        db.commit()

src/database.py

@@ -1,100 +1,99 @@
-import databases
 import sqlalchemy
 import os
 from dotenv import load_dotenv
 from datetime import datetime
 
+# Import Enums, Base, and specific ORM models needed for initialization
+from src.models import (
+    UserRole, ClearanceDepartment, ClearanceStatusEnum, Base, TargetUserType,
+    Student as StudentORM, # Alias to avoid confusion if Student Pydantic model is also imported
+    ClearanceStatus as ClearanceStatusORM, # Alias for ORM model
+    User as UserORM,
+    Device as DeviceORM
+)
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+
 # Load environment variables from a .env file
 load_dotenv()
 
 # Database setup
-# Get the database URL from environment variables
-# IMPORTANT: Ensure your .env file has the correct DATABASE_URL for PostgreSQL
-# Example: DATABASE_URL="postgresql+asyncpg://user:password@host:port/database_name"
 DATABASE_URL = os.getenv("POSTGRES_URI") or os.getenv("DATABASE_URL")
 
 # Check if DATABASE_URL is set
 if not DATABASE_URL:
     raise ValueError("DATABASE_URL environment variable not set!")
 
-# Create a Database instance for asynchronous operations
-# The 'databases' library uses the connection string to determine the dialect and driver
-database = databases.Database(DATABASE_URL)
+# SQLAlchemy engine
+engine = sqlalchemy.create_engine(DATABASE_URL)
 
-# Create a MetaData object to hold the database schema
-metadata = sqlalchemy.MetaData()
+metadata = Base.metadata
 
-# Define the 'students' table using SQLAlchemy
-students = sqlalchemy.Table(
-    "students",
-    metadata,
-    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
-    sqlalchemy.Column("student_id", sqlalchemy.String, unique=True, index=True), # Added index for faster lookups
-    sqlalchemy.Column("name", sqlalchemy.String),
-    sqlalchemy.Column("department", sqlalchemy.String),
-    sqlalchemy.Column("tag_id", sqlalchemy.String, unique=True, index=True), # Added index
-)
+def create_db_tables():
+    """Creates database tables based on SQLAlchemy ORM metadata."""
+    try:
+        print("Attempting to create database tables (if they don't exist)...")
+        metadata.create_all(bind=engine) # Use Base.metadata from models.py
+        print("Database tables creation attempt finished.")
+    except Exception as e:
+        print(f"Error during database table creation: {e}")
+        print("Please ensure your database is accessible and the connection string is correct.")
 
-# Define the 'clearance_statuses' table using SQLAlchemy
-clearance_statuses = sqlalchemy.Table(
-    "clearance_statuses",
-    metadata,
-    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
-    sqlalchemy.Column("student_id", sqlalchemy.String, index=True), # Added index
-    sqlalchemy.Column("department", sqlalchemy.String, index=True), # Added index
-    sqlalchemy.Column("status", sqlalchemy.Boolean, default=False),
-    sqlalchemy.Column("remarks", sqlalchemy.String, nullable=True),
-    sqlalchemy.Column("updated_at", sqlalchemy.DateTime, default=datetime.utcnow),
-    # Add a unique constraint to prevent duplicate entries for the same student and department
-    sqlalchemy.UniqueConstraint('student_id', 'department', name='uq_student_department')
-)
 
-# Define the 'device_logs' table to log device activity using SQLAlchemy
-device_logs = sqlalchemy.Table(
-    "device_logs",
-    metadata,
-    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
-    sqlalchemy.Column("device_id", sqlalchemy.String, index=True), # Added index
-    sqlalchemy.Column("tag_id", sqlalchemy.String, index=True), # Added index
-    sqlalchemy.Column("timestamp", sqlalchemy.DateTime, default=datetime.utcnow),
-    sqlalchemy.Column("action", sqlalchemy.String), # e.g., "scan", "register"
-)
+# Initialize default clearance statuses for new students (Synchronous ORM version)
+def initialize_student_clearance_statuses_orm(db: SQLAlchemySessionType, student_id_str: str):
+    """
+    Creates default clearance status entries for all departments for a new student.
+    Uses SQLAlchemy ORM session.
+    """
+    created_rows_info = []
+    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
 
-# Define the 'devices' table to manage registered ESP32 devices using SQLAlchemy (Location Removed)
-devices = sqlalchemy.Table(
-    "devices",
-    metadata,
-    sqlalchemy.Column("id", sqlalchemy.Integer, primary_key=True),
-    sqlalchemy.Column("device_id", sqlalchemy.String, unique=True, index=True), # Added index
-    # Removed: sqlalchemy.Column("location", sqlalchemy.String),
-    sqlalchemy.Column("api_key", sqlalchemy.String, unique=True, index=True), # Added index for quick API key lookups
-    sqlalchemy.Column("last_seen", sqlalchemy.DateTime, nullable=True),
-)
+    for dept_enum_member in ClearanceDepartment: # Iterate through centralized Enum
+        # Check if status already exists for this student and department
+        existing_status = db.query(ClearanceStatusORM).filter(
+            ClearanceStatusORM.student_id == student_id_str,
+            ClearanceStatusORM.department == dept_enum_member
+        ).first()
 
-# Create a SQLAlchemy engine (used for creating tables - typically run once)
-# Note: For PostgreSQL, check_same_thread=False is not needed.
-# This engine is primarily used here for the metadata.create_all call.
-engine = sqlalchemy.create_engine(DATABASE_URL)
+        if not existing_status:
+            new_status = ClearanceStatusORM(
+                student_id=student_id_str,
+                department=dept_enum_member,
+                status=ClearanceStatusEnum.NOT_COMPLETED,
+                created_at=datetime.utcnow(),
+                updated_at=datetime.utcnow()
+            )
+            db.add(new_status)
+            created_rows_info.append({"department": dept_enum_member.value, "status": "initialized"})
+        else:
+            created_rows_info.append({"department": dept_enum_member.value, "status": "already_exists"})
+    
+    if created_rows_info:
+        try:
+            db.commit()
+            print(f"Committed clearance statuses for student {student_id_str}: {created_rows_info}")
+        except Exception as e:
+            db.rollback()
+            print(f"Error committing clearance statuses for student {student_id_str}: {e}")
+            raise
+    else:
+        print(f"No new clearance statuses to initialize or commit for student {student_id_str}.")
 
-try:
-    print("Attempting to create database tables (if they don't exist)...")
-    metadata.create_all(engine)
-    print("Database tables creation attempt finished.")
-except Exception as e:
-    print(f"Error during database table creation: {e}")
-    print("Please ensure your Supabase database is accessible and the connection string is correct.")
-    print("You might need to manually create tables in Supabase using the provided SQL script.")
 
+from sqlalchemy.orm import sessionmaker
 
-# Database connection lifecycle events (to be called by FastAPI)
-async def connect_db():
-    """Connects to the database on application startup."""
-    print("Connecting to database...") # Added print statement for debugging
-    await database.connect()
-    print("Database connected.") # Added print statement for debugging
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
-async def disconnect_db():
-    """Disconnects from the database on application shutdown."""
-    print("Disconnecting from database...") # Added print statement for debugging
-    await database.disconnect()
-    print("Database disconnected.") # Added print statement for debugging
+def get_db():
+    """
+    FastAPI dependency to get a SQLAlchemy database session.
+    Ensures the session is closed after the request.
+    """
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

src/models.py

@@ -1,52 +1,235 @@
-from pydantic import BaseModel
-from typing import List, Optional
-from datetime import datetime
+from pydantic import BaseModel, Field, EmailStr
+from typing import List, Optional, Dict
+from sqlalchemy import Column, Integer, String, Boolean, DateTime, ForeignKey, Enum as SQLAlchemyEnum
+from sqlalchemy.orm import relationship
+from sqlalchemy.ext.declarative import declarative_base
+from datetime import datetime, timedelta
+import enum
+import os
 
-# Pydantic models for data validation and serialization
+Base = declarative_base()
+
+JWT_SECRET_KEY = os.getenv("JWT_SECRET_KEY", "your-default-secret-key-for-dev-only-CHANGE-ME")
+if JWT_SECRET_KEY == "your-default-secret-key-for-dev-only-CHANGE-ME":
+    print("WARNING: Using default JWT_SECRET_KEY. Please set a strong JWT_SECRET_KEY environment variable for production.")
+
+# Enums - Values must EXACTLY match the labels in the PostgreSQL ENUM types, case-sensitively.
+class UserRole(str, enum.Enum):
+    # This one works with lowercase, so we keep it.
+    STUDENT = "student"
+    STAFF = "staff"
+    ADMIN = "admin"
+
+class ClearanceStatusEnum(str, enum.Enum):
+    # Assuming this enum in the DB uses capitalized labels
+    COMPLETED = "COMPLETED"
+    NOT_COMPLETED = "NOT_COMPLETED"
+    PENDING = "PENDING"
+
+class ClearanceDepartment(str, enum.Enum):
+    DEPARTMENTAL = "DEPARTMENTAL" 
+    LIBRARY = "LIBRARY"
+    BURSARY = "BURSARY"
+    ALUMNI = "ALUMNI"
+class TargetUserType(str, enum.Enum):
+    # Assuming this one is lowercase, a common convention
+    STUDENT = "student"
+    STAFF_ADMIN = "staff_admin"
+
+class OverallClearanceStatusEnum(str, enum.Enum):
+    # These are used within the API logic and may not correspond to a DB type
+    COMPLETED = "COMPLETED"
+    PENDING = "PENDING"
+
+# Helper for SQLAlchemyEnum to ensure values are used
+def enum_values_callable(obj):
+    return [e.value for e in obj]
+
+# --- ORM Model Definitions ---
+
+class Student(Base):
+    __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)
+    email = Column(String, unique=True, index=True, nullable=True)
+    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)
+
+class User(Base):
+    __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)
+    role = Column(SQLAlchemyEnum(UserRole, name="userrole", create_type=False, values_callable=enum_values_callable), default=UserRole.STAFF, nullable=False)
+    department = Column(SQLAlchemyEnum(ClearanceDepartment, name="clearancedepartment", create_type=False, values_callable=enum_values_callable), nullable=True)
+    tag_id = Column(String, unique=True, index=True, nullable=True)
+    is_active = Column(Boolean, default=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+
+class ClearanceStatus(Base):
+    __tablename__ = "clearance_statuses"
+    id = Column(Integer, primary_key=True, autoincrement=True, index=True)
+    student_id = Column(String, ForeignKey("students.student_id"), index=True, nullable=False)
+    department = Column(SQLAlchemyEnum(ClearanceDepartment, name="clearancedepartment", create_type=False, values_callable=enum_values_callable), index=True, nullable=False)
+    status = Column(SQLAlchemyEnum(ClearanceStatusEnum, name="clearancestatusenum", create_type=False, values_callable=enum_values_callable), default=ClearanceStatusEnum.NOT_COMPLETED, nullable=False)
+    remarks = Column(String, nullable=True)
+    cleared_by = Column(Integer, ForeignKey("users.id"), nullable=True)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    created_at = Column(DateTime, default=datetime.utcnow)
+
+class Device(Base):
+    __tablename__ = "devices"
+    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
+    name = Column(String, index=True, 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)
+    description = Column(String, nullable=True)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
+    last_seen = Column(DateTime, nullable=True)
+
+class PendingTagLink(Base):
+    __tablename__ = "pending_tag_links"
+    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
+    device_id_fk = Column(Integer, ForeignKey("devices.id"), index=True, nullable=False, name="device_id")
+    target_user_type = Column(SQLAlchemyEnum(TargetUserType, name="targetusertype", create_type=False, values_callable=enum_values_callable), nullable=False)
+    target_identifier = Column(String, nullable=False)
+    initiated_by_user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
+    created_at = Column(DateTime, default=datetime.utcnow)
+    expires_at = Column(DateTime, nullable=False)
+
+class DeviceLog(Base):
+    __tablename__ = "device_logs"
+    id = Column(Integer, primary_key=True, index=True, autoincrement=True)
+    device_fk_id = Column(Integer, ForeignKey("devices.id"), index=True, nullable=True, name="device_id")
+    actual_device_id_str = Column(String, index=True, nullable=True)
+    tag_id_scanned = Column(String, index=True, nullable=True)
+    user_type = Column(String, nullable=True)
+    action = Column(String, nullable=False)
+    timestamp = Column(DateTime, default=datetime.utcnow, nullable=False)
+
+# --- Pydantic Models ---
 
 class StudentCreate(BaseModel):
-    """Model for creating a new student."""
     student_id: str
     name: str
+    email: Optional[EmailStr] = None
     department: str
-    tag_id: str
+    tag_id: Optional[str] = None
 
-class Student(StudentCreate):
-    """Model for returning student data, including database ID."""
+class StudentResponse(BaseModel):
     id: int
+    student_id: str
+    name: str
+    email: Optional[EmailStr] = None
+    department: str
+    tag_id: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    class Config: from_attributes = True
+
+class UserBase(BaseModel):
+    username: str
+    role: UserRole
+    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
+    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 ClearanceStatusCreate(BaseModel):
-    """Model for creating or updating a student's clearance status for a specific department."""
     student_id: str
-    department: str
-    status: bool
+    department: ClearanceDepartment
+    status: ClearanceStatusEnum
+    remarks: Optional[str] = None
+
+class ClearanceStatusItem(BaseModel):
+    department: ClearanceDepartment
+    status: ClearanceStatusEnum
     remarks: Optional[str] = None
+    updated_at: datetime
+    class Config: from_attributes = True
 
-class ClearanceStatus(ClearanceStatusCreate):
-    """Model for returning clearance status data, including database ID and update timestamp."""
+class ClearanceStatusResponse(BaseModel):
     id: int
+    student_id: str
+    department: ClearanceDepartment
+    status: ClearanceStatusEnum
+    remarks: Optional[str] = None
+    cleared_by: Optional[int] = None
     updated_at: datetime
+    created_at: datetime
+    class Config: from_attributes = True
 
 class ClearanceDetail(BaseModel):
-    """Model for returning a student's full clearance details."""
     student_id: str
     name: str
     department: str
-    clearance_items: List[dict] # List of dictionaries representing each clearance item
-    overall_status: bool
+    clearance_items: List[ClearanceStatusItem]
+    overall_status: OverallClearanceStatusEnum
+    class Config: from_attributes = True
 
 class DeviceRegister(BaseModel):
-    """Model for registering a new ESP32 device."""
     device_id: str
     location: str
 
-class DeviceResponse(DeviceRegister):
-    """Model for returning device registration details, including the API key."""
+class DeviceCreateAdmin(BaseModel):
+    name: str
+    description: Optional[str] = None
+    device_id: Optional[str] = None
+    location: Optional[str] = None
+
+class DeviceResponse(BaseModel):
+    id: int
+    name: Optional[str] = None
+    device_id: Optional[str] = None
+    location: Optional[str] = None
     api_key: str
+    is_active: bool
+    description: Optional[str] = None
+    created_at: datetime
+    updated_at: datetime
+    last_seen: Optional[datetime] = None
+    class Config: from_attributes = True
 
 class TagScan(BaseModel):
-    """Model for data received from an ESP32 device after scanning a tag."""
     device_id: str
     tag_id: str
-    api_key: str
-    timestamp: datetime
+    timestamp: Optional[datetime] = Field(default_factory=datetime.utcnow)
+
+class Token(BaseModel):
+    access_token: str
+    token_type: str
+
+class TokenData(BaseModel):
+    username: Optional[str] = None
+    role: Optional[UserRole] = None
+
+class TagLinkRequest(BaseModel):
+    tag_id: str
+
+class PrepareTagLinkRequest(BaseModel):
+    device_identifier: str
+    target_user_type: TargetUserType
+    target_identifier: str
+
+class ScannedTagSubmit(BaseModel):
+    scanned_tag_id: str

src/routers/admin.py

@@ -0,0 +1,109 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+from typing import List, Optional, Dict
+
+from src import crud, models # crud functions are now sync ORM
+from src.database import get_db
+from src.auth import (
+    get_current_active_admin_user_from_token, # Returns ORM User model (Token-based)
+)
+from fastapi.concurrency import run_in_threadpool 
+
+router = APIRouter(
+    prefix="/api/admin",
+    tags=["admin"],
+    dependencies=[Depends(get_current_active_admin_user_from_token)]
+)
+
+# --- Device Management Endpoints (Synchronous ORM) ---
+@router.post("/devices/", response_model=models.DeviceResponse, status_code=status.HTTP_201_CREATED)
+def register_new_device_admin( # Endpoint is synchronous
+    device_data: models.DeviceCreateAdmin,
+    db: SQLAlchemySessionType = Depends(get_db),
+    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging who did it
+):
+    """
+    Admin registers a new ESP32/RFID reader device. Uses ORM.
+    """
+    print(f"Admin '{current_admin_orm.username}' creating device: {device_data.name}")
+    try:
+        created_device_orm = crud.create_device(db=db, device_data=device_data)
+    except HTTPException as e:
+        raise e
+    return created_device_orm # Pydantic converts from ORM model
+
+@router.get("/devices/", response_model=List[models.DeviceResponse])
+def list_all_devices_admin( # Endpoint is synchronous
+    skip: int = 0,
+    limit: int = 100,
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Admin lists all registered devices. Uses ORM.
+    """
+    devices_orm_list = crud.get_all_devices(db, skip=skip, limit=limit)
+    return devices_orm_list
+
+@router.get("/devices/{device_pk_id}", response_model=models.DeviceResponse)
+def get_device_details_admin( # Endpoint is synchronous
+    device_pk_id: int,
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Admin gets details of a specific device by its Primary Key. Uses ORM.
+    """
+    # crud.get_device_by_pk is now sync ORM
+    db_device_orm = crud.get_device_by_pk(db, device_pk=device_pk_id)
+    if db_device_orm is None:
+        raise HTTPException(status_code=404, detail="Device not found")
+    return db_device_orm
+
+# --- Tag Linking Preparation Endpoint (Synchronous ORM) ---
+@router.post("/prepare-device-tag-link", status_code=status.HTTP_202_ACCEPTED, response_model=Dict)
+def prepare_device_for_tag_linking_admin( # Endpoint is synchronous
+    request_payload: models.PrepareTagLinkRequest,
+    db: SQLAlchemySessionType = Depends(get_db),
+    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
+):
+    """
+    Admin prepares a device for tag linking. Uses synchronous ORM.
+    """
+    device_identifier_val = request_payload.device_identifier
+    device_orm_instance: Optional[models.Device] = None
+
+    try: 
+        device_pk = int(device_identifier_val)
+        device_orm_instance = crud.get_device_by_pk(db, device_pk)
+    except ValueError: # If not an int, assume it's the hardware string ID
+        device_orm_instance = crud.get_device_by_hardware_id(db, device_identifier_val)
+
+    if not device_orm_instance:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=f"Device with identifier '{device_identifier_val}' not found.")
+    if not device_orm_instance.is_active: # Check if device is active
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail=f"Device '{device_orm_instance.name or device_orm_instance.device_id}' is not active.")
+
+    device_pk_for_link = device_orm_instance.id
+    admin_user_pk = current_admin_orm.id # User's primary key
+
+    try:
+        pending_link_orm = crud.create_pending_tag_link(
+            db=db,
+            device_pk=device_pk_for_link,
+            target_user_type=request_payload.target_user_type,
+            target_identifier=request_payload.target_identifier,
+            initiated_by_user_pk=admin_user_pk, # Pass admin's PK
+            expires_in_minutes=5
+        )
+        
+        device_display_name = device_orm_instance.name or device_orm_instance.device_id or f"PK:{device_pk_for_link}"
+        return {
+            "message": f"Device '{device_display_name}' is now ready to scan a tag for {request_payload.target_user_type.value} '{request_payload.target_identifier}'. Tag scan must occur within 5 minutes.",
+            "pending_link_id": pending_link_orm.id,
+            "expires_at": pending_link_orm.expires_at.isoformat()
+        }
+    except HTTPException as e: # Catch known exceptions from CRUD (e.g., 409 if device busy)
+        raise e
+    except Exception as e:
+        print(f"Unexpected error in prepare_device_for_tag_linking_admin: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=f"An unexpected error occurred: {str(e)}")
+

src/routers/clearance.py

@@ -0,0 +1,100 @@
+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, Optional # For type hinting
+
+from src import crud, models
+from src.auth import (
+    get_current_staff_or_admin_via_tag, # Returns ORM User model (Tag-based)
+    get_current_student_via_tag,        # Returns ORM Student model (Tag-based)
+    verify_department_access            # Sync utility function
+)
+from src.database import get_db
+
+router = APIRouter(
+    prefix="/api/clearance",
+    tags=["clearance"],
+)
+
+@router.post("/", response_model=models.ClearanceStatusResponse)
+async def update_clearance_status_endpoint( # Async endpoint
+    status_data: models.ClearanceStatusCreate,
+    db: SQLAlchemySessionType = Depends(get_db),
+    # current_user_orm is User ORM model (staff/admin) via Tag-based auth
+    current_user_orm: models.User = Depends(get_current_staff_or_admin_via_tag)
+):
+    """
+    Staff/Admin creates or updates a student's clearance status. Uses ORM.
+    """
+    # crud.get_student_by_student_id is sync
+    student_orm = await run_in_threadpool(crud.get_student_by_student_id, db, status_data.student_id)
+    if not student_orm:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Student not found")
+
+    # verify_department_access is sync
+    # status_data.department is ClearanceDepartment enum from Pydantic
+    if not verify_department_access(current_user_orm.role, current_user_orm.department, status_data.department):
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail=f"User '{current_user_orm.username}' does not have permission to update clearance for the {status_data.department.value} department."
+        )
+    
+    cleared_by_user_pk = current_user_orm.id # User's primary key
+
+    try:
+        # crud.create_or_update_clearance_status is sync, returns ORM model
+        updated_status_orm = await run_in_threadpool(
+            crud.create_or_update_clearance_status, db, status_data, cleared_by_user_pk
+        )
+    except HTTPException as e: # Catch known errors from CRUD
+        raise e
+    return updated_status_orm # Pydantic converts from ORM model
+
+
+# Helper for student's own clearance view (similar to one in students.py/devices.py)
+async def _format_my_clearance_response(
+    db: SQLAlchemySessionType,
+    student_orm: models.Student # Expect Student ORM model
+) -> models.ClearanceDetail:
+    
+    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
+    )
+
+@router.get("/me", response_model=models.ClearanceDetail)
+async def get_my_clearance_status( # Async endpoint
+    # current_student_orm is Student ORM model via Tag-based auth
+    current_student_orm: models.Student = Depends(get_current_student_via_tag),
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Student retrieves their own complete clearance status via RFID Tag. Uses ORM.
+    """
+    return await _format_my_clearance_response(db, current_student_orm)
+

src/routers/devices.py

@@ -0,0 +1,211 @@
+from fastapi import APIRouter, HTTPException, Depends, status, Header
+from fastapi.concurrency import run_in_threadpool
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+from typing import Dict, Any, List, Optional # Added List for _format_clearance_for_scan_response
+
+from src import crud, models
+from src.database import get_db
+from src.auth import get_verified_device # Returns ORM Device model
+
+router = APIRouter(
+    prefix="/api", # Keep common prefix or change to /api/devices if preferred
+    tags=["devices"],
+)
+
+@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_esp, 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
+
+
+# Helper for formatting scan response (moved to be more specific to this router's needs)
+async def _format_clearance_for_device_scan(
+    db: SQLAlchemySessionType, # Pass db session for sync crud calls
+    student_orm: models.Student # Expect Student ORM model
+) -> models.ClearanceDetail:
+    """Helper to format clearance details for the /scan endpoint response using ORM."""
+    
+    # crud.get_clearance_statuses_by_student_id is sync, needs run_in_threadpool
+    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, # Already enum from ORM
+            status=status_orm.status,       # Already enum from ORM
+            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
+    )
+
+@router.post("/scan", response_model=models.ClearanceDetail)
+async def scan_tag_endpoint( # Async endpoint
+    scan_data: models.TagScan, # Contains device_id (hardware_id) and tag_id
+    verified_device_orm: models.Device = Depends(get_verified_device), # Returns ORM Device model
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Device scans a tag. Verifies device, logs scan, gets student clearance. ORM-based.
+    """
+    if verified_device_orm.device_id != scan_data.device_id: # Compare hardware IDs
+        # This might indicate a misconfiguration or an attempt to spoof.
+        # Log this with verified_device_orm.id and scan_data.device_id
+        await run_in_threadpool(
+            crud.create_device_log, db, verified_device_orm.id, "scan_error_device_id_mismatch",
+            scanned_tag_id=scan_data.tag_id, actual_device_id_str=scan_data.device_id
+        )
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Device identity mismatch. API key valid, but payload device_id differs."
+        )
+
+    device_pk = verified_device_orm.id
+    device_hw_id = verified_device_orm.device_id # ESP32's hardware ID (string)
+
+    # Update last seen (sync crud)
+    await run_in_threadpool(crud.update_device_last_seen, db, device_pk)
+    
+    # Check if tag belongs to a student
+    student_orm = await run_in_threadpool(crud.get_student_by_tag_id, db, scan_data.tag_id)
+
+    if student_orm:
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk, "scan_student_clearance",
+            scanned_tag_id=scan_data.tag_id, user_type=models.UserRole.STUDENT.value, actual_device_id_str=device_hw_id
+        )
+        return await _format_clearance_for_device_scan(db, student_orm)
+    else:
+        # Check if tag belongs to staff/admin (not for clearance check, but for logging)
+        user_orm = await run_in_threadpool(crud.get_user_by_tag_id, db, scan_data.tag_id)
+        user_type_log = models.UserRole.ADMIN.value if user_orm and user_orm.role == models.UserRole.ADMIN else \
+                        models.UserRole.STAFF.value if user_orm and user_orm.role == models.UserRole.STAFF else \
+                        "unknown_user_tag"
+        
+        await run_in_threadpool(
+             crud.create_device_log, db, device_pk, f"scan_failed_not_student_tag ({user_type_log})",
+             scanned_tag_id=scan_data.tag_id, user_type=user_type_log, actual_device_id_str=device_hw_id
+        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Tag does not belong to a registered student for clearance check.")
+
+
+@router.post("/devices/submit-scanned-tag", response_model=Dict) # Return a success message dict
+async def submit_scanned_tag_endpoint( # Async endpoint
+    payload: models.ScannedTagSubmit, # Contains scanned_tag_id
+    verified_device_orm: models.Device = Depends(get_verified_device), # Returns ORM Device model
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Device submits a scanned tag to complete a pending link. ORM-based.
+    """
+    device_pk = verified_device_orm.id
+    device_hw_id = verified_device_orm.device_id # ESP32's hardware ID (string)
+
+    # crud.get_active_pending_tag_link_by_device_pk is sync
+    pending_link_orm = await run_in_threadpool(crud.get_active_pending_tag_link_by_device_pk, db, device_pk)
+
+    if not pending_link_orm:
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk, "submit_tag_failed_no_pending",
+            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
+        )
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No active tag linking process for this device.")
+
+    # Check tag uniqueness (crud.check_tag_id_globally_unique_for_target is sync and raises HTTPException)
+    try:
+        await run_in_threadpool(
+            crud.check_tag_id_globally_unique_for_target,
+            db,
+            payload.scanned_tag_id,
+            pending_link_orm.target_user_type, # Pass the TargetUserType enum
+            # PK of the target entity (student.id or user.id) is NOT known here yet.
+            # The check_tag_id_globally_unique_for_target needs to be careful if target_pk is None
+            # or fetch the target's PK if the identifier is unique (student_id/username).
+            # For now, pass None for target_pk, meaning it checks against ALL existing.
+            # This is safer. If target was already assigned this tag, it should have been caught
+            # during prepare_tag_link.
+            None 
+        )
+    except HTTPException as e_tag_conflict: # Specifically catch tag conflict from the check
+        await run_in_threadpool(crud.delete_pending_tag_link, db, pending_link_orm.id) # Cancel link
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk, "submit_tag_failed_tag_conflict",
+            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
+        )
+        raise e_tag_conflict # Re-raise the 409
+
+    linked_identifier_val: Optional[str] = None
+    try:
+        if pending_link_orm.target_user_type == models.TargetUserType.STUDENT:
+            # crud.update_student_tag_id is sync
+            updated_student_orm = await run_in_threadpool(
+                crud.update_student_tag_id, db, pending_link_orm.target_identifier, payload.scanned_tag_id
+            )
+            linked_identifier_val = updated_student_orm.student_id
+        elif pending_link_orm.target_user_type == models.TargetUserType.STAFF_ADMIN:
+            # crud.update_user_tag_id is sync
+            updated_user_orm = await run_in_threadpool(
+                crud.update_user_tag_id, db, pending_link_orm.target_identifier, payload.scanned_tag_id
+            )
+            linked_identifier_val = updated_user_orm.username
+        
+        # Delete the processed pending link (sync crud)
+        await run_in_threadpool(crud.delete_pending_tag_link, db, pending_link_orm.id)
+        
+        # Log success (sync crud)
+        await run_in_threadpool(crud.update_device_last_seen, db, device_pk)
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk,
+            f"tag_linked_to_{pending_link_orm.target_user_type.value}:{linked_identifier_val}",
+            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
+        )
+
+        return {
+            "message": f"Tag ID '{payload.scanned_tag_id}' successfully linked to {pending_link_orm.target_user_type.value} '{linked_identifier_val}'.",
+            "device_id": device_hw_id,
+            "tag_id": payload.scanned_tag_id,
+        }
+    except HTTPException as e_update: # Catch errors from update_..._tag_id
+        # If update fails (e.g. target not found, though checked in prepare), log and raise
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk, f"submit_tag_failed_update_error: {e_update.detail}",
+            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
+        )
+        # Consider if pending link should be deleted on update failure.
+        # It might be better to leave it for investigation if it wasn't a tag conflict.
+        raise e_update
+    except Exception as e_generic:
+        print(f"Unexpected error during submit_scanned_tag: {e_generic}")
+        await run_in_threadpool(
+            crud.create_device_log, db, device_pk, "submit_tag_failed_unexpected_error",
+            scanned_tag_id=payload.scanned_tag_id, actual_device_id_str=device_hw_id
+        )
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred linking the tag.")
+

src/routers/students.py

@@ -0,0 +1,109 @@
+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, Dict, Any # For type hinting
+
+from src import crud, models
+from src.auth import get_current_active_admin_user_from_token # Returns ORM User
+from src.database import get_db
+
+router = APIRouter(
+    prefix="/api/students",
+    tags=["students"],
+    # All student management routes require an active admin (token-based)
+    dependencies=[Depends(get_current_active_admin_user_from_token)]
+)
+
+# Helper function to format clearance details for student endpoints
+# This is very similar to the one in devices.py, consider consolidating to a utils.py
+async def _format_student_clearance_details_response(
+    db: SQLAlchemySessionType,
+    student_orm: models.Student
+) -> models.ClearanceDetail:
+    
+    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
+    )
+
+@router.post("/", response_model=models.StudentResponse, status_code=status.HTTP_201_CREATED)
+async def create_student_endpoint( # Async endpoint
+    student_data: models.StudentCreate,
+    db: SQLAlchemySessionType = Depends(get_db),
+    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging
+):
+    """Admin creates a new student. Uses ORM."""
+    try:
+        # crud.create_student is sync, handles checks and returns ORM model
+        created_student_orm = await run_in_threadpool(crud.create_student, db, student_data)
+    except HTTPException as e: # Catch known exceptions from CRUD (e.g., student_id exists)
+        raise e
+    return created_student_orm # Pydantic converts from ORM model
+
+@router.get("/", response_model=List[models.StudentResponse])
+async def get_students_endpoint( # Async endpoint
+    skip: int = 0,
+    limit: int = 100,
+    db: SQLAlchemySessionType = Depends(get_db),
+    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
+):
+    """Admin gets all students. Uses ORM."""
+    # crud.get_all_students is sync
+    students_orm_list = await run_in_threadpool(crud.get_all_students, db, skip, limit)
+    return students_orm_list # Pydantic converts list of ORM models
+
+@router.get("/{student_id_str}", response_model=models.ClearanceDetail)
+async def get_student_clearance_endpoint( # Async endpoint
+    student_id_str: str,
+    db: SQLAlchemySessionType = Depends(get_db),
+    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
+):
+    """Admin gets clearance details for a specific student. Uses ORM."""
+    # crud.get_student_by_student_id is sync
+    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_response(db, student_orm)
+
+@router.put("/{student_id_str}/link-tag", response_model=models.StudentResponse)
+async def link_student_tag_endpoint( # Async endpoint
+    student_id_str: str,
+    tag_link_request: models.TagLinkRequest,
+    db: SQLAlchemySessionType = Depends(get_db),
+    # current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token)
+):
+    """Admin links or updates RFID tag for a student. Uses ORM."""
+    try:
+        # crud.update_student_tag_id is sync, handles checks
+        updated_student_orm = await run_in_threadpool(crud.update_student_tag_id, db, student_id_str, tag_link_request.tag_id)
+    except HTTPException as e: # Catch known errors from CRUD
+        raise e
+    except Exception as e_generic:
+        print(f"Unexpected error in link_student_tag_endpoint: {e_generic}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred.")
+    return updated_student_orm

src/routers/token.py

@@ -0,0 +1,49 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from fastapi.concurrency import run_in_threadpool # To call sync CRUD in async endpoint
+from sqlalchemy.orm import Session as SQLAlchemySessionType
+
+from src import crud, models # crud now contains sync ORM functions
+from src.auth import create_access_token # JWT creation is sync
+from src.database import get_db # Dependency for SQLAlchemy session
+
+router = APIRouter(
+    prefix="/api/token",
+    tags=["authentication"],
+)
+
+@router.post("/login", response_model=models.Token)
+async def login_for_access_token( # Endpoint remains async
+    form_data: OAuth2PasswordRequestForm = Depends(),
+    db: SQLAlchemySessionType = Depends(get_db)
+):
+    """
+    Provides an access token for an authenticated staff or admin user.
+    Requires username and password. Uses ORM.
+    """
+    # crud.get_user_by_username is now sync, call with run_in_threadpool
+    user = await run_in_threadpool(crud.get_user_by_username, db, form_data.username)
+    
+    if not user:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    # crud.verify_password is sync
+    is_password_valid = await run_in_threadpool(crud.verify_password, form_data.password, user.hashed_password)
+    if not is_password_valid:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+    if not user.is_active:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="Inactive user")
+        
+    access_token = create_access_token( # create_access_token is sync
+        data={"sub": user.username, "role": user.role.value} # user.role is UserRole enum
+    )
+    return {"access_token": access_token, "token_type": "bearer"}

src/routers/users.py

@@ -0,0 +1,85 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+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 # Returns ORM User
+from src.database import get_db
+from src.auth import get_current_active_user # Returns ORM User model
+
+
+router = APIRouter(
+    prefix="/api/users",
+    tags=["users"],
+)
+
+@router.post("/register", response_model=models.UserResponse, status_code=status.HTTP_201_CREATED)
+async def register_user( # Endpoint remains async
+    user_data: models.UserCreate,
+    db: SQLAlchemySessionType = Depends(get_db),
+   ):
+    """
+    Admin registers a new staff or admin user. Uses ORM.
+    """
+    # Role check (user_data.role is already UserRole enum from Pydantic)
+    if user_data.role not in [models.UserRole.STAFF, models.UserRole.ADMIN]:
+         raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"User role must be '{models.UserRole.STAFF.value}' or '{models.UserRole.ADMIN.value}'"
+        )
+    
+    # Check if username already exists  
+    try:
+        created_user_orm = await run_in_threadpool(crud.create_user, db, user_data)
+    except HTTPException as e: # Catch HTTPExceptions raised by CRUD (e.g., username exists)
+        raise e
+    
+    return created_user_orm # Pydantic UserResponse will convert from ORM model
+
+@router.put("/{username_str}/link-tag", response_model=models.UserResponse)
+async def link_user_tag_endpoint( # Endpoint remains async
+    username_str: str,
+    tag_link_request: models.TagLinkRequest,
+    db: SQLAlchemySessionType = Depends(get_db),
+    current_admin_orm: models.User = Depends(get_current_active_admin_user_from_token) # For logging, if needed
+):
+    """
+    Admin links or updates the RFID tag_id for a specific staff/admin user. Uses ORM.
+    """
+    try:
+        # crud.update_user_tag_id is sync, call with run_in_threadpool
+        # It handles tag uniqueness and user existence checks.
+        updated_user_orm = await run_in_threadpool(crud.update_user_tag_id, db, username_str, tag_link_request.tag_id)
+    except HTTPException as e: # Catch HTTPExceptions from CRUD
+        raise e
+    except Exception as e:
+        # Generic error logging
+        print(f"Unexpected error in link_user_tag_endpoint: {e}")
+        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail="An unexpected error occurred.")
+        
+    return updated_user_orm # Pydantic UserResponse will convert
+
+@router.get("/", response_model=List[models.UserResponse])
+async def list_all_users( 
+    skip: int = 0,
+    limit: int = 100,
+    db: SQLAlchemySessionType = Depends(get_db),
+):
+    """
+    Admin lists all staff/admin users with pagination. Uses ORM.
+    """
+    # crud.get_users is sync, call with run_in_threadpool
+    users_orm_list = await run_in_threadpool(crud.get_users, db, skip, limit)
+    return users_orm_list # Pydantic will convert the list of ORM User models
+
+@router.get("/users/me", response_model=models.UserResponse, summary="Get current authenticated user details")
+async def read_users_me(
+    current_user_orm: models.User = Depends(get_current_active_user) # Depends on token auth
+):
+    """
+    Returns the details of the currently authenticated user (via token).
+    The user object is already an ORM model instance.
+    Pydantic's UserResponse will convert it using from_attributes=True.
+    """
+    return current_user_orm