System Architecture Overview

Purpose and Scope

This document describes the high-level architecture of the jsjiit library, focusing on the organization of modules, their interactions, and the overall design patterns. It covers the layered structure, core components, data flow patterns, and session management mechanisms.

For details on specific API methods and their usage, see API Reference. For information about the encryption mechanisms, see Encryption and Security. For module export strategies, see Module Organization.

Layered Architecture

The jsjiit library follows a three-tier layered architecture that separates concerns between API communication, domain logic, and public interface exposure.

Architecture Layers Diagram

Sources: src/index.js1-32 src/wrapper.js1-720 src/encryption.js src/attendance.js src/registration.js src/exam.js src/exceptions.js

Layer Responsibilities

Sources: src/index.js1-32 src/wrapper.js1-720

Core Components

WebPortal Class

The WebPortal class (src/wrapper.js75-671) is the primary orchestrator for all portal interactions. It maintains a reference to the current WebPortalSession and provides methods for each portal API endpoint.

Key Responsibilities:

• Authentication: student_login() method (src/wrapper.js168-186)
• HTTP Communication: __hit() internal method (src/wrapper.js97-158) handles all HTTP requests
• Domain Object Creation: Instantiates AttendanceMeta, Registrations, ExamEvent objects from API responses
• Session Lifecycle: Stores and validates session state

WebPortalSession Class

The WebPortalSession class (src/wrapper.js25-70) encapsulates authenticated session state.

Key Properties:

Methods:

• get_headers() (src/wrapper.js63-69): Generates authentication headers including JWT token and LocalName for each request

Sources: src/wrapper.js25-70

Authentication Decorator Pattern

The library uses a decorator pattern to enforce authentication requirements on methods. The authenticated() function (src/wrapper.js679-686) wraps methods that require an active session.

Implementation:

• Decorated methods list: src/wrapper.js692-715
• Decorator application: src/wrapper.js717-719

Sources: src/wrapper.js679-719

Module Dependency Graph

This diagram maps the actual import relationships between source modules.

Import Details:

Sources: src/index.js1-32 src/wrapper.js1-5

Request/Response Flow Architecture

API Communication Flow

Sources: src/wrapper.js97-158 src/wrapper.js242-254 src/wrapper.js63-69

HTTP Request Method: __hit()

The __hit() method (src/wrapper.js97-158) is the centralized HTTP communication handler.

Parameters:

Error Handling:

• HTTP 513: Portal temporarily unavailable (src/wrapper.js138-140)
• HTTP 401: Session expired (src/wrapper.js141-143)
• Non-success status: Throws custom exception (src/wrapper.js147-149)
• CORS errors: Detected and wrapped (src/wrapper.js152-155)

Sources: src/wrapper.js97-158

Session Management Architecture

Login Flow

Implementation Details:

1. Pre-token Check: src/wrapper.js169-175 - Validates username and CAPTCHA
2. Token Generation: src/wrapper.js177-183 - Exchanges password for JWT
3. Session Creation: src/wrapper.js184-185 - Stores session in this.session
4. Token Parsing: src/wrapper.js50-51 - Extracts expiry from JWT payload

CAPTCHA Bypass: The library uses a default CAPTCHA value (src/wrapper.js20) that bypasses CAPTCHA validation:

export const DEFCAPTCHA = { captcha: "phw5n", hidden: "gmBctEffdSg=" };

Sources: src/wrapper.js168-186 src/wrapper.js20 src/wrapper.js39-57

Session State Management

Session Validation:

• The authenticated() decorator (src/wrapper.js679-686) checks this.session == null
• Throws NotLoggedIn exception if no session exists
• Applied to all data retrieval methods (src/wrapper.js692-715)

Sources: src/wrapper.js75-82 src/wrapper.js679-719

Error Handling Architecture

Exception Hierarchy

Exception Types: All defined in src/exceptions.js

Sources: src/exceptions.js src/wrapper.js1 src/wrapper.js97-158

Error Propagation Pattern

The __hit() method accepts an exception parameter to customize error types:

// Example from change_password method
const resp = await this.__hit("POST", API + ENDPOINT, {
  json: payload,
  authenticated: true,
  exception: AccountAPIError,  // Custom exception type
});

Reference: src/wrapper.js231-236

Sources: src/wrapper.js97-102 src/wrapper.js231-236

API Endpoint Constants

Base Configuration

The library defines two critical constants in src/wrapper.js:

Endpoint Organization

Endpoints are defined inline within each method as relative paths appended to the API constant:

const ENDPOINT = "/StudentClassAttendance/getstudentInforegistrationforattendence";
const resp = await this.__hit("POST", API + ENDPOINT, {...});

Example Endpoints:

• Authentication: /token/pretoken-check, /token/generate-token1 (src/wrapper.js169-170)
• Attendance: /StudentClassAttendance/getstudentInforegistrationforattendence (src/wrapper.js244)
• Registration: /reqsubfaculty/getregistrationList (src/wrapper.js307)
• Exams: /studentcommonsontroller/getstudentexamevents (src/wrapper.js355)

Sources: src/wrapper.js14 src/wrapper.js20 src/wrapper.js169-670

Public API Export Strategy

The src/index.js module (src/index.js1-32) serves as a facade that re-exports all public APIs from internal modules.

Export Mapping

Import/Export Pattern:

• Line src/index.js5: Import from wrapper.js
• Line src/index.js6: Import from attendance.js
• Line src/index.js7: Import from registration.js
• Line src/index.js8: Import from exam.js
• Line src/index.js9: Import from exceptions.js
• Line src/index.js10: Import from encryption.js
• Lines src/index.js13-31: Re-export all imports

Sources: src/index.js1-32

Build Configuration Integration

The architecture is reflected in the build configuration (package.json).

Module Entry Points

Bundled Files

The files array (package.json26-29) specifies which directories are included in the npm package:

• dist/ - Built bundles
• src/ - Source code for sourcemap resolution

Sources: package.json1-61