Superior Erp Automated Marks Entry

A high-performance, dual-interface (Desktop GUI and Web Dashboard) automation suite designed for academic management within the Superior University ERP ecosystem. It provides faculty with a centralized, secure interface to sync attendance records, fetch active student rosters, verify assessment marks comparisons, and deploy results directly from Excel data matrices to the ERP.

📖 Executive Summary

Academic administration often involves repetitive data-entry tasks that are prone to human error and server timeouts. The Superior ERP Automated Command Center solves this by establishing a robust, programmatic integration layer directly with the Superior University ERP.

By utilizing direct HTTP session requests and BeautifulSoup parsing rather than heavy browser automation engines (like Selenium), the suite operates at maximum efficiency. It features:

1. A Desktop GUI Application powered by CustomTkinter for faculty who prefer local desktop execution.
2. A Responsive Web Application built with Flask, Vanilla CSS, and JS for a modern, browser-based management experience.
3. An Asynchronous Worker Pool with thread-safe execution, request retries, and isolation to prevent ERP server bottlenecks.

🏗️ System Architecture

The project consists of three core components:

                  ┌──────────────────────────────┐
                  │      SuperiorERPAPI          │
                  │   (erp_api_client.py)        │
                  └──────────────┬───────────────┘
                                 │
         ┌───────────────────────┴───────────────────────┐
         ▼                                               ▼
┌──────────────────┐                           ┌──────────────────┐
│   Desktop GUI    │                           │  Web Dashboard   │
│  (erp_gui.py)    │                           │  (erp_web.py)    │
└──────────────────┘                           └────────┬─────────┘
                                                        │
                                         ┌──────────────┴──────────────┐
                                         ▼                             ▼
                                ┌─────────────────┐           ┌─────────────────┐
                                │ HTML Templates  │           │  Static Assets  │
                                │ (templates/)    │           │ (css/, js/)     │
                                └─────────────────┘           └─────────────────┘

1. Unified API Client (erp_api_client.py)

The backbone of the suite. It maintains authenticated HTTP sessions (requests.Session) and handles all communication with the Superior ERP domain (https://erp.superior.edu.pk):

• Authentication: Secures logins, fetches CSRF tokens, and tracks active session status.
• Metadata Queries: Extracts active sessions/terms, course lists, class-specific assessment structures, and attendance percentages.
• Roster Builder: Compiles student rosters with names, registration numbers, existing marks, and final grades.
• Safe Submission: Executes HTTP posts to commit grade lists, using a thread lock where necessary to ensure safe state transitions.

2. Desktop Interface (erp_gui.py)

A custom desktop application styled with a dark theme, custom fonts (Outfit & Inter), glassmorphism-inspired widgets, and slide-in toast notifications:

• Implements a ThreadPoolExecutor to execute API requests asynchronously, avoiding main-loop UI freezing.
• Offers real-time progress logging directly in a feedback text console.

3. Web Dashboard (erp_web.py + templates/ + static/)

A Flask web application matching the aesthetics of the desktop environment:

• Dashboard Control: Browse active terms, view courses, track attendance metrics, and inspect class sheets.
• Visual Diff Tool: Allows previewing exact grade differences (ERP vs. Excel) before committing the sync.
• Upload Handler: Securely processes Excel uploads and matches columns dynamically.

⚡ Key Features

📅 Automated Attendance Sync

The command center parses attendance sheets directly and compares the number of marked lectures against the total. High-visibility progress bars color-code compliance (Emerald for >80%, Amber for >50%, Rose for critical).

📊 Global Excel Mapping Matrix

When uploading a grading spreadsheet, the system parses structural metadata:

• Auto-Discovery: Identifies columns representing Mids, Finals, Quizzes, Projects, and Labs by matching text keywords (task, mid, final, etc.).
• Dynamic Dropdowns: Allows manual reassignment or corrections to mapping indices before deployment.
• Sanitization: Standardizes student registration formats (e.g., stripping concatenated names or normalizing casing) to guarantee exact match keys.

🔄 Intelligent Comparison & Dry-Run

Before committing changes, the web portal generates a detailed comparison:

• Highlights additions, modifications, and matching grades.
• Allows faculty to verify and proceed only when data integrity is fully checked.

🛡️ Resilient Threading & Retries

The ERP server occasionally drops connections. To handle this, the suite features isolated sessions per worker thread. If a request fails, it attempts a 3-stage retry automatically back-to-back before returning a failure status to the user.

⚙️ Installation & Setup

Prerequisites

• Python 3.10 or higher installed.

Step-by-Step Configuration

1. Clone/Move to the Repository Directory:

   cd "E:\zPythonStuff\Superior - ERP Automated"
   

2. Initialize a Virtual Environment:

   python -m venv venv
   

3. Activate the Virtual Environment:

   # On Windows PowerShell:
   .\venv\Scripts\activate
   

4. Install Required Packages:

   pip install -r requirements.txt
   

🚀 Running the Applications

Always ensure your virtual environment is activated before launching either application.

Syntax Check Command

Before running or making modifications, you can quickly compile and check code syntax:

python -m py_compile erp_api_client.py erp_gui.py erp_web.py

Launching the Desktop GUI

To launch the CustomTkinter desktop interface:

python erp_gui.py

Launching the Web Server

To spin up the local Flask web development server:

python erp_web.py

Once running, navigate to http://127.0.0.1:5000 in your web browser.

📁 Project Structure

Superior - ERP Automated/
├── erp_api_client.py   # Core ERP API abstraction (requests + BeautifulSoup)
├── erp_gui.py          # CustomTkinter Desktop Client
├── erp_web.py          # Flask Web Dashboard Application
├── requirements.txt    # Project dependencies
├── AGENTS.md           # Instructions for agent-led development syntax checks
├── data/               # Standardized data and sample grading sheets
├── uploads/            # Temporary directory for uploaded Excel sheets
├── static/             # Assets for Flask Web Application
│   ├── css/
│   │   └── style.css   # Dark-theme layout stylesheet
│   └── js/
│       └── main.js     # AJAX requests, dropdown actions, and comparison logic
├── templates/          # Jinja2 HTML Templates
│   ├── base.html       # Base layout with sidebar and headers
│   ├── login.html      # Glassmorphic login viewport
│   └── dashboard.html  # Roster mapping view and sync consoles
└── output*/            # Auto-generated script outputs (ignored)

[!NOTE] All Selenium ChromeDriver binaries and script versions (erp_login.py, Chromedriver/) have been removed from the repository. The tool operates completely under a lightweight requests architecture, removing the need for local web drivers.