ATAS: Academic Tracking and Alert System 🎓

ATAS is a Django-based web application designed to automate the detection and tracking of students requiring compartment (re-take) exams (currently for Kathmandu Universtiy transcripts only). By leveraging Optical Character Recognition (OCR) and Pandas Data Processing, ATAS eliminates manual grade entry and identifies at-risk students instantly.

🚀 Key Features

• ⚠️ Automated Failure Detection: Instantly flags students with a GPA < 2.0 or specific failing grades (F, D, or incomplete 'X')
• 📤 Bulk CSV/Excel Upload: Integrated Pandas engine for processing entire semester result sheets
• 🗂️ Relational Academic Tracking: Manages Faculty, Courses, Students, and Exam Deadlines with database relationships
• 📱 Live Camera Integration: Scan physical documents directly from the browser using webcam

🛠️ Tech Stack

Layer	Technology
Backend	Python 3.10+, Django 4.x
Data Processing	Pandas, NumPy
Computer Vision	Pytesseract, Tesseract OCR, OpenCV, Pillow
Frontend	HTML5, Bootstrap 5, CSS3, JavaScript (Webcam API)
Database	SQLite (Development), PostgreSQL (Production-ready)

⚙️ Installation & Setup

Prerequisites

Ensure you have the following installed:

System Requirements

• Python 3.10+
• Tesseract OCR
  • Linux: sudo apt install tesseract-ocr
  • macOS: brew install tesseract
  • Windows: Download from Tesseract OCR Releases

Quick Start

1. Clone the repository

   git clone https://github.com/neeteshupreti/AcademicTrackingandAlertSystem.git
   cd AcademicTrackingandAlertSystem

2. Create and activate virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

   pip install -r requirements.txt

4. Run migrations

   python manage.py migrate

5. Create superuser account

   python manage.py createsuperuser

6. Start development server

   python manage.py runserver

7. Access the application

   • Admin Panel: http://localhost:8000/admin
   • Main App: http://localhost:8000

📁 Project Structure

AcademicTrackingandAlertSystem/
├── manage.py                 # Django management script
├── requirements.txt          # Python dependencies
├── db.sqlite3               # SQLite database
├── ATAS/                    # Django configuration
│   ├── settings.py          # Project settings
│   ├── urls.py              # Main URL routing
│   └── wsgi.py
├── core/                    # Core application
│   ├── views.py            # Admin & main views
│   ├── models.py           # Core models
│   ├── urls.py
│   └── templates/          # HTML templates
├── students/               # Students management app
│   ├── views.py           # Student views & import logic
│   ├── models.py          # Student models
│   ├── forms.py           # Django forms
│   └── templates/         # Student templates
├── notifications/         # Notifications app
│   ├── views.py
│   ├── models.py          # Alert models
│   └── templates/
└── static/               # Static assets
    ├── css/             # Stylesheets
    └── js/              # JavaScript files

🔬 OCR Processing Pipeline

Overview

ATAS includes a specialized KU (Kathmandu University) Report Parser that accurately extracts:

• Student Name: From "Name" labels with text normalization
• Semester: Supports multiple semester indicators (Semester: X, Sem: X, Year: X)
• GPA: Recognizes 6 different GPA formats including failure markers (X, F)
• Failed Subjects: Subject codes (CS101, MATH304, etc.) paired with failure grades

Supported Failure Grades

• F - Direct failure
• (F) - Parenthesized failure
• INC - Incomplete
• FAIL - Full word failure
• X - GPA failure marker

Subject Code Patterns

Automatically detects: CS101, MATH304, IT102, ALGO301, etc.

• Pattern: 2-4 letter code + 2-4 digit number
• Case-sensitive extraction

Multi-Semester Support

• Students can have multiple compartments from different semesters
• Database allows same subject to be failed in different semesters
• Each compartment record stores:
  • Semester of failure
  • GPA at time of failure
  • Timestamp of record creation

Example Extraction

Input Transcript:
  Name: JOHN DOE
  Semester: 3
  GPA: 2.5
  Failed: CS101(F), IT102(F), ALGO301(INC)

Output JSON:
{
  "name": "JOHN DOE",
  "semester": 3,
  "gpa": "2.5",
  "failed_subjects": ["CS101", "IT102", "ALGO301"],
  "is_failing": true,
  "extraction_confidence": {
    "name": "high",
    "gpa": "high",
    "subjects": "high",
    "semester": "high"
  }
}

For detailed OCR implementation notes, see OCR_IMPLEMENTATION_NOTES.md.

🎯 Usage

Admin Dashboard

1. Log in with superuser credentials
2. Manage Faculty, Courses, and Students
3. Set compartment deadlines
4. Monitor active alerts

Upload Student Records

1. Navigate to Import Records section
2. Choose between:
   • File Upload: Upload CSV/Excel with student results
   • Camera Scanner: Capture transcript photos with webcam
3. System automatically detects failures and creates alerts

View Alerts

• Dashboard displays all active compartment alerts
• Sorted by deadline urgency
• Track student status in real-time

🔧 Configuration

Edit ATAS/settings.py to customize:

• Database settings
• Tesseract path (if not in system PATH)
• Email notifications (SMTP configuration)
• Static/Media file locations

📝 Notes

• Tesseract Path: If Tesseract isn't in your system PATH, add to settings.py:

  import pytesseract
  pytesseract.pytesseract.pytesseract_cmd = r'C:\Program Files\Tesseract-OCR\tesseract.exe'  # Windows

• Database: SQLite is included for development. For production, configure PostgreSQL in settings.py

🤝 Contributing

Pull requests are welcome! Please follow Django coding standards and include tests for new features.

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

📧 Contact & Support

For issues, questions, or contributions, please open an issue on GitHub or reach out to the development team.