Data Model & Types

This document defines the TypeScript interfaces and data structures that represent timetable data throughout the application. It covers the primary YourTietable interface, schedule event structures, class type enumerations, and the raw JSON data format consumed from static files.

For information about how these types are managed in React state and persisted to localStorage, see State Management. For details on how Python processing transforms raw JSON into these structures, see Python Processing Pipeline.

Core Type Definitions

YourTietable Interface

The YourTietable interface represents a complete weekly schedule. It is a nested dictionary structure mapping days to time slots to class details.

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

Structure Breakdown:

Event Object Properties:

Sources: src/App.tsx28-36 src/components/schedule-display.tsx12-14

ClassType Enumeration

The ClassType defines four possible class types using a union type:

Type Values:

The type determines visual styling in the UI through color mappings:

const typeColors: Record<ClassType | "C", string> = {
  L: "bg-[#F0BB78]/10 border-[#F0BB78]/20 hover:bg-[#F0BB78]/20",
  T: "bg-[#543A14]/10 border-[#543A14]/20 hover:bg-[#543A14]/20",
  P: "bg-[#FFF0DC]/10 border-[#FFF0DC]/20 hover:bg-[#FFF0DC]/20",
  C: "bg-[#FF9B50]/10 border-[#FF9B50]/20 hover:bg-[#FF9B50]/20",
};

Sources: src/components/schedule-display.tsx4 src/components/schedule-display.tsx26-31 src/components/schedule-display.tsx33-38

Raw Timetable Data Format

Static JSON files in /public/data/time-table/ODD25/ provide the source data. Each file (e.g., 62.json, 128.json, BCA.json) contains timetable and subject information structured by academic year.

JSON Structure Schema

Top-Level Structure:

{
  "1": {
    "timetable": { ... },
    "subjects": [ ... ]
  },
  "2": { ... }
}

Sources: public/data/time-table/ODD25/62.json1-703 public/data/time-table/ODD25/128.json1-510

Timetable Format

Within each year's timetable object, days map to time slots which contain arrays of activity strings.

Example from Campus 62 (Year 1, Monday):

"MON": {
  "9-9.50": [
    "TC2(EC112)-TS6/MN",
    "TA4(CI111)-TS7/SHV",
    "PB10(GE111)-CAD1/SWET"
  ],
  "10-10.50": [
    "LA1,A2(PH111)-G2/GPK",
    "LA3,A4(PH111)-G9/NFP1"
  ]
}

Example from Campus 128 (Year 1, Monday):

"MON": {
  "9 - 9:50 AM": [
    "LE3E4(15B11PH111) -123 /SHALU",
    "PF7F8F9(24B15CS111) - /CL1/AKB/SHG/NIB"
  ]
}

Activity String Format:

Each activity string encodes multiple pieces of information in a specific pattern:

Sources: public/data/time-table/ODD25/62.json4-48 public/data/time-table/ODD25/128.json4-91

Subjects Array Format

The subjects array contains metadata for all courses offered in that year:

{
  "Code": "15B17PH171",
  "Full Code": "PH171",
  "Subject": "Physics Lab-1"
}

Sources: public/data/time-table/ODD25/62.json637-703 public/data/time-table/ODD25/128.json458-509

State Management Types

UserContext Schedule State

The React Context stores two schedule objects that share the same YourTietable structure:

const [schedule, setSchedule] = React.useState<{
  [day: string]: {
    [time: string]: {
      subject_name: string;
      type: "L" | "T" | "P" | "C";
      location: string;
    };
  };
} | null>(null);

const [editedSchedule, setEditedSchedule] = 
  React.useState<UserContextType["editedSchedule"]>(null);

Display Priority Logic:

const displaySchedule = editedSchedule || schedule;

If editedSchedule exists, it completely overrides schedule for display. Otherwise, the base schedule is shown.

Sources: src/context/userContextProvider.tsx5-16 src/components/schedule-display.tsx40

EditEventDialog Form Data

When editing events, a temporary form state structure is used:

const [formData, setFormData] = React.useState({
  subject_name: currentEvent?.subject_name || "",
  type: currentEvent?.type || "C",
  location: currentEvent?.location || "",
  startTime: time ? time.split("-")[0] || "" : "",
  endTime: time ? time.split("-")[1] || "" : "",
});

Time Slot Formatting:

The dialog splits and rejoins time slot strings:

• Input: "9-9.50" or "10:00-10:50 AM"
• Split: startTime = "9", endTime = "9.50"
• Output: "09:00-09:00" (normalized to HH:mm format)

Sources: src/components/edit-event-dialog.tsx45-51 src/components/edit-event-dialog.tsx91-99

Type Flow Through System

The following diagram shows how data types transform as they flow through the application:

Data Transformation Steps:

1. Fetch: React loads JSON from /public/data/time-table/ODD25/{campus}.json
2. Extract: Year-specific timetable and subjects objects are passed to Pyodide
3. Process: Python creator function filters by batch, extracts electives, formats time slots
4. Convert: pyodide.toJs() transforms Python dictionary to JavaScript object
5. Store: setSchedule() stores in React state, triggers localStorage persistence
6. Display: Components receive typed YourTietable props
7. Edit: User modifications create editedSchedule which overrides base schedule

Sources: src/App.tsx115-152 src/App.tsx186-214 src/context/userContextProvider.tsx4-49

Time Format Variations

Different campuses use different time slot formats in their raw JSON data:

Normalization in Python:

Python creator functions standardize these to consistent formats before returning to JavaScript. The formatTime() helper function adds spaces for display readability:

const formatTime = (time: string) => {
  return time.replace("-", " - ");
};

Sources: src/components/schedule-display.tsx42-44 public/data/time-table/ODD25/62.json5-13 public/data/time-table/ODD25/128.json5-18

Type Safety Considerations

Optional Chaining for Data Access

Since schedule data comes from external JSON and Python processing, defensive coding is used throughout:

{displaySchedule &&
  typeof displaySchedule === "object" &&
  Object.entries(displaySchedule).map(([day, slots]) => (
    // ...
    {slots &&
      typeof slots === "object" &&
      Object.entries(slots).map(([time, class_]) => {
        if (!class_ || typeof class_ !== "object") return null;
        // ...
      })}
  ))}

This pattern guards against:

• schedule being null (initial state)
• Malformed data from Python processing
• Missing day or time slot keys
• Type mismatches during JSON parsing

Sources: src/components/schedule-display.tsx52-84

Null Safety in Context

The UserContext explicitly allows null values for both schedule states:

schedule: {
  [day: string]: {
    [time: string]: {
      subject_name: string;
      type: "L" | "T" | "P" | "C";
      location: string;
    };
  };
} | null

This reflects the application lifecycle:

1. Initial: Both schedule and editedSchedule are null
2. After Generation: schedule contains data, editedSchedule remains null
3. After Editing: editedSchedule contains modified data
4. After Reset: editedSchedule can be set back to null

Sources: src/context/userContextProvider.tsx5-13 src/context/userContextProvider.tsx15-16

Summary Table: All Type Interfaces