Application Structure & Authentication

This document provides a detailed explanation of the application's core structure, authentication mechanisms, and routing system. It covers the App component hierarchy, authentication flows (real and demo modes), route guards, and the AuthenticatedApp wrapper that coordinates all feature modules.

For state management patterns across feature modules, see State Management Strategy. For details on the data access abstraction layer, see Data Layer & API Integration.

Application Entry Point

The application entry point is defined in src/App.jsx243-374 The App component serves as the root coordinator, managing authentication state and determining which component tree to render based on user authentication status.

Core Component Structure

Sources: src/App.jsx243-376

Global Providers

The App component establishes several global providers that wrap the entire application:

Sources: src/App.jsx1-26 src/App.jsx302-334

Authentication System

The authentication system supports two operational modes: real mode (connecting to JIIT portal) and demo mode (using mock data). This dual-mode architecture enables offline development and user demonstration without requiring actual credentials.

Portal Instance Architecture

Sources: src/App.jsx18-29 src/App.jsx243-250

Authentication State Management

The App component maintains three critical state variables:

// From App.jsx lines 244-247
const [isAuthenticated, setIsAuthenticated] = useState(false);
const [isDemoMode, setIsDemoMode] = useState(false);
const [isLoading, setIsLoading] = useState(true);
const [error, setError] = useState(null);

Sources: src/App.jsx244-247

Auto-Login Flow

On application mount, the App component attempts to authenticate using stored credentials:

Sources: src/App.jsx252-288

The auto-login implementation handles several error scenarios:

• Server unavailable: Displays error message indicating JIIT portal is down
• Network issues: Prompts user to check internet connection
• Invalid credentials: Clears stored credentials and requires re-login

Error handling logic is found at src/App.jsx265-282

Login Component

The Login component src/components/Login.jsx24-174 provides the user interface for authentication:

Sources: src/components/Login.jsx1-174

Login Form Schema

The form validation is defined using Zod src/components/Login.jsx15-22:

const formSchema = z.object({
  enrollmentNumber: z.string({
    required_error: "Enrollment number is required",
  }),
  password: z.string({
    required_error: "Password is required",
  }),
});

Login Process Flow

1. User submits credentials: Form calls onSubmit src/components/Login.jsx90-95
2. State update triggers effect: Sets loginStatus.credentials
3. Effect performs login: Calls w.student_login() src/components/Login.jsx51
4. Credentials persisted: Stored in localStorage src/components/Login.jsx54-55
5. Success callback invoked: onLoginSuccess() triggers src/components/Login.jsx63
6. Navigation occurs: LoginWrapper navigates to /attendance src/App.jsx228

Sources: src/components/Login.jsx46-87 src/App.jsx221-241

Routing Architecture

JPortal uses React Router DOM with hash-based routing to enable deployment on GitHub Pages without server-side configuration.

Route Guard Implementation

Sources: src/App.jsx334-369

Route Configuration

The route guard logic uses React Router's conditional rendering based on authentication state:

Sources: src/App.jsx336-367

AuthenticatedApp Route Definitions

Inside AuthenticatedApp, feature routes are defined src/App.jsx107-215:

Sources: src/App.jsx107-215

AuthenticatedApp Wrapper

The AuthenticatedApp component src/App.jsx32-219 serves as a state management hub and layout coordinator for all authenticated features.

Component Responsibilities

Sources: src/App.jsx32-219

State Organization

The AuthenticatedApp maintains separate state slices for each feature module:

Sources: src/App.jsx33-97

Props Drilling Pattern

Each feature component receives its state and setters as props. Example from Attendance route src/App.jsx110-142:

<Attendance
  w={w}
  attendanceData={attendanceData}
  setAttendanceData={setAttendanceData}
  semestersData={attendanceSemestersData}
  setSemestersData={setAttendanceSemestersData}
  selectedSem={selectedAttendanceSem}
  setSelectedSem={setSelectedAttendanceSem}
  attendanceGoal={attendanceGoal}
  setAttendanceGoal={setAttendanceGoal}
  // ... 6 more props
/>

This pattern enables:

• Centralized state persistence: State survives navigation between routes
• Cross-feature coordination: Multiple features can share state if needed
• Simplified debugging: All state mutations traceable to AuthenticatedApp

Sources: src/App.jsx110-214

LocalStorage Integration

Specific state values are persisted to localStorage for user preferences:

// Attendance goal persistence (lines 53-61)
const [attendanceGoal, setAttendanceGoal] = useState(() => {
  const savedGoal = localStorage.getItem("attendanceGoal");
  return savedGoal ? parseInt(savedGoal) : 75;
});

useEffect(() => {
  localStorage.setItem("attendanceGoal", attendanceGoal.toString());
}, [attendanceGoal]);

Sources: src/App.jsx53-61

Navigation System

The navigation system consists of two persistent components rendered by AuthenticatedApp:

Header Component

Located at src/App.jsx104-106 the Header component:

• Provides theme selection and light/dark mode toggle
• Displays logout button
• Receives setIsAuthenticated and setIsDemoMode for logout functionality
• Positioned with sticky positioning (top-0 z-30)

Navbar Component

The bottom navigation bar src/components/Navbar.jsx8-50 provides primary navigation:

Sources: src/components/Navbar.jsx1-51

Navbar Implementation Details

• Component: Fixed position at bottom of screen src/components/Navbar.jsx18
• Navigation: Uses React Router's NavLink with active state detection src/components/Navbar.jsx20-27
• Icons: SVG icons imported as React components src/components/Navbar.jsx2-6
• Active state styling: Highlights current route with bg-primary and full opacity src/components/Navbar.jsx32
• Responsive text: Font size adapts for small screens src/components/Navbar.jsx39

Sources: src/components/Navbar.jsx1-51

Component Lifecycle

The complete authentication and routing lifecycle:

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