Architecture Overview

Purpose and Scope

This document describes the high-level architecture of JPortal, including the technology stack, application structure, component organization, routing system, and key design patterns. For detailed information about specific subsystems, refer to:

• Authentication flow and routing: Application Structure & Authentication
• State management patterns: State Management Strategy
• Data access layer: Data Layer & API Integration
• Theme infrastructure: Theme System
• Individual feature modules: Feature Modules

Technology Stack

JPortal is built as a single-page application (SPA) using modern web technologies:

Sources: package.json1-66 index.html1-25

Application Entry Point and Bootstrap

HTML and Script Loading

The application bootstraps from index.html, which defines critical resources:

Sources: index.html1-25

Main Entry Point

The main.jsx file renders the root App component into the DOM:

Sources: src/main.jsx1-10 (implied from standard Vite React setup)

Application Architecture

Top-Level Component Structure

The App component serves as the authentication gatekeeper and application shell:

Key State Variables in App:

• isAuthenticated: Boolean indicating user authentication status
• isDemoMode: Boolean determining whether to use mockPortal or realPortal
• isLoading: Boolean for auto-login attempt on mount
• error: String for displaying login errors

Sources: src/App.jsx243-376

Portal Instance Management

Two portal instances are created at the module level and conditionally passed to child components:

Sources: src/App.jsx18-30 src/App.jsx250 src/App.jsx350 src/App.jsx360

Routing Architecture

Route Structure

JPortal uses HashRouter for client-side routing with route guards based on authentication:

Sources: src/App.jsx334-367 src/App.jsx107-216

AuthenticatedApp Internal Routing

The AuthenticatedApp component defines protected routes and provides global UI chrome:

Sources: src/App.jsx102-218

State Management Architecture

State Hierarchy

JPortal implements a hierarchical state management pattern with extensive props drilling:

State Persistence:

• attendanceGoal: Saved to localStorage with default value of 75
• Login credentials: Stored in localStorage for auto-login

Sources: src/App.jsx32-101 src/App.jsx52-61

State Flow to Feature Components

All feature states are passed as props to their respective components:

Sources: src/App.jsx110-214

Data Access Layer: Portal Abstraction

Portal Strategy Pattern

The application uses a strategy pattern through the w prop to abstract data access:

Common Portal Methods:

• student_login(username, password)
• get_attendance(stud_id, sem_id)
• get_grades()
• get_subject_faculty(stud_id, sem_id)
• get_exam_schedule()
• get_header()
• get_exam_events()
• Additional methods for marks and grade cards

Sources: src/App.jsx18 src/components/Login.jsx24 src/components/MockWebPortal.jsx1-200 (implied)

Login Flow

Auto-Login on Mount: The App component attempts auto-login using stored credentials in localStorage:

Sources: src/App.jsx252-288 src/components/Login.jsx46-87

Theme Infrastructure

Theme State Management with Zustand

The theme system uses Zustand for global state, separate from React component state:

Sources: src/stores/theme-store.ts1-50 (implied), src/components/DynamicFontLoader.tsx1-34

Dynamic Font Loading

The DynamicFontLoader component monitors theme changes and loads Google Fonts dynamically:

Key Functions:

• extractFontFamily(fontFamilyValue): Parses CSS font-family string, filters out system fonts
• buildFontCssUrl(family, weights): Constructs Google Fonts API URL
• loadGoogleFont(family, weights): Injects <link> element into document head

Default Font Weights: ["400", "500", "600", "700"]

Sources: src/components/DynamicFontLoader.tsx1-34 src/utils/fonts.ts1-35

Component Architecture Patterns

Feature Module Pattern

All feature modules follow a consistent pattern:

Example: Attendance Component Props

w, attendanceData, setAttendanceData, semestersData, setSemestersData,
selectedSem, setSelectedSem, attendanceGoal, setAttendanceGoal,
subjectAttendanceData, setSubjectAttendanceData, selectedSubject,
setSelectedSubject, isAttendanceMetaLoading, setIsAttendanceMetaLoading,
isAttendanceDataLoading, setIsAttendanceDataLoading, activeTab,
setActiveTab, dailyDate, setDailyDate, calendarOpen, setCalendarOpen,
isTrackerOpen, setIsTrackerOpen, subjectCacheStatus, setSubjectCacheStatus

Sources: src/App.jsx110-142

Global UI Components

The Header component handles theme switching and logout. The Navbar provides bottom navigation to feature routes.

Sources: src/components/Header.jsx1-100 (implied), src/components/Navbar.jsx1-100 (implied)

External Service Integration

Service Dependencies

jsjiit Library Usage:

• Imported via CDN: https://cdn.jsdelivr.net/npm/jsjiit@0.0.20/dist/jsjiit.esm.js
• Provides WebPortal class and LoginError exception
• Handles authentication and data retrieval from JIIT portal

Pyodide Usage:

• Loaded from CDN in index.html
• Used in Grades module for parsing marks PDFs with PyMuPDF
• Enables client-side Python execution

Sources: src/App.jsx18 index.html17 index.html14-15

Error Handling and Loading States

Authentication Error Handling

Error States:

• App-level error state for auto-login failures
• Feature-level error states (e.g., gradesError)
• Toast notifications via sonner library

Sources: src/App.jsx265-284 src/components/Login.jsx65-82

Summary

JPortal's architecture is characterized by:

1. Authentication-first design: The App component acts as a gatekeeper, controlling access to all features
2. Portal abstraction: The w prop provides a clean interface to switch between real and demo data sources
3. Props drilling pattern: All state is lifted to AuthenticatedApp, then passed down to feature modules
4. Hybrid state management: React hooks for feature state, Zustand for theme, TanStack Query available but underutilized
5. Component composition: Radix UI primitives composed into custom feature components
6. Hash-based routing: Client-side routing without server configuration requirements
7. Progressive enhancement: PWA features, offline caching, installability
8. External service integration: Seamless integration with jsjiit, Pyodide, and Cloudflare services

This architecture supports rapid feature development through consistent patterns while maintaining separation of concerns between authentication, data access, and presentation layers.