Frontend Architecture & Routing

Purpose and Scope

This document describes the frontend architecture of the JIIT Timetable application, focusing on the application structure, routing system, navigation implementation, and URL state management. It covers how the React application is initialized, how pages are organized and connected via React Router, and how URL parameters enable shareable schedule configurations.

For information about individual page components and their features, see Schedule Generation, Timeline View, Compare Timetables, Academic Calendar, and Mess Menu. For state management details, see State Management. For URL parameter encoding specifics, see Shareable URLs & Configuration Sharing.

Application Entry Point

The application entry point is src/main.tsx1-72 This file initializes the React application with a multi-layered provider structure that establishes global context, routing, analytics, and UI theming.

Provider Hierarchy

Sources: src/main.tsx22-72

Provider Stack Details

Provider	Purpose	Configuration
`PostHogProvider`	Product analytics tracking	API key from `VITE_PUBLIC_POSTHOG_KEY`, proxied through `/ph` endpoint
`Background`	Animated background component	Wraps entire application
`UserContextProvider`	Global schedule state management	Provides `schedule` and `editedSchedule` context
`NuqsAdapter`	URL state synchronization	Enables URL query parameter state management with React Router v6
`BrowserRouter`	Client-side routing	React Router v6 implementation
`Analytics`	Vercel Analytics	Page view and performance tracking

Sources: src/main.tsx18-32

Routing Configuration

The application uses React Router v6 for client-side routing with a flat route structure. All routes are defined in src/main.tsx35-49

Route Definition Diagram

Sources: src/main.tsx32-49

Route Table

Path	Component	Description	Import
`/`	`App`	Schedule creator form and display	src/main.tsx4
`/timeline`	`TimelineWrapper`	Calendar-style timeline view	src/main.tsx5
`/academic-calendar`	`AcademicCalendar`	Institutional calendar viewer	src/main.tsx11
`/compare-timetables`	`CompareTimetablePage`	Side-by-side schedule comparison	src/main.tsx13
`/mess-menu`	`MessMenuPage`	Dining hall menu display	src/main.tsx7
`*` (catch-all)	`NotFoundPage`	404 error page	src/main.tsx6

Sources: src/main.tsx35-49

Server-Side Routing Configuration

The vercel.json1-16 file configures URL rewriting for deployment:

PostHog Proxy Rewrites (vercel.json3-10): Proxies analytics requests to PostHog EU servers through /ph to avoid ad blockers
SPA Fallback (vercel.json12-14): All unmatched routes redirect to index.html for client-side routing

Sources: vercel.json1-16

Navigation System

The navigation system is implemented in src/components/navbar.tsx1-90 It provides both click-based and swipe-based navigation with responsive design.

Navigation Component Architecture

Sources: src/components/navbar.tsx1-90

Navigation Tabs Configuration

The tabs are defined as a static array at src/components/navbar.tsx4-10:

const tabs = [
  { name: "Create TimeTables", path: "/" },
  { name: "Timeline View", path: "/timeline" },
  { name: "Mess Menu", path: "/mess-menu" },
  { name: "Academic Calender", path: "/academic-calendar" },
  { name: "Compare TimeTables", path: "/compare-timetables" },
];

Sources: src/components/navbar.tsx4-10

Swipe Navigation Implementation

The swipe navigation system is implemented using react-swipeable library:

Feature	Implementation	Details
Swipe Direction	`onSwipedLeft`, `onSwipedRight`	Navigate to next/previous tab in array
Edge Detection	Fixed positioned divs on left/right edges	6px wide invisible areas at screen edges
Conditional Disable	`isTimelinePage` check	Swipe disabled on `/timeline` to avoid conflict with calendar swiping
Delta Threshold	`delta: 50`	Minimum 50px movement required to trigger navigation
Touch/Mouse Support	`trackTouch`, `trackMouse`	Works on both mobile and desktop

Sources: src/components/navbar.tsx26-46 src/components/navbar.tsx71-86

