overview

JIIT Timetable Creator is a browser PWA that builds a personal class schedule. Python parsing runs in the page through Pyodide, so timetable generation does not need a backend. A Workbox service worker keeps the app usable offline after the first load.

Live site: jiit-timetable.tashif.codes

Deeper pages:

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

Three runtime layers sit in the browser. Static JSON is the data layer. Next.js App Router API routes only serve that JSON (and a mess-menu proxy). They do not generate schedules.

flowchart TB
  subgraph browser [Browser]
    UI["website/ Next.js 16 App Router"]
    CTX["UserContext + nuqs + localStorage"]
    PY["Pyodide 0.27.0 WASM"]
    WHEEL["parser wheel<br/>/parser/jiit_timetable_parser-0.1.0-py3-none-any.whl"]
    SW["Workbox SW<br/>website/public/sw.js"]
    UI --> CTX
    UI --> PY
    PY --> WHEEL
    SW --> UI
    SW --> PY
  end
  JSON["website/data JSON<br/>time-table, calender, exam"]
  API["app/api/* routes"]
  CDN["jsDelivr Pyodide CDN"]
  GCal["Google Calendar API"]
  Mess["Mess JSON / n8n proxy"]
  UI --> API
  API --> JSON
  PY --> CDN
  UI --> GCal
  API --> Mess

The service worker at website/public/sw.js uses three strategies:

• NetworkFirst for / (start-url cache)
• CacheFirst for https://cdn.jsdelivr.net/pyodide/v0.27.0/full/* with a 1-year TTL
• Precache for Next.js chunks, fonts, manifest.json, leftover /modules/*.py files, and _creator.py

Schedule generation#

sequenceDiagram
  participant Form as ScheduleForm
  participant Home as HomeContent
  participant API as /api/time-table
  participant Py as callTimeTableCreator
  participant Ctx as UserContext
  Form->>Home: campus, year, batch, electives
  Home->>API: semester + campus JSON
  API-->>Home: timetable + subjects
  Home->>Py: create_time_table(...)
  Py-->>Home: YourTietable
  Home->>Ctx: setSchedule + localStorage

HomeContent fetches mappings with TanStack Query (useTimeTables, useBatchMappings), then calls callTimeTableCreator in website/utils/pyodide.ts. Campus and year routing lives in Python create_time_table, not in a JS function-name switch.

Client-side Python#

initializePyodide() injects pyodide.js from jsDelivr, loads micropip, installs /parser/jiit_timetable_parser-0.1.0-py3-none-any.whl, then runs:

from main import create_time_table, compare_timetables, create_and_compare_timetable

create_time_table in parser/main.py picks the campus parser:

State#

flowchart LR
  URL["URL query<br/>nuqs"]
  CTX["UserContext<br/>schedule / editedSchedule"]
  LS["localStorage<br/>cachedSchedule, params,<br/>classConfigs, editedSchedule"]
  URL <--> Form["ScheduleForm"]
  Form --> CTX
  CTX --> LS
  LS --> CTX

UserContext holds schedule (Python output) and editedSchedule (user edits). nuqs keeps year, batch, campus, selectedSubjects in the URL. When those params disagree with a cached schedule, UrlParamsDialog offers override, prefill, or keep existing.

Creator tools (creator/) are Streamlit + Typer. They convert Excel/PDF into JSON and use Gemini for PDF notices. They are not part of the website runtime.

1. User picks campus, year, batch, electives on /.
2. HomeContent loads /api/time-table/{semester}/{campus} JSON.
3. Pyodide runs create_time_table.
4. Result is stored in context and cachedSchedule.
5. ScheduleDisplay and /timeline render it. Export tools read editedSchedule || schedule.

flowchart TD
  A[Form submit] --> B[Fetch campus JSON]
  B --> C[create_time_table in Pyodide]
  C --> D[UserContext + localStorage]
  D --> E[Grid / timeline]
  D --> F[PNG PDF iCal Google Calendar]
  D --> G[Share URL via nuqs]

.
├── website/                 Next.js 16 app
│   ├── app/                 pages and API routes
│   ├── components/
│   ├── context/
│   ├── data/                calendars, timetables, exams
│   ├── public/              sw.js, parser wheel, manifest
│   └── utils/               pyodide.ts, download.ts, calendar.ts
├── parser/                  Python package, built as a wheel
├── creator/                 Streamlit + Typer JSON converters
└── data/                    shared JSON (API also looks here)

There is no src/App.tsx and no Vite main.tsx. Routing is App Router under website/app/.

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

Defined in website/types/index.ts.

Vercel hosts the Next app. website/vercel.json proxies PostHog:

• /ph/static/* → eu-assets.i.posthog.com
• /ph/* → eu.i.posthog.com

website/next.config.ts adds the same /ph/:path* rewrite and PWA Workbox options. There is no SPA index.html fallback. App Router owns the routes.