System Architecture

• pyjiit/encryption.py
• pyjiit/exam.py
• pyjiit/registration.py
• pyjiit/wrapper.py
• pyproject.toml

Purpose and Scope

This document describes the high-level architecture of the pyjiit library, including its layered structure, core components, and how they interact to provide a Python API client for the JIIT Webportal system. It focuses on the organization of modules, the flow of data through the system, and the relationships between major components.

For detailed information about the encryption implementation, see Security and Encryption. For installation and basic usage, see Getting Started. For complete API method documentation, see Core API Reference.

Architectural Overview

The pyjiit library follows a three-layer architecture that cleanly separates concerns:

Sources: pyjiit/wrapper.py1-489 pyjiit/encryption.py1-50 pyjiit/__init__.py

Core Components

Webportal Class

The Webportal class defined in pyjiit/wrapper.py70-489 is the central orchestrator. It provides all public methods for interacting with the JIIT Webportal API.

Key characteristics:

• Stateful: Maintains a self.session attribute of type WebportalSession
• Method categories: Authentication, attendance, exams, registrations, marks, account management
• Internal HTTP handler: Private __hit method pyjiit/wrapper.py82-108 centralizes all HTTP requests
• Decorator-based access control: @authenticated decorator pyjiit/wrapper.py19-36 validates session state before method execution

Sources: pyjiit/wrapper.py70-489 pyjiit/wrapper.py38-68 pyjiit/wrapper.py19-36

WebportalSession Class

The WebportalSession class pyjiit/wrapper.py38-68 encapsulates all session state after successful authentication.

Session attributes extracted from login response:

• token: JWT token parsed to extract expiry timestamp
• instituteid, memberid, clientid: Required in most API payloads
• membertype: Student identifier ("S")
• regdata: Raw registration data from authentication

Key method:

• get_headers() pyjiit/wrapper.py61-68: Returns Authorization header with Bearer token and LocalName header for every authenticated request

Sources: pyjiit/wrapper.py38-68

Encryption Module

The encryption module pyjiit/encryption.py1-50 implements all cryptographic operations required for communication with JIIT Webportal.

Sources: pyjiit/encryption.py1-50

Key functions:

Critical implementation details:

• Daily key rotation: Key changes at 00:00 IST via generate_date_seq() from pyjiit.utils
• Fixed IV: Constant b"dcek9wb8frty1pnm" pyjiit/encryption.py7
• Key composition: "qa8y" + date_seq + "ty1pn" pyjiit/encryption.py11

Sources: pyjiit/encryption.py7-44

Data Models

Data model classes provide structured representations of API responses. All models are defined as dataclasses or classes with from_json() factory methods.

Sources: pyjiit/exam.py1-24 pyjiit/registration.py1-44 pyjiit/attendance.py pyjiit/tokens.py

Exception Hierarchy

The library defines a hierarchy of custom exceptions in pyjiit/exceptions.py for precise error handling.

Sources: pyjiit/wrapper.py8 (import statement), pyjiit/exceptions.py

Usage in code:

• LoginError: Raised by student_login() pyjiit/wrapper.py111-143
• NotLoggedIn: Raised by @authenticated decorator when self.session is None pyjiit/wrapper.py26-27
• SessionExpired: Raised by __hit() on HTTP 401 status pyjiit/wrapper.py102-103
• AccountAPIError: Raised by set_password() pyjiit/wrapper.py214-230
• APIError: Default exception for generic API failures pyjiit/wrapper.py83-106

Request/Response Flow

Every API call follows a standardized pattern through the internal __hit() method.

Flow Diagram: Authenticated API Call

Sources: pyjiit/wrapper.py82-108 pyjiit/wrapper.py19-36 pyjiit/encryption.py39-44

The __hit() Method

The __hit() method pyjiit/wrapper.py82-108 is the central HTTP request handler with the following responsibilities:

1. Header Management:

• Adds LocalName header to all requests pyjiit/wrapper.py93
• Adds Authorization header for authenticated requests pyjiit/wrapper.py90

2. Error Handling:

• Detects HTTP 401 → raises SessionExpired pyjiit/wrapper.py102-103
• Detects API-level failures → raises custom exception pyjiit/wrapper.py105-106

3. Extensibility:

• Accepts custom exception types via exception kwarg pyjiit/wrapper.py83-87
• Forwards all kwargs to requests.request() pyjiit/wrapper.py101

Sources: pyjiit/wrapper.py82-108

Module Dependencies

The following diagram shows compile-time dependencies between modules:

Sources: pyjiit/wrapper.py1-14 pyjiit/encryption.py1-5

Dependency Table

Sources: pyjiit/wrapper.py1-14 pyjiit/encryption.py1-5

Design Patterns

1. Decorator Pattern: @authenticated

The @authenticated decorator pyjiit/wrapper.py19-36 enforces preconditions on methods that require an active session:

@authenticated
def get_attendance_meta(self): # Method body only executes if self.session is not None

Applied to: get_attendance_meta(), get_attendance(), get_registered_semesters(), get_exam_events(), set_password(), download_marks(), get_grade_card(), get_sgpa_cgpa(), get_fee_summary(), get_subject_choices(), and others.

Sources: pyjiit/wrapper.py19-36 pyjiit/wrapper.py156 pyjiit/wrapper.py172

2. Factory Pattern: from_json()

Data model classes use static factory methods to construct instances from API responses:

@staticmethod
def from_json(resp: dict):
return ExamEvent(
resp["exameventcode"],
resp["eventfrom"],
resp["exameventdesc"],
resp["registrationid"],
resp["exameventid"]
)

Used by: ExamEvent pyjiit/exam.py13-20 RegisteredSubject pyjiit/registration.py18-32 Semester, Captcha

Sources: pyjiit/exam.py13-20 pyjiit/registration.py18-32

3. Centralized Error Handling

The __hit() method centralizes HTTP communication and error detection, allowing individual methods to specify custom exceptions via the exception parameter:

resp = self.\_\_hit("POST", API+endpoint, data=payload, exception=LoginError)

Sources: pyjiit/wrapper.py82-108 pyjiit/wrapper.py130

4. Encapsulation of External API

The constant API = "https://webportal.jiit.ac.in:6011/StudentPortalAPI" pyjiit/wrapper.py17 combined with endpoint strings creates complete URLs. This centralizes the base URL configuration.

Sources: pyjiit/wrapper.py17

External Dependencies

The library has minimal runtime dependencies defined in pyproject.toml9-12:

Additional documentation dependencies (not included in runtime): sphinx and furo for documentation generation pyproject.toml19-21

Sources: pyproject.toml9-12 pyproject.toml19-21