Active Tab Highlighting

Active tab detection is implemented in src/components/navbar.tsx16-21:

For root path (/): Exact match required
For other paths: Prefix match using location.pathname.startsWith()
Active styling: Background color, text color, and border styling via NavLink isActive prop

Sources: src/components/navbar.tsx53-66

Responsive Layout

The navbar adapts its layout based on screen size:

Screen Size	Layout	Styling
Mobile (`< md`)	Horizontal bottom nav	Fixed at top with `md:ml-56 mt-9` offset
Desktop (`≥ md`)	Vertical sidebar	Fixed left sidebar 192px wide (`md:w-48`)

Sources: src/components/navbar.tsx34 src/components/navbar.tsx49

URL State Management

The application uses nuqs library for URL query parameter state synchronization, enabling shareable schedule configurations.

URL Parameter Flow

Sources: src/components/url-params-dialog.tsx1-161 src/main.tsx12

URL Parameter Conflict Resolution

The UrlParamsDialog component (src/components/url-params-dialog.tsx22-160) handles conflicts when URL parameters are detected but a schedule already exists:

Action	Behavior	Implementation
Generate New Schedule	Replace existing schedule with URL params	`onOverride` callback
Use as Form Prefill	Populate form fields without generating	`onPrefill` callback
View Existing Schedule	Dismiss dialog, keep current schedule	`onViewExisting` callback

Sources: src/components/url-params-dialog.tsx133-155

URL Parameters Display

The dialog displays parsed parameters in a structured format (src/components/url-params-dialog.tsx81-130):

Basic Parameters: Campus, Year, Batch
Subject Codes: Displays subject names with code mapping
Deduplication: Handles concatenated codes and removes duplicates
Code-to-Name Mapping: Resolves subject codes to readable names from mapping data

Sources: src/components/url-params-dialog.tsx46-53 src/components/url-params-dialog.tsx106-128

Layout Structure

The main content area is wrapped with consistent layout structure in src/main.tsx34-50

Layout Hierarchy Diagram

Sources: src/main.tsx32-66

Layout Specifications

Element	Positioning	Styling
Navbar	Fixed sidebar (desktop) or top bar (mobile)	`md:fixed md:top-0 md:left-0 md:h-full md:w-48`
Main Content	Offset by navbar width	`md:ml-56 mt-9 md:mt-0 p-4`
GitHub Icon	Fixed bottom-right	`fixed right-2 bottom-2 z-50`

Sources: src/main.tsx34 src/main.tsx51-65

Content Area Offset Calculation

The main content area includes responsive margins to prevent overlap with the navbar:

Mobile: mt-9 (top margin) to account for fixed top navbar
Desktop: md:ml-56 (left margin) to account for 192px sidebar + padding
Padding: p-4 applied to all sides for consistent spacing

Sources: src/main.tsx34

Component Import Map

All page-level components are imported at the top of src/main.tsx4-14:

Sources: src/main.tsx4-15

Router Integration with State

The routing system integrates tightly with the UserContext state management:

Route	State Access	Persistence
`/`	Full read/write to `schedule`, `editedSchedule`	Auto-saves to `localStorage`
`/timeline`	Read-only access to `schedule` + `editedSchedule`	No modification
`/compare-timetables`	Generates two separate schedules	Not persisted to context
`/academic-calendar`	Independent of schedule state	N/A
`/mess-menu`	Independent of schedule state	N/A

All routes wrapped by UserContextProvider can access schedule state, but only the home route (/) modifies it. Other routes consume the cached schedule for display purposes.

Sources: src/main.tsx29

Navigation State Tracking

The navbar tracks the current route to highlight the active tab using useLocation hook:

Sources: src/components/navbar.tsx14-21

The active tab index is used for:

Visual Highlighting: Border, background, and text color changes
Swipe Navigation: Calculating next/previous tab indices
Accessibility: Marking current page for screen readers