Getting Started

This document guides developers through setting up the JIIT Personalized Timetable Creator development environment, running the application locally, and understanding the core project structure and build system. For information about the overall system architecture and how components interact, see System Architecture. For specific feature implementation details, see Schedule Generation.

Purpose and Scope

This page covers:

• Prerequisites and system requirements
• Repository cloning and dependency installation
• Running the development server
• Project directory structure and organization
• Build system configuration
• Development workflow basics

Prerequisites

The following tools are required before beginning development:

Note: Python is NOT required for local development. The application uses Pyodide (Python compiled to WebAssembly) which runs entirely in the browser. The external Python Streamlit app mentioned in README.md71 is only used for data preparation and is not part of the development workflow.

Installation Steps

1. Clone the Repository

git clone https://github.com/tashifkhan/JIIT-time-table-website
cd JIIT-time-table-website

This creates a local copy of the repository with the following structure:

JIIT-time-table-website/
├── public/          # Static assets served directly
├── src/             # React application source code
├── package.json     # Node.js dependencies and scripts
├── vite.config.ts   # Vite build configuration
└── tsconfig.json    # TypeScript compiler settings

2. Install Dependencies

Using bun (recommended for faster installation):

bun i

Or using npm:

npm i

This command reads package.json and installs all required dependencies into node_modules/, including:

• React 18 and React DOM
• TypeScript and type definitions
• Vite build tooling
• Tailwind CSS and PostCSS
• Pyodide WASM runtime (loaded from CDN at runtime, not bundled)
• Various UI libraries (Radix UI, Framer Motion, etc.)

The node_modules/ directory is excluded from version control via .gitignore10

3. Run the Development Server

bun dev

Or with npm:

npm run dev

This executes the dev script defined in package.json, which starts Vite's development server. The application will be available at:

http://localhost:5173

The development server provides:

• Hot Module Replacement (HMR): Changes to source files automatically update in the browser without full page reload
• Fast refresh: React component state is preserved during updates
• TypeScript compilation: Type checking occurs in real-time
• Asset serving: Files in public/ are served at the root path

Application Entry Point Flow

The following diagram shows how the application initializes when the development server starts, mapping natural language concepts to actual code entities:

Component Initialization Order:

1. main.tsx22: createRoot() mounts React to DOM element with id root
2. main.tsx23: StrictMode wrapper enables additional development checks
3. main.tsx24-27: PostHogProvider initializes analytics with API key from environment variable VITE_PUBLIC_POSTHOG_KEY
4. main.tsx28: Background component provides visual styling
5. main.tsx29: UserContextProvider establishes global state management (see State Management)
6. main.tsx30: Analytics component from Vercel tracks page views
7. main.tsx31: NuqsAdapter enables URL query parameter synchronization
8. main.tsx32: BrowserRouter enables client-side routing
9. main.tsx33: Navbar renders persistent navigation
10. main.tsx35-49: Routes defines path-to-component mappings

Project Structure

The repository follows a standard React TypeScript project layout with specific directories for static assets and data:

Directory Breakdown

Build System Configuration

The application uses Vite as its build tool, configured via vite.config.ts. Key characteristics:

Development Mode

When running bun dev or npm run dev:

• Port: 5173 by default
• Hot Module Replacement: Enabled
• Source maps: Inline for debugging
• TypeScript: Compiled on-the-fly without type checking (use separate tsc --noEmit for type validation)
• Asset serving: Files in public/ served at / path

Production Build

The bun run build or npm run build command:

1. Compiles TypeScript to JavaScript
2. Bundles React components and dependencies
3. Minifies output
4. Generates static HTML/CSS/JS in dist/ directory
5. Optimizes assets (images, fonts, etc.)

The dist/ directory is excluded from version control via .gitignore11

Deployment Configuration

The vercel.json1-16 file configures deployment on Vercel:

• PostHog Proxy: Requests to /ph/* are proxied to PostHog analytics servers vercel.json3-10
• SPA Routing: All routes redirect to /index.html for client-side routing vercel.json12-14

This configuration ensures:

• Analytics tracking works without CORS issues
• Direct URL access to routes like /timeline or /compare-timetables loads the SPA correctly

Environment Variables

The application uses environment variables for external service configuration. Create a .env file in the project root (excluded from version control via .gitignore25):

VITE_PUBLIC_POSTHOG_KEY=your_posthog_api_key_here

Usage in code: Environment variables prefixed with VITE_ are accessible via import.meta.env main.tsx25

Note: Google Calendar API credentials are configured client-side during the OAuth flow, not via environment variables. See Google Calendar Integration for details.

Development Workflow

The typical development cycle follows this pattern:

Recommended Development Practices

1. File Watching: The dev server automatically detects changes to:

   • src/**/*.tsx and src/**/*.ts files
   • src/**/*.css files
   • public/**/* static assets

2. Type Checking: Run tsc --noEmit in a separate terminal for continuous type validation, as the dev server skips type checking for speed

3. Linting: Configure ESLint integration in your editor for real-time code quality feedback

4. Browser DevTools:

   • React DevTools extension for component inspection
   • Network tab to verify Pyodide WASM loading
   • Application tab to inspect localStorage state

5. Testing Routes: Navigate directly to routes during development:

   • http://localhost:5173/ - Schedule creator
   • http://localhost:5173/timeline - Calendar view
   • http://localhost:5173/compare-timetables - Comparison tool
   • http://localhost:5173/academic-calendar - Institutional calendar
   • http://localhost:5173/mess-menu - Dining schedule

Accessing Static Data

During development, static JSON files in public/data/ are accessible at the root path:

http://localhost:5173/data/time-table/ODD25/62.json
http://localhost:5173/data/time-table/ODD25/128.json
http://localhost:5173/data/calender/2526/calender.json

Python modules in public/modules/ and public/_creator.py are fetched by the Pyodide runtime README.md89-93 See Pyodide WASM Integration for details on how these files are loaded and executed.

External Access: The production API allows external access to data README.md56-64:

# Timetable data
curl https://simple-timetable.tashif.codes/data/time-table/ODD25/62.json

# Calendar data
curl https://simple-timetable.tashif.codes/data/calender/2526/calender.json

Troubleshooting Common Issues

Browser Compatibility: Modern browsers with WebAssembly support are required README.md220 Verify support at chrome://flags (Chrome) or about:config (Firefox).

Next Steps

After successfully running the development server:

1. Understand the Architecture: Read System Architecture to learn how components interact
2. Explore the Core Feature: See Schedule Generation for the main timetable creation pipeline
3. Review Data Structures: Consult Data Model & Types for TypeScript interfaces
4. Learn State Management: Study State Management for context and persistence patterns
5. Explore Python Integration: Read Pyodide WASM Integration for client-side Python execution details