Getting Started

This document provides instructions for running JPortal locally for development, configuring the application, and deploying it. It covers installation of dependencies, environment configuration, development workflows, and building the Progressive Web App for production.

For information about the overall architecture and design patterns, see Architecture Overview. For details about individual feature modules, see Feature Modules.

Prerequisites

Before setting up JPortal locally, ensure you have the following installed:

Sources: jportal/package.json1-66

Quick Start: Using the Live Application

JPortal is deployed as a Progressive Web App and can be accessed immediately without local setup.

Accessing the Application

1. Navigate to https://codeblech.github.io/jportal/
2. Login with your JIIT credentials (real mode) or use demo mode

Diagram 1: Application Access Flow

Sources: README.md36-38 jportal/package.json6

Installing as PWA

JPortal can be installed on various platforms for app-like experience:

Sources: README.md39-44

Local Development Setup

Step 1: Clone the Repository

git clone https://github.com/codeblech/jportal.git
cd jportal

Step 2: Navigate to Project Directory

The main application code is located in the jportal subdirectory:

cd jportal

Step 3: Install Dependencies

npm install

This installs all dependencies defined in jportal/package.json15-43 including:

• React 18.3.1 - UI framework
• Vite 5.4.10 - Build tool and dev server
• VitePWA 0.20.5 - Progressive Web App plugin
• Radix UI - Accessible component primitives
• TanStack Query - Server state management
• Zustand - Theme state management

Diagram 2: Dependency Installation Process

Sources: jportal/package.json15-65

Environment Configuration

JPortal uses environment variables for configuration. Create a .env file in the jportal directory.

Creating the Environment File

Copy the example file:

cp .env.example .env

Environment Variables

Configuration File Structure:

VITE_USE_FAKE_DATA=false
VITE_CLOUDFLARE_API_TOKEN=your_token_here
VITE_CLOUDFLARE_PROXY_URL=https://cors-header-proxy.my-malikyash.workers.dev
VITE_CLOUDFLARE_BASE_URL=https://api.cloudflare.com/client/v4/graphql
VITE_CLOUDFLARE_ACCOUNT_TAG=your_account_tag
VITE_CLOUDFLARE_SITE_TAG=your_site_tag

Sources: jportal/.env.example1-7

Demo Mode vs Real Mode

The VITE_USE_FAKE_DATA variable controls which data source the application uses:

Diagram 3: Mode Selection and Data Flow

The mode is determined in App.jsx where either WebPortal or MockWebPortal is instantiated based on the environment variable.

Sources: jportal/.env.example1 jportal/vite.config.ts10

Running the Application

Development Server

Start the Vite development server with hot module replacement:

npm run dev

This executes the dev script defined in jportal/package.json8 The application will be available at:

• Local: http://localhost:5173/jportal/
• Network: http://<your-ip>:5173/jportal/

Note: The base path /jportal/ is configured in jportal/vite.config.ts13

Diagram 4: Development Server Architecture

Sources: jportal/package.json8 jportal/vite.config.ts1-99

Development Server Features

The Vite configuration provides:

1. Hot Module Replacement (HMR) - Instant updates without full page reload
2. PWA in Development - Service worker enabled via devOptions.enabled: true (jportal/vite.config.ts20-22)
3. API Proxy - Cloudflare API proxy to avoid CORS issues (jportal/vite.config.ts81-96)
4. Path Aliases - @/ resolves to ./src (jportal/vite.config.ts76-78)

Preview Production Build

To preview the production build locally:

npm run build
npm run preview

The preview command serves the dist/ directory on a local server.

Sources: jportal/package.json9-11

Linting

Run ESLint to check code quality:

npm run lint

Sources: jportal/package.json10

Building for Production

Build Process

Create an optimized production build:

npm run build

This command:

1. Compiles TypeScript to JavaScript
2. Bundles React components with Vite
3. Minifies and tree-shakes code
4. Generates PWA manifest and service worker
5. Outputs to dist/ directory

Diagram 5: Production Build Pipeline

Sources: jportal/package.json9 jportal/vite.config.ts17-73

Build Configuration Details

The production build is configured in jportal/vite.config.ts1-99 with:

PWA Configuration

• Register Type: autoUpdate - Automatically updates service worker
• Inject Register: auto - Automatically injects service worker registration
• Maximum Cache Size: 30MB (jportal/vite.config.ts24)
• Glob Patterns: Caches all *.js, *.css, *.html, *.ico, *.png, *.svg, *.whl files

Cached Resources

The service worker pre-caches:

1. Pyodide Runtime: https://cdn.jsdelivr.net/pyodide/v0.23.4/full/pyodide.js
2. Python Wheels:
   • /jportal/artifact/jiit_marks-0.2.0-py3-none-any.whl
   • /jportal/artifact/PyMuPDF-1.24.12-cp311-abi3-emscripten_3_1_32_wasm32.whl

These are used by the Grades module for client-side PDF parsing.

Sources: jportal/vite.config.ts23-42

Manifest Configuration

The PWA manifest (jportal/vite.config.ts44-72) defines:

{
  "name": "JPortal",
  "short_name": "JPortal",
  "start_url": "/jportal/",
  "display": "standalone",
  "background_color": "#191c20",
  "theme_color": "#191c20",
  "orientation": "portrait",
  "icons": [...]
}

Sources: jportal/vite.config.ts44-72

Deployment

Deploying to GitHub Pages

JPortal uses gh-pages for automated deployment:

npm run deploy

This command:

1. Runs npm run build (via predeploy hook)
2. Deploys the dist/ directory to the gh-pages branch
3. Makes the app available at https://codeblech.github.io/jportal

Diagram 6: Deployment Process

Sources: jportal/package.json12-13

Deployment Configuration

Key configuration for GitHub Pages:

Sources: jportal/package.json6-13 jportal/vite.config.ts13

Development Workflow Summary

Diagram 7: Complete Development Workflow

Sources: jportal/package.json7-13

Common Commands Reference

Sources: jportal/package.json7-13

Project Structure Overview

After setup, the project structure is:

jportal/
├── public/              # Static assets
│   ├── fakedata.json   # Mock data for demo mode
│   ├── pwa-icons/      # PWA icons
│   └── artifact/       # Python wheels for PDF parsing
├── src/                # Application source code
│   ├── components/     # React components
│   ├── lib/           # Utilities and helpers
│   └── main.jsx       # Application entry point
├── .env               # Environment variables (create from .env.example)
├── package.json       # Dependencies and scripts
├── vite.config.ts     # Vite and PWA configuration
└── index.html         # HTML shell for PWA

Sources: jportal/package.json1-66 jportal/vite.config.ts1-99

Next Steps

After completing the setup:

1. Understand the Architecture - See Architecture Overview for system design patterns
2. Explore Feature Modules - See Feature Modules for detailed component documentation
3. Learn the Theme System - See Theme System for customization options
4. Review State Management - See State Management Strategy for data flow patterns
5. Study the Build Pipeline - See Build & Deployment for advanced build configuration

Sources: README.md1-61 jportal/package.json1-66 jportal/vite.config.ts1-99