app/docs/TIMETABLE_FEATURE.md

# Timetable Feature Documentation

## Overview

The Timetable module provides comprehensive class management and scheduling capabilities for Classroom Copilot. It enables teachers to create and manage classes, students to enroll and view their schedules, and real-time lesson management with TLDraw whiteboard integration.

---

## Features

### 1. My Timetable
- **Route**: `/timetable`
- **Description**: Personal calendar view showing all enrolled classes
- **Components**:
  - Week/Month view toggle
  - Lesson cards with time, subject, and location
  - Quick access to join ongoing lessons
  - Color-coded subjects

### 2. Browse Classes
- **Route**: `/classes`
- **Description**: Discovery page for finding available classes
- **Components**:
  - Search and filter (by subject, teacher, schedule)
  - Class cards with enrollment status
  - One-click enrollment request
  - Class details modal

### 3. My Classes
- **Route**: `/my-classes`
- **Description**: Management dashboard for enrolled/teaching classes
- **Teacher View**:
  - Classes they teach
  - Enrollment requests pending approval
  - Quick links to edit class details
  - Lesson management controls
- **Student View**:
  - Enrolled classes list
  - Progress indicators
  - Assignment due dates
  - Teacher contact info

### 4. Enrollment Requests
- **Route**: `/enrollment-requests`
- **Description**: Teacher approval interface for class enrollments
- **Components**:
  - Pending requests list
  - Student information preview
  - Approve/Reject actions
  - Bulk approval options
  - Request history

### 5. Lesson View
- **Route**: `/lessons/:lessonId`
- **Description**: Individual lesson page with TLDraw whiteboard
- **Components**:
  - Real-time collaborative whiteboard
  - Lesson info sidebar
  - Student roster
  - Join/Leave controls

---

## Routes Configuration

### AppRoutes.tsx

```typescript
{
  element: <FullContextRoutes />,
  children: [
    // ... other routes ...
    {
      path: "/timetable",
      element: <TimetablePage />,
    },
    {
      path: "/classes",
      element: <ClassesPage />,
    },
    {
      path: "/my-classes",
      element: <MyClassesPage />,
    },
    {
      path: "/enrollment-requests",
      element: <EnrollmentRequestsPage />,
    },
    {
      path: "/lessons/:lessonId",
      element: <LessonPage />,
    },
  ],
}
```

### Navigation (Header.tsx)

```typescript
{
  label: "Timetable",
  path: "/timetable",
  icon: <CalendarMonthIcon />,
  roles: ["teacher", "student"],
},
{
  label: "Browse Classes",
  path: "/classes",
  icon: <SchoolIcon />,
  roles: ["teacher", "student"],
},
{
  label: "My Classes",
  path: "/my-classes",
  icon: <ClassIcon />,
  roles: ["teacher", "student"],
},
{
  label: "Enrollment Requests",
  path: "/enrollment-requests",
  icon: <PendingIcon />,
  roles: ["teacher"], // Teacher only
},
```

---

## Component Structure

```
src/
├── components/
│   ├── timetable/
│   │   ├── CalendarView.tsx         # Week/Month calendar display
│   │   ├── LessonCard.tsx           # Individual lesson card
│   │   ├── ClassCard.tsx            # Class listing card
│   │   ├── EnrollmentRequestCard.tsx # Pending request item
│   │   ├── CreateClassModal.tsx     # Class creation form
│   │   └── LessonWhiteboard.tsx     # TLDraw integration
│   └── navigation/
│       └── Header.tsx               # Navigation with timetable items
├── pages/
│   ├── TimetablePage.tsx            # Main calendar view
│   ├── ClassesPage.tsx              # Browse available classes
│   ├── MyClassesPage.tsx            # Enrolled/teaching classes
│   ├── EnrollmentRequestsPage.tsx   # Teacher approval interface
│   └── LessonPage.tsx               # Individual lesson with whiteboard
├── services/
│   └── timetable/
│       ├── classes.service.ts       # Class CRUD operations
│       ├── timetable.service.ts     # Schedule management
│       └── lessons.service.ts       # Lesson operations
├── stores/
│   └── timetableStore.ts            # Zustand state management
└── types/
    └── timetable.ts                 # TypeScript interfaces
```

---

## Dependencies

### Required Packages
```json
{
  "@mui/icons-material": "^5.x",
  "@mui/material": "^5.x",
  "zustand": "^4.x",
  "react-router-dom": "^6.x",
  "axios": "^1.x",
  "date-fns": "^2.x",
  "@tldraw/tldraw": "^2.x"
}
```

---

## Configuration

### Environment Variables
```bash
# API Base URL
VITE_API_BASE_URL=http://localhost:8000

# Supabase (for auth)
VITE_SUPABASE_URL=http://192.168.0.155:8000
VITE_SUPABASE_ANON_KEY=<your-anon-key>

# TLDraw Sync Server
VITE_TLDRAW_SYNC_URL=ws://192.168.0.145:8000
```

---

## Usage Examples

### Navigate to Timetable
```typescript
import { useNavigate } from 'react-router-dom';

const navigate = useNavigate();
navigate('/timetable');
```

### Fetch Classes
```typescript
import { useTimetableStore } from '../stores/timetableStore';

const { classes, fetchClasses } = useTimetableStore();

useEffect(() => {
  fetchClasses();
}, []);
```

### Enroll in Class
```typescript
const { enrollInClass } = useTimetableStore();

await enrollInClass('class-uuid-here');
```

---

## Development Notes

### Running Locally
```bash
# Start all services
cd /a0/usr/projects/classroom_copilot_app
./scripts/dev-start.sh

# Frontend only
cd frontend
npm run dev -- --host 0.0.0.0
```

### Testing Endpoints
```bash
# Run comprehensive tests
python scripts/test_timetable_endpoints.py
```

### Demo Credentials
| Role | Email | Password |
|------|-------|----------|
| Teacher | teacher1@kevlarai.edu | DemoTeacher123! |
| Student | student1@kevlarai.edu | DemoStudent123! |

---

## Related Documentation

- [Backend API Spec](../planning/phase1_timetable_lessons/02_BACKEND_API_SPEC.md)
- [Frontend Architecture](../planning/phase1_timetable_lessons/03_FRONTEND_ARCHITECTURE.md)
- [TLDraw Sync Spec](../planning/phase1_timetable_lessons/05_WEBSOCKET_SYNC_SPEC.md)

---

## Changelog

### 2026-02-26
- ✅ Added Header navigation for timetable features
- ✅ Integrated timetable routes in AppRoutes.tsx
- ✅ Created documentation

---

**Last Updated**: 2026-02-26