Python 3.10+ FastAPI PostgreSQL Moodle LMS

Examination Middleware

LMS-SAE Bridge

A robust, secure, and automated bridge designed to streamline the digitization and submission of physical examination answer sheets to the Moodle Learning Management System.

Quick Start View Architecture
3-Step
Upload-Verify-Push
100%
Student Verification
Complete
Audit Trail
15+
API Endpoints

The Problem

In academic institutions transitioning to digital grading, handling physical answer scripts presents significant challenges.

Manual Labor

Individually scanning, renaming, and uploading hundreds of answer scripts is time-consuming and inefficient.

Human Error

Manual processes are prone to uploading wrong files or mislabeling student submissions.

Security & Integrity

Direct database manipulation or unverified uploads can compromise the chain of custody.

Student Verification

Students lack a mechanism to verify their physical paper was scanned correctly before grading.

The Solution

Our 3-Step "Upload-Verify-Push" workflow decouples scanning from submission with a secure validation layer.

1

Bulk Ingestion

Administrative staff upload bulk batches of scanned PDF/Images.

2

Intelligent Processing

System parses filenames to extract Student Register Number and Subject Code automatically.

3

Student-Led Submission

Students log in, view their scripts, and trigger final submission ensuring non-repudiation.

Core Concept

The system acts as an intelligent intermediary between the physical examination hall and the digital grading environment, ensuring secure validation and student verification at every step.

Non-repudiation Audit Trail Secure Tokens

System Architecture

Designed for data integrity, security, and complete auditability

Physical Layer

Scanned Answer Sheets

611221104088_19AI405.pdf

Examination Middleware

FastAPI + PostgreSQL

Authentication
Validation
Submission

Moodle LMS

Learning Management System

Assignment Submissions

Database Schema Overview

Model Description
ExaminationArtifact Core entity storing UUID, file path, SHA-256 hash, extracted metadata, and workflow status.
SubjectMapping Configuration mapping Subject Code to Moodle Course ID and Assignment ID.
StaffUser Accounts for administrative staff authorized to perform bulk uploads.
StudentSession Manages ephemeral sessions with encrypted Moodle access tokens.
AuditLog Rigid ledger tracking every action with IP addresses and timestamps.
SubmissionQueue Buffer for handling Moodle API failures, ensuring no submission is lost.

bcrypt Hashing

Password hashing with 12 rounds

AES-256 Encryption

Fernet encryption for Moodle tokens

Audit Logging

Complete chain of custody tracking

Platform Workflow

A streamlined 3-phase process ensuring secure and verified submissions

Phase 1

Administration & Setup

1

Mapping

Admin configures SubjectMapping table (e.g., CS101 → Assignment ID: 55)

2

Scanning

Examination cell scans answer sheets using naming convention: {R_N0}_{Sub_Code}.pdf

Phase 2

Staff Operations

1

Login

Staff logs into the Staff Portal

2

Bulk Upload

Staff drags and drops folders of scanned files

3

Validation

System validates filenames; valid files are hashed and stored as ExaminationArtifacts

Phase 3

Student Operations

1

Login

Student logs in with Moodle credentials

2

Dashboard

System displays all papers tagged with their Register Number

3

Review

Student previews the PDF to ensure it's their paper

4

Submit

Student clicks 'Submit' to finalize

5

Backend

System authenticates with Moodle, uploads file, and finalizes submission

6

Confirmation

Status updates to SUBMITTED_TO_LMS

File Naming Convention

{RegNumber}_{SubCode}.{extension}
611221104088_19AI405.pdf
611221104089_ML.jpg
611221104090_19AI411.png
Register Number: 12 digits
Subject Code: 2-10 alphanumeric
Extensions: pdf, jpg, jpeg, png

API Endpoints

Complete RESTful API with authentication, file management, and submission handling

🔗 Access Points

Staff Upload Portal

http://localhost:8000/portal/staff

Student Portal

http://localhost:8000/portal/student

API Documentation

http://localhost:8000/docs

ReDoc

http://localhost:8000/redoc

Health Check

http://localhost:8000/health
POST /auth/staff/login Staff login
POST /auth/student/login Student login with Moodle credentials
POST /auth/student/logout Student logout
POST /upload/single Upload single file
POST /upload/bulk Upload multiple files
POST /upload/validate Validate filename
GET /student/dashboard Get assigned papers
GET /student/paper/{id}/view View paper content
POST /student/submit/{id} Submit paper to Moodle
GET /student/submission/{id}/status Check submission status
GET /admin/mappings List subject mappings
POST /admin/mappings Create mapping
GET /admin/queue View submission queue
GET /admin/stats System statistics

API Testing with cURL

# Staff Login
curl -X POST http://localhost:8000/auth/staff/login \
  -F "username=admin" \
  -F "password=admin123"

# Upload File (use token from login)
curl -X POST http://localhost:8000/upload/single \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@611221104088_19AI405.pdf" \
  -F "exam_session=2024SPRING"

# Health Check
curl http://localhost:8000/health

Quick Start

Get up and running in minutes with our simple setup process

Prerequisites

Python 3.10+ PostgreSQL 14+ Moodle LMS with Web Services Redis (optional)
1
Clone and Setup 
cd exam_middleware
2
Create Virtual Environment 
python -m venv venv

# Windows
.\venv\Scripts\activate

# Linux/Mac
source venv/bin/activate
3
Install Dependencies 
pip install -r requirements.txt
4
Configure Environment 
copy .env.example .env
Edit .env with your database and Moodle settings
5
Setup PostgreSQL Database 
psql -U postgres -c "CREATE DATABASE exam_middleware;"
6
Initialize Database 
python init_db.py
Creates tables, default admin user (admin/admin123), and subject mappings
7
Run the Application 
python run.py
Server starts at http://localhost:8000

Project Structure

Clean, modular architecture following Python best practices

exam_middleware
app/
api/routes/
admin.py, auth.py, health.py, student.py, upload.py
core/ config.py, security.py
db/ database.py, models.py
schemas/ schemas.py
services/ artifact, file processor, moodle, submission
templates/ staff_upload.html, student_portal.html
main.py FastAPI application
uploads/ Temporary upload storage
storage/ Permanent file storage
.env, .env.example, init_db.py, run.py, requirements.txt

Moodle Configuration

Required Moodle setup for Web Services integration

1

Enable Web Services

Site administration → Advanced features → Enable web services
2

Create External Service

Site administration → Server → Web services → External services Create service: "FileUpload"

Add these functions:

core_webservice_get_site_info mod_assign_save_submission mod_assign_submit_for_grading
3

Create Token

Site administration → Server → Web services → Manage tokens Create token for admin user with "FileUpload" service
4

Enable Upload

Ensure webservice/upload.php is accessible Configure max upload size in Moodle settings

🛡️ Security Considerations

Password Hashing

bcrypt with 12 rounds

Token Encryption

AES-256 (Fernet)

JWT Tokens

Short-lived access tokens

File Validation

Extension and size checks

Audit Logging

All operations logged

CORS

Configurable origin whitelist