System Architecture

Purpose and Scope

This document describes the overall system architecture of the JIIT Personalized Timetable Creator application. It explains the high-level design decisions, component interactions, data flow patterns, and the unique client-side architecture that eliminates the need for a traditional backend server.

For detailed information about specific architectural subsystems:

• Frontend component hierarchy and routing: see Frontend Architecture & Routing
• Pyodide integration and Python execution: see Pyodide WASM Integration
• Data structures and TypeScript types: see Data Model & Types
• State persistence and synchronization: see State Management

High-Level Overview

The JIIT Timetable website is a fully client-side application that runs entirely in the user's browser. It leverages WebAssembly through Pyodide to execute Python timetable generation logic without requiring a backend server. The application fetches static JSON data files, processes them using Python modules compiled to WASM, and renders personalized schedules using React components.

The system is deployed as a static site on Vercel, with all computation happening client-side. This architecture provides several advantages:

• Zero server infrastructure costs
• Instant schedule generation after initial load
• Offline functionality via PWA capabilities
• No data transmission to external servers (privacy-preserving)

Key Technologies:

• Frontend Framework: React 18 with TypeScript
• Runtime Environment: Pyodide v0.27.0 (Python 3.11 in WebAssembly)
• State Management: React Context API + localStorage
• Routing: React Router v6 with nuqs for URL state
• Build Tool: Vite
• Deployment: Vercel (static hosting)

Core Architectural Principles

1. Client-Side First Architecture

The application implements all business logic in the browser, with no backend API:

Architectural Decision: No Backend Server

The system fetches the Pyodide runtime (~10MB) and Python modules from CDN on first load. All timetable generation, filtering, and processing occurs in the browser's WASM runtime. This eliminates deployment complexity and server costs while maintaining full functionality.

2. Data-Driven Schedule Generation

The application operates on static JSON files containing timetable and subject data:

The JSON structure is generated by an external Streamlit app (json_creater.py) that parses Excel files from the institution.

3. Multi-Campus Support

The system handles three distinct campus/program types with different timetable structures:

Function Selection Algorithm

The evaluteTimeTable function in src/App.tsx115-152 implements dynamic Python function selection based on campus and year parameters. Each campus has distinct batch naming conventions, subject code formats, and timetable structures requiring specialized parsing logic.

Component Architecture

React Component Hierarchy

Component Responsibilities:

Data Flow Architecture

Schedule Generation Pipeline

Critical Code Paths:

1. Form Submission: src/App.tsx154-229 - Coordinates the entire generation process
2. Pyodide Initialization: src/utils/pyodide.ts23-58 - Loads WASM runtime and Python code
3. Function Calling: src/utils/pyodide.ts91-109 - Bridges JavaScript and Python
4. Python Processing: public/modules/BE62_creator.py316-410 - Parses and filters timetable

State Management Flow

State Persistence Strategy:

The application uses a three-tier persistence model:

1. URL Parameters (src/App.tsx231-247): For shareable links using nuqs library
2. UserContext (src/context/userContext.ts): Runtime state with React Context API
3. localStorage (src/App.tsx84-109): Cross-session persistence with keys:
   • cachedSchedule: Generated timetable
   • cachedScheduleParams: Generation parameters for comparison
   • classConfigs: Saved configuration presets
   • editedSchedule: User modifications to base schedule

Client-Side Python Execution

Pyodide Integration Architecture

The system uses Pyodide to run Python timetable generation logic in the browser:

Implementation Details:

• Runtime Caching: src/utils/pyodide.ts6 maintains a global pyodideInstance to avoid reloading
• Async Initialization: src/utils/pyodide.ts23-58 handles concurrent initialization requests
• Type Conversion: src/utils/pyodide.ts99-102 converts between JavaScript and Python objects
• Function Registry: Python modules expose functions in global namespace via public/script.py1-6

The Python modules (public/modules/BE62_creator.py public/modules/BE128_creator.py) contain complex parsing logic for:

• Batch number expansion (e.g., "A1-A10" → ["A1", "A2", ..., "A10"])
• Subject code extraction from activity strings
• Location parsing from formatted strings
• Time format conversion (12-hour → 24-hour)
• Elective subject matching

For detailed implementation: see Pyodide WASM Integration

Routing and Navigation

Route Structure

Navigation Implementation:

• Router Configuration: src/main.tsx32-50 defines all application routes
• Navbar Component: src/components/navbar.tsx provides swipeable mobile navigation
• URL State Sync: Uses nuqs library for bidirectional URL parameter synchronization
• Route Protection: /timeline checks for cached schedule, redirects to landing if absent

The navbar implements touch gestures via react-swipeable for mobile-first navigation experience.

For detailed routing implementation: see Frontend Architecture & Routing

External Dependencies and Services

Third-Party Integrations

API Proxy Configuration:

The vercel.json1-16 file configures reverse proxies:

• PostHog analytics → eu.i.posthog.com (avoids ad-blockers)
• Catch-all SPA routing → index.html

Export Capabilities

The system provides multiple export formats:

Export Implementations:

• Image Export: src/utils/download.ts uses html-to-image to capture DOM as PNG
• PDF Export: Same module uses jsPDF to convert PNG to downloadable PDF
• Google Calendar: src/utils/calendar.ts creates recurring events with RRULE specifications

Deployment Architecture

Build and Deployment Pipeline

Deployment Characteristics:

• Static Site Generation: All assets compiled to static files via Vite
• Edge Distribution: Served via Vercel's global CDN
• No Server-Side Logic: Zero compute costs beyond CDN bandwidth
• PWA Support: Service worker (public/service-worker.js) enables offline functionality
• Build Output: Single-page application with client-side routing

The application is production-ready at https://simple-timetable.tashif.codes/ with automatic deployments on git push.

Data Types and Structures

Core Data Interfaces

The application uses TypeScript interfaces for type safety:

YourTietable Interface (src/App.tsx28-36):

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

Example Data Flow:

1. Python returns dict: {"Monday": {"09:00-10:00": {...}}}
2. Converted via result.toJs() to JavaScript object
3. Type-asserted as YourTietable in React
4. Stored in UserContext and rendered by ScheduleDisplay

For complete type definitions: see Data Model & Types

Performance Considerations

Optimization Strategies

Known Performance Issue:

The first Pyodide execution returns incorrect results (warm-up issue). The system runs generation twice on initial load: src/App.tsx194-204 This is a Pyodide runtime quirk that requires investigation.

This architecture enables a fully functional timetable generation system with zero backend infrastructure, leveraging modern web technologies to deliver computation-intensive features entirely client-side.