Overview

The JIIT Personalized Timetable Creator is a browser-based Progressive Web App (PWA) that generates customized class schedules for students at Jaypee Institute of Information Technology. The system executes Python timetable generation logic entirely in the browser using Pyodide WebAssembly, eliminating traditional backend infrastructure. The application operates fully offline through service worker caching and provides features including personalized schedule generation, timeline visualization, timetable comparison, academic calendar integration, and Google Calendar synchronization.

Architectural Approach: The system implements a three-layer architecture: React frontend (Next.js App Router), Python processing layer (Pyodide WASM), and PWA/offline layer (Service Worker with Workbox). Static JSON data files serve as the data layer, generated at build time from Excel sources.

Scope: This page provides a high-level overview of the system architecture, core features, technology stack, and data flow. For detailed information about specific subsystems, refer to:

• System architecture: #3
• Schedule generation pipeline: #4
• Pyodide WASM integration: #3.2
• PWA and offline capabilities: #3.3
• State management: #3.5
• Export and sharing mechanisms: #9

System Overview

The application consists of three primary runtime layers operating in the browser: React frontend (UI and routing), Python processing layer (Pyodide WASM), and PWA/offline layer (Service Worker). Static JSON files provide timetable and calendar data, while external services handle Google Calendar integration and Pyodide runtime delivery.

System Architecture Diagram

Key Architectural Characteristics:

The service worker at public/sw.js implements three caching strategies:

• NetworkFirst: Root path / to prioritize fresh content
• CacheFirst: Pyodide CDN assets with 1-year TTL for performance
• Precache: Static assets (Next.js chunks, JSON data, Python modules)

Core Features

The system provides five primary feature areas, each implemented as a distinct route and component:

Schedule Generation Workflow

The schedule generation process involves user input collection, Python-based parsing, and display rendering:

Architecture Highlights

Client-Side Python Execution

The most distinctive architectural decision is using Pyodide to execute Python code client-side. The initializePyodide() function in pyodide.ts loads the Pyodide WASM runtime (~10MB) from CDN, then fetches and executes the _creator.py module containing timetable generation logic.

The evaluteTimeTable() function at src/App.tsx115-152 implements function selection logic that maps user parameters to specific Python functions:

• Campus 62, Year 1: time_table_creator
• Campus 62, Year 2-4: time_table_creator_v2
• Campus 128, Year 1: bando128_year1
• Campus 128, Year 2-4: banado128
• Campus BCA, Year 1: bca_creator_year1
• Campus BCA, Year 2-3: bca_creator

State Management Strategy

The application implements a three-tier state persistence model:

The UserContext defined in src/context/userContext.ts and provided by UserContextProvider src/context/userContextProvider.tsx maintains two schedule objects:

• schedule: Base schedule generated by Python processing
• editedSchedule: User modifications that override the base schedule

The nuqs library synchronizes form state with URL parameters, enabling shareable links. When URL parameters conflict with cached data, the UrlParamsDialog component src/components/url-params-dialog.tsx prompts the user to choose between overriding, prefilling, or viewing the existing schedule.

Technology Stack

Technology Stack

Frontend Technologies

Python Processing Layer

The initializePyodide() function at src/utils/pyodide.ts performs one-time initialization, downloading ~10MB Pyodide runtime from CDN and caching the instance globally. The callPythonFunction() bridge converts JavaScript objects to Python using toPy() and Python objects to JavaScript using toJs().

PWA & Performance

External Integrations

Development Tools

The development environment supports multiple package managers (npm, yarn, pnpm, bun) and includes ESLint configuration eslint.config.mjs PostCSS configuration postcss.config.mjs and Tailwind configuration tailwind.config.ts The .gitignore file at .gitignore excludes build artifacts (.next/, out/), dependency directories (node_modules/), and environment files.

Data Sources & Build Pipeline

Static JSON Data Layer

Example data paths:

• Timetable: /data/time-table/ODD25/62.json, /data/time-table/EVEN25/128.json, /data/time-table/ODD25/BCA.json
• Calendar: /data/calender/2425/calendar.json, /data/calender/2526/calender.json

Data Preparation Pipeline

The json_creater.py Streamlit application at json_creater.py converts Excel files to JSON format. The timetable parser (JIIT-time-table-parser) and academic calendar parser (JIIT-Academic-Calender) are external tools that process raw Excel data.

The Next.js build process at next.config.ts integrates the @ducanh2912/next-pwa plugin, which generates service worker files with precache manifests. See Timetable Data Format Reference for detailed JSON structure specifications.

Data Flow Overview

The data flow follows a unidirectional pattern:

1. User provides parameters through ScheduleForm component
2. App.tsx component fetches appropriate JSON data based on campus selection src/App.tsx43-53
3. handleFormSubmit() function invokes Pyodide execution src/App.tsx154-229
4. Generated schedule updates UserContext and persists to localStorage
5. Display components consume schedule from context
6. Export utilities transform schedule data to PDF, PNG, or Google Calendar events

Project Structure

The codebase is organized into functional directories:

src/
├── components/          # React components for UI
│   ├── schedule-form.tsx        # Input collection
│   ├── schedule-display.tsx     # Grid timetable view
│   ├── timeline.tsx             # Calendar visualization
│   ├── compare-timetable.tsx    # Comparison tool
│   ├── academic-calendar.tsx    # Institutional calendar
│   └── mess-menu.tsx            # Dining schedule
├── context/             # Global state management
│   ├── userContext.ts           # Context definition
│   └── userContextProvider.tsx  # Context provider
├── utils/               # Utility functions
│   ├── pyodide.ts               # Python WASM integration
│   ├── calendar.ts              # Google Calendar sync
│   └── download.ts              # PDF/PNG export
├── App.tsx              # Main schedule creator page
└── main.tsx             # Application entry point

public/
├── _creator.py          # Main Python module
├── modules/             # Campus-specific Python modules
│   ├── BE62_creator.py
│   └── BE128_creator.py
└── data/                # Static JSON data
    ├── time-table/      # Timetable data by semester
    └── calender/        # Academic calendar by year

The entry point at src/main.tsx1-73 configures routing with BrowserRouter, wraps the application in UserContextProvider, and integrates analytics through Vercel and PostHog. The Navbar component provides navigation with mobile gesture support via react-swipeable.

Key Interfaces

YourTietable Type

The primary data structure for generated schedules:

interface YourTietable {
  [day: string]: {
    [timeSlot: string]: {
      subject_name: string;
      type: "L" | "T" | "P" | "C";  // Lecture, Tutorial, Practical, Club
      location: string;
    };
  };
}

Defined at src/App.tsx28-36 and used throughout the application for schedule representation.

Schedule Generation Functions

Python functions exposed to JavaScript:

• time_table_creator() - Campus 62, Year 1
• time_table_creator_v2() - Campus 62, Years 2-4
• bando128_year1() - Campus 128, Year 1
• banado128() - Campus 128, Years 2-4
• bca_creator_year1() - BCA, Year 1
• bca_creator() - BCA, Years 2-3
• compare_timetables() - Compare two schedules

Each function accepts time_table_json, subject_json, batch, and electives_subject_codes parameters and returns a YourTietable object.

Deployment Architecture

The application is deployed on Vercel with custom rewrites defined in vercel.json1-17:

• PostHog analytics proxied through /ph/* routes
• All other routes serve index.html for client-side routing

The system operates as a Progressive Web App (PWA) with service worker public/service-worker.js for offline functionality and web manifest public/manifest.json for installability